amfs-mcp-server

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.

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.

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 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

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.

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.

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".

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

Read a memory entry by entity path and key. Returns the full entry as JSON including value, confidence, provenance, and version. Returns a message if the entry does not exist. Example: amfs_read("checkout-service", "retry-pattern")

Find the most relevant memories for a natural language query. Blends semantic similarity, recency, and confidence into a single ranked list. Use this when you need to find memories by meaning, not exact key/value match. Use amfs_search for structured filtering.

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.

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.

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.

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.

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.

Search across all memory entries with filters. 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. 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.

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

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.

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?"

Recall YOUR OWN memory for a key — what do I know about this? Unlike amfs_read (which returns the latest version by any agent), amfs_recall returns only entries written by you. Use this to check your own knowledge before acting.

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"] }

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.

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

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

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.

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.

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.

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.

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

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.

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.

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.

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