Memory Recall

Local repo memory and context for Codex, Claude Code, Cursor, and other coding agents.
Governed SQLite memory. Read-only MCP. Experimental Rust acceleration requires a local build. The default local path needs no hosted account or model API key.

Memory Recall turns a repository into a governed context source. New agent sessions get reviewed repo facts, changed-file impact, required local reads, and proof of what was sent instead of a giant pasted transcript.

npm install -g memory-recall
recall setup
recall map --root . --sqlite .local/memory.sqlite --format summary
recall handoff

recall setup creates only local state. recall map is the explicit first read-only repository scan; it does not run silently during setup.

Normal quickstarts use recall. The developer-first product contract defines the implemented, experimental, and unsupported capability vocabulary. See Compatibility identifiers for preserved legacy names and URIs.

Why Developers Use It

Need	What Memory Recall gives you
New agent session	A compact handoff with required local reads, changed-file coverage, hashes, and MCP proof.
Repo memory	SQLite/FTS5 facts that start as proposals and become ACTIVE only after review.
Fast local code intelligence	Implemented JS/TS static graph; experimental Rust ingest and graph/search require a local build.
First look at a repository	Recall Map shows bounded source coverage, entry points, changed impact, and separate memory status without writing.
Long context pressure	Repeat MCP pulls use cursors and deltas instead of resending the same profile.
Trust	Dry-run first, confirm-gated writes, local-only storage, and no automatic transcript import.
Codebase context	Source graph hints, locator-only context packs, and manifest-backed selection.

Five-Minute Path

# Install the CLI.
npm install -g memory-recall

# Create local state only. This does not scan the repository.
recall setup

# Run the first explicit read-only repository map.
recall map --root . --sqlite .local/memory.sqlite --format summary

# Run the handoff verification gate.
recall verify

# Preview local agent setup. This writes nothing.
recall connect codex --dry-run --format json
recall mcp install --client claude-code --dry-run --format json

# Build governed memory proposals. Facts are not trusted until reviewed.
recall memory ingest --root . --sqlite .local/memory.sqlite --format json
recall memory review --root . --sqlite .local/memory.sqlite --format summary

# Produce the compact handoff for the next coding agent.
recall handoff

The default path is local and explicit: no hosted account, no model API key, no silent memory capture, and no automatic permanent memory.

Optional semantic setup uses the active coding agent or one explicitly consented provider request to create pending proposals from selected documentation. Start with the body-free plan:

recall semantic plan --harness codex --root . --dry-run
recall semantic task --harness codex --root .
recall semantic import --input semantic-result.json --root . --sqlite .local/memory.sqlite

The CLI does not invoke the harness. Direct API execution requires a user-owned environment credential and --allow-network. See Semantic setup for data limits and explicit-ID approval.

Manual MCP install flow: run the mcp install --client claude-code --dry-run --format json preview, review it, then run the printed --apply --confirm <fingerprint> command only when the fingerprint matches. That path installs the five-tool read-only MCP server. recall connect is separate: it installs a resource bridge plus hooks for Codex or Claude Code, and its MCP tools/list is empty. The support matrix names the difference and reversal path.

Documentation

Start	Reference
Quickstart	MCP server reference
Recall Map	Security model
Semantic setup	Memory lifecycle
Codex setup	Memory lifecycle
Claude Code setup	Token savings measurement
Cursor setup	Rust acceleration
Docs hub	Security model
Troubleshooting	Launch plan
Support matrix	Benchmark proof
Uninstall and data preservation	Token savings measurement
Developer-first contract	Compatibility identifiers

Reproducible Proof

Every public measurement names its dataset, baseline, command, generated JSON artifact, pass condition, and limitation in Benchmark proof. They are local delivery-token estimates and correctness checks, not provider billing claims.

Fixture or gate	Current claim	Command
Session cursor-delta fixture	6/6 current answers and 72% lower estimated delivery than full resend	recall bench session --read-only --root . --format json
Temporal current-truth fixture	10/10 correct and clean; not a token-saving claim	recall bench temporal --read-only --root . --format json
In-repo structured-ingest sufficiency	12/12 checkout-derived answers present after structured ingest	recall bench realqa --read-only --root . --format json
Truth-floor regression gate	Fixture-backed merge gate, not a user-task benchmark	recall benchmark truth-floor --suite benchmark-truth-floor --dataset evals/benchmark-truth-floor/cases.v1.json --format json

Memory Recall is designed for changing repository context, repeated handoffs, and reviewed local truth. It is not a hosted memory API, semantic embedding service, graph database, billing-meter replacement, or cross-product benchmark leaderboard.

How It Compares

