Troubleshooting

New install? The first-run walkthrough is Getting Started.

First Step: Run Doctor

recall doctor

This checks all subsystems: database, MCP registration, hooks, extraction tracker, CLI paths, and Ollama. Start here before debugging individual issues.

Common Issues

“Database not found”

recall init

Re-initializes the database. Safe to re-run — won’t destroy existing data.

“L0 identity tier is empty at session start”

The RecallStart hook loads identity.md for the L0 tier. If you’ve never written one, the L0 section of your session-start context is empty.

recall onboard                 # Interactive interview — creates identity.md
recall benchmark run B         # Confirm v2_l0_chars > 0 after onboarding

If onboard writes to the wrong location, check for RECALL_IDENTITY_PATH in your shell env, a project-local ./.atlas-recall/identity.md, or an existing user-owned ~/.claude/MEMORY/identity.md. See Identity & Onboarding for the complete shared precedence.

“My identity.md was silently truncated”

RecallStart hard-caps L0 at MAX_L0_CHARS = 1200 on read and appends [identity truncated — edit <path> to shorten]. Trim your identity file or re-run recall onboard --print to preview length before writing.

“Bun install fails — unzip required” (Linux only)

sudo apt-get install -y unzip

Then re-run ./packaging/install.sh.

“Fabric extraction failed”

Fabric is the fabric Extractor for Curated LoA. recall loa write requires it and fails closed if Fabric is missing. recall dump tries Fabric and, on failure, writes a basic summary (not a second Extractor). Core search, add, and MCP tools work without Fabric.

Verify Fabric works:

echo "test" | fabric --pattern extract_wisdom

“MCP server not connecting”

Run diagnostics: recall doctor
Check config: grep recall-memory ~/.claude/settings.json
Verify PATH: which recall-mcp
Test manually: recall-mcp (should hang waiting for stdin — Ctrl+C to exit)
Restart Claude Code

The MCP server is registered in ~/.claude/settings.json under mcpServers (user scope).

“MCP worked yesterday but broke after I restarted Claude Code”

The installer-managed Claude MCP entry runs bun with args run and the recall-mcp path (which recall-mcp, usually ~/.bun/bin/recall-mcp). That symlink points at this checkout’s dist/mcp-server.js. If the symlink is gone or stale, the running recall-mcp process keeps the deleted inode open — so the current session works, but the next Claude Code restart can’t spawn a fresh MCP server and it silently fails.

Common causes:

bun unlink, bun upgrade, or npm clean-up removed the symlink
An older ./packaging/update.sh (pre-0.7.21) didn’t re-run bun link after rebuild, leaving the symlink stale after bun install pruning
./packaging/update.sh was run from a git worktree instead of the main checkout, redirecting the global recall registry to the worktree — which then vanished when the worktree was removed

Repair:

cd /path/to/Recall       # the MAIN checkout, not a worktree
bun install && bun run build && bun link
ls -la ~/.bun/bin/recall ~/.bun/bin/recall-mcp    # verify symlinks exist
# Restart Claude Code

Or, from a shell:

cd /path/to/Recall
./packaging/update.sh --force --no-confirm

Starting in 0.7.21, ./packaging/update.sh runs bun link after every rebuild. Starting in 0.7.22, it also verifies that the bin symlinks resolve to readable files after linking — so a silent bun link no-op now surfaces with a diagnostic instead of reporting “[OK] Re-linked” while the bin dir stayed stale.

“Session extraction not running”

Run diagnostics: recall doctor
Check hook registered: grep RecallExtract ~/.claude/settings.json
Check hook file exists: ls ~/.claude/hooks/RecallExtract.ts
Check bun accessible: which bun (hooks resolve bun dynamically — not hardcoded)
Check claude CLI available: which claude

Extraction hooks fire on the Stop event. If the hook isn’t registered in settings.json, re-run ./packaging/install.sh.

“OpenCode sessions are not being captured”

Verify the host and runtime: opencode --version and bun --version.
Verify the host export contract: opencode export <session-id> should print JSON.
Check the installed plugin, its helper, and the config: ls ~/.config/opencode/plugins/RecallExtract.ts ~/.config/opencode/plugins/lib/session-export.ts and inspect opencode.json for mcp.recall-memory. The plugin imports the helper, so an install that predates it fails to load and captures nothing. Re-run ./packaging/install.sh (or ./packaging/update.sh) to place both.
Check the drop directory: ls ~/.agents/Recall/MEMORY/opencode-sessions/.
Run the batch extractor manually with bun run ~/.agents/Recall/shared/hooks/RecallBatchExtract.ts --dry-run.

The plugin tracks a session only after a successful JSON export and markdown write. Export failures are reported to stderr and retried on a later idle event; they do not silently become successful extraction records.

“Search returns nothing, but the data is there”

recall show / recall recent find records that recall search never returns. The usual cause is an FTS5 index out of sync with its source table — classically a database created by an older version where the index or its sync triggers were never created, so every write since has been silently unindexed.

recall doctor            # the FTS index check reports which indexes drifted
recall repair            # dry-run: shows the planned rebuilds, writes nothing
recall export --backup   # recommended before any repair
recall repair --execute  # rebuild the indexes from the source tables

See Repair in the CLI reference for the full safety model. recall doctor --fix does not fix this. Doctor repairs install and Claude MCP configuration drift; data and index maintenance always goes through recall repair.

“Embedding service unavailable”

Embeddings are optional. Hybrid search falls back to FTS5-only automatically.

To enable semantic search:

ollama pull qwen3-embedding:0.6b
curl http://localhost:11434/api/tags   # Verify Ollama is running

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

“Command not found: recall”

The recall CLI is linked globally via bun link, producing a symlink at ~/.bun/bin/recall → the Recall checkout’s dist/index.js. If that symlink is missing or stale:

cd /path/to/Recall       # the MAIN checkout, not a worktree
bun install && bun run build && bun link
ls -la ~/.bun/bin/recall    # verify
recall --version            # full X.Y.Z

If recall --version still fails, confirm ~/.bun/bin is on your PATH:

echo $PATH | tr ':' '\n' | grep bun

Add to your shell init if missing:

# fish
set -U fish_user_paths $HOME/.bun/bin $fish_user_paths

# bash/zsh
export PATH="$HOME/.bun/bin:$PATH"

Recovery via update.sh (0.7.22+ verifies the symlink post-rebuild and fails loudly if linking silently no-ops):

cd /path/to/Recall
./packaging/update.sh --force --no-confirm

See also: “MCP worked yesterday but broke after I restarted Claude Code” for the recall-mcp counterpart — same root cause, same repair path.