amfs-mcp-server

Find the common ancestor of two commits (merge-base). Given two commit IDs, walks the DAG to find the most recent commit that is an ancestor of both.

Trigger a memory consolidation cycle. Runs the Cortex consolidation strategy which: - Tier A (automatic): archives superseded beliefs, prunes stale entries - Tier B (proposals): creates consolidation proposals for convergent knowledge and outcome rollups that need review

Record external context that influenced this session's decisions. Call this AS IT HAPPENS — not all at the end. This preserves causal order. Use this for: - External tool results: amfs_record_context("git-log", "15 commits since last deploy", "git") - User decisions: amfs_record_context("user-decision", "User chose X over Y", "chat") - Architecture decisions: amfs_record_context("arch-decision", "Using Redis for cache", "analysis") - API responses: amfs_record_context("pagerduty", "3 SEV-1 in 24h", "PagerDuty API") The context is added to the causal chain persisted by amfs_commit_outcome(), making decision traces complete and explainable.

List all entries written by YOU — what's in my brain? Returns only entries authored by this agent. Optionally filter to a specific entity path.

List entries that are candidates for consolidation. These are entries the Cortex has identified as potentially redundant, superseded, or compressible. Review these to understand what the consolidation system would act on.

Show the current active identity and whether it was restored from disk. Useful for debugging identity issues or confirming which agent name is being used for reads/writes.

Get aggregate statistics about the memory store. Returns total entries, entities, agents, confidence distribution, and time range. Useful for understanding the current state of shared knowledge.

Retrieve a full decision trace by ID. Returns the complete causal chain: every memory read, external context, query, error, and the outcome. Use this to understand exactly what information drove a past decision.

Atomically write multiple memory entries as a single commit. All writes succeed or fail together — no partial updates. Each write in the batch is a dict with at least "entity_path", "key", "value", and optionally "confidence", "memory_type", "pattern_refs", "shared".

Verify the content integrity of your memory store. Checks that stored content hashes match actual values, and that integrity chains link correctly across entry versions. Use this to detect corruption or tampering.

View the commit log — atomic groups of writes with messages. Shows commits newest first, including the entries that were part of each commit.

List all current memory entries, optionally filtered to an entity path. Use to explore what knowledge exists for a given service or module.

Write a memory entry with automatic provenance tracking. WHEN TO WRITE (only write things that help a future agent): - After completing a task: key="task-summary-<desc>", value="what you did and why" - When discovering a pattern: key="pattern-<name>", add pattern_refs for cross-referencing - When finding a bug or risk: key="risk-<name>", use memory_type="belief" for hypotheses - When making a non-obvious decision: key="decision-<topic>", include rationale - When logging actions: key="action-<desc>", use memory_type="experience" (decays slower) DON'T write trivial info ("added a comment") — write things a colleague would need. Keep values concise but informative. Think of it as a note to a future agent.

Clear the sticky identity so it reverts to auto-detection. After calling this, the identity will fall back to environment-based detection (e.g. "cursor/username", "claude-code/username") until amfs_set_identity is called again.

Explain the causal chain — which memories influenced this session's decisions. Shows every memory the agent read (in order) before committing an outcome. This is production-grounded explainability: not what the LLM inferred, but which stored knowledge actually drove the decision.

Show which other agents' memory this agent has read. Returns a mapping of other agent IDs to the specific entity/key pairs read from them, with read counts. Use this to understand inter-agent communication and memory sharing relationships. Answers questions like: - "Which agents have I talked to?" - "What memory did I get from agent X?" - "Who wrote the knowledge I'm relying on?" Example response: { "agent_id": "review-agent", "reads_from": { "deploy-agent": [ {"entity_path": "checkout-service", "key": "retry-pattern", "read_count": 3} ] }, "agents_read_from": ["deploy-agent"] }

Discover other agents by capability or entity path. Use this to find which agents know about a topic or work on a codebase area.

Set the agent identity for this conversation. CALL THIS FIRST before any other AMFS tool. Without this, all your work is attributed to a generic default identity. **Sticky identity**: Once set, the identity is saved to disk and automatically restored in future sessions. You only need to call this again to change roles or update the description. If the identity is already active (from a previous session or the same session), this is a no-op. MANDATORY WORKFLOW — follow this order every session: 1. amfs_set_identity(name, description, model) ← you are here 2. amfs_briefing(entity_path="repo/module") ← get compiled context before starting work 3. Do your work, calling amfs_write() for important discoveries, decisions, and patterns 4. amfs_record_context() for external tool results and user decisions as they happen 5. amfs_commit_outcome("task-ref", "success|failure") ← always do this when done Naming rules: - Use kebab-case role names that persist across conversations: "api-agent", "auth-debugger", "infra-agent" - BAD: "fix-button-color" (too specific), "agent-1" (meaningless) - If continuing previous work, reuse the same name to build on that agent's knowledge - The description should say what you're doing right now Entity path convention: use "repo/module" paths (e.g. "myapp/auth", "amfs/core-engine") Confidence guidelines: 1.0=verified fact, 0.7-0.9=high confidence, 0.4-0.6=hypothesis, <0.4=speculative

Set your agent profile — description, tags, and auto-context paths. The profile helps other agents discover you and understand your role.

