Skip to main content
Glama
README.md
<div align="center">

<img src="https://raw.githubusercontent.com/atifjubaer/fastrmemory/main/assets/fastrmemory-mark.png" width="128" height="128" alt="FastrMemory Logo">

# FastrMemory

### High-Performance Cognitive Agent Memory Engine
**Zero Daemon โ€ข Native Node 22+ `node:sqlite` โ€ข Bi-Temporal Git Sync โ€ข Triple-Stream RRF โ€ข Official MCP v2**

[![CI](https://github.com/atifjubaer/fastrmemory/actions/workflows/ci.yml/badge.svg)](https://github.com/atifjubaer/fastrmemory/actions)
[![npm](https://img.shields.io/npm/v/fastrmemory?style=flat-square&logo=npm&label=npm)](https://www.npmjs.com/package/fastrmemory)
[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg?style=flat-square)](LICENSE)
[![Node](https://img.shields.io/badge/Node-%3E%3D22.16.0-339933?style=flat-square&logo=node.js&logoColor=white)](https://nodejs.org)
[![Protocol](https://img.shields.io/badge/Protocol-MCP%20v2-7C3AED?style=flat-square)](https://modelcontextprotocol.io)
[![MCP Directory](https://mcprush.com/badge/fastrmemory-mcp/compact.svg)](https://mcprush.com/to/fastrmemory-mcp?ref=badge)
[![Tests](https://img.shields.io/badge/Tests-481%20Passed-brightgreen?style=flat-square)](tests/)
[![MCP Setup](https://img.shields.io/badge/MCP%20Setup-fastr%20mcp%20init-7C3AED?style=flat-square)](#-one-click-agent-mcp-configuration)
[![Architecture](https://img.shields.io/badge/Architecture-Zero--Daemon%20WAL-orange?style=flat-square)](#-architecture)

> **Status (2026-11-01):** **`fastrmemory@0.9.3` is published and is `latest`.** Evidence: `npm view fastrmemory version` -> `0.9.3`; `npm view fastrmemory dist-tags --json` -> `{"latest":"0.9.3"}`; tag `v0.9.3` (`15a772f`); 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, 819,117 bytes packed, 3,289,741 bytes unpacked; GitHub Release asset SHA-256 `eebda8ab3f90b73ee5f4bd4a64a6ff511f9c93468576c167de3a1c1e2efbcf22`; a clean `npm install fastrmemory@0.9.3` + `fastr --version` -> `0.9.3`; `npm audit signatures` reports 5 verified registry signatures and 4 verified attestations. The official MCP registry lists `io.github.atifjubaer/fastrmemory@0.9.3` as `active` and `isLatest`. Caveat: Node.js >=22.16.0; `0.9.2`, `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 release makes code-graph indexing automatic: setup and hook install index once, SessionStart repairs an empty index, and prompt/session-end hooks refresh recent edits; the schema is 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.3`** and has **481 tests / 74 files**. Use the exact `0.9.3` 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.2` release commit `b2c6502`, `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).

<p align="center">
  <a href="#-overview">Overview</a> &bull;
  <a href="#-design-principles">Design Principles</a> &bull;
  <a href="#-retrieval-benchmark-240-synthetic-cases">Benchmarks</a> &bull;
  <a href="#-local-web-dashboard">Web UI</a> &bull;
  <a href="#-works-with-mcp--and-http-compatible-agents">Supported Agents</a> &bull;
  <a href="#-quick-start">Quick Start</a> &bull;
  <a href="#-one-click-agent-mcp-configuration">MCP Setup</a> &bull;
  <a href="#-mcp-server-tools--resources">MCP Tools</a> &bull;
  <a href="#-architecture">Architecture</a> &bull;
  <a href="MIGRATION.md">Migration</a> &bull;
  <a href="SECURITY.md">Security</a> &bull;
  <a href="SCORECARD.md">Scorecard</a>
</p>

</div>

---

## Launch Status at a Glance

| Claim | Current result | Evidence |
|---|---|---|
| Install path | Published `fastrmemory@0.9.3` | `npm view fastrmemory version` -> `0.9.3`; `npm view fastrmemory dist-tags --json` -> `{"latest":"0.9.3"}`; `npm install fastrmemory@0.9.3`; `fastr --version` -> `0.9.3`; GitHub Release tarball SHA-256 `eebda8ab...`; old scoped npm entries removed |
| MCP registry | `io.github.atifjubaer/fastrmemory@0.9.3`, status `active`, `isLatest` | `curl --get --data-urlencode "search=io.github.atifjubaer/fastrmemory" https://registry.modelcontextprotocol.io/v0.1/servers`; `gh run view 40262643667` |
| Synthetic retrieval (optional MiniLM) | Holdout `95.8%` Hit@1, `100%` Hit@5, MRR `0.969` | `npx tsx scripts/eval-bench.ts --split all --embeddings minilm --out bench/results/minilm.json` |
| Test suite | `481` tests across `74` files on current `main`; published `0.9.3` is `481` / `74`; published `0.9.2` is `476` / `74`; published `0.9.1` is `476` / `74`; published `0.9.0` is `476` / `74`; published `0.8.2` is `461` / `69`; published `0.8.1` is `461` / `69`; published `0.8.0` is `461` / `69`; published `0.7.2` is `456` / `67`; published `0.7.1` is `456` / `67`; published `0.7.0` is `455` / `67`; published `0.6.0` is `388` / `61`; `0.5.0` is `297` / `53`; historical `0.4.0` is `293` / `53`; `0.3.1` is `282` / `52`; v0.2.1 is `235` / `43` | `npm test`; `npm run check:ci` |
| MCP setup | `fastr mcp init` merges portable registry configs or active-CLI local configs for 9 JSON clients and prints a Codex TOML snippet; `--source local` ships in published `0.9.3`, `0.9.2`, `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`, and `0.5.0` | `npm test -- tests/mcp-init.test.ts` -> `15 passed`; `fastr mcp init --client claude --source local --dry-run --json` -> `node .../dist/bin/fastr.js mcp --project ...` |
| Cross-engine (MCP stdio) | `80/120` overall Hit@1 (`66.7%`, 95% CI `57.8`-`74.5`): exact `40/40`, multi `40/40`, paraphrase `0/40`; `1.094` ms/doc ingest, `1.86` ms recall p50 | `npm run bench:vs`; `bench/results/vs-engines.json` |
| Crash safety | 10/10 runs, 0 lost, 0 duplicate ids/titles | `npm run test:crash`; `bench/results/crash-test.json` |
| Public retrieval (0.3.0) | LongMemEval `+10.4pp` / `+11.0pp` Hit@5; LoCoMo `+4.4pp` / `+2.3pp` (target missed) | [docs/EXTERNAL_BASELINE.md](docs/EXTERNAL_BASELINE.md) |
| Release score | Provisional `9.4 / 10`; `9.2` target met; Retrieval remains Partial | [SCORECARD.md](SCORECARD.md) |

The synthetic table is not SWE-bench or LongMemEval. Public numbers are retrieval-only and are not QA-leaderboard results. The `95.8%` row uses optional MiniLM; the default offline hash path scores `77.1%` Hit@1 / `93.8%` Hit@5 on the same holdout. Full provenance is in [CLAIMS.md](CLAIMS.md).

---

## ๐Ÿ’ก Overview

AI coding agents (Claude Code, Cursor, Windsurf, Codex, Antigravity) degrade on long-running codebases when project memory is lossy or operationally heavy. Common designs make one of three trade-offs:
- **Decay and merge** old episodes to keep the store small, which can lose exact file paths, stack traces, and edge cases.
- **Run a daemon or external database**, which adds ports, containers, and setup failure modes.
- **Dump a static context file**, which grows without bound and is not queryable.

**FastrMemory** keeps a verbatim event log, bi-temporal memory history, and a replayable Git mirror in a **single in-process TypeScript engine** (3 runtime dependencies; local embeddings and the daemon are optional):

<table>
<tr>
<td width="33%" align="center">

### Zero Daemon Overhead
Pure 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).

</td>
<td width="33%" align="center">

### ๐Ÿ”€ Bi-Temporal Git Sync
Never 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.

</td>
<td width="33%" align="center">

### ๐ŸŽฏ Triple-Stream RRF ($k=20$)
Fuses 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.

</td>
</tr>
</table>

### โš”๏ธ Architectural & Performance Comparison

| Capability | Hippo Memory (`hippo-memory`) | Memoria (`matrixorigin/Memoria`) | AgentMemory (`@agentmemory/mcp`) | **FastrMemory (0.9.3+)** |
| :--- | :--- | :--- | :--- | :--- |
| **Runtime Architecture** | SQLite store | MatrixOne relational/vector DB container | Dual-layer engine + Redis/Docker | **Zero-Daemon โ€ข Native `node:sqlite` in WAL mode** |
| **Ingestion Speed** | 88.9 ms/doc | Container roundtrip | 1.74 ms/doc | **1.09 ms/doc (80x faster than Hippo)** |
| **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** |
| **AST Symbol Anchoring** | โŒ None (file path only) | โŒ None | โŒ None | **โœ… `declaration_id` (AST hash survives renames & file moves)** |
| **Self-Verifying Traps** | โŒ None | โŒ None | โŒ None | **โœ… Machine assertions (`text_present`, etc.) auto-retire fixed bugs** |
| **Context Token Overhead** | โš ๏ธ High (dumps entire rule sets) | โš ๏ธ High (dumps knowledge graphs) | โš ๏ธ High (dumps session contexts) | **Ultra-low (โ‰ค150 tokens targeted per-turn injection)** |
| **Passive Learning** | โŒ Manual commands only | โŒ Manual commands only | โŒ Manual commands only | **โœ… Auto-distills traps from test failures & subsequent edits** |
| **Cross-Machine Team Sync**| Manual markdown git commits | Cloud database cluster | Custom daemon | **โœ… Bidirectional `fastr sync` on Git pull** |
| **Editor Integration** | Basic CLI instructions | None | Basic plugin | **โœ… Native VS Code & Cursor extension with Problems tab diagnostics** |
| **MCP Protocol Support** | stdio | REST / MCP adapter | stdio | **Official MCP v2 (12-tool core & 45-tool full profiles)** |

*Verified benchmark evidence from [`bench/results/vs-engines.json`](bench/results/vs-engines.json) and [`docs/PUBLIC_BENCHMARKS.md`](docs/PUBLIC_BENCHMARKS.md).*

### ๐Ÿงญ Memory Landscape: Where Each Project Starts

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

| Project | Best starting point for | How it runs | FastrMemory difference |
| :--- | :--- | :--- | :--- |
| [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 |
| [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 |
| [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 |
| [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 |
| [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 |
| [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 |
| [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 |
| **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** | โ€” |

---

## ๐Ÿงญ Design Principles

| Principle | Implementation |
| :--- | :--- |
| **Lossless by default** | Raw events, bi-temporal `valid_from` / `valid_to`, and supersession chains are retained. Nothing is destroyed by consolidation. |
| **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. |
| **Replayable** | Git-diffable Markdown mirrors plus snapshots and rollback keep history inspectable. |
| **Measured, not asserted** | Public claims are tied to committed benchmark JSON with a 20% holdout; simulated baselines are labeled as simulations. |

---

---

## ๐Ÿค– Works With MCP- and HTTP-Compatible Agents

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

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

### ๐Ÿงฉ Integration Depth by Client

One MCP server reaches every MCP client. The layers above MCP depend on what the client exposes:

| Layer | What the agent gets | Wired automatically | Other clients |
| :--- | :--- | :--- | :--- |
| **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 <id>` or a manual stdio entry |
| **Mandatory rules** | The instruction that makes the agent recall before editing and log a trap after a failure | Claude Code (`.claude/rules/fastrmemory.md`), Cursor (`.cursor/rules/fastrmemory.mdc`, `alwaysApply: true`), GitHub Copilot, Windsurf, Gemini CLI, and `AGENTS.md` for Codex, OpenCode, Devin, and Aider | Agents that read `AGENTS.md` |
| **Lifecycle hooks** | SessionStart context, the per-prompt next step (Claude Code), PreToolUse trap warnings, pre-compaction snapshots, SessionEnd distillation | Claude Code, OpenCode, Gemini CLI, and Copilot CLI (`fastr hook install`) | Clients without a hook API rely on MCP plus rules |
| **`/fastr` command** | One slash command for recall, trap logging, and handoff | Claude Code, Cursor, Codex, OpenCode, Gemini CLI, Copilot, and Windsurf (`fastr skill install`) | โ€” |
| **VS Code extension** | Sidebar, commands, and Problems-tab diagnostics | VS Code and Cursor (`npm run package:extension`) | Marketplace / Open VSX workflow |

<p align="center">
  <a href="https://mcprush.com/to/fastrmemory-mcp?ref=badge">
    <img src="https://mcprush.com/badge/fastrmemory-mcp/card.svg" alt="FastrMemory MCP server" width="380" height="200" />
  </a>
</p>

---

## ๐Ÿš€ Quick Start

### Run Without a Global Install

The canonical package target is unscoped `fastrmemory`. The old scoped npm entries were removed on 2026-10-23.

```bash
# Canonical one-shot (always uses the latest release):
npx -y fastrmemory setup

# Or launch the local Web UI:
npx -y fastrmemory ui
```

For a reproducible install pinned to a specific release: `npx -y fastrmemory@0.9.3 setup`. The default `latest` channel automatically tracks new releases, while `--channel pinned` records the exact version.

The GitHub source path remains available for development only: `npx github:atifjubaer/fastrmemory setup`. For a reproducible source install, pin the tag: `npx github:atifjubaer/fastrmemory#v0.9.3 setup`. Do not use either GitHub form in generated MCP or hook configs; those must use the npm package.

---

### Install from npm

```bash
# Canonical install (always latest):
npm install -g fastrmemory
fastr --version

# Or run one-shot:
npx -y fastrmemory --version
```

To pin an exact release instead: `npm install -g fastrmemory@0.9.3`.

The official MCP registry lists the server as `io.github.atifjubaer/fastrmemory` (`0.9.3`, status `active`), so registry-aware clients can find it by name; the entry carries the same `npx -y fastrmemory@0.9.3 mcp` package and stdio transport. `0.9.3` is built from tag `v0.9.3` by `.github/workflows/release.yml`, which runs the full gate, publishes with npm provenance, and attaches the same tarball to the GitHub Release. Verify the registry result with `npm view fastrmemory@0.9.3 version` and `npm view fastrmemory dist-tags --json`; a first E404 for a few minutes is registry propagation, not a failed publish. The old scoped npm entries remain removed. Do not republish `0.3.0`. `0.5.0`, `0.4.0`, and `0.3.1` remain published historical.

### Update an Existing Install

Stop every agent, hook, `fastr ui`, and `fastr daemon` before changing versions. Run this from the project root:

```bash
# 1. Back up memory before changing versions
fastr backup fastr-backup.jsonl
fastr backup --verify fastr-backup.jsonl

# 2. Update the global CLI
npm install -g fastrmemory@latest
fastr --version

# 3. Refresh project integration
fastr setup                                   # MCP configs, mandatory rules, and skills
fastr hook install --client all               # lifecycle hooks plus MCP for hook clients
fastr skill install --client all              # optional /fastr command for 7 clients

# 4. Verify
fastr status
fastr hygiene
```

**Upgrading from `0.8.x` or `0.9.0` requires step 3.** The mandatory rule files added in `0.9.1` are written by `fastr setup` and `fastr hook install`; upgrading the CLI or the MCP entry alone does not create them. After step 3, restart the client so it reloads `.claude/rules/fastrmemory.md`, `.cursor/rules/fastrmemory.mdc`, `.github/copilot-instructions.md`, `.windsurf/rules/fastrmemory.md`, `GEMINI.md`, and `AGENTS.md`.

**Automatic code-graph indexing (current `main`).** `fastr setup` and `fastr hook install` index the project once, SessionStart repairs an empty index, and the prompt and session-end hooks re-index the two most recent edits. This keeps 1-hop trap warnings and `fastr_god_nodes` populated without a manual step. `fastr index` remains available for a full rebuild; add `--no-index` to `fastr hook install` or set `FASTR_AUTO_INDEX=0` to disable it. `0.9.3` includes this; `0.9.2` and earlier still need a manual `fastr index`.

`0.9.x` has additive-only schema migrations (`symbols`, `code_edges`, `file_edits`, `memories.assertion`, and queues). If you use `--channel pinned`, rerun `fastr mcp init` after each update; with the default `latest` channel, restart the client to pick up the new release. If you use `--source local` (or ran `fastr setup` from a global install), the config points at the installed CLI, so updating the global package updates the server without rewriting the config. npx-generated configs pin the version that created them, so re-run `npx -y fastrmemory@latest setup` to move them forward. `fastr setup` refreshes copied skills, overwrites same-named skill files, removes retired skills, and leaves user-owned directories. `fastr hook install` does not copy skills. See [MIGRATION.md](MIGRATION.md) for rollback.

### One-Command MCP Setup

`fastr mcp init` is the shadcn-style setup path. It is config-only: it merges the `fastrmemory` MCP entry into an existing client config, preserves unrelated keys, writes a one-time `.fastr.bak` backup, and is idempotent. It does not install lifecycle hooks, skills, or the OpenCode plugin; use `fastr hook install` for hooks and the OpenCode plugin, and `fastr setup` for skills.

```bash
# Claude Code (project-scoped .mcp.json)
npx -y fastrmemory@latest mcp init --client claude

# Cursor
npx -y fastrmemory@latest mcp init --client cursor

# VS Code (.vscode/mcp.json)
npx -y fastrmemory@latest mcp init --client vscode

# OpenCode (opencode.json)
npx -y fastrmemory@latest mcp init --client opencode

# Gemini CLI and GitHub Copilot CLI
npx -y fastrmemory@latest mcp init --client gemini,copilot

# Every project-scoped client at once
npx -y fastrmemory@latest mcp init --client all --scope project
```

The same command through the other package runners:

```bash
pnpm dlx fastrmemory@latest mcp init --client claude
yarn dlx fastrmemory@latest mcp init --client claude
bunx fastrmemory@latest mcp init --client claude
```

The default `--channel latest` writes `fastrmemory@latest`, so a client restart picks up the newest npm release. Use `--channel pinned` for a reproducible config containing the exact version that ran the command; on current `main` that writes `fastrmemory@0.9.3`. `--runner pnpm|yarn|bunx` changes the generated runner, `--profile full` selects the 45-tool surface (the default is the 12-tool core profile), `--dry-run` prints targets without writing, and `--scope user` writes user-level configs with an explicit `--project /absolute/path` so the server always opens the intended database. Codex prints a `[mcp_servers.fastrmemory]` TOML block for `~/.codex/config.toml` instead of rewriting a user-owned TOML file.

For a globally installed CLI, use `--source local` to write the active CLI path instead of an npx command. It always appends an absolute `--project`, so the config is machine-specific but starts without an npx cold start:

```bash
fastr mcp init --client all --scope user --source local --profile core
```

Updating the global package updates the server; rerun the command only if the CLI path changes. Use the default `--source registry` for portable project configs that are committed and shared across machines.

> `--source local` ships in published `0.5.0` and later; on older releases, use `fastr setup` for an installed-CLI config.

> `mcp init` ships in `0.4.0` and later; `npx fastrmemory@latest mcp init ...` now resolves to published `0.9.3`. If you need an earlier release, use `fastr setup` or pin the exact version.

### Install from GitHub

For a one-shot source run, pin the release tag:

```bash
npx --yes github:atifjubaer/fastrmemory#v0.9.3 --version
npx --yes github:atifjubaer/fastrmemory#v0.9.3 setup
```

For a global CLI without npm's Git resolver, download the release tarball:

```bash
curl -L -o fastrmemory-0.9.3.tgz \
  https://github.com/atifjubaer/fastrmemory/releases/download/v0.9.3/fastrmemory-0.9.3.tgz
npm install -g ./fastrmemory-0.9.3.tgz
fastr --version
```

On Windows, download the same URL with `Invoke-WebRequest` or a browser, then run `npm install -g .\fastrmemory-0.9.3.tgz`. For a local project install, use `npm install --no-save ./fastrmemory-0.9.3.tgz` instead of the global flag.

> Git installs build from source and are slower than the npm tarball; for a global CLI, prefer the npm package or the release tarball above. `npm install -g git+https://...` is not recommended with npm 11 because the `prepare` build does not receive dev dependencies. Both `fastrmemory` and `fastr` (short alias) are executable after installation. The canonical package is unscoped `fastrmemory@0.9.3`; the old scoped npm entries are gone. Use npm for generated MCP and hook configs so installs stay reproducible.

### 2. Verify Database Health

```bash
fastrmemory status
```

Output:
```text
=== FastrMemory Health (my-project) ===
- Project ID:          proj_1cce2a654e3a
- Active Memories:     2
- Staging Memories:    0
- Superseded History:  0
- Ingested Events:     0
- Pending Spool:       Clear (0)
- Database File:       .fastr/fastr.db
```

### 3. Record & Recall a Memory

```bash
# Record an error trap linked to an exact file:
fastrmemory remember "Never Use Date.now() Milliseconds for JWT Expiration" \
  -c "JWT exp claims expect integer seconds. Always use Math.floor(Date.now() / 1000)." \
  -m auth -k error_trap -f "src/auth/jwt.ts" --verified

# Recall with conditional 2.0x trap boost & file-graph matching:
fastrmemory recall "JWT expiration" -f "src/auth/jwt.ts"
```

Output:
```text
=== Recalled Memories (1 results, ~46 tokens) ===

[mem_009e4a7d] [TRAP] [verified] Never Use Date.now() Milliseconds for JWT Expiration (Score: 0.08)
JWT exp claims expect integer seconds. Always use Math.floor(Date.now() / 1000).
```

Open contradictions are marked on both sides of the recall result instead of being silently mixed into context (**0.3.0**):

```bash
# Inspect unresolved contradictions:
fastrmemory conflict list

# Keep the rule that matches the project and supersede the loser:
fastrmemory conflict resolve 1 --keep mem_009e4a7d --forget --reason "Seconds are the project standard"
```

#### Import Existing Local Rules (**0.3.0**)

Bring `AGENTS.md`, `CLAUDE.md`, or `.cursor/rules/*.mdc` content into memory without hand-copying every section. Level 2+ headings become memories; bullet lists and paragraphs are fallbacks. Re-importing the same file skips exact duplicates.

```bash
# Preview the parsed sections without writing:
fastrmemory import AGENTS.md --from agents-md --module rules --dry-run

# Import as staging memories for review, or verify them immediately:
fastrmemory import AGENTS.md --from agents-md --module rules
fastrmemory import AGENTS.md --from agents-md --module rules --verified

# JSONL snapshots use the same entry point:
fastrmemory import snapshot.jsonl --from jsonl
```

### 4. Cognitive Git Blame & Memory-Aware Commit

```bash
# Cognitive Git Blame linking lines directly to commit, author, and governing error traps (conditional 2.0x boost):
fastrmemory blame src/auth/jwt.ts:42

# Pre-commit error trap validation & conventional commit synthesis:
fastrmemory commit
```

### 5. Git Snapshots, Branches, Rollback & Background Daemon (branches are **0.3.0**)

```bash
# Point-in-time memory snapshot (Git for Agent Memory):
fastrmemory snapshot create "pre-refactor-checkpoint"
fastrmemory snapshot list
fastrmemory snapshot rollback "pre-refactor-checkpoint"

# Portable backup with a sidecar provenance manifest:
fastrmemory backup backups/pre-upgrade.jsonl
fastrmemory backup --verify backups/pre-upgrade.jsonl
fastrmemory backup --restore backups/pre-upgrade.jsonl --dry-run
fastrmemory backup --restore backups/pre-upgrade.jsonl

# Bidirectional Team Memory Sync (Git-backed .fastr/pages/*.md):
fastrmemory sync

# Passive Cognitive Distillation (harvest traps from recent session errors):
fastrmemory distill

# Check self-verifying memory assertions and retire fixed traps:
fastrmemory trap verify
fastrmemory trap verify --apply

# Immutable memory branch and one-way merge with a conflict report:
fastrmemory branch create feature/auth
fastrmemory branch list
fastrmemory merge feature/auth
fastrmemory merge feature/auth --force --strategy branch

# Hybrid Background Daemon (Optional HTTP/SSE service for cross-process tools):
fastrmemory daemon start
fastrmemory daemon status
fastrmemory daemon stop

# Auto-wire MCP + lifecycle hooks for Claude Code, Cursor, Gemini CLI, Copilot CLI, and OpenCode:
fastrmemory hook install

# Auto-wire MCP + AGENTS.md + Planetary Skills; setup also wires Antigravity, Claude Desktop, and Windsurf:
fastrmemory setup

# Mine past Git bug fixes directly into staging error traps:
fastrmemory learn -n 30 --days 90
```

Branches are immutable snapshot pointers. `merge` is one-way into the current active set: branch-only memories are added, target-only memories are preserved, and same-identity changes are reported as conflicts. Conflicts block writes by default; `--force` applies non-conflicting additions, and `--force --strategy branch` supersedes the target while keeping old rows in history. Branch checkout or a mutable branch working tree is not implemented.

`backup` writes the portable JSONL snapshot plus `<file>.manifest.json` with the file SHA-256, content hash, record counts, tool version, environment, and source integrity. `--restore` verifies both hashes before importing; `--dry-run` reports counts without writing. The backup scope is memories, raw events, file links, and conflicts, not a physical SQLite/WAL copy. See [MIGRATION.md](MIGRATION.md) for the full backup and rollback path.

### 6. Token Compression, Database Doctor & Vision Search

```bash
# Compress markdown docs & LLM prompt context to reduce token usage:
fastrmemory compress docs/architecture.md --dry-run

# Run deep health check across SQLite, FTS5 indices, file links, and task DAGs:
fastrmemory diagnose

# Auto-repair FTS5 indices, orphaned file links, and WAL fragmentation:
fastrmemory heal

# Report orphaned records, duplicate active memories, and stale rows:
fastrmemory hygiene
fastrmemory hygiene --stale-days 30 --json --fail-on-issues

# Tag a UI screenshot or architecture diagram with OCR & 384-dim vector indexing:
fastrmemory vision tag screenshots/modal-error.png --desc "Modal error 401 alert" --ocr "HTTP 401"

# Semantic search across tagged screenshots and visual diagrams:
fastrmemory vision search "modal error 401"

# Pre-merge CI/CD gate checking PR diffs against active error traps:
fastrmemory guard --strict

# Optional 30 MB static semantic model (never downloaded implicitly):
fastrmemory model status
fastrmemory model install
```

`fastrmemory hygiene` reports orphaned file links, conflict rows, and feedback rows; duplicate active memories by normalized title or exact content; and stale unpinned active memories (default 90 days since the last recall or creation). `npm run check:hygiene` runs the same inspector against a deterministic fixture inside `check:ci`; it does not mutate a project database. Use `--fail-on-issues` when a script should exit nonzero on findings.

`fastrmemory model install` fetches `minishlab/potion-base-8M` (256-dim, 30,236,760 bytes), verifies both files against pinned SHA-256 hashes, and stores them under `~/.fastr/models/`. The tier is a bounded reranker over BM25 candidates: it fixes 1 case and breaks 1 across the 120-case LongMemEval slice, so it is documented as non-regressive, not as an accuracy win. Default recall is BM25-only until the asset is installed and backfill has produced vectors.

---

## ๐Ÿ”Œ One-Click Agent MCP Configuration

`fastr mcp init` is the one-command path for MCP-only wiring. By default it uses `--source registry` and writes the platform-correct portable runner (`npx`, `pnpm dlx`, `yarn dlx`, or `bunx`; `cmd /c ...` on native Windows). Pass `--source local` to write the active CLI path plus an absolute `--project`, which is useful for a globally installed CLI but makes the config machine-specific. It preserves unrelated config keys and is idempotent. `fastr setup` remains the full installer for `.fastr/`, `AGENTS.md`, MCP configs, and skills; `fastr hook install` adds lifecycle hooks plus MCP configs for Claude Code, Cursor, Gemini CLI, Copilot CLI, and OpenCode.

`fastr hook install` merges lifecycle hooks for Claude Code, Cursor, Gemini CLI, GitHub Copilot CLI, and OpenCode, and writes the OpenCode context/compaction plugin. `fastr hook uninstall` removes exactly what install wrote โ€” the `fastrmemory` MCP entry, the hook commands, the managed OpenCode plugin, and the `AGENTS.md` discipline block โ€” while leaving every user entry in the same files untouched. Both commands are idempotent, accept `--client <ids|all>`, `--project <dir>`, `--no-agents-md`, and `--json`, and are covered by [docs/CLIENT_SUPPORT.md](docs/CLIENT_SUPPORT.md). Gemini CLI requires strict JSON on hook stdout; Copilot returns `permissionDecision: "ask"` for an active trap because it has no model-facing advisory field for `preToolUse`.

| Client | Project config | User config | JSON key |
| :--- | :--- | :--- | :--- |
| Claude Code | `.mcp.json` | `~/.claude.json` | `mcpServers` |
| Cursor | `.cursor/mcp.json` | `~/.cursor/mcp.json` | `mcpServers` |
| VS Code | `.vscode/mcp.json` | VS Code `User/mcp.json` | `servers` |
| OpenCode | `opencode.json` | project only | `mcp.servers` |
| Gemini CLI | `.gemini/settings.json` | `~/.gemini/settings.json` | `mcpServers` |
| GitHub Copilot CLI | `.github/mcp.json` | project only | `mcpServers` |
| Windsurf | user only | `~/.codeium/windsurf/mcp_config.json` | `mcpServers` |
| Antigravity | user only | `~/.gemini/antigravity/mcp_config.json` | `mcpServers` |
| Claude Desktop | user only | platform-specific | `mcpServers` |
| Codex | user only | `~/.codex/config.toml` | printed TOML |

Example POSIX project config generated by `fastr mcp init --client cursor` (Windows uses `cmd /c npx ...`):

```json
{
  "mcpServers": {
    "fastrmemory": {
      "command": "npx",
      "args": ["-y", "fastrmemory@latest", "mcp"]
    }
  }
}
```

VS Code uses `servers` instead of `mcpServers`; OpenCode uses `mcp.servers` with a command array and `"type": "local"`. Existing `opencode.json(c)` settings are preserved, but a JSONC config is reported for manual wiring rather than rewritten. Codex is always printed as a `[mcp_servers.fastrmemory]` TOML block because rewriting a user-owned TOML file safely requires a dedicated parser.

For user-scoped clients, the generated entry includes `--project /absolute/path/to/repo`; this prevents the client's launch directory from selecting the wrong database. `fastr setup` also writes the absolute `node` path and is the recommended path when the client cannot launch package-runner shims. `--source local` is the `mcp init` equivalent for an installed CLI: it writes the active CLI path and an absolute `--project`; use `--source registry` (the default) when the config will be committed or shared. `--source local` ships in published `0.5.0` and later; on older builds, use `fastr setup` for an installed-CLI config. On native Windows, `fastr mcp init` automatically emits `"command": "cmd"` with `"/c"` and the runner, so manual `npx.cmd` fixes are not needed.

`--client all --scope project` covers the six project-scoped clients in the table. `--client all --scope user` covers the eight user-scoped clients; OpenCode and Copilot CLI are project-only, while Codex prints a TOML block for manual insertion. User-scoped entries pin one `--project` database, so use project scope when each developer may open a different checkout.

---

## ๐Ÿ› ๏ธ MCP Server: Tools & Resources

Built using the official **v2 `@modelcontextprotocol/server`** SDK. The tool list below describes **0.9.3**; 45 tools across the 12-tool core and full profiles.

### 45 MCP Tools

The default **core profile** exposes 12 tools: the daily loop (`fastr_recall`, `fastr_remember`, `fastr_handoff`, `fastr_trap_recall`, `fastr_trap_log`, `fastr_status`, `fastr_get`, `fastr_replay`, `fastr_compress`, `fastr_diagnose`) plus `fastr_tools` for discovery and `fastr_call` for dispatch. Its `tools/list` payload is 8,715 bytes (~2,179 tokens). The **full profile** exposes all 45 tools; start it with `fastrmemory mcp --profile full` or `FASTR_MCP_PROFILE=full`. Every full-profile tool stays reachable from the core profile through `fastr_call`. Resources and prompts are the same in both profiles. Pass `--project /absolute/path/to/repo` when the host starts the server outside the repository, so memory is written to the intended `.fastr/fastr.db`.

#### Cognitive Retrieval & Memory Core
1. `fastr_recall`: Triple-stream hybrid search (BM25 + Vector + Spreading Activation Graph) with progressive L0โ€“L3 token budgeting and air-gapped offline vector fallback.
2. `fastr_get`: Retrieves complete memory details (including status, timestamps, reward scores, and full content) by memory ID.
3. `fastr_list`: Lists memories with bounded filtering by module, kind, status, limit, and offset.
4. `fastr_drill`: Resolves `source_event_ids` to retrieve untruncated verbatim stack traces, diffs, and tool outputs from `raw_events`.
5. `fastr_file_history`: Returns active rules, `[TRAP]` warnings, and past supersessions for a specific file path.
6. `fastr_symbol_history`: Returns active rules, [TRAP] warnings, and past supersessions anchored to a named function, class, or type. The anchor follows the declaration through a rename or a file move, so a trap written against `signToken` is still found after it becomes `signJwt`.
7. `fastr_god_nodes`: Returns the top architectural hub symbols (functions and classes with highest caller in-degree), identifying core abstractions with the highest blast radius.
8. `fastr_remember`: Records new rules, decisions, or traps. Automatically extracts NER entities, scrubs secrets, and re-renders Markdown mirrors. Supports `scope: 'project' | 'global'`.
9. `fastr_pin`: Pins critical rules so they are permanently preserved and prioritized in L0 assembly without time decay.
10. `fastr_forget`: Tombstones and deactivates an outdated memory cleanly with audit logging.
11. `fastr_supersede`: Retires an outdated rule (`valid_to = now`), records the rationale, and inserts a replacement verified rule.
12. `fastr_feedback`: Updates `reward_score` and the confidence tier on one memory ID (+0.2 good, -0.5 bad). Three consecutive bad outcomes make it dormant; never penalizes innocent memories.
13. `fastr_handoff`: Saves or retrieves cross-agent session milestones and promotes staging memories to verified.
14. `fastr_status`: Returns active/staging counts, spool health, and embedding coverage %.
15. `fastr_graph_query`: Explores 1-hop and 2-hop structural file-link dependencies, entity links, and connected error traps.
16. `fastr_timeline`: Chronological audit trail of memory events, newly verified rules, error traps, and historical supersessions.

#### Versioning & Error Traps
17. `fastr_snapshot`: Creates named point-in-time memory snapshots for branch tracking and experiment safety.
18. `fastr_rollback`: Instant Git-like rollback to any previous memory snapshot.
19. `fastr_trap_log`: One-line rapid logging of error traps and bug solutions with a conditional 2.0x recall boost.
20. `fastr_trap_recall`: Targeted lookup of high-priority error traps protecting specific target files before editing.

#### Proactive Contradiction Detection & Resolution
21. `fastr_conflicts`: Proactive contradiction detection using Jaccard token overlap (minimum 0.35) and 50-word opposing-polarity analysis.
22. `fastr_resolve`: Resolves contradictions by keeping preferred rule and superseding or weakening the loser.

#### Kahneman Planning Fallacy & Base-Rate Calibrator
23. `fastr_predict`: Records effort/time/risk predictions and closes predictions with actual empirical outcomes.
24. `fastr_predict_baserate`: Computes historical reference-class statistics (Mean, Median p50 ratio, MAE) to debias agent estimates.

#### Multi-Agent Action DAG & Frontier
25. `fastr_action_create`: Creates structured work item actions with prerequisite (`requires`) and conflict (`conflicts_with`) constraints.
26. `fastr_action_update`: Updates task lifecycle (`pending`, `active`, `done`, `blocked`), assignments, and memory crystallization.
27. `fastr_frontier`: Computes unblocked, ready-to-execute frontier actions with satisfied dependencies.
28. `fastr_next`: Atomically claims and returns the highest-priority frontier action for autonomous worker agents.

#### Bounded Working Memory & Obsidian Vault Export
29. `fastr_slot_get`: Retrieves bounded working memory slot (e.g. `current_goal`, `user_preferences`, `active_hypothesis`).
30. `fastr_slot_set`: Updates working memory slot with hard character ceiling enforcement to prevent context bloat.
31. `fastr_slot_list`: Lists all working memory slots and active character usage.
32. `fastr_obsidian_export`: Exports all memories, entities, and relationships into an Obsidian-compatible markdown vault with YAML frontmatter, `[[wikilinks]]`, and `MOC.md`.

#### Multi-Repository Federation & Context Assembly
33. `fastr_federate`: Manages cross-repository organization-wide shared rules and error traps via SQLite native `ATTACH DATABASE` (`~/.fastr/global.db`).
34. `fastr_assemble`: Dynamically formats and packs high-density structured prompt context (`<fastr_context>`) with token budgeting.
35. `fastr_risk_predict`: Computes historical failure probability and active trap hazard score for target codebase files.
36. `fastr_verify_provenance`: Cryptographically verifies SHA-256 provenance hashes for recorded agent attribution.

#### Token Compression & Autonomous Doctor
37. `fastr_compress`: Compresses markdown files or prompt context while strictly preserving headings, URLs, and code blocks with `.original.md` backup.
38. `fastr_diagnose`: Deep health audit of SQLite B-Tree integrity, FTS5 BM25 search indices, orphaned file links, and task DAGs.
39. `fastr_heal`: Automatic repair of database indices, dangling edges, and WAL page reclamation.

#### Memory Replay & Diff
40. `fastr_replay`: Reconstructs memory state at a timestamp and returns the active snapshot for audit or recovery.
41. `fastr_diff`: Compares two snapshots and reports added, superseded, and removed memories.

#### Multimodal Visual Memory
42. `fastr_vision_tag`: Tags screenshots, UI diagrams, and wireframes with OCR and semantic descriptions with 384-dim embeddings.
43. `fastr_vision_search`: Hybrid vector and keyword search across stored visual assets for multimodal coding agents.

#### Tool Discovery & Dispatch
44. `fastr_tools`: Lists every tool the server can run, with its JSON input schema, filtered by name or description. Part of the core profile.
45. `fastr_call`: Runs any tool from `fastr_tools` by name after validating arguments against that tool's schema. Part of the core profile.

### 2 MCP Prompt Templates

- `pre-edit-check`: Given file paths, instructs the agent to check traps and relevant rules before editing.
- `session-wrap-up`: End-of-session checklist for logging traps, superseding stale rules, scoring memories, and saving a handoff.

### 5 MCP Resources (0.3.0; v0.2.1 has 4)

- `fastr://project/overview`: L0 project summary containing active counts and storage location.
- `fastr://project/traps`: All active `[TRAP]` warnings for immediate bug avoidance.
- `fastr://session/handoff`: Latest cross-agent handoff milestone.
- `fastr://memory/{id}` (resource template): Full JSON for a single memory, including linked files and its validity window.
- `fastr://memory/{id}/envelope` (resource template): Metadata, cryptographic provenance, file/graph links, and open/resolved conflict state for one memory.

---

## ๐Ÿ“„ Two-Zone Git-Diffable Mirror

Every write to the local SQLite database automatically synchronizes human-readable markdown files in `.fastr/pages/<module>.md`. This allows developers to review AI memories directly in GitHub Pull Requests:

```markdown
# Module: auth

> Auto-generated by FastrMemory. Active rules are at the top; superseded history is preserved below for Git diffs.

---

## Compiled Truth (Active Rules & Traps)

### [mem_009e4a7d] [TRAP] Never Use Date.now() Milliseconds for JWT Expiration
- **Kind**: `error_trap`
- **Status**: `verified` (Reward Score: 1)
- **Linked Files**: `src/auth/jwt.ts`
- **Active Since**: `2026-10-18T21:46:20Z`

JWT exp claims expect integer seconds. Always use Math.floor(Date.now() / 1000).

---

## Append-Only Timeline (History & Superseded)

### [EXPIRED 2026-10-18T20:00:00Z -> 2026-10-18T21:46:20Z] [mem_abc123] Token Signing
- **Superseded By**: `[mem_009e4a7d]`
- **Reason**: Standardized on integer seconds
- **Historical Status**: `superseded`

> Old implementation used milliseconds which failed expiration validation.
```

---

## ๐Ÿง  Planetary Agent Skills Suite

FastrMemory ships 10 Agent Skills (in `skills/`, mirrored to `.cursor/skills/`) that tell agents *when* to use each memory tool. Install them as a Claude Code plugin (`.claude-plugin/`) or copy them with `fastrmemory setup`:

- [fastr-memory](skills/fastr-memory/SKILL.md): At the start of a task and before editing files: `fastr_trap_recall`, then `fastr_recall` / `fastr_assemble`.
- [fastr-trap-log](skills/fastr-trap-log/SKILL.md): The moment a failure is diagnosed: record it with `fastr_trap_log`.
- [fastr-session-commit](skills/fastr-session-commit/SKILL.md): When a task is done and tests pass: supersede, rate memories, and `fastr_handoff` with `verifyStaging`.
- [fastr-curate](skills/fastr-curate/SKILL.md): When storing durable lessons or fixing contradictions: dedupe, remember, supersede, resolve conflicts, snapshot/rollback.
- [fastr-setup](skills/fastr-setup/SKILL.md): When FastrMemory is not wired into Claude Code: `fastrmemory hook install`, `claude mcp add`, verify with `fastrmemory status`.
- [fastr-plan-estimate](skills/fastr-plan-estimate/SKILL.md): When estimating effort or risk: base rates, file risk, and closing predictions.
- [fastr-dag](skills/fastr-dag/SKILL.md): When work has dependent steps or several agents share a backlog.
- [fastr-doctor](skills/fastr-doctor/SKILL.md): When recall misses memories or the database looks unhealthy: diagnose, then heal.
- [fastr-compress](skills/fastr-compress/SKILL.md): When a doc or context block exceeds its token budget.
- [fastr-vision](skills/fastr-vision/SKILL.md): When screenshots or diagrams should be remembered or searched.

Run `npm run check:skills` to validate every tool call in the skills against `src/mcp/server.ts`.

After updating the CLI, re-run `fastr setup` to refresh the copied skills. The installer overwrites same-named skill files, removes retired skills, and leaves unrelated user-owned directories. `fastr hook install` does not copy skills. Restart the client after setup. If you install the Claude Code plugin instead, update the plugin rather than maintaining a second copied skill set.

---

## ๐Ÿ—๏ธ Architecture

```mermaid
flowchart TD
    subgraph Ingestion["1. Lossless Ingestion & Spool"]
        Agent["AI Coding Agent\n(Claude Code, Cursor, Antigravity)"] --> Scrubber["Secret Scrubber\n(API Keys, Bearer, PEM)"]
        Scrubber --> Spool{"SQLite Busy?"}
        Spool -- Yes --> SpoolFile[".fastr/spool/pending.jsonl\n(async fallback)"]
        Spool -- No --> DB
    end

    subgraph Storage["2. Bi-Temporal Storage & Git Mirror"]
        DB[("Node 22 node:sqlite (WAL)\nraw_events | memories\nfile_links | handoffs")]
        DB --> Mirror["Markdown Mirror Engine"]
        Mirror --> Pages[".fastr/pages/<module>.md\nTop: ## Compiled Truth\nBottom: ## Append-Only Timeline"]
    end

    subgraph Search["3. Triple-Stream Hybrid Retrieval"]
        Query["Recall / File Query"] --> FTS["Stream A: FTS5 BM25\n(Sub-millisecond)"]
        Query --> Vec["Stream B: Xenova Vectors\n(all-MiniLM-L6-v2)"]
        Query --> Graph["Stream C: file_links Graph\n(1-2 Hop Structural Match)"]
        FTS & Vec & Graph --> RRF["RRF Fusion (k=20)\n+ Conditional 2.0x Error Trap Multiplier\n+ 1.25x Verified Multiplier"]
        RRF --> Budget["Progressive Token Packer\nL0 (150t) | L1 (500t) | L2 (1500t) | L3 (4000t)"]
    end

    subgraph Protocol["4. Official MCP Protocol"]
        Budget --> MCPServer["Official MCP v2 Server\n(@modelcontextprotocol/server)"]
        MCPServer --> Tools["44 tools โ€ข 2 prompts โ€ข 5 resources"]
        Tools --> Agent
    end
```

---

## ๐Ÿงช Testing & Verification

Run the comprehensive unit test suite:

```bash
npm test
```

All **481 tests pass** across **74 test files** on current `main`; published `0.9.3` carries the same **481 / 74**, `0.9.2` and `0.9.1` carry **476 / 74**, `0.9.0` has **476 / 74**, `0.8.2` has **461 / 69**, `0.8.1` has **461 / 69**, `0.8.0` has **461 / 69**, `0.7.2` has **456 / 67**, `0.7.1` has **456 / 67**, `0.7.0` has **455 / 67**, and `0.6.0` has **388 / 61**, `0.5.0` has **297 tests / 53 files**, historical `0.4.0` has **293 tests / 53 files**, `0.3.1` has **282 / 52**, and v0.2.1 has **235 / 43**. Coverage includes database schema, WAL locking, offline spooling, bi-temporal supersession, secret scrubbing, two-zone rendering, automated benchmarks, snapshots/rollback, branch merge conflict reports, replay/diff, memory envelopes, confidence tiers and 3-bad dormancy, memory hygiene checks, Memory CI, conflict-aware recall, portable backup manifests and verified restore, local rule import, OpenCode V2, Gemini CLI, and Copilot CLI wiring, git-learner, cognitive blame, commit synthesis, hybrid background daemon, token compression, self-healing doctor, multimodal vision, web dashboard server, pre-merge trap guardian, symbol indexing and declaration anchoring, per-turn injection, read-only recall, self-verifying memories, UI loopback security boundaries, atomic installer configuration safety, and shadcn-style `mcp init` client config merges, including local-source entries.

**CI performance gates:** `check:query-plans`, `check:recall-latency`, and `check:install-size` run inside `check:ci`. CI executes them on the canonical Ubuntu/Node 24 job; other matrix jobs set `FASTR_PERF_GATE=0` because timing is runner-sensitive, while functional tests still run on every matrix entry.

**Clean-machine install evidence:** `npm run smoke:npx` downloads the published package with `npx` from an empty directory (no checkout, no global install, no `node_modules`), then runs `--version` and `status`. `status` opens a real `node:sqlite` database, so a package that ships without a working SQLite path fails there rather than in an editor. The script retries a registry 404 for up to ten minutes, and `.github/workflows/npx-smoke.yml` runs it on Ubuntu, Windows, and Intel macOS for Node 22.x and 24.x. CI run `40261934471` at `b9645ef` passed all six jobs, and every job reported `"version":"0.6.0"`, `"statusBooted":true`, `"attempts":1`, and `"ok":true` on a cold `npx` install; the same script passes locally on Windows / Node 24.15.0.

**Crash-safety evidence:** `npm run test:crash` kills the writer at randomized points across 10 runs, then reopens the WAL database. The committed report at [`bench/results/crash-test.json`](bench/results/crash-test.json) records **10,718 acknowledged writes**, **10,727 committed rows**, **0 lost**, **0 duplicate ids/titles**, and `PRAGMA integrity_check = ok`; methodology is in [`docs/audit/2026-10-21-crash-test.md`](docs/audit/2026-10-21-crash-test.md). `npm run check:crash` validates the report during `check:ci`. This is a process-crash test (`taskkill /F`), not a power-loss test; SQLite runs with `synchronous=NORMAL` in WAL mode.

---

## Retrieval Benchmark (240 synthetic cases)

Generated from [`bench/results/minilm.json`](bench/results/minilm.json) on **2026-10-20** at benchmark commit `562f461`. The corpus is deterministic: 120 memories and 240 queries, split into **192 train / 48 holdout (20%)**. The holdout was fixed before tuning and is reported separately. Reproduce with:

```bash
npx tsx scripts/eval-bench.ts --split all --embeddings minilm --out bench/results/minilm.json
npx tsx scripts/eval-bench.ts --split all --embeddings hash   --out bench/results/hash.json
```

| Configuration | Split | Cases | Hit@1 | Hit@3 | Hit@5 | MRR | nDCG@10 | Context tokens | p50 |
| :--- | :--- | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: |
| FastrMemory + MiniLM | Train | 192 | 96.4% | 99.0% | 100% | 0.976 | 0.982 | 208 | 3.30 ms |
| FastrMemory + MiniLM | **Holdout** | 48 | **95.8%** | **97.9%** | **100%** | **0.969** | **0.977** | 209 | 3.41 ms |
| FastrMemory BM25-only | Train | 192 | 79.7% | 90.6% | 100% | 0.868 | 0.900 | 203 | 0.48 ms |
| FastrMemory BM25-only | Holdout | 48 | 77.1% | 77.1% | 93.8% | 0.804 | 0.835 | 204 | 0.60 ms |
| Static dump - simulated baseline | Train | 192 | 2.1% | 6.3% | 8.3% | 0.055 | 0.081 | 3652 | 0.00 ms |
| Static dump - simulated baseline | Holdout | 48 | 0.0% | 0.0% | 8.3% | 0.025 | 0.056 | 3652 | 0.00 ms |

> **Caveats:** this is a deterministic synthetic corpus, not SWE-bench or LongMemEval. The static-dump row is a simulation implemented in this repository, not an external project. Separate public retrieval-only external baselines are documented in [docs/EXTERNAL_BASELINE.md](docs/EXTERNAL_BASELINE.md); the synthetic table does not measure them. Context tokens are the compact prompt text under a 250-token budget; the ranked result objects retain full memory content. Methodology, per-category breakdowns, ablations, and confidence intervals are in [BENCHMARKS.md](BENCHMARKS.md) and [docs/benchmark-report.md](docs/benchmark-report.md).

## ๐Ÿ–ฅ๏ธ Local Web Dashboard v2 & 3D Brain Observatory

Visualize active rules, error traps, timeline audits, and interactive 3D memory constellations directly in your browser from bundled UI assets (no external service or database):

```bash
fastrmemory ui
```

- **Live URL**: `http://localhost:4242`
- **Dashboard v2 Architecture**: Built with **shadcn/ui**, **Tailwind CSS v4**, and **TanStack Query**, with SSE updates plus version polling for cross-process writes.
- **12 Focused Route Workspaces (0.3.0 adds `/replay`)**:
  - `/`: Real-time system vitals, active trap alerts, recent memory feed, and quick-action shortcuts.
  - `/memories`: Search, filter, and inspect memories with the slide-out **Memory Detail Sheet**, status toggles, pin, and 1-click forget.
  - `/traps`: Dedicated **Error Trap Quarantine** displaying governing files, conditional boost conditions, and verified mitigation lessons.
  - `/conflicts`: Proactive bi-temporal contradiction detection with side-by-side **Word Diff** and 1-click resolution (`Keep A`, `Keep B`, `Keep Both`).
  - `/actions`: Real-time interactive **Action DAG Canvas** tracking task dependencies, worker assignments, and glowing unblocked frontier aura.
  - `/graph`: Interactive file and entity relationship graph with 1-hop/2-hop inspection and memory drill-down.
  - `/observatory`: High-performance **Three.js 3D Constellation Galaxy** with a smooth lerp camera, celestial star dust, glowing amber trap halos, and memory inspect modals.
  - `/treemap`: Interactive high-DPI squarified treemap visualising memory strength bands and module density.
  - `/search`: **Search Lab** evaluating triple-stream RRF retrieval with latency waterfall breakdown (BM25 vs Vector vs Graph).
  - `/replay` (**0.3.0**): **Replay & Diff** workspace reconstructing the active set at two timestamps with snapshot metrics and added/superseded/changed/conflict review.
  - `/health`: Autonomous SQLite self-healing Doctor with 1-click integrity diagnosis, FTS5 rebuild, and vacuum.
  - `/settings`: Live database path, project configuration, and export controls.
- **Memory CI**: The PR diff workflow and comment lifecycle are documented in [docs/MEMORY_CI.md](docs/MEMORY_CI.md).
- **Dual Theme Support**: Light, dark, and system-preference modes.
- **Default Zero-Daemon Path**: The dashboard is served by the in-process Node.js HTTP server and embedded SQLite WAL mode; `fastrmemory daemon start` is an optional local REST/SSE service.

---

## ๐Ÿงฉ Native VS Code & Cursor Extension

Package and install the native FastrMemory Guardian extension for **VS Code** and **Cursor**:

```bash
# Compile and package extension
npm run build:extension
npx @vscode/vsce package --no-dependencies

# Install into Cursor or VS Code
cursor --install-extension fastrmemory-vscode-0.1.0.vsix
```

- **Status Bar Pill**: Displays active trap count in the status bar (`3 Traps Active` or `1 Trap on File`). Clicking opens an interactive QuickPick listing all active traps.
- **Amber Underlines**: Trapped files are underlined in amber with full hover mitigation instructions and conditional 2.0x boost conditions.
- **Problems Tab Integration**: Active error traps populate the IDE Problems panel as non-blocking warning diagnostics.
- **Zero Daemons**: Reads directly from `.fastr/fastr.db` via `node:sqlite`.

---

## ๐Ÿ“„ License

Apache License 2.0. Built by **Fastrsoft**. Free for personal and commercial use.