Memory Recall

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.

The source and package release candidate are 1.1.0. Check the registry before using the global install path:

npm view memory-recall version
npm install -g [email protected]
recall setup
recall map --root . --sqlite .local/memory.sqlite --format summary
recall handoff

If the registry still reports an older version, use the source checkout:

git clone https://github.com/rebel0789/Memory-Recall.git
cd Memory-Recall
npm install
npm run recall -- setup
npm run recall -- map --root . --sqlite .local/memory.sqlite --format summary
npm run 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. Source checkouts use npm run recall -- <command> in place of recall <command>.

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

# Confirm and install the 1.1.0 package.
npm view memory-recall version
npm install -g [email protected]

# 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 | Source checkout: npm run 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 |

The package bundles the session, temporal, and truth-floor fixtures. The structured-ingest check measures this repository's own status and provider manifests, so run it only from a Memory Recall source checkout.

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

Release candidate: 1.1.0. Registry version: verify with npm view memory-recall version.

| Surface | Status | | --- | --- | | Source checkout | 1.1.0 local-ready release candidate | | npm package | 1.1.0 publish-ready; use only after the registry reports 1.1.0 | | 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.