Find memories by meaning — the default tool for any recall/lookup. Use this FIRST whenever the user asks you to find, recall, look up, or remember something, or when you want to check whether relevant memory exists. Just pass the user's own words as `query`. You do NOT need to know where it's stored: `entity_path` is optional and, when omitted, this searches across everything you can see (all your agents and all entities). It blends semantic similarity, recency, and confidence into one ranked list, so paraphrases and synonyms match even without exact keywords. Prefer this over `amfs_read` (which needs exact coordinates) and over `amfs_search` (which is for structured filtering / exact keywords).

Export outcome-validated knowledge as a fine-tuning dataset. Generates training examples from decision traces in SFT, DPO, or Reward Model format. Only includes entries meeting the confidence threshold and linked to production outcomes. Requires AMFS_HTTP_URL to be set and the amfs-pro-api package installed on the server.

Read a single memory entry when you ALREADY know its exact path and key. Only use this when you have the exact entity_path AND key (e.g. from a prior search/retrieve result). Do NOT guess coordinates — if you're trying to find something by meaning or the user gave you a plain phrase, use `amfs_retrieve` instead (it needs no path/key). Returns the full entry as JSON including value, confidence, provenance, and version. Returns a not_found message if the entry does not exist. Example: amfs_read("checkout-service", "retry-pattern")

Explore the knowledge graph around an entity. Shows what services, agents, patterns, and outcomes are connected to the given entity, with relationship types and confidence scores. Use depth > 1 for multi-hop traversal.

Check the current memory consolidation status. Returns metrics about automatic memory consolidation: how many entries have been auto-archived, how many proposals are pending review, and the overall health of the consolidation system.

Compute a structural diff for a memory entry between versions. Shows field-level changes (add/remove/replace) with JSON Pointer paths. If old_version is not specified, diffs between the two most recent versions.

Read a specific key from ANOTHER agent's memory. Use this when you want to explicitly learn from another agent's experience. The read is tracked for causal tracing.

Recall YOUR OWN memory for an EXACT key — needs the precise path + key. NOTE: despite the name, this is NOT free-text recall — it requires the exact entity_path AND key. If the user asked in plain language ("what food do I like?") or you're guessing the key, use `amfs_retrieve(query=...)` instead — it searches by meaning with no path/key needed. Only use amfs_recall to re-read a key you already know you wrote.

Get a compiled knowledge briefing — call this at the START of every session after setting identity. Returns pre-compiled digests from the Memory Cortex, ranked by relevance. This is your most important context-gathering step — it tells you what other agents know, recent risks, and confidence-ranked facts about the entity you're about to work on. Call this BEFORE reading code or making decisions. After briefing, use amfs_recall() for specific keys you remember, or amfs_search() for broader queries.

Browse persisted decision traces from past sessions. Each trace captures the full causal chain: which memories were read, what external context was gathered, what decisions were made, and the final outcome. Use this to learn from past decisions before making similar ones.

Search across all memory entries with structured filters or exact keywords. Use this before starting work to find context about the entity you're modifying, or to check if another agent already solved a similar problem. For plain natural-language recall ("what's my favorite ice cream?"), prefer `amfs_retrieve` — it ranks by meaning and needs no filters. Reach for this tool when you want to filter by agent/confidence/date/pattern or match an exact keyword. `query`, `entity_path`, and all filters are optional. When a Postgres adapter with tsvector support is configured, the query text is used for full-text search. Otherwise falls back to Python substring matching on keys/values.

Get the full version history of a memory entry over time. Returns all CoW versions of a key, showing how the value and confidence evolved. Useful for temporal reasoning — "how did this decision change?"

List memory consolidation proposals. Consolidation proposals are created by the Cortex when it detects opportunities to compress, merge, or archive memory entries. Tier B proposals require human/agent review before merging.

Record an action you took — the tool you called and what you passed it. Call this AS IT HAPPENS, right after taking a consequential action: deploying, rolling back, editing a file, refunding, sending, opening a PR, changing a setting. Not for reading or searching — record what you *did*, not what you looked at. Use amfs_record_context for what you learned. This is the counterpart to task_input on amfs_commit_outcome. Together they form a complete record of the decision: what you were asked, and what you did about it. AMFS cannot see this by itself — it observes only its own tools, so a call to your deploy or refund tool is invisible unless you record it.

Declare a capability this agent has. Capabilities help other agents discover who knows about what.

Record an outcome and auto-link it to everything read this session. ALWAYS call this at the end of meaningful work. Without it, the decision trace (which memories were read, what contexts were gathered, what was decided) is lost when the session ends. This snapshots all reads, writes, recorded contexts, and decisions from this session into a persisted DecisionTrace. It also back-propagates confidence changes: entries linked to successes stabilize, entries linked to failures get flagged for review. Back-propagation applies to memories READ this session, since those are the ones the outcome is evidence about. A session that only wrote therefore returns affected_entries: 0 and still saves a full trace — check entries_created, entries_updated and external_contexts for what it holds.

View recent events on this agent's timeline (git commit log). Every write, outcome, and cross-agent read is recorded as an event. Use this to see the history of what happened to your agent's memory.

Set a memory contract — enforce schema/confidence expectations on writes. Contracts define what quality and structure is expected for memory entries matching a given entity_path and key pattern.