Most agent memory is pull: a store you query. You ask, it returns the closest matches, and it is on you to notice when a fact has gone stale. Recall is push: the agent and the substrate run a loop together. It checks what it already knows before it acts, does the work, and writes back what it learned, superseding the old fact when something changes and surfacing the contradiction without being asked. No reminding it to save, no separate cloud service mining your transcript after the fact. Under the hood an LLM proposes a structured write, an admission firewall validates it, and the compiler returns only the relevant subgraph, ranked by evidence, fit to a word budget, all in local SQLite: no server, no account, no cloud. The memory is yours, and every fact still carries provenance, confidence, and a one-command undo.

One installable Node.js tool: CLI, read-only TUI, MCP server, quiet maintenance daemon, strict write schema, semantic search, encrypted secrets side graph, and a reproducible benchmark harness.

Install

npm install -g github:H-XX-D/recall-memory-substrate

Or use the installer script, which clones, builds, and links recall + recall-mcp:

curl -fsSL https://raw.githubusercontent.com/H-XX-D/recall-memory-substrate/main/scripts/install.sh | bash

Requires Node.js 24+. Recall uses Node's built-in SQLite, so there is no database server, no native build step, no account, and no network dependency. CI runs the core suite on Linux, macOS, and Windows, plus a readiness lane for MCP smoke, Python hooks/toolkit checks, public benchmarks, and installer validation. Upgrades, uninstall, and troubleshooting: Installation Guide.

Put your agent on Recall in one command

The installer above already wires up any agent CLI it finds. To do it yourself (or after installing a new agent), one idempotent command sets up the skill, the MCP server, the consult-Recall hook, and makes Recall the durable memory layer:

recall claude sync     # Claude Code: skill + MCP + SessionStart hook; turns OFF native auto-memory
recall codex sync      # OpenAI Codex:  skill + MCP in config.toml + a Recall directive in AGENTS.md
recall claude status   # confirm what's wired   (recall codex status for Codex)

Restart your agent and it's armed: it reads memory before relying on recollection and writes durable findings back on its own; you never tell it to "save." Both syncs back up your config before editing, are safe to re-run, and are reversible (recall claude enable-auto-memory). Using a different MCP client? See hook up your agent.

The 60-second tour

recall version    # confirm the installed package version
recall init       # create the local graph in ./.recall
recall status     # store health, counts, config

Memory enters as structured, schema-validated proposals. Normally your agent submits these over MCP (see below), but the same path works from the shell:

recall admit --json decision.json   # validated, provenance-stamped, rollbackable

It comes back as a compiled context packet, not a dump of the store:

recall compile "prepare the auth service deploy" --words 220

objective:
prepare the auth service deploy

compiler_state:
- retrieval=fts5-bm25; query="prepare the auth service deploy"; selected_cells=3; budget_words=220
- health=beliefs:0, contradictions:0, stale_or_low_trust:0, critical_warnings:0

relevant_memory:
- Cap the Postgres pool at 20 connections: Staging fell over at 35 concurrent
  connections during the load test on June 3. Capped pool_size at 20 in service
  config; raising it requires a load test sign-off. [decision:07fbbfd9-…]

risks:
- Auth tokens expire but never rotate: Access tokens have 24h expiry but no
  rotation path; a leaked token stays valid until expiry. [risk:1cb991a1-…]

tasks:
- Add a smoke check for the new rate limiter: The rate limiter shipped behind a
  flag; nobody has verified the 429 path end to end. [task:8bddbb07-…]

expansion_handles:
- 07fbbfd9-…  1cb991a1-…  8bddbb07-…

A packet holds ranked evidence, open risks and tasks, contradiction warnings when they exist, and expansion handles for drilling into any cell, all under a hard word budget. You can browse the graph at any time:

recall tui                          # read-only terminal dashboard
recall search "rate limiter"        # FTS5 + BM25 lexical search
recall semantic "token rotation"    # semantic search (hash or real embeddings)

Every cell also carries an effective confidence next to the author's immutable stated confidence. It is recomputed on every read from incoming supports, challenges, and the writer's contradiction record. Write one contradiction and the number moves:

