## 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
```bash
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
```bash
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
```bash
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:

```bash
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.