FastrMemory

FastrMemory

High-Performance Cognitive Agent Memory Engine

Zero Daemon • Native Node 22+ `node:sqlite` • Bi-Temporal Git Sync • Triple-Stream RRF • Official MCP v2

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. 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; no QA-leaderboard parity is claimed. Performance, packaging, and retrieval claims are tracked in 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.

Overview • Design Principles • Benchmarks • Web UI • Supported Agents • Quick Start • MCP Setup • MCP Tools • Architecture • Migration • Security • Scorecard

---

Launch Status at a Glance

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.

---

💡 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):

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.

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

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

⚔️ Architectural & Performance Comparison

*Verified benchmark evidence from bench/results/vs-engines.json and docs/PUBLIC_BENCHMARKS.md.*

🧭 Memory Landscape: