amcs/llm/memory.md

# AMCS Memory Instructions

AMCS (Avalon Memory Control Service) is an MCP server for capturing and retrieving thoughts, memory, and project context. It is backed by Postgres with pgvector for semantic search.

`amcs-cli` is a pre-built CLI that connects to the AMCS MCP server so agents do not need to implement their own HTTP MCP client. Download it from https://git.warky.dev/wdevs/amcs/releases

The key command is `amcs-cli stdio`, which bridges the remote HTTP MCP server to a local stdio MCP transport. Register it as a stdio MCP server in your agent config and all AMCS tools are available immediately without any custom client code.

Configure with `~/.config/amcs/config.yaml` (`server`, `token`), env vars `AMCS_URL` / `AMCS_TOKEN`, or `--server` / `--token` flags.

You have access to an MCP memory server named AMCS.

Use AMCS as memory with two scopes:
- Project memory: preferred when the current work clearly belongs to a known project.
- Global notebook memory: allowed only when the information is not tied to any specific project.

## Scope Selection Rules

1. Infer the current project from the repo, current working directory, README, package or app name, and any explicit user instruction.
2. Call `get_active_project`.
3. If the active project clearly matches the current work, use it.
4. If not, call `list_projects` and look for a strong match by name or explicit user intent.
5. If a strong match exists, call `set_active_project` and use project-scoped memory.
6. If no strong project match exists, you may use global notebook memory with no project.
7. If multiple projects plausibly match, ask the user before reading or writing project memory.

## Session Startup

At the very start of any session with AMCS:

1. Read the `amcs://world-model/intro` resource.
2. Identify the current project and call `bootstrap_world_model` with its explicit name or ID and the smallest useful `context_limit`.
3. Apply the returned skills and guardrails, but keep persona manifests and memory summaries as indexes. Load detailed content only when the current task requires it.
4. Call `describe_tools` only when tool discovery or saved usage notes are needed. Prefer a category filter instead of loading the full catalog.

## Token Budget and Progressive Loading

- Minimize startup and working context. Do not load data merely because it is available.
- Start with names, summaries, manifests, and metadata. Fetch full skill, guardrail, persona, trait, part, thought, plan, learning, chat, or file content only when it is relevant to the current task.
- Use the smallest practical `limit` or `context_limit`, narrow queries, and project/category filters. Increase them only when the initial result is insufficient.
- Do not preload every persona, skill, guardrail, plan, file, or historical memory. Follow references on demand.
- Avoid repeating unchanged world-model content in the conversation. Keep a concise working summary and refresh only when the project or task changes, or when stale context is suspected.
- Prefer `get_persona_manifest` and compiled summaries before `get_agent_persona(detail=true)`. Prefer `list_skills` metadata before `get_skill`, and file metadata before `load_file`.
- Guardrails and directly applicable skills are mandatory even under a tight token budget; token minimization must never omit an applicable constraint.

## Project Session Startup

After setting the active project:

1. Call `list_project_skills` to load any saved agent behaviour instructions for the project.
2. Call `list_project_guardrails` to load any saved agent constraints for the project.
3. Apply all returned skills and guardrails immediately and for the duration of the session.
4. Only generate or define new skills and guardrails if none are returned. If you do create new ones, store them with `add_skill` or `add_guardrail` and link them to the project with `add_project_skill` or `add_project_guardrail` so they persist for future sessions.

## Project Does Not Exist Yet

If any tool returns a `project_not_found` error:

1. Call `create_project` with the same name you tried to use.
2. Immediately retry the original tool call with that project.

Do not abandon the project scope or retry without a project. The project simply needs to be created first.

## Project Memory Rules

- Use project memory for code decisions, architecture, TODOs, debugging findings, and context specific to the current repo or workstream.
- Before substantial work, retrieve focused context with `get_project_context` or `recall_context` only when prior decisions may affect the task. Use a narrow query and small limit first.
- Save durable project facts with `capture_thought` after completing meaningful work.
- Use structured learnings for curated, reusable lessons that should remain distinct from raw thought capture.
- Use `save_file` or `upload_file` for project assets the memory should retain, such as screenshots, PDFs, audio notes, and other documents.
- If the goal is to retain the artifact itself, store the file directly instead of first reading, transcribing, or summarizing its contents.
- For binary files or files larger than 10 MB, call `upload_file` with `content_path` (absolute server-side path) first to get an `amcs://files/{id}` URI, then pass that URI to `save_file` as `content_uri` to link it to a thought. This avoids base64 encoding entirely.
- For small files (≤10 MB) where a server path is not available, use `save_file` or `upload_file` directly with `content_base64`.
- Link files to a specific memory with `thought_id` when the file belongs to one thought, or to the project with `project` when the file is broader project context.
- Use `list_files` to browse project files or thought-linked files before asking the user to resend something that may already be stored.
- Use `load_file` when you need the actual stored file contents back. The result includes both `content_base64` and an embedded MCP binary resource at `amcs://files/{id}` — prefer the embedded resource when your client supports it.
- You can also read a stored file's raw binary content directly via MCP resources using the URI `amcs://files/{id}` without calling `load_file`.
- Stored files and attachment metadata must not be sent to the metadata extraction client.
- Do not attach memory to the wrong project.

## Structured Learnings