# before: the pool-cap decision stands alone
decision:6eba1114…  state=active/conf:0.7/eff:0.7/…

# after: one cell contradicts it (nothing deleted, no model ran)
decision:6eba1114…  state=active/conf:0.7/eff:0.29(challenged)/…

Challenged cells sink in ranking, supported cells hold, and writers with a record of overconfidence get discounted. All of it is deterministic and runs offline.

Runtime state stays local and is git-ignored by default:

.recall/recall.sqlite3      # primary graph
.recall/secrets.sqlite3     # encrypted secrets side graph

Back up or move a graph with the portable archive path:

recall export > recall-export.json
recall import --json recall-export.json --db .recall/restored.sqlite3

Undo a bad write through the rollback journal:

recall rollback list
recall rollback show <journal-id>
recall rollback apply <journal-id>

See Backup And Recovery for the full restore path, including file-level SQLite copies and upgrade safety.

Demo

Change your mind without losing the past. Recall's moat is supersession: a correction is never an overwrite. You admit a new cell that --contradicts the old one, and every future read demotes the superseded value instead of deleting it; the conflict resolves automatically, at read time.

▶ Click the frame (or open assets/recall-supersede-demo.mp4) for a ~17s screencast, a real, unedited recall run:

• v1: "Cache TTL is 60s" lands at full strength (eff:0.70).
• v2 --contradicts v1: "…is 300s." Read it back and compile doesn't return both as equals: v1 is demoted to eff:0.29(challenged), v2 stays high. The old value is still in the graph: preserved, queryable, just down-weighted.
• v3 --contradicts v2: a 3-link chain. v1 and v2 collapse to eff:0; exactly one live answer remains, the why-we-changed trail intact.
• The run asserts a tripwire: the real graph was untouched (334 → 334, a throwaway db).

Demotion-not-deletion is the line between memory that merely persists and memory that stays honest, the whole point of Recall over a flat note file.

See it all working

Every Recall capability has a short, honest screencast: real CLI, real output, an isolated graph, with the full script and the unedited transcript beside each clip. Browse them all in the companion gallery.

Hook up your agent

Routine memory is agent-managed through MCP. Users should not have to hand-save ordinary observations, decisions, risks, or tasks.

recall mcp config --db .recall/recall.sqlite3   # print an MCP config block
recall-mcp                                       # start the stdio MCP server

Paste the config block into any MCP-capable client (Claude Code, desktop apps, agent runtimes), then add the LLM System Prompt to your agent's instructions. The agent's loop becomes: compile, work, write back.

There are 42 MCP tools in total, covering status, hyperedges, programs, DAGs, evals, ACP agent coordination, and calibration. The LLM Integration Guide is the full operating contract, including the proposal shape.

The /recall command (Claude Code)

The repo ships a Claude Code slash command at .claude/commands/recall.md. Copy it into your own project, or make it global, and /recall becomes a one-word way to wire a session to Recall:

# global (available in every project):
mkdir -p ~/.claude/commands && cp .claude/commands/recall.md ~/.claude/commands/

# or per-project:
cp .claude/commands/recall.md /path/to/your/project/.claude/commands/

After the one-time MCP setup above, typing /recall resolves your store (RECALL_DB if set, otherwise the local .recall/recall.sqlite3), ensures it exists, compiles a context packet for what you are about to do, and hands the agent the compile, work, write-back loop. No schema to manage, no setup to repeat. /recall <topic> compiles for that topic; bare /recall orients on recent state. If your memory already lives in a shared or global store, export RECALL_DB so /recall targets it instead of minting an empty local db.

One-command agent integration (Claude Code & Codex)

The MCP-config-and-system-prompt setup above is also available as a single idempotent command per agent runtime. scripts/install.sh runs these automatically (fail-soft) when the corresponding CLI is present, and you can re-run them anytime to refresh to the latest bundled version:

recall claude sync     # Claude Code
recall codex sync      # OpenAI Codex
recall claude status   # report which pieces are installed (codex status likewise)

