Recall

For paused native builds and explicit production requests, see CI cost policy.

Cross-tool coding memory + instruction compiler.

Recall is a local repo-memory compiler for coding agents. It learns from corrections, review feedback, repo scans, and session outcomes, then injects compact trusted instructions through CLI, MCP, daemon endpoints, and lifecycle hooks.

• Website: https://recallmemory.dev/
• Recall Cloud login: https://app.recallmemory.dev/login
• Support: mailto:[email protected]
• Releases: https://github.com/edihasaj/recall/releases
• Contributing: CONTRIBUTING.md
• Comparison vs other memory systems: benchmark/COMPARISON.md

Why Recall?

You correct your agent. Next session it forgets. You correct it again. Recall captures the durable rules hidden in those corrections — once — and re-injects them every session via lifecycle hooks. Local-first, no cloud, no API keys required for the common path.

The story in 3 lines:

recall correct -r owner/repo "don't use npm, use pnpm"   # one correction
# next session start:
# → SessionStart hook fires, injects:  "- use pnpm as the package manager"
# → your agent never reaches for npm again

Web Dashboard

The bundled web dashboard (open via the menu bar item Open Dashboard in Browser, or recall webui start) is the fastest way to see what Recall has learned: memories, the knowledge graph, recent activity, and live sessions across every agent that hits the daemon.

Knowledge graph	Timeline	Sessions

• Graph — 2D layered view by entity kind plus a 3D force layout (toggle in the toolbar). Repo + kind dropdowns and a contains-match name search filter the visible set; click a node to drill into linked memories and neighbours.
• Timeline — filterable feed of every daemon event (compile, query, scan, correction, feedback, tool calls…). Click a row to expand the full request/result JSON; jump straight to the linked memories or pivot into the session view.
• Sessions — every distinct session Recall has seen across MCP, hooks, and CLI traffic, with duration, event count, and type breakdown. Expand a session to see its events inline or hand it off to the Timeline filtered by session_id.

Benchmarks

LongMemEval-S answer accuracy

Recall answered 474 of 500 LongMemEval-S questions correctly (94.8%) in its best experimental run.

Best of two runs of the same setup (474 and 470), answered and judged with Qwen. Other scores are as published by Hindsight with different models, so this is not a head-to-head test. See the results, everything we tried and how we measured it.

A separate Cloud Linux backend evidence evaluation also scored 474/500, with Qwen answering and judging. See its configuration and scope.

Retrieval vs agentmemory

LongMemEval-S, N=500, including 30 unanswerable question IDs. Same dataset agentmemory publishes; these are retrieval metrics, not answer accuracy.

The MiniLM row isolates the system contribution (same embedding model agentmemory uses); the e5 row is what Recall actually ships with. Full numbers, per-type breakdown, ablation, methodology → benchmark/COMPARISON.md.

Install

Cloud is optional. Connecting a server-readable Cloud account enables syncing and online retrieval, which sends agent question text to your configured Cloud. Turn retrieval off independently in the Cloud tab or with recall cloud-query off. Existing explicit off settings are preserved.

For private backup and device sync, choose Private sync · local search in the Mac app. Memory text, notes and evidence are encrypted before upload; search runs on your device, including offline after sync and indexing. Save the same passphrase for every device. Hosted MCP and Cloud search require the separate server-readable mode. See private Cloud sync for recovery and the limits of this privacy boundary.

Mac App Store edition

The sandboxed store edition, Recall: Coding Memory, has the same window as the direct app. Version 2.0.7 was rejected on 15 October 2026 (Guidelines 4.3 and 4.2.6); 2.0.14 (1) was uploaded on 23 October 2026 and is not yet submitted. It will be free and publish automatically after approval. It includes its own runtime and connects agents through local HTTP. Memory is stored in the app container, and repository access is granted through a folder picker. See store release and connection details.

Homebrew (macOS)

brew tap edihasaj/tap
brew trust --cask edihasaj/tap/recall
brew install --cask edihasaj/tap/recall
recall setup --yes
recall doctor

Homebrew 7+ requires explicit trust for third-party packages. These commands trust only the Recall cask. Run brew update first if brew trust is unavailable.

Recall checks for complete releases in the menu bar and dashboard. A Homebrew installation can update from the dashboard's Updates page; Recall installs the cask, restarts its daemon, and reopens the app. Direct .app installs in a writable /Applications folder also update in-app. Recall verifies the archive checksum, its Apple developer signature, and notarization before replacing the app. It restores the previous app if the new daemon cannot start.

Bash one-liner (macOS, Linux)

curl -fsSL https://recallmemory.dev/install.sh | bash

Runs npm i -g @edihasaj/recall + recall setup --yes for you, then prints next steps for the optional background service.

