Memory Recall

Local repo memory and context for Codex, Claude Code, Cursor, and other coding agents.
Governed SQLite memory. Read-only MCP. Rust code intelligence. No hosted account. No 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 handoff

Why Developers Use It

Five-Minute Path

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

# Bootstrap local files and run the handoff verification gate.
recall setup
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.

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. The installed server does not import harness history, enable write tools, call cloud/model APIs, or claim provider billing-token savings.

Documentation

Verified Numbers

These are local measurements from this repository. They are delivery-token
estimates and correctness checks, not provider billing claims.

Memory Recall is strongest when context changes over time, handoffs repeat, and
the next agent needs reviewed local truth. It is not a hosted memory API,
semantic embedding service, graph database, or billing-meter replacement.
The LoCoMo number is model-free retrieval coverage, not official generative QA
F1; the command does not call a model API.

How It Compares

What Works Now

• 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.
• Read-only recall mcp server exposing memory.recall, context.profile, and
  context.pack 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.
• Rust workspace for local ingest, governed graph/search, wiki, MCP, and the
  graph-query evaluation path. Rust source ships in the npm package; build
  output stays out of the tarball.
• Deterministic local benches for temporal correctness, session delta delivery,
  and real repo question answering.

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

See REPOSITORY_MAP.md for ownership and dependency
boundaries.

Status

Development kit: 1.0.5.

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.