Installation

This guide covers everything needed to install Recall: prerequisites, what the installer does, verification, session extraction setup, and environment variables.

First run? Walk through Getting Started for install, first commands, where the database lives, how a session starts, and how MCP/hooks get wired.

Not sure which command to run (install vs. update vs. uninstall, source checkout vs. local tarball, re-install, custom DB path, recovery)? See Managing Recall — which command do I run? for the decision table.

Prerequisites

Install these before the source checkout or a local tarball link, and before recall install. Items marked Optional enhance Recall but are not required for core functionality.

Supported platforms: macOS 13+ (Apple Silicon and Intel) and Linux (Ubuntu 22.04+, Debian 12+).

Bun (JavaScript runtime)

Recall uses Bun for TypeScript execution and bun:sqlite for the database. Minimum version: 1.0+.

# macOS (Homebrew)
brew install oven-sh/bun/bun

# Linux / macOS (curl)
curl -fsSL https://bun.sh/install | bash
source ~/.bashrc   # or: source ~/.zshrc on macOS

Verify: bun --version — bun.sh

Node.js

Required for a source checkout. bun run build runs node after tsup to rewrite shebangs. Putting recall and recall-mcp on PATH is bun link; npm link is only the fallback when that link does not verify.

# macOS (Homebrew)
brew install node

# Linux (Ubuntu/Debian — via NodeSource)
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs

# Any platform (nvm)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash
nvm install --lts

Verify: node --version — nodejs.org

Claude Code

Recall is an extension for Claude Code. You need a working Claude Code installation with an active Anthropic API subscription or Claude Pro/Max plan.

# macOS / Linux
npm install -g @anthropic-ai/claude-code

Verify: claude --version — docs.anthropic.com

Preferred attach is the native plugin, not this installer: see Claude Integration. The installer still owns Claude lifecycle hooks.

OpenCode (Optional)

If OpenCode is installed, Recall registers its MCP entry and native plugins. The integration requires the supported opencode CLI and Bun on PATH; the plugin uses opencode export <session-id> (JSON) and converts the result into a markdown drop for the shared batch extractor. Verify with opencode --version. Use the interactive installer and leave OpenCode unselected when it should remain untouched. ./packaging/install.sh has no --skip-opencode flag (--yes configures every detected agent). Uninstall can still skip it with ./packaging/uninstall.sh --skip-opencode.

Grok Build CLI (Optional)

If grok is installed, Recall adds the managed user-level lifecycle hook documented in Grok Integration. The hook exports completed sessions through the public Grok CLI and writes them immediately to recall.db. It does not add automatic session-start injection.

Verify with grok --version. Deselect Grok in the interactive installer when it should remain untouched. Grok has no working plugin/extension install path; this installer is the only supported attach. See Grok Integration.

Claude Code, Codex, Pi, and omp prefer their native plugin/extension. omp capture is a separate native package attach; the installer only owns its skill links. Cursor stays snippets under templates/cursor/ with no marketplace plugin. See the README Quick Start, Codex Integration, Pi Integration, omp Integration, and JCode Integration.

Fabric (Optional — recommended)

Fabric is the fabric Extractor for Curated LoA (recall loa, dump extract). Automatic-capture LoA does not use Fabric. Requires Go 1.22+.

# macOS / Linux (Go required)
go install github.com/danielmiessler/fabric@latest
fabric --setup

Verify: echo "test" | fabric --pattern extract_wisdom — github.com/danielmiessler/fabric

Ollama (Optional — enables semantic search)

Vector embeddings enable semantic search: finding related content even when exact keywords do not match. Without Ollama, Recall uses keyword search only (FTS5), which works well for most queries.

Model: qwen3-embedding:0.6b — 1024-dimension embeddings, approximately 640 MB.

# macOS (Homebrew)
brew install ollama
ollama pull qwen3-embedding:0.6b

# Linux (curl)
curl -fsSL https://ollama.ai/install.sh | sh
ollama pull qwen3-embedding:0.6b

Verify: curl http://localhost:11434/api/tags — ollama.ai