Claude Code (recall claude sync) installs a SessionStart/UserPromptSubmit hook that nudges the agent to consult Recall, copies the recall skill into ~/.claude/skills/, registers the recall MCP server in ~/.claude.json, and sets CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 so Recall is the durable memory layer instead of Claude Code's built-in note memory (keep native auto-memory with RECALL_KEEP_AUTOMEMORY=1; revert with recall claude enable-auto-memory). Already accumulated native auto-memory? recall import auto-memory [--root path] [--project name] [--apply] [--db path] imports your ~/.claude/projects/<slug>/memory/*.md files into Recall as calibrated cells (dry-run by default; pass --apply to write). It is idempotent per file content, and a changed file supersedes its prior version via a contradicts edge, the migration wedge for owning your memory.

Codex (recall codex sync) copies the recall skill into ~/.codex/skills/, registers the recall MCP server under [mcp_servers.recall] in ~/.codex/config.toml, and injects a marker-delimited Recall directive into ~/.codex/AGENTS.md, Codex's always-read global instructions, the analog of Claude Code's SessionStart hook. Codex exposes no native-memory kill switch, so Recall is positioned as the durable memory layer at the prompt level via that directive. All edits are backed up before write, preserve your existing config, and are idempotent.

How it works

1. Propose. The LLM submits a recall.write.v1 proposal with content, evidence, confidence, provenance, and structured tags.
2. Admit. Admission validates the schema, applies firewall checks, attenuates unsupported claims, warns on near-duplicates, blocks secret-looking content, and journals a rollback entry.
3. Store. Memory persists as addressable cells and n-ary hyperedges in SQLite, reachable by address, tag, relation, or semantic search.
4. Compile. The compiler builds a compact, task-specific packet under a word budget, listing each cell's challengers alongside it and computing each cell's effective confidence from the live graph.
5. Maintain. A quiet daemon runs stale-memory, contradiction, derivation, and eval passes outside the LLM, writing back through the same admission path as everyone else.

The base structure is a hypernetwork. DAGs are optional overlays for ordered workflows, evidence chains, and execution traces.

Hyperedges can also carry programs: declared, versioned, sandboxed operations (recall.program.v1) that run on demand. Bind a decision to its risks and verifications and the bundle can score itself. Because the score reads live effective confidence, it works as a tripwire:

recall program run <program-id>     # Friday deploy gate
  → averageEffectiveConfidence: 0.7, score: 0.827

# new evidence contradicts the load-test verification

recall program run <program-id>     # same gate, no model ran
  → averageEffectiveConfidence: 0.322, score: 0.638

recall program run <program-id> --derive
  → derives a witness cell, filed through the same admission gate as any
    other write

Other memory systems store relations as passive records that only an external model can act on. Here, a deploy gate's score falls on its own when any member is contradicted, whether by a teammate, another agent, or a failing test wired in through test-contradicts edges. See Advanced Graph Operations.

The watch operation turns a bundle into a standing reflex. It baselines against its own previous run (run history is the state, so no extra machinery is needed), trips when the bundle's live effective confidence moves more than delta, and derives nothing otherwise. A quiet watch means the value was checked and had not moved.

recall program add <hyperedge-id> --json watch.json
  # { "schemaVersion": "recall.program.v1", "operation": "watch",
  #   "params": { "delta": 0.15, "concernTarget": "<decision-cell-id>" } }

recall program run <program-id> --derive
  → untripped: derives nothing
  → tripped:   files a concern against the target decision, through the
               same admission gate as every other write, attributed to
               program:<id>

A tripped watch does not modify its target. It files a concern through admission like any other writer, which means reflexes carry produced_by and accumulate a calibration record. A watcher whose concerns keep getting refuted gets discounted by the same loop that scores humans and LLMs. Watches can chain: a verification collapses, its watcher files a concern on the decision built on it, that decision's effective confidence falls, and a watcher on the decision can fire next. Run a watch from cron and a standing decision becomes a monitored service.

Two more operations round out the set:

• drift is watch with attribution. A tripped run names which member moved (topMover, plus a ranked movers list), so you can see what caused a gate to fall.
• quorum is k-of-m sign-off as a graph object. A member counts as an approval when its live effective confidence clears minEff, counted across distinct actors so one writer cannot stack the gate. If an approver's cell is later contradicted, its effective confidence drops and the approval stops counting, with no policy code involved. Quorum runs always derive their attestation.