- Learnings are curated memory records for durable insights, decisions, and evidence-backed findings.
- Prefer `capture_thought` for fast/raw notes during work; prefer learnings when the information is stable enough to normalize and track.
- Create learnings with `add_learning` (required: `summary`; optional: `details`, `category`, `area`, `status`, `priority`, `confidence`, `action_required`, `tags`, and related links).
- Retrieve one learning with `get_learning` and browse/filter with `list_learnings` (project/category/area/status/priority/tag/query).
- Keep learnings concise, specific, and non-duplicative; use `tags` and status fields so future retrieval is reliable.

## Global Notebook Rules

- Use global memory only for information that is genuinely cross-project or not project-bound.
- Examples: user preferences, stable personal workflows, reusable conventions, general background facts, and long-lived non-project notes.
- If information might later be confused as project-specific, prefer asking or keep it out of memory.

## Memory Hygiene

- Save only durable, useful information.
- Do not save secrets, raw logs, or transient noise.
- Prefer concise summaries.
- Prefer linking a file to a thought plus a concise thought summary instead of storing opaque binary artifacts without context.
- Do not read a file just to make it storable; store the file directly and read it only when the file contents are needed for reasoning.
- Do not base64-encode a file to pass it to `save_file` if an `amcs://files/{id}` URI is already available from a prior `upload_file` or HTTP upload.
- When saving, choose the narrowest correct scope: project if project-specific, global if not.

## Plans

Plans are structured, trackable work items linked to projects. Use plans for multi-step goals, workstreams, or anything that needs an owner, due date, status lifecycle, or explicit dependency tracking.

- **Status lifecycle**: `draft` → `active` → `blocked` | `completed` | `cancelled` | `superseded`
- **Priority**: `low`, `medium` (default), `high`, `critical`
- Create plans with `create_plan` (required: `title`; optional: `description`, `status`, `priority`, `project`, `owner`, `due_date`, `supersedes_plan_id`, `tags`).
- Retrieve a full plan with `get_plan` — returns the plan plus `depends_on`, `blocks`, `related_plans`, `skills`, and `guardrails` in a single call.
- Partially update a plan with `update_plan` (only provided fields change). Use `mark_reviewed: true` to stamp `last_reviewed_at` without manually passing a timestamp.
- List and filter with `list_plans` (project/status/priority/owner/tag/query).
- Delete permanently with `delete_plan`.

**Dependencies** (directional — "A cannot proceed until B is done"):
- `add_plan_dependency` / `remove_plan_dependency` using `plan_id` and `depends_on_plan_id`.
- `get_plan` returns `depends_on` (plans this plan waits on) and `blocks` (plans waiting on this one).

**Related plans** (bidirectional — thematically linked, no ordering):
- `add_related_plan` / `remove_related_plan` using `plan_a_id` and `plan_b_id` (order does not matter).

**Plan skills and guardrails** (agent behaviour scoped to a plan):
- `add_plan_skill` / `remove_plan_skill` / `list_plan_skills`
- `add_plan_guardrail` / `remove_plan_guardrail` / `list_plan_guardrails`
- Load plan skills and guardrails alongside project skills/guardrails when working within a specific plan's scope.

**Freshness**: use `last_reviewed_at` and `reviewed_by` to track whether a plan is current. Set `mark_reviewed: true` on `update_plan` after reviewing a plan so staleness is visible in `list_plans` results.

## Tool Annotations

As you learn non-obvious behaviours, gotchas, or workflow patterns for individual tools, persist them with `annotate_tool`:

```json
{ "tool_name": "capture_thought", "notes": "Always pass project explicitly — session state is unreliable in this client." }
```

Notes are returned by `describe_tools` in future sessions. Annotate whenever you discover something worth remembering: a required field combination, a parameter that behaves unexpectedly, or a preferred call sequence. Pass an empty string to clear a note.

## Skills and Guardrails

- **Skills** are reusable agent behaviour instructions (e.g. output formatting rules, reasoning strategies, workflow conventions).
- **Guardrails** are agent constraints and safety rules (e.g. never delete without confirmation, do not expose secrets). Each guardrail has a severity: `low`, `medium`, `high`, or `critical`.
- Use `add_skill` / `add_guardrail` to create new entries, `list_skills` / `list_guardrails` to browse the full library, and `remove_skill` / `remove_guardrail` to delete entries.
- Use `add_project_skill` / `add_project_guardrail` to attach entries to the current project, and `remove_project_skill` / `remove_project_guardrail` to detach them.
- Always load project skills and guardrails at session start before generating new ones — see Project Session Startup above.

## Short Operational Form

At session start, identify the project and call `bootstrap_world_model` with a small `context_limit`. Apply mandatory skills and guardrails, but otherwise use summaries and manifests as indexes and load details only when needed. Call `describe_tools` only for discovery or saved notes, preferably with a category filter. Use project scope when the work matches a known project; pass `project` explicitly for stateless clients. Store durable notes with `capture_thought`, curated lessons with `add_learning`, and multi-step work with `create_plan`. Retrieve plans, memories, personas, and files on demand using narrow queries and the smallest useful limits. Never store memory in the wrong scope, silently choose an ambiguous project, or omit an applicable guardrail to save tokens. Record non-obvious tool behavior with `annotate_tool`.