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. Call describe_tools to get the full list of available tools with their categories and any notes you have previously annotated. Read the notes before using a tool — they contain accumulated gotchas, workflow patterns, and field-ordering requirements you have recorded from prior sessions.

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, always retrieve context with get_project_context or recall_context so prior decisions inform your approach.
• 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:

{ "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 the start of every session, call describe_tools to read the full tool list and any accumulated usage notes. Use AMCS memory in project scope when the current work matches a known project; if no clear project matches, global notebook memory is allowed for non-project-specific information. At the start of every project session call list_project_skills and list_project_guardrails and apply what is returned; only create new skills or guardrails if none exist. If your MCP client does not preserve sessions across calls, pass project explicitly instead of relying on set_active_project. Store raw/durable notes with capture_thought, store curated durable lessons with add_learning, and track structured multi-step goals with create_plan. Use get_plan to load a plan's full context including dependencies, related plans, and linked skills/guardrails. Stamp last_reviewed_at on plans you review with update_plan mark_reviewed: true. For binary files or files larger than 10 MB, call upload_file with content_path to stage the file and get an amcs://files/{id} URI, then pass that URI to save_file as content_uri to link it to a thought. For small files, use save_file or upload_file with content_base64 directly. Browse stored files with list_files, and load them with load_file only when their contents are needed. Stored files can also be read as raw binary via MCP resources at amcs://files/{id}. Never store project-specific memory globally when a matching project exists, and never store memory in the wrong project. If project matching is ambiguous, ask the user. If a tool returns project_not_found, call create_project with that name and retry — never drop the project scope. Whenever you discover a non-obvious tool behaviour, gotcha, or workflow pattern, record it with annotate_tool so future sessions benefit.