Compile packets carry a standing_programs section listing the gates, watches, and quorums covering each returned cell, with program and bundle handles, so an agent writing new evidence can tie it into the existing bundle instead of orphaning it. Deeper concepts live in the docs: the write schema, tagging & subgraphs, the context compiler, and cells & graph views.

Inception: grounded synthesis

recall incept is an experimental primitive for synthesis rather than retrieval. It compiles a slice of the graph for an open objective, then emits a write-back template whose depends_on is pre-populated with the slice's cell ids. A model fills in the synthesis (a method, a connection, an insight implied by a contradiction between cells) and admits it. Because the template is pre-grounded, any cell created this way is born linked to the sources it was synthesized from.

The generative step stays in the model on purpose. Recall gathers the slice, guarantees the grounding, and admits the result, but it does not synthesize, because putting a model in the runtime would break the no-model trust loop. The new cell lands as a hypothesis at conservative confidence, marked unverified, so it enters the graph and earns or loses trust over time through the same effective-confidence machinery as any other write. The model synthesizes, Recall grounds it and lets the graph vet it.

recall incept "novel approaches given what we know about X and Y"

Why Recall

Recall makes a few opinionated bets that most memory layers don't:

The common thread is auditability: provenance on every cell, a firewall on every write, and a packet you can actually read.

How Recall compares

The main design split in agent memory is how trust changes when new information arrives. The field has three mechanisms:

Other systems ask a model what to believe. Recall computes it.

The rest are architectural design properties, not benchmark claims. Pick the tool that matches how much you care about auditability and local control.

Tiered, agent-navigated retrieval is an emerging pattern across the field. Letta pages between memory tiers, and progressive-disclosure indexes are appearing elsewhere. Recall's difference is what sits at each tier: not auto-summaries of activity, but gate-vetted claims carrying live trust state, addressed in the same namespace the evidence machinery uses. The index layer tells the agent where digging is warranted, not just that it may dig.

Recall trades turnkey cloud convenience for local control and an audit trail. If you want a hosted, batteries-included memory service, projects like mem0, Letta, and Zep are excellent. Recall is the other kind of tool: the graph lives on your disk, every write comes with a receipt, and nothing in it is above being challenged.

One graph, many writers

Most memory layers assume one user and one assistant. Recall's write path was built for traffic. Humans, agents, CI jobs, the daemon, and tripped reflexes all write through the same admission gate, so every cell lands schema-checked, attributed, timestamped, and rollbackable no matter who sent it. That is what makes a single project graph safe to share: when a decision changes overnight, a teammate does not ask around in chat, they compile. The packet says who changed it, when, on what evidence, and what it contradicts. Run recall compile "what changed since Friday" on Monday morning and the briefing writes itself.

The gate is also vendor-blind. A proposal from GPT, Claude, Gemini, or a local model is the same recall.write.v1 JSON, judged by the same rules, landing in the same graph. Calibration then scores every writer separately, human or model, on one ledger. Route work to whichever model is cheap this month, and let track records rather than logos decide how much to trust what comes back.

It is tier-blind for the same reason. The write contract asks for discipline, not brilliance, so a small model can hold the same memory standards as a frontier one. And because the compile packet carries the team's accumulated judgment, including the calls, the risks, and the open contradictions, a cheap model starts its session with the same briefing an expensive one gets. The packet does the remembering so the model does not have to.

Standing programs turn the shared graph into something a team can watch without opening a terminal. The fully actuated setup puts the store on a box everyone can reach and lets the tripwires do the talking. Point the whole team at one graph by setting RECALL_DB once on the host: the CLI, the MCP server, and the helper scripts all read it, so agents, cron jobs, and exporters route to the same store with no per-command flag (pass --db when you want to override it). Then let a scheduler run each standing gate on a heartbeat. Every program run prints plain JSON, so it wires into whatever the room already watches with no integration to install:

export RECALL_DB=/srv/recall/payments.sqlite3   # one graph, whole team

