# Faf Memory Mcp

> MCP server for .fafm — Permanent Memory Layer (PML). Wraps claude-fafm-sdk via fastmcp. IANA-registered cross-vendor persistent memory. 412× faster type-filter queries vs grep (see faf-memory-proof for falsifiable receipt).

- **Type:** MCP server
- **Install:** `agentstack add mcp-wolfe-jam-faf-memory-mcp`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [Wolfe-Jam](https://agentstack.voostack.com/s/wolfe-jam)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [Wolfe-Jam](https://github.com/Wolfe-Jam)
- **Source:** https://github.com/Wolfe-Jam/faf-memory-mcp

## Install

```sh
agentstack add mcp-wolfe-jam-faf-memory-mcp
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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`](https://pypi.org/project/claude-fafm-sdk/) via [`fastmcp`](https://pypi.org/project/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://github.com/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](https://github.com/Wolfe-Jam/faf-memory-proof)).

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

```bash
uvx faf-memory-mcp
```

## Use in a host

**Claude Code** — [`faf-memory`](https://github.com/Wolfe-Jam/faf-memory) plugin on `claude-plugins-community`:

```bash
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`](https://docs.astral.sh/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).

```json
{
  "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](https://github.com/Wolfe-Jam/faf/blob/main/MEMORY-FORMAT.md)
- Paper: [Zenodo DOI 10.5281/zenodo.20348942](https://doi.org/10.5281/zenodo.20348942)
- Reference impls: [`claude-fafm-sdk`](https://pypi.org/project/claude-fafm-sdk/) (Python) · [`grok-faf-voice`](https://pypi.org/project/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`](https://pypi.org/project/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`](https://pypi.org/project/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`](https://github.com/Wolfe-Jam/faf-memory) — the Claude Code plugin that installs this MCP
- [`Wolfe-Jam/faf-memory-proof`](https://github.com/Wolfe-Jam/faf-memory-proof) — the falsifiable receipt (412× methodology + scripts)
- [`claude-fafm-sdk`](https://pypi.org/project/claude-fafm-sdk/) — the open Python SDK this server wraps
- [`Wolfe-Jam/faf`](https://github.com/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](https://github.com/Wolfe-Jam)
- **Source:** [Wolfe-Jam/faf-memory-mcp](https://github.com/Wolfe-Jam/faf-memory-mcp)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-wolfe-jam-faf-memory-mcp
- Seller: https://agentstack.voostack.com/s/wolfe-jam
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.