faf-memory-mcp 0.1.0

MCP server for .fafm — the Permanent Memory Layer (PML). Wraps claude-fafm-sdk via fastmcp. IANA-registered, cross-vendor, offline-first.

faf-memory-mcp

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.

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.

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

Install

uvx faf-memory-mcp

Use in Claude Code (recommended)

Via the faf-memory plugin (coming to claude-plugins-community):

/plugin install faf-memory

Or wire .mcp.json directly:

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

Tools

Tool	What it does
etch(text, id?, type?, priority?, tags?)	Write a durable fact. 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?)	Persist the soul to a .fafm 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

License

MIT.