139 lines
12 KiB
Markdown
139 lines
12 KiB
Markdown
# 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`:
|
|
|
|
```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 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.
|