npm (macOS, Linux)

npm i -g @edihasaj/recall
recall setup --yes
recall doctor
# Optional: run as a background service
recall daemon install            # launchd on macOS, systemd --user on Linux

On Linux, recall daemon install writes ~/.config/systemd/user/recall-daemon.service and enables it. Logs: journalctl --user -u recall-daemon.

PowerShell (Windows)

irm https://recallmemory.dev/install.ps1 | iex

Installs the @edihasaj/recall CLI via npm, downloads the system-tray companion (recall-tray-<arch>.exe) into %LOCALAPPDATA%\Programs\Recall, registers a per-user Run-key entry for autostart, and launches the tray. Supports arm64 and amd64. The tray shows Update Recall when a complete release is ready; it opens the same installer in a separate PowerShell window, after the tray exits. Re-running the installer also updates an existing installation, with a database backup and package and tray checksum checks. Logs land in %LOCALAPPDATA%\Recall\.

GitHub Releases

Download Recall.app.zip, unzip it, move Recall.app into /Applications, then run setup:

open /Applications/Recall.app             # click Install + Start once
recall setup --yes
recall doctor

Install + Start exposes the bundled Node 22 CLI at ~/.local/bin/recall. The Homebrew cask links the same bundled launcher automatically.

Source

git clone https://github.com/edihasaj/recall.git
cd recall
nvm use
npm ci
npm run build
npm link

Source development expects Node 22, matching the bundled app runtime. If tests fail with a NODE_MODULE_VERSION error from better-sqlite3, switch to Node 22 and reinstall dependencies so the native module ABI matches the test runtime.

Build macOS App From Source

Build the macOS app bundle:

npm run build:app

scripts/build-app.sh embeds Node 22. It prefers RECALL_NODE_PATH=/path/to/node when set, otherwise the Node runtime from the currently installed /Applications/Recall.app, then your shell node.

Install it into /Applications:

npm run install:app

The app embeds its own Node runtime plus Recall dist/, drizzle/, and node_modules/, then manages the bundled daemon via launchd. When run from /Applications, the app registers itself as a login item by default so the menu bar status icon comes back after login; the daemon LaunchAgent remains the background worker. Preferences has two visibility switches: Show Dock Icon (off by default) and Show Menu Bar Icon (on by default). With both off, Recall keeps running in the background; open Recall.app again (Finder, Spotlight or Launchpad) to bring the dashboard back.

Configure local agent runtimes against the installed app. recall setup --yes wires MCP and lifecycle hooks for supported detected runtimes so memory injection does not depend on the model choosing to call query:

recall setup --yes                       # shared MCP + hooks for detected runtimes
recall setup --scope project --yes       # add project-scoped hooks to the current repo
recall setup --uninstall-hooks --yes     # remove Recall-managed hooks

By default the hooks inject a compact repo memory pack at SessionStart and relevance-scored matches on each UserPromptSubmit. To opt out of prompt-time injection or wire provider credentials so the daemon can run memory maintenance on a schedule, see docs/configuration.md.

Supported runtimes, and how deep the integration goes:

Runtimes without a lifecycle-hook API can't be called on prompt/tool/session events, so Recall installs a managed rules block instructing the agent to call capture_correction and query itself. Capture there depends on the model following it — the hook-based runtimes do not.

Codex profiles (multiple CODEX_HOMEs)

Codex supports multiple homes, and tools that drive it (Paseo, per-account setups) commonly point providers at ~/.codex-primary, ~/.codex-secondary, and so on. recall setup wires every profile it finds, not just ~/.codex:

• The default home (CODEX_HOME if set, else ~/.codex), plus any ~/.codex-* sibling that looks like a real Codex home (config.toml, auth.json, or sessions/). Backup-suffixed directories are skipped.
• Set RECALL_CODEX_HOMES to a :/, separated list to override discovery.
• Profiles that share a symlinked config.toml are written once, and the symlink is followed rather than replaced — so a shared-config layout stays shared instead of forking into diverging copies.

Install + setup behavior:

• Routine app launch, daemon start, and daemon restart are non-mutating for agent integrations. They do not re-add hooks or repo instruction files after you remove them.
• Memory "rethinking": when provider credentials are stored, the daemon runs the dispatcher daily (tunable via RECALL_DISPATCHER_INTERVAL_SECONDS) to refine/merge/summarize memories. Use recall maintenance credentials --help for provider-specific fields. Observability: recall maintenance usage, recall maintenance stats. Without a key, pending tasks surface via SessionStart for the live agent to claim.
• recall doctor checks install state; recall doctor --fix or recall setup --yes wires MCP + hooks for supported agent runtimes.
• Repo-local .recall/context.md is an optional export/fallback, not the primary integration.

