FastrMemory

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

⚔️ Architectural & Performance Comparison

Verified benchmark evidence from bench/results/vs-engines.json and 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.

🧭 Design Principles

🤖 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:

[FastrMemory MCP server]

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

# 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 [email protected] 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

# Canonical install (always latest):npm install -g fastrmemoryfastr --version
# Or run one-shot:npx -y fastrmemory --version

To pin an exact release instead: npm install -g [email protected].

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 [email protected] 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 [email protected] 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:

# 1. Back up memory before changing versionsfastr backup fastr-backup.jsonlfastr backup --verify fastr-backup.jsonl
# 2. Update the global CLInpm install -g fastrmemory@latestfastr --version
# 3. Refresh project integrationfastr setup                                   # MCP configs, mandatory rules, and skillsfastr hook install --client all               # lifecycle hooks plus MCP for hook clientsfastr skill install --client all              # optional /fastr command for 7 clients
# 4. Verifyfastr statusfastr 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 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.

# Claude Code (project-scoped .mcp.json)npx -y fastrmemory@latest mcp init --client claude
# Cursornpx -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 CLInpx -y fastrmemory@latest mcp init --client gemini,copilot
# Every project-scoped client at oncenpx -y fastrmemory@latest mcp init --client all --scope project

The same command through the other package runners:

pnpm dlx fastrmemory@latest mcp init --client claudeyarn dlx fastrmemory@latest mcp init --client claudebunx 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 [email protected]. --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:

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:

npx --yes github:atifjubaer/fastrmemory#v0.9.3 --versionnpx --yes github:atifjubaer/fastrmemory#v0.9.3 setup

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

curl -L -o fastrmemory-0.9.3.tgz \  https://github.com/atifjubaer/fastrmemory/releases/download/v0.9.3/fastrmemory-0.9.3.tgznpm install -g ./fastrmemory-0.9.3.tgzfastr --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 [email protected]; the old scoped npm entries are gone. Use npm for generated MCP and hook configs so installs stay reproducible.

2. Verify Database Health

fastrmemory status

Output:

=== 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

# 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:

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

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

# 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 rulesfastrmemory 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

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

# Point-in-time memory snapshot (Git for Agent Memory):fastrmemory snapshot create "pre-refactor-checkpoint"fastrmemory snapshot listfastrmemory snapshot rollback "pre-refactor-checkpoint"
# Portable backup with a sidecar provenance manifest:fastrmemory backup backups/pre-upgrade.jsonlfastrmemory backup --verify backups/pre-upgrade.jsonlfastrmemory backup --restore backups/pre-upgrade.jsonl --dry-runfastrmemory 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 verifyfastrmemory trap verify --apply
# Immutable memory branch and one-way merge with a conflict report:fastrmemory branch create feature/authfastrmemory branch listfastrmemory merge feature/authfastrmemory merge feature/auth --force --strategy branch
# Hybrid Background Daemon (Optional HTTP/SSE service for cross-process tools):fastrmemory daemon startfastrmemory daemon statusfastrmemory 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 for the full backup and rollback path.

6. Token Compression, Database Doctor & Vision Search

# 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 hygienefastrmemory 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 statusfastrmemory 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. 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.

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

{  "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:

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

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:

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

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

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; 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 and 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):

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.
• 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:

# Compile and package extensionnpm run build:extensionnpx @vscode/vsce package --no-dependencies
# Install into Cursor or VS Codecursor --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.