# cron, every 10 min: trip the deploy gate, ping the channel
recall program run <watch-id> --derive \
  | jq -e '.run.output.tripped' >/dev/null &&
  curl -s -X POST "$SLACK_WEBHOOK" -H 'content-type: application/json' \
    -d '{"text":"Deploy gate tripped: the load-test verification moved."}'

# run history is a time series of gate scores (createdAt + output.current).
# An exporter scrapes it into Prometheus/Grafana, where alerting fires when
# a gate's effective confidence crosses your threshold.
recall program runs --limit 200

A panel of gate scores is the project's live status, read straight off the trust graph: each score is its bundle's effective confidence, so the board shows at a glance what is currently believed, what is contested, and what just moved. The tripped run has already filed its concern in the graph through admission, so Slack and Grafana are only the echo into the room, not the source of truth.

One caveat, stated plainly: today "shared" means the writers are processes on that one host. Team SSH sessions, CI jobs, agents running there, and the cron watchers all hit the same store over SQLite WAL, which handles the concurrency. Putting the file on a network share for many separate machines to write is not safe, by SQLite's own guidance. One graph served over HTTP with authenticated actor identity, so remote machines write without sharing the host, is next on the roadmap.

Beyond memory: Checker, Solver, and Lattice

Recall is the memory layer of a four-part system. The other three parts plug into the same graph through the same admission gate.

Checker is the verification layer, built on one rule: absence of refutation is not verification. It runs declared checks and stores honest verdicts (verified / refuted / unverifiable / error / partial) in a ledger, and its attestation is git-native: verify-commit refuses dirty trees and non-HEAD SHAs, gate --ref answers whether a specific commit is verified, and a fail-closed pre-push hook gates pushes on that answer. Checker emits typed checker-supports and checker-contradicts edges into the Recall graph, where they already count for more than peer testimony in effective confidence, and compile packets surface checker challenges on every affected cell. Verification is tied to an exact commit on a clean tree, not to a claim that the tests passed at some point.

Solver is the compute layer: a library of 96 small, fast, gated solvers spanning control theory, signal processing, estimation, and optimization. Kalman filtering, FIR/biquad, CORDIC, Goertzel, count-min sketches, matrix-free conjugate gradient, and an Ising/simulated-annealing tier that makes QUBO formulations practical where hand-rolled heuristics used to be the only affordable option. The CPU tier is plain C, the GPU tier is CUDA, and every solver is validated against a reference oracle before any speed number is trusted. Each solver carries an optimality contract declaring what class of claim its answers make: exact, tolerance-bounded, or heuristic. Results land in Recall as addressable, priced claims. The division of labor: the model formulates, Lattice maps the code, Solver computes, Recall remembers, Checker attests.

Lattice is the code-analysis layer, and the one part that is an enterprise capability rather than open source: access-gated, vetted, and not bundled in the OSS distribution. It ingests a codebase over the Language Server Protocol into the same typed hypernetwork Recall uses (symbols, modules, and the import, call, and reference edges between them), then runs structural analyses over that graph. impact returns a change's reverse-reachability blast radius before you edit; hunt ranks structural bugs, including cross-signal findings no single diagnostic shows, like an exported path that reaches unimplemented code; diagnose surfaces cycles, dead code, stubs, and coupling hotspots in one pass; plan lays out the ordered, verify-gated steps to land a change; and verify is a differential gate that reports only the structural regressions a change caused, measured against a git ref in a throwaway worktree. A gated security-audit mode maps attack surface and source-to-sink reachability for authorized review of your own code. Every finding carries the same explicit verified / not_verified contract Checker enforces: reachability tells you where to look, never that a bug is proven.

What sets it apart is where the findings go. Lattice grounds everything it computes: the hard combinatorial step (the minimum feedback arc set that breaks a dependency cycle) routes to Solver's gated QUBO tier and is verified locally before it is trusted, and results land in Recall as addressable, evidence-weighted cells through the same admission gate as every other write. A structural regression stops being a console warning that scrolls away and becomes a cell with provenance that a deploy gate can score and a teammate can compile tomorrow. It ships an MCP server built for the agent edit loop (ask impact before an edit, gate with hunt after), served in milliseconds off a graph ingested once and cached.