Permanently erase local data

Preview every local item Recall will remove:

recall data purge --dry-run

Then permanently erase it:

recall data purge --yes

The purge removes the entire Recall data directory, including the database, WAL files, backups, logs, caches, local models, and sync state. It also removes Recall-managed Keychain credentials, generated .recall/context.md exports, the daemon service, agent hooks and rules, and Recall MCP registrations. The Recall executable or app remains installed. The command is safe to rerun and supports --json for automation. Use --keep-integrations only when you want hooks and MCP wiring to remain and recreate a clean local store on next use. Environment variables and user-authored files are never rewritten.

First Run

Initialize DB:

recall init

Scan a real repo:

recall scan ~/Projects/some-repo
recall list
recall publish ~/Projects/some-repo

If an unseen repo is later queried through the daemon or MCP, Recall now tries a lazy one-time bootstrap by resolving the local clone and scanning just that repo. Recall can also publish repo-local context into .recall/context.md; treat it as an optional export/fallback, not the primary agent integration. Bootstrap now keeps operational commands hot and leaves softer scan facts as candidates or drops them during maintenance cleanup.

Inspect quality / health / injection pack:

recall quality -r owner/repo
recall health -r owner/repo
recall maintenance quality
recall eval value-retrieval --snapshot
recall maintenance quality --history
recall reliability
recall reliability --canary --real-embeddings
recall compile -r owner/repo
recall compile -r owner/repo --query "pytest -q" --include-candidates

Bootstrap local embeddings and the derived sqlite-vec index:

recall doctor
recall embeddings setup
recall embeddings info
recall embeddings bootstrap
recall embeddings verify
recall embeddings rebuild-index
recall search -r owner/repo "pnpm"

Optional embedding env vars:

RECALL_EMBEDDING_PROVIDER=multilingual-e5
RECALL_EMBEDDING_DIMS=384
RECALL_EMBEDDINGS_DISABLED=true

Windows x64 and ARM64 support local vector retrieval. Native ARM64 uses a bundled ARM64 extension; other platforms keep the existing sqlite-vec loader. This update preserves existing databases. If the native extension is missing or cannot load, Recall keeps lexical retrieval available and reports the reason in /health. See storage strategy.

Daemon maintenance runs in-process on a timer.

Useful env vars:

RECALL_MAINTENANCE_INTERVAL_SECONDS=3600
RECALL_ACTIVITY_RETENTION_DAYS=30
RECALL_FEEDBACK_RETENTION_DAYS=180
RECALL_SIGNAL_RETENTION_DAYS=180
RECALL_SQLITE_VACUUM_ENABLED=true
RECALL_SQLITE_VACUUM_MIN_FREE_PAGES=100
RECALL_SQLITE_VACUUM_MIN_FREE_RATIO=0.1
RECALL_CANDIDATE_UNCONFIRMED_DAYS=30
RECALL_RELIABILITY_PROBE_ENABLED=true
RECALL_RELIABILITY_PROBE_INTERVAL_SECONDS=86400
RECALL_RELIABILITY_PROBE_REAL_EMBEDDINGS=true

recall reliability separates compiler selection, hook emission, observed use, and resolved outcomes. The daily probe checks the live database, newest backup, and a disposable real-vector canary. See Reliability and uncertainty.

Inspect rolled-up session history:

recall history list -r owner/repo
recall history search -r owner/repo "pnpm"

Session history rolls up corrections, review feedback, compile observations, and durable user decisions/directions from prompt activity. Compiled context includes a small relevant history section so decisions can be reused without promoting every prompt into a durable memory. History injections are tracked separately from memory injections in recall maintenance quality.

Run retrieval eval fixtures:

recall eval retrieval --file docs/retrieval-eval.example.json
recall eval retrieval --file docs/retrieval-eval.example.json --json
recall eval retrieval --file docs/retrieval-eval.recall.json
recall eval retrieval --file docs/retrieval-eval.recall-hybrid.json

For facts that change over time, the experimental local MCP tools temporal_remember and temporal_query preserve dated evidence and support explicit historical queries. See temporal assertions and comparison methodology for semantics, current boundaries, and the synthetic benchmark.

Teach It

Add a correction:

recall correct -r owner/repo "don't use npm, use pnpm"
recall list -r owner/repo

Confirm a memory manually:

recall confirm <memory-id>

Report review feedback:

recall review -r owner/repo "review said use error boundaries"

Quality Model

recall quality shows:

• stage: cold | growing | mature
• quality score
• repeat sessions needed before promotion
• compile confidence threshold
• dedup similarity threshold

Behavior:

• cold repos learn faster
• mature repos need more repeat evidence
• noisy repos inject less aggressively