Set OLLAMA_URL if Ollama runs on a different host (default: http://localhost:11434).

Install Recall

Recall has one install root: ~/.agents/Recall. The runtime tree is not relocatable. RECALL_DB_PATH, recall install --db-path, and ./packaging/install.sh --db-path may place the SQLite database elsewhere; they do not move the install root.

Recall itself is not published to npm; the recall-memory package there is an unrelated project (see #312). Use a source checkout for the canonical install, or a local tarball when you need a packaged global binary.

Local tarball

Retain the permanent checkout described under Source checkout. Keep the tarball at ~/.agents/Recall/packages/recall-memory.tgz for as long as Recall is installed globally. For upgrades, replace that file, remove the existing global dependency, then reinstall. Installing again without removal can leave the old version at the same path or duplicate dependency keys at a different path.

Before the first pack and every later update, refresh that checkout so the tarball contains the intended release. On the first install, skip bun remove -g recall-memory:

cd /absolute/path/to/Recall
git fetch --tags origin
git switch main
git pull --ff-only origin main
bun install
bun run build
package_dir="$HOME/.agents/Recall/packages"
mkdir -p "$package_dir"
archive="$(npm pack --pack-destination "$package_dir")"
mv "$package_dir/$archive" "$package_dir/recall-memory.tgz"
bun remove -g recall-memory
bun install -g "$package_dir/recall-memory.tgz"
recall init

bun install -g records that absolute tarball path, and bun update -g re-extracts it. If the file is gone, bun update -g fails for every global package with ENOENT extracting tarball from recall-memory. Recover by following the upgrade recipe above, including removal before reinstalling.

Continue with the applicable integration guide: Claude Code, Codex, Pi, omp, or Grok. Each guide owns its host’s attach commands and whether it also needs recall install. In packaged (tarball) mode, recall install runs packaging/install.sh with RECALL_PACKAGED=1, skipping clone, dependency installation, build, and link.

Source checkout

Clone into a permanent directory, not /tmp. This directory is also the local marketplace root:

git clone https://github.com/edheltzel/Recall.git
cd Recall

Claude Code users must complete the plugin attach in Claude Code Integration before installer-owned setup. Other hosts can run the source installer now, then continue with their integration guide:

./packaging/install.sh

The script runs bun install, builds Recall, links recall / recall-mcp, and performs installer-owned setup. Later updates use recall update, which refreshes the checkout before rebuilding.

Install flags

Note: Do not clone to a temporary directory. bun link creates symlinks back to the clone location — if the directory is removed (e.g. on reboot), recall commands will break.

The installer auto-detects your OS (macOS or Linux) and runs these steps:

After install: Restart each configured host to load its integration.

Claude plugin ownership detection fails closed. If its state files are unreadable or invalid, the installer returns an error before ownership-dependent skill or MCP changes. See Claude Code Integration for the state rules and recovery.

Installation Flow

flowchart LR
    A[packaging/install.sh] --> B[Backup existing files]
    B --> C[bun install]
    C --> D[bun run build]
    D --> E[bun link]
    E --> F[recall init\nInit DB]
    F --> G{Claude plugin state?}
    G -->|Active| H[Reconcile plugin MCP and skills]
    G -->|Absent or disabled| I[Register MCP and link skills]
    G -->|Unreadable or invalid| X[Stop before ownership-dependent changes]
    H --> J[Register installer-owned hooks]
    I --> J
    J --> K[Copy Guide\nRecall_GUIDE.md]
    K --> L[Configure Memory Pointer\nor defer to managed Recall rule]
    L --> M[Reconcile Quarterly Aging Cron]
    M --> N[Done\nRestart Claude Code]

Verify Installation

After the installer completes and you have restarted Claude Code, run these checks:

which recall recall-mcp          # Both CLIs should resolve to a path
ls -la ~/.agents/Recall/recall.db # Database file should exist
recall stats                  # Should return record counts (zeros on fresh install)
recall doctor                 # Full health check — database, MCP, hooks, embeddings

recall doctor is the authoritative health check. Run it first any time something seems wrong.

Recommended: seed your L0 identity tier

Recall’s supported session-start integrations inject a small user-authored identity file at the top of a session (the L0 tier). Without it, the L0 section is empty and the v2 tiered context is only half-populated.

recall onboard                 # Interactive 7-question interview
recall onboard --print --yes   # Preview what would be written (no side effects)

Global onboarding uses the same resolver as RecallStart. An existing user-owned ~/.claude/MEMORY/identity.md remains authoritative; otherwise the path is the canonical file under the Recall install root, ~/.agents/Recall/MEMORY/identity.md. A managed Claude link, when present, exposes that same canonical file. --project instead writes ./.atlas-recall/identity.md. Files exceeding 1200 characters are silently truncated at load; the command warns if your rendered output exceeds that limit.

Session Extraction

Session extraction runs automatically after every Claude Code session ends. No manual steps are required.

When a session ends, the Stop hook triggers RecallExtract.ts, which:

1. Reads the session’s JSONL conversation file from ~/.claude/projects/
2. Extracts the text content (skipping tool results and thinking blocks)
3. Runs the Automatic-capture Extractor (default claude-cli, then ollama, unless extraction.automatic is set)
4. Applies a quality gate — rejects extractions missing required sections
5. Appends results to six memory files in ~/.claude/MEMORY/ (full archive, hot recall, session index, decisions, rejections, error patterns)
6. Tracks extraction state per-file to prevent duplicates and enable 24-hour retries

If claude-cli is unavailable, the hook falls back to a local Ollama model. Set Recall_OLLAMA_MODEL to change which model is used (default: qwen2.5:3b). A present extraction.automatic list replaces that cascade. A missing key keeps it. See architecture. OLLAMA_URL is the shared Ollama endpoint (embeddings and automatic ollama Extractor).

The hook self-spawns in the background so the session exits immediately — extraction is non-blocking.

Optional: Batch Extraction (cron)

The RecallBatchExtract.ts script catches any sessions that the Stop hook missed (e.g. if Claude Code was force-quit). Set it up as a cron job:

crontab -e
# Add this line (runs every 30 minutes):
*/30 * * * * ~/.bun/bin/bun run ~/.claude/hooks/RecallBatchExtract.ts --limit 20 >> /tmp/recall-batch.log 2>&1

Quarterly aging (cron)

Install schedules recall age --execute at 0 3 1 1,4,7,10 * (03:00 on the 1st of January, April, July, and October) when the package that ran install is a durable source checkout or the Bun-global package. A stale ~/.bun/bin/recall is not used. The crontab line is fixed text, so a user SHELL setting does not change how the job starts:

0 3 1 1,4,7,10 * /bin/sh '/Users/you/.agents/Recall/shared/age-quarterly.sh' # recall-memory: quarterly age

/bin/sh runs the absolute wrapper path ~/.agents/Recall/shared/age-quarterly.sh (mode 0700). Install replaces the first active marked line in place and removes duplicate active entries, so a CRON_TZ line above it still applies. It appends only when no marked line exists. update.sh rewrites the wrapper and refreshes active marked entries only after verification succeeds. Deleting all marked lines prevents update from adding the job again; a later install can add it.

Install and update preserve every marked line whose first non-space character is #. When all marked lines are commented, preview and completion report Quarterly aging: disabled by user, kept and leave the wrapper unchanged. When active and commented marked lines coexist, active entries are refreshed and reported as scheduled, while commented lines remain unchanged.

Interactive install and update confirmations show the planned crontab action. An add or refresh preview also shows the schedule, command, and selected database. Preview and apply use the same classification. Previews for source installs and updates account for the planned build; applying the schedule requires the built runner to exist.

The wrapper exports RECALL_DB_PATH and execs the installing package’s dist/index.js through bun, appending to ~/.agents/Recall/logs/age.log. Install and update prefer an explicit RECALL_DB_PATH override, then MEM_DB_PATH, then the database stored in an existing wrapper. Without those, they use Claude MCP database selection, which falls back to the default when no custom pin exists. Relative overrides are stored as absolute paths; stored wrapper and MCP paths must already be absolute. For database relocation, use recall migrate.

Paths inside the wrapper may contain spaces, quotes, and %. A newline in a path is rejected. If the install root contains %, ', or a control character, scheduling is rejected. Install and update report the reason without changing an existing schedule. An unsupported runner keeps an existing job; when no job exists, they print NOT scheduled and tell you to run recall install after making it durable. If crontab cannot be read or updated, the existing schedule is left unchanged. If writing the wrapper fails after updating crontab, Recall attempts to restore the previous crontab; a failed restoration is reported explicitly with a crontab -e recovery instruction.

--skip-age-cron and uninstall.sh remove all active and commented marked lines and the wrapper when they can read and update the user crontab. If the lines are removed but wrapper deletion fails, aging is disabled and the leftover wrapper is reported. Other crontab lines are left alone. For aging behavior and safeguards, see Age.

Environment Variables

Set these in your shell profile (~/.bashrc, ~/.zshrc, ~/.config/fish/config.fish) if you need non-default values. The RECALL_DB_PATH variable is the most commonly changed — useful if you want to keep the database outside ~/.agents/Recall/. You can also pass --db-path /custom/path/recall.db to ./packaging/install.sh for non-interactive overrides.

When resolving RECALL_DB_PATH or its legacy fallback, the CLI, MCP server, hooks, and installer replace ~ with HOME and ~/rest with HOME plus /rest. The remaining text stays literal, including repeated spaces and .. segments; resolution does not normalize the path, evaluate shell syntax, or expand ~other. For example, export RECALL_DB_PATH='~/data/two spaces/recall.db' preserves both spaces. If both variables are unset or empty, Recall uses the default database path.

Backup and Restore

Install and update automatically create a timestamped backup before making changes, stored at ~/.agents/Recall/backups/. After each snapshot is created, rotation keeps the newest 2 full backups and also protects the backup named by latest if it is older.

Full backups eligible for rotation are non-hidden direct child directories containing manifest.txt and a non-empty recall.db or memory.db. Backups with no database or only an empty database do not count toward the retention limit. Rotation leaves directory symlinks, loose files (including recall export --backup dumps), and other directories untouched. A symlinked backup root is not pruned.

Restore saves the current files in pre_restore_<TIMESTAMP>/ without rotating existing backups. Rotation failures warn without failing install or update.

Automatic snapshots cover the existing files listed in FILES_TO_BACKUP. They do not include directories such as ~/.claude/MEMORY/; back up those separately.

CLI backup locations used by recall export --backup, recall scrub-archive, recall doctor --fix, and recall migrate use the current HOME value, falling back to the operating system’s home directory when it is unset or empty.

./packaging/install.sh list              # List available backups
./packaging/install.sh restore           # Restore from most recent backup
./packaging/install.sh restore 20260219  # Restore a specific backup by timestamp

Manual database backup:

cp ~/.agents/Recall/recall.db ~/.agents/Recall/recall.db.backup

Uninstalling

Recall ships an uninstall.sh that removes its integration surgically while preserving your memory by default. Exit Claude Code first, then:

cd /path/to/Recall
./packaging/uninstall.sh --dry-run        # preview what will change, touch nothing
./packaging/uninstall.sh                  # remove integration; preserve ~/.agents/Recall/ (DB + backups)
./packaging/uninstall.sh --purge          # also destroy ~/.agents/Recall/ tree (confirmed)

For a local-tarball install, run lifecycle cleanup while the CLI is available, then remove Bun’s global dependency:

recall uninstall
bun remove -g recall-memory

Use recall uninstall --purge for a purge, then run the same bun remove -g recall-memory. Purge deletes the retained tarball; bun unlink alone leaves the global tarball dependency behind. For a preview, run only recall uninstall --dry-run.

What gets removed (default)

• Recall-managed slash-command symlinks under ~/.claude/commands/Recall/ and legacy ~/.claude/commands/recall/; either directory is removed only when empty
• Recall-managed Agent Skill symlinks under ~/.claude/skills/do-recall-*/ and ~/.omp/agent/skills/do-recall-*/ (unless --skip-omp for omp); real files and foreign links are preserved
• ~/.claude/Recall_GUIDE.md
• Recall’s hook entries in ~/.claude/settings.json (Stop/SessionStart/PreCompact/PostToolUse/UserPromptSubmit) — other hooks are preserved
• mcpServers["recall-memory"] in settings.json — other MCP servers preserved
• Recall-owned hook files under ~/.claude/hooks/, including RecallInSession.ts, and installed TypeScript helpers under ~/.claude/hooks/lib/ — only inventoried Recall paths, never either whole directory
• The ## MEMORY section in ~/.claude/CLAUDE.md only if Recall generated it (current ownership marker or a normalized exact match of the complete legacy-generated body); unmarked customized/externally owned sections and the rest of CLAUDE.md are preserved; a marked section remains Recall-owned even if its body was edited
• ~/.claude/MEMORY/extract_prompt.md — only if unmodified from source; user-edited versions are preserved
• OpenCode MCP entry + plugins + the shared plugin helpers Recall installs under plugins/lib/ + agent + guide (unless --skip-opencode). plugins/lib/ itself is removed only when Recall emptied it, so your own files there survive. An opencode.json that Recall cannot parse is reported and left untouched; the plugins, agent, and guide are still removed and the rest of the uninstall continues
• Recall’s native Pi package registration, owned Pi MCP entry, guide link, and Recall-generated AGENTS.md MEMORY section (current marker or normalized exact legacy Pi body); legacy Recall extension/skill links are removed, while unrelated Pi packages and pi-mcp-adapter remain (unless --skip-pi)
• The managed Grok lifecycle symlink at ~/.grok/hooks/RecallLifecycle.json; a foreign file at that path is preserved (unless --skip-grok)
• The source-checkout global link via bun unlink
• The managed crontab line marked # recall-memory: quarterly age and the wrapper ~/.agents/Recall/shared/age-quarterly.sh; other crontab lines are left alone

If direct cleanup cannot safely parse an owned Claude, OpenCode, or Pi config, it leaves that file unchanged. Config cleanup errors or managed cron cleanup failures still allow the other safe cleanup to finish, then exit nonzero with Uninstall Incomplete.

Separately installed omp capture is removed with omp plugin uninstall recall-memory, followed by an omp restart. The lifecycle uninstaller does not manage that native plugin registration.

What is preserved (default)

• ~/.agents/Recall/recall.db — your persistent memory database
• ~/.agents/Recall/backups/ — the backup tree written by install/update
• User-authored identity and distilled memory under ~/.agents/Recall/MEMORY/, together with any managed Claude links or legacy files in ~/.claude/MEMORY/
• This source directory (remove with rm -rf /path/to/Recall)

Flags

Even with --purge, user-authored identity and distilled memory are retained. An existing foreign Claude file is never overwritten; the canonical Recall copy remains available in the pre-purge snapshot.

Next: Getting Started | CLI Reference | MCP Tools | Troubleshooting