Together they cover memory, verification, computation, and code structure behind one write path, with no model in the loop.

Checker org capabilities, Solver access, and Lattice (enterprise): todd@hendrixxdesign.com

CLI cheat sheet

# inspect
recall version
recall status
recall tui [--watch]

# retrieve
recall search "query"
recall semantic "query"
recall subgraph --project Recall --category memory --subject compiler
recall compile "task description" --words 900
recall incept "open objective"        # compile a slice into a grounded synthesis template

# write (agent/debug path; normal memory flows through MCP recall_write)
recall validate --json proposal.json
recall admit    --json proposal.json

# backup / restore
recall export > recall-export.json
recall import --json recall-export.json --db .recall/restored.sqlite3
recall import auto-memory [--project name] [--apply]   # import Claude Code auto-memory files as calibrated cells (dry-run default)

# undo
recall rollback list
recall rollback show <journal-id>
recall rollback apply <journal-id>

# advanced graph runtime
recall hyperedge add --json hyperedge.json
recall program add <hyperedge-id> --json program.json
recall dag analyze <overlay-id> --derive
recall eval run --derive
recall operate once --derive

# health & trust
recall beliefs
recall calibration
recall maintenance --derive
recall repair [--apply]               # prune dangling/unresolvable trust edges (dry-run default; --apply deletes)

# daemon
recall daemon run-once [--derive]
recall daemon run --interval-ms 60000

# secrets (encrypted side graph, explicit confirmation required)
printf 'password\nsecret-value' | recall secrets save \
  --title "service token" --confirm-secret-save --password-stdin --value-stdin

Run recall help for the full command surface, or see the CLI & TUI reference.

Benchmarks

Recall ships a reproducible public benchmark: a synthetic corpus in a throwaway database, measuring latency and throughput across the operational surfaces (admit_write, search, semantic, compile, paging, daemon and operator passes, secrets):

Numbers vary by machine. The point is that anyone can rerun the measurement. See Public Benchmark for methodology.

Documentation

Start with the docs index, which routes by purpose and by audience. Highlights:

• Installation Guide
• Architecture
• Strict Write Schema, the recall.write.v1 contract
• Context Compiler
• LLM Integration Guide · LLM System Prompt
• Secrets Side Graph
• Daemon, MCP & Semantic Search
• Public Benchmark
• Backup And Recovery

Development

npm install
npm run build     # tsc
npm test          # 162 unit/integration tests
npm run e2e       # 94 end-to-end checks across user + agent workflows
npm run smoke     # init + status on a throwaway db
npm run smoke:mcp # stdio MCP initialize + tools/list smoke
npm run test:python
npm run verify:full

Contributions are welcome. See CONTRIBUTING.md and the Code of Conduct. Keep changes schema-first, small, tested, and aligned with the single-runtime architecture. A good first PR runs npm test && npm run e2e clean; release-readiness changes should run npm run verify:full. The Roadmap lays out direction by ring: Foundation, Runtime, and Interfaces. Working in this repo with an AI agent? Point it at AGENTS.md.

Security

Read SECURITY.md before using Recall with sensitive data. Important defaults:

• runtime databases and logs are git-ignored
• primary-graph writes reject secret-looking content, matched against a broad set of credential shapes (cloud keys, vendor tokens, JWTs, private-key blocks, and secret-named assignments) and tuned to never trip on the graph's own cell ids
• encrypted secret saves require explicit confirmation
• primary-graph writes are schema-validated and rollbackable

Report vulnerabilities via GitHub Security Advisories. See the policy for details.

Project status

Recall is an early working runtime foundation. It is suitable for local experimentation and integration work, and it does not claim production-grade or state-of-the-art behavior without external benchmarks and deployment review. Interfaces may change before a stable release. Treat compiled context packets as evidence, not unquestionable truth, which is how Recall is designed to be used anyway.

Citation

If Recall helps your work, please cite it. See CITATION.cff or use GitHub's "Cite this repository" button.

License

Recall is licensed under the Apache License 2.0. See NOTICE.