Daemon

Start HTTP daemon:

node dist/daemon.js

Install as a user service (launchd on macOS, systemd --user on Linux; on Windows the tray app supervises the daemon — see the PowerShell installer above):

recall daemon install
recall daemon status

Useful service commands:

recall daemon start
recall daemon stop
recall daemon uninstall

Inspect hook telemetry:

recall hook stats
recall hook stats --agent codex
recall hook stats --json

Default URL:

http://localhost:7890

Useful endpoints:

curl -s http://localhost:7890/doctor
curl -s http://localhost:7890/update
curl -s 'http://localhost:7890/quality?repo=owner/repo'
curl -s -X POST http://localhost:7890/compile \
  -H 'Content-Type: application/json' \
  -d '{"repo":"owner/repo"}'

curl -s -X POST http://localhost:7890/correct \
  -H 'Content-Type: application/json' \
  -d '{"repo":"owner/repo","session_id":"s1","text":"don'\''t use npm, use pnpm"}'

GET /doctor returns the installed version, data path, detected agent setup, and upgrade signal as JSON. The Windows tray uses this local status report; recall doctor performs the full audit. GET /update compares the installed runtime with GitHub's latest complete release. It offers an update only after the package, macOS app, both Windows tray binaries, and the checksummed updater have finished uploading.

Session collector endpoints:

curl -s -X POST http://localhost:7890/session/start \
  -H 'Content-Type: application/json' \
  -d '{"session_id":"codex-1","client":"codex","repo_path":"'"$PWD"'"}'

curl -s -X POST http://localhost:7890/session/end \
  -H 'Content-Type: application/json' \
  -d '{"session_id":"codex-1","client":"codex","repo_path":"'"$PWD"'","payload":{"exit_code":0}}'

Optional repo-local context artifact:

recall publish .
cat .recall/context.md

Claude Code MCP

Recall supports both MCP transports:

• stdio: Claude Code spawns Recall directly. This is the most portable default.
• HTTP: Claude Code connects to the daemon at http://localhost:7890/mcp. This requires the Recall app/daemon to be running.

Packaged macOS app, stdio config:

{
  "mcpServers": {
    "recall": {
      "command": "/Applications/Recall.app/Contents/Resources/Runtime/bin/node",
      "args": ["/Applications/Recall.app/Contents/Resources/Runtime/dist/mcp.js"]
    }
  }
}

Source checkout, stdio config after npm run build:

{
  "mcpServers": {
    "recall": {
      "command": "node",
      "args": ["/path/to/recall/dist/mcp.js"]
    }
  }
}

Daemon HTTP config:

claude mcp add --transport http -s user recall http://localhost:7890/mcp

Equivalent JSON:

{
  "mcpServers": {
    "recall": {
      "type": "http",
      "url": "http://localhost:7890/mcp"
    }
  }
}

The rest of the daemon API remains available on the same port, for example /health, /compile, and /session/start.

Useful MCP tools:

• query
• report_correction
• capture_correction
• report_review
• signal_outcome
• session_end
• quality
• list
• confirm

Session Wrappers

Use the thin wrappers in scripts/ if you want Recall to auto-learn from session starts before retrieval is useful:

scripts/recall-codex
scripts/recall-claude

They:

• send /session/start with the current git root or pwd
• let the real client run normally
• send /session/end with the final exit code

Override targets if needed:

RECALL_CODEX_BIN=/path/to/codex scripts/recall-codex
RECALL_CLAUDE_BIN=/path/to/claude scripts/recall-claude
RECALL_DAEMON_URL=http://localhost:7890 scripts/recall-codex

MCP First

Recommended production pattern:

• run Recall locally via /Applications/Recall.app
• let agents query/live-report through Recall MCP
• treat .recall/context.md as optional export/fallback, not the primary path

Fast Test Loop

recall init
recall scan ~/Projects/some-real-repo
recall quality -r owner/repo
recall compile -r owner/repo
recall correct -r owner/repo "don't use npm, use pnpm"
recall list -r owner/repo

If you want repeated-session promotion testing, use the daemon /correct endpoint with different session_id values.

Development

npm ci
npm run docs:check
npm run typecheck
npm test
npm run build

Release and Homebrew publishing notes live in docs/RELEASING.md. The landing page is static HTML/CSS in docs/ and deploys with GitHub Pages. Public crawl configuration lives in docs/robots.txt, with canonical landing-page URLs listed in docs/sitemap.xml.

IndexNow ownership is not committed to the repository. The Pages workflow writes the public /<key>.txt verification file into the uploaded site at deploy time from the repository secret COMPASS_INDEXNOW_KEY, the shared Compass portfolio key. Runs without that secret skip the step and publish the site unchanged.