\n\n
![\"FastrMemory](\"https://raw.githubusercontent.com/atifjubaer/fastrmemory/main/assets/fastrmemory-mark.png\")
\n\n# FastrMemory\n\n### High-Performance Cognitive Agent Memory Engine\n**Zero Daemon โข Native Node 22+ `node:sqlite` โข Bi-Temporal Git Sync โข Triple-Stream RRF โข Official MCP v2**\n\n[](https://github.com/atifjubaer/fastrmemory/actions)\n[](https://www.npmjs.com/package/fastrmemory)\n[](LICENSE)\n[](https://nodejs.org)\n[](https://modelcontextprotocol.io)\n[](https://mcprush.com/to/fastrmemory-mcp?ref=badge)\n[](tests/)\n[](#-one-click-agent-mcp-configuration)\n[](#-architecture)\n\n> **Status (2026-11-01):** **`fastrmemory@0.9.2` is published and is `latest`.** Evidence: `npm view fastrmemory version` -> `0.9.2`; `npm view fastrmemory dist-tags --json` -> `{\"latest\":\"0.9.2\"}`; tag `v0.9.2` (`b2c6502`); published 2026-11-01 via GitHub Actions OIDC with npm provenance; the release workflow passed the full gate, clean tarball install, registry verification, and GitHub Release upload; the npm tarball is 358 files, 814,420 bytes packed, 3,273,691 bytes unpacked; GitHub Release asset SHA-256 `2a24f2aa99ce647390b021cb1be7d62fac50edacb2e826c13deba6dcdbe16732`; a clean `npm install fastrmemory@0.9.2` + `fastr --version` -> `0.9.2`; `npm audit signatures` reports 5 verified registry signatures and 4 verified attestations. The official MCP registry lists `io.github.atifjubaer/fastrmemory@0.9.2` as `active` and `isLatest`. Caveat: Node.js >=22.16.0; `0.9.1`, `0.9.0`, `0.8.2`, `0.8.1`, `0.8.0`, `0.7.2`, `0.7.1`, `0.7.0`, `0.6.0`, `0.5.0`, `0.4.0`, `0.3.1`, and `0.3.0` remain published historical. This documentation patch adds the memory landscape, per-client integration matrix, and 0.9.1 upgrade path; the runtime and schema are unchanged. The old scoped npm entries (`@atifjubaer/fastrmemory` and `fastrmemory@0.0.0-stage`) were removed on 2026-10-23; the GitHub `v0.2.1` tag and release remain as history. This README tracks current `main`. Current `main` is **`0.9.2`** and has **481 tests / 74 files**. Use the exact `0.9.2` version for reproducibility. PR #46 at `5da9b2e` passed all required checks (six matrix jobs plus Replayable Memory Diff and Pre-Merge Trap Guardian); the historical `0.9.1` release commit `5da9b2e`, `0.9.0` release commit `c204f50`, `0.8.2` release commit `8cc925b`, `0.8.1` release commit `4e7d9ac`, `0.8.0` release commit `44b2d9a`, `0.7.2` release commit `583223f`, `0.7.1` release commit `31d8e12`, `0.7.0` release commit `5512557`, `0.6.0` release commit `a57a656`, `0.5.0` release commit `54a79ab`, and `0.4.0` release commit `bb365c2` remain published historical. The exact release surface is in [CHANGELOG.md](CHANGELOG.md). The headline benchmark uses **240 deterministic synthetic cases with a 20% holdout**, not SWE-bench or LongMemEval. Public LongMemEval, LoCoMo, and self-repository retrieval-only results plus pinned external baselines are in [BENCHMARKS.md](BENCHMARKS.md); no QA-leaderboard parity is claimed. Performance, packaging, and retrieval claims are tracked in [CLAIMS.md](CLAIMS.md); every README section is mapped to claim IDs in the README claim trace at the end of that ledger. Methodology, caveats, and raw JSON are in [BENCHMARKS.md](BENCHMARKS.md).\n\n
\n Overview •\n Design Principles •\n Benchmarks •\n Web UI •\n Supported Agents •\n Quick Start •\n MCP Setup •\n MCP Tools •\n Architecture •\n Migration •\n Security •\n Scorecard\n
\n\n
\n\n| \n\n### Zero Daemon Overhead\nPure Node 22+ built-in `node:sqlite` in WAL mode. On the 240-case suite, engine-level recall is **0.95 ms p50 / 1.60 ms p95** with hash embeddings and **3.30 ms p50 / 5.11 ms p95** with MiniLM on the train split (CLI startup measured separately). The default CLI/MCP path has no background daemon and no open port; `daemon start` is optional. Native on Windows, macOS, and Linux (the current CI matrix uses Intel macOS; Apple Silicon is not covered); CI matrix status is reported in [Actions](https://github.com/atifjubaer/fastrmemory/actions).\n\n | \n\n\n### ๐ Bi-Temporal Git Sync\nNever deletes facts during consolidation (there is no destructive sleep step). Replaces half-life decay with `valid_from` / `valid_to` timestamps and auto-mirrors human-readable `.fastr/pages/*.md` files into Git.\n\n | \n\n\n### ๐ฏ Triple-Stream RRF ($k=20$)\nFuses FTS5 BM25 + optional local embeddings + file-graph links. Error traps receive a **conditional 2.0x boost** only for trap-intent or file-scoped queries, with per-ID outcome feedback (+0.2 / -0.5). Three consecutive bad outcomes move a memory to dormant; confidence tiers are `high`, `medium`, `low`, `dormant`, and `superseded`. Counting questions (\"how many projects have I led?\") additionally run an aggregate-coverage pass: a second lexical query over their content terms, fused with the original, returning up to 20 rows so the caller can count. `retrieval.temporalFilter` adds opt-in date windows (\"past two weeks\", \"this year\") parsed against the question date.\n\n | \n
\n
\n\n### โ๏ธ Architectural & Performance Comparison\n\n| Capability | Hippo Memory (`hippo-memory`) | Memoria (`matrixorigin/Memoria`) | AgentMemory (`@agentmemory/mcp`) | **FastrMemory (0.9.2+)** |\n| :--- | :--- | :--- | :--- | :--- |\n| **Runtime Architecture** | SQLite store | MatrixOne relational/vector DB container | Dual-layer engine + Redis/Docker | **Zero-Daemon โข Native `node:sqlite` in WAL mode** |\n| **Ingestion Speed** | 88.9 ms/doc | Container roundtrip | 1.74 ms/doc | **1.09 ms/doc (80x faster than Hippo)** |\n| **Recall Latency (p50)** | 12.8 ms (spikes to 386 ms p95) | 50โ100 ms | 1.52 ms | **0.95 ms p50 / 1.60 ms p95** |\n| **AST Symbol Anchoring** | โ None (file path only) | โ None | โ None | **โ
`declaration_id` (AST hash survives renames & file moves)** |\n| **Self-Verifying Traps** | โ None | โ None | โ None | **โ
Machine assertions (`text_present`, etc.) auto-retire fixed bugs** |\n| **Context Token Overhead** | โ ๏ธ High (dumps entire rule sets) | โ ๏ธ High (dumps knowledge graphs) | โ ๏ธ High (dumps session contexts) | **Ultra-low (โค150 tokens targeted per-turn injection)** |\n| **Passive Learning** | โ Manual commands only | โ Manual commands only | โ Manual commands only | **โ
Auto-distills traps from test failures & subsequent edits** |\n| **Cross-Machine Team Sync**| Manual markdown git commits | Cloud database cluster | Custom daemon | **โ
Bidirectional `fastr sync` on Git pull** |\n| **Editor Integration** | Basic CLI instructions | None | Basic plugin | **โ
Native VS Code & Cursor extension with Problems tab diagnostics** |\n| **MCP Protocol Support** | stdio | REST / MCP adapter | stdio | **Official MCP v2 (12-tool core & 45-tool full profiles)** |\n\n*Verified benchmark evidence from [`bench/results/vs-engines.json`](bench/results/vs-engines.json) and [`docs/PUBLIC_BENCHMARKS.md`](docs/PUBLIC_BENCHMARKS.md).*\n\n### ๐งญ Memory Landscape: Where Each Project Starts\n\nThe memory category is not one product. Each project below is the best starting point for a different job; FastrMemory's difference is listed against that job, not as a universal benchmark. Positioning is paraphrased from each project's public documentation (checked 2026-11-01). For engines measured head-to-head, see the evidence table above.\n\n| Project | Best starting point for | How it runs | FastrMemory difference |\n| :--- | :--- | :--- | :--- |\n| [AgentMemory](https://github.com/rohitg00/agentmemory) | Shared local memory for existing coding agents, automatic capture, scoped recall, and a live viewer | Local Node/iii server on four ports, native plugins, 54 MCP tools, 12 hooks | **Zero daemon and zero ports by default**: one SQLite file, 45 MCP tools, AST-anchored traps, and a code call graph |\n| [Mem0](https://github.com/mem0ai/mem0) | Memory APIs, hosted or self-hosted, with SDKs and agent plugins | Hosted API or self-hosted service with an external vector store | **No account, API key, or vector database**: local-first, Git-diffable, MCP-native |\n| [Supermemory](https://github.com/supermemoryai/supermemory) | Memory and document context through a hosted API or local server | Hosted API or local server | **Single-file database**; no server process to operate |\n| [Zep / Graphiti](https://github.com/getzep/graphiti) | Enterprise context and temporal knowledge graphs | Service plus a graph database | **Bi-temporal SQLite plus a Git Markdown mirror**; no graph database service |\n| [Letta](https://github.com/letta-ai/letta) | Building stateful agents with their own managed memory | Agent server/runtime with managed memory | **A memory layer for any agent**, not a new agent runtime |\n| [Cognee](https://github.com/topoteretes/cognee) | Turning documents, code, and conversations into searchable knowledge | Python pipelines with graph and vector stores | **Zero Python**: in-process TypeScript with declaration-anchored code memory |\n| [claude-mem](https://github.com/thedotmack/claude-mem) | Capturing and summarizing coding sessions across supported agents | Hook-based session capture and summaries | **Typed error traps with assertions and a code graph** on top of session capture |\n| **FastrMemory** | **Local-first cognitive memory for coding agents: zero-daemon MCP, self-verifying traps, graph-grounded recall, and Git-diffable bi-temporal rules** | **Node 22.16+, built-in `node:sqlite` in WAL mode, 3 runtime dependencies** | โ |\n\n---\n\n## ๐งญ Design Principles\n\n| Principle | Implementation |\n| :--- | :--- |\n| **Lossless by default** | Raw events, bi-temporal `valid_from` / `valid_to`, and supersession chains are retained. Nothing is destroyed by consolidation. |\n| **Zero daemon by default** | One Node 22+ process uses built-in `node:sqlite` in WAL mode. The default CLI/MCP path opens no ports or background services; `daemon start` is optional. |\n| **Replayable** | Git-diffable Markdown mirrors plus snapshots and rollback keep history inspectable. |\n| **Measured, not asserted** | Public claims are tied to committed benchmark JSON with a 20% holdout; simulated baselines are labeled as simulations. |\n\n---\n\n---\n\n## ๐ค Works With MCP- and HTTP-Compatible Agents\n\nFastrMemory exposes one stdio MCP server and optional local HTTP services (dashboard and daemon). **Native installers wire Claude Code (MCP config plus lifecycle hooks), Cursor (MCP config plus rules), and, since 0.3.0, Gemini CLI, GitHub Copilot CLI, and OpenCode V2** (`fastrmemory hook install`); `fastrmemory setup` also writes MCP configs for Antigravity, Claude Desktop, and Windsurf. Since `0.9.1`, both commands also write the mandatory rule file each client reads, so the agent calls the memory tools without being asked. Every other client connects through its own MCP configuration or the REST API. Integration depth varies by client - only the native installers are covered by tests in this repository.\n\nClients commonly used with FastrMemory include Codex CLI, Gemini CLI, OpenCode, GitHub Copilot CLI, Antigravity, Claude Desktop, Cline, Continue, Roo Code, Goose, Zed, Warp, and Aider. Listing a client does **not** imply a tested native integration.\n\n### ๐งฉ Integration Depth by Client\n\nOne MCP server reaches every MCP client. The layers above MCP depend on what the client exposes:\n\n| Layer | What the agent gets | Wired automatically | Other clients |\n| :--- | :--- | :--- | :--- |\n| **MCP tools** (12-tool core / 45-tool full) | Recall, trap recall and logging, handoff, graph queries, status | Antigravity, Claude Desktop, Claude Code, Cursor, and Windsurf via `fastr setup`; Claude Code, Cursor, OpenCode, Gemini CLI, and Copilot CLI via `fastr hook install` | Any MCP client via `fastr mcp init --client ![\"FastrMemory](\"https://mcprush.com/badge/fastrmemory-mcp/card.svg\"){kind=icon}
\n