Faf Memory Mcp

faf-memory-mcp

v0.1.1 — etch writes the file so memory survives the process. Plugin install matches live faf-memory@claude-community.

MCP server for .fafm — the Permanent Memory Layer (PML) for Claude Code, Cursor, Grok, and any MCP host.

Cross-vendor persistent memory in a file you can read. Offline-first. Your soul, your bytes.

What's New in 0.1.1

etch writes the file so memory survives the process. Plugin install matches live faf-memory@claude-community.

• etch persists to $FAF_SOUL_PATH immediately (default ./soul.fafm).
• Claude Code install: claude plugin install faf-memory@claude-community.
• Full arc: [CHANGELOG](CHANGELOG.md).

Wraps claude-fafm-sdk via fastmcp. Receipt: 400+× faster type-filter queries vs grep on a real 492-file AI memory corpus — falsifiable methodology at Wolfe-Jam/faf-memory-proof.

[](https://pypi.org/project/faf-memory-mcp/) [](https://github.com/Wolfe-Jam/faf-memory-mcp/actions/workflows/ci.yml) [](https://www.iana.org/assignments/media-types/application/vnd.fafm+yaml) [](https://doi.org/10.5281/zenodo.20348942) [](https://doi.org/10.5281/zenodo.21951641) [](LICENSE)

Why

Every AI session, your agent starts blank — no memory of what you decided yesterday, what worked, what was tried. The fix isn't another hosted memory service; it's a file the AI reads at session start and writes back to as it learns. That file is .fafm — IANA-registered, cross-vendor, and 996 KB / 49 ms cold-load for a 492-fact corpus (full numbers: the receipt).

This server is that file, over MCP. FAFA’s etch_memory / recall_memory is the hosted namepoint path on mcpaas. Complementary, not a second product.

Install

uvx faf-memory-mcp

Use in a host

Claude Code — faf-memory plugin on claude-plugins-community:

claude plugin marketplace add anthropics/claude-plugins-community
claude plugin install faf-memory@claude-community

Or in-session: /plugin install faf-memory@claude-community

Requires uv — the plugin launches this server with uvx.

Cursor · Grok · any host — same JSON. Cursor: ~/.cursor/mcp.json. Grok: .mcp.json (Grok also reads Cursor’s file).

{
  "mcpServers": {
    "faf-memory": {
      "command": "uvx",
      "args": ["faf-memory-mcp"]
    }
  }
}

Tools

| Tool | What it does | |---|---| | etch(text, id?, type?, priority?, tags?) | Write a durable fact and persist to $FAF_SOUL_PATH. O(1) dedup by id. | | recall(query?, type?, tags?, min_priority?, limit?) | Filter (substring + type + tags + priority floor) → rank by priority then recency. | | list_facts() | List ALL facts — no filter, no rank. | | save_soul(path?) | Write the soul to another path (etch already saves the default file). | | load_soul(path?) | Load a .fafm from disk, replacing the in-memory soul. |

Configuration

| Env var | Default | What | |---|---|---| | FAF_SOUL_NAMEPOINT | @local | Initial soul identifier | | FAF_SOUL_PROFILE | knowledge | .fafm profile (knowledge or voice) | | FAF_SOUL_PATH | soul.fafm | Default save/load path |

Format

.fafm is IANA-registered as application/vnd.fafm+yaml (registered 2026-05-13). Sibling of .faf (application/vnd.faf+yaml, 2025-10-30).

• Spec: Wolfe-Jam/faf · MEMORY-FORMAT.md
• Paper: Zenodo DOI 10.5281/zenodo.20348942
• Reference impls: claude-fafm-sdk (Python) · grok-faf-voice (voice profile, Python)
• Cross-vendor proof: a .fafm written by claude-fafm-sdk reads cleanly via grok-faf-voice, both directions tested.

How to know it's working

• Your agent doesn't ask "what is this project?" twice in the same week.
• recall("X") surfaces what you etched last session, not just this one.
• The .fafm file grows readably — it's plain YAML, diff it like code.
• Open the same .fafm in grok-faf-voice — same facts. Cross-vendor proven.

Tradeoff note

Biases toward deterministic recall (substring + type + tags + priority + recency) over semantic recall. For semantic/ranked recall + LLM smart-merge, see hosted namepoints in claude-fafm-sdk. Offline-first ≠ offline-only.

The FAF Memory cluster

• This repo — faf-memory-mcp — the MCP server (wraps the SDK)
• Wolfe-Jam/faf-memory — the Claude Code plugin that installs this MCP
• Wolfe-Jam/faf-memory-proof — the falsifiable receipt (412× methodology + scripts)
• claude-fafm-sdk — the open Python SDK this server wraps
• Wolfe-Jam/faf — the format spec + IANA registration

Citation

> Wolfe, J. (2026). Permanent Memory and Instant Recall: The .fafm Standard for Multi-Profile AI Agent Memory. Zenodo. https://doi.org/10.5281/zenodo.20348942

> Wolfe, J. (2026). Why Agents Need a Passport: .fafa — Portable Identity for the Agentic Era. Zenodo. https://doi.org/10.5281/zenodo.21951641

License

MIT.

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Wolfe-Jam
• Source: Wolfe-Jam/faf-memory-mcp
• License: MIT

Install and usage instructions live in the source repository linked above.