Category	Usually strong at	Memory Recall position
Hosted memory APIs	Cross-app memory, cloud connectors, managed retrieval	Use a hosted service when managed cross-app memory is required. Memory Recall focuses on local repository handoff.
Persistent agent memory frameworks	Long-term personalization and retrieval across products	Choose these for cross-product personalization. Memory Recall stores repo-scoped proposals and exposes their sources and approval state.
Temporal graph memory	Changing facts, provenance, entity relationships	Memory Recall has local temporal facts and supersession, but does not claim a full temporal graph database.
Code graph MCP tools	Static code graph search and token-heavy repo compression	Memory Recall combines code locators with governed memory, handoff manifests, MCP proof, and local UX.
IDE indexing	Smooth editor-native search	Memory Recall reports which context units were selected, excluded, pinned, and delivered; it does not replace editor-native search.

Current Capabilities

• Dependency-free Node.js 22 bootstrap with no paid service, database server, or model API required.
• Native SQLite/FTS5 governed memory with temporal facts, supersession, entity edges, proposal queue, explicit approve/reject, and no hard delete.
• Bounded semantic setup packets for Codex, Claude Code, Cursor, or a generic harness; strict result import; pending-only proposals; and source-rechecked named approval. Optional direct API execution is experimental and explicitly consented.
• Read-only recall mcp server exposing memory.recall, context.profile, context.pack, repo.map, and code.impact over local stdio with active facts separated from proposals.
• Persisted MCP cursors and since deltas so repeated reads send only changed current truth, including after restart.
• Preview-then-confirm install paths for Claude Code, Cursor, and Codex with explicit project root and project SQLite memory path.
• Local /memory cockpit over the loopback Control API with temporal facts, proposal counts, MCP delivery stats, and confirm-gated approvals.
• Experimental Rust acceleration paths for local ingest, governed graph/search, wiki, MCP, and static analysis when explicitly invoked. They require a local cargo build --release before use; Rust source ships in the npm package, but build output stays out of the tarball.
• Deterministic local benches for temporal correctness, session delta delivery, and checkout-derived structured-ingest sufficiency.

Safety Model

Memory Recall is built around explicit authority:

• memory ingest creates proposals, not trusted facts;
• active memory requires review and approval;
• rejections and supersessions are recorded, not silently deleted;
• MCP resources are read-only by default;
• setup and connect commands support dry-run previews;
• local storage remains local unless you intentionally move it;
• external adapters stay disabled until reviewed, pinned, licensed, and tested.

See Security model, fork policy, and integration policy for the deeper boundary rules.

What Is Not Claimed

Production PostgreSQL repositories, production authentication, hosted embeddings, vector databases, hosted memory sync, write-capable MCP tools, automatic harness history import, real social connectors, hardened sandboxes, signed Agent Pack distribution, and a production frontend framework are not claimed.

PROJECT_STATUS.json is the machine-readable source for current capability status and limitations.

Useful Commands

recall setup
recall map --root . --sqlite .local/memory.sqlite --format summary
recall verify
recall connect codex --dry-run --format json
recall mcp install --client claude-code --dry-run --format json
recall memory ingest --root . --sqlite .local/memory.sqlite --format json
recall memory review --root . --sqlite .local/memory.sqlite --format summary
recall memory refine --read-only --root . --sqlite .local/memory.sqlite --format json
recall token-saver
recall graph stats --root . --format summary
recall graph search --root . --query "auth workflow" --format summary
recall graph trace --root . --symbol runAuthWorkflow --format summary
recall context handoff --read-only --from codex --root . --objective "Prepare handoff" --step "select next agent context" --target codex --format summary
recall handoff

For source checkouts, use npm run recall -- <command> instead of the global recall binary.

npm run recall -- memory refine --read-only --root . --sqlite .local/memory.sqlite --target-active-facts 200 --format json
npm run recall -- context handoff --read-only --from codex --root . --objective "Prepare handoff" --step "select next agent context" --target codex --changed apps/web/app.js --format json

Repository Map

Path	Purpose
apps/	Local web and CLI interfaces
services/	Application services and Control API
packages/	Provider-neutral domain packages, schemas, Agent Packs, and replay logic
providers/native/	Local baseline provider implementations
rust/	Local ingest, graph/search, wiki, and MCP workspace
docs/usage/	User-facing install, setup, memory, MCP, security, and measurement docs
evals/	Deterministic regression datasets
tests/	Node test suite and release checks

See REPOSITORY_MAP.md for ownership and dependency boundaries.

Status

Development kit: 1.0.5.

Surface	Status
Source checkout	Local-ready reference path
npm package	Published as memory-recall
CLI	recall
Marketplace / plugin registry	Manifest prepared; not submitted
Client hooks	Opt-in Codex/Claude connect writer; dry-run/manual fallback

Run npm run status for the checked-in task state. Run npm run task -- <OAF-ID> only when status names a next task.

Contributing

Read CONTRIBUTING.md, SECURITY.md, and CODE_OF_CONDUCT.md. Keep changes evidence-backed, local by default, and honest about what is implemented versus planned.