amcs/AGENTS.md

What This Project Is

AMCS (Avalon Memory Control Service) is an MCP server written in Go that provides memory, knowledge, and task management for AI agents. It exposes 56+ tools via HTTP/SSE MCP transport and includes a Svelte 5 admin UI embedded in the binary.

Agent Rules

Keep your answers short. Question everything, never assume or guess. Ask the user if you are unsure about anything. You must use the AMCS MCP system tools. Set Origin as the active project and always capture summaries of what was done as thoughts using the capture_thought tool. If amcs is not available write files to doc/llm/log/yyyymmdd_hh.md When working on postgresql use the postgresql skill. On go/api/backend the go-skill and for the frontend the "svelte-architect" skill.

Commands

Build & Run

make build          # Build server binary (outputs to bin/amcs-server), embeds UI
make build-cli      # Build CLI binary (bin/amcs-cli)
make clean          # Remove bin/

# Run locally (builds UI then starts server)
./scripts/run-local.sh configs/dev.yaml

# UI hot-reload dev server (proxy to backend on :8080)
make ui-dev         # http://localhost:5173

Testing

make test                                           # All tests (svelte-check + go test ./...)
go test ./internal/tools -run TestFunctionName -v  # Single test
go test ./internal/tools -v                        # Package tests

Database

make migrate                 # Apply SQL migrations
make check-schema-drift      # Verify no drift between DBML and SQL

Architecture

Key Pattern: Store → Tool → MCP Handler

Every tool domain follows the same three-layer pattern:

1. Store (internal/store/) — database access via BUN ORM + pgx. One file per domain (e.g., thoughts.go, plans.go).
2. Tool (internal/tools/) — MCP tool handler structs with a Handle(ctx, req, input) method. Input/output types are plain Go structs; JSON schemas are auto-generated from struct tags.
3. Registration (internal/mcpserver/handlers.go) — each domain has a registerXxxTools(server, logger, ts) function called from NewHandlers.

Adding a New Tool Domain

Follow the checklist in internal/tools/ (see project_conventions.md in memory, or look at any existing domain like skills.go as a reference):

• Define input/output structs with jsonschema tags
• Implement a struct with Handle method
• Add the struct to ToolSet in mcpserver/handlers.go
• Wire the store in internal/store/db.go
• Add a registerXxxTools call in NewHandlers

AI Provider Architecture

Configured in YAML under ai.providers. Each role (embeddings, metadata extraction) supports a primary provider and a fallback chain. Providers are named references (litellm, ollama, openrouter) that resolve to OpenAI-compatible endpoints. Health tracking per provider with cooldown on transient failures.

Error Handling

All tool errors return structured mcperrors.RPCError with:

• data.type — machine-readable category (invalid_input, project_required, entity_not_found, etc.)
• data.field / data.detail / data.hint — structured validation data

Use helpers in internal/mcperrors/ rather than raw errors.

Authentication

• API key via x-brain-key header (dev/simple deployments)
• OAuth 2.0 client credentials for production
• Session store tracks active project per client connection

Database Schema

DBML files in schema/ are the source of truth for the database schema. Never edit the generated SQL or Go models directly — always edit the DBML, then regenerate:

make generate-migrations   # DBML → SQL migration files
make generate-models       # DBML → Go model structs
make migrate               # Apply pending migrations to the database

All primary keys are bigserial int64 (migrated from UUID in migration 015).

Frontend

Svelte 5 + Tailwind + Skeleton UI in ui/. Built via pnpm and embedded into the Go binary as a static filesystem. The Vite dev server proxies API calls to the backend on :8080.

The UI uses resolvespec-js for admin CRUD views. The backend API for the UI follows the ResolveSpec convention — resource endpoints, filtering, and pagination are structured according to that spec.

Configuration

YAML config with schema version: 2. Key env var overrides:

• DATABASE_URL — PostgreSQL connection string
• AMCS_LITELLM_API_KEY, AMCS_OPENROUTER_API_KEY — AI provider keys
• AMCS_SERVER_PORT — defaults to 8080

See configs/config.example.yaml for the full schema. Config auto-migrates v1→v2 on startup.