Getting Started

This is the first-run tutorial for Recall: install it, find the database, start a session, and see how MCP, hooks, and skills get wired. For prerequisites, uninstall, and environment variables see Installation. For every flag see the CLI Reference.

Recall ships two binaries: recall (CLI) and recall-mcp (MCP server). The MCP server name is recall-memory. Do not rename them.

1. Install

Recall requires Bun (bun:sqlite and Bun-native hooks). Put Bun on PATH first.

Complete the canonical Installation guide, which owns the supported bootstrap paths and their ordering. Then follow the applicable host guide: Claude, Codex, Pi, omp, or Grok.

After any attach, restart each configured agent so it loads the plugin, extension, or snippets.

Which command to run for re-install, update, custom database paths, and recovery lives in Managing Recall.

2. Where the database lives

Recall has one install root: ~/.agents/Recall. The runtime tree is not relocatable.

Override the database with RECALL_DB_PATH (legacy MEM_DB_PATH is still honored when RECALL_DB_PATH is unset). That moves the SQLite file only; it does not move the install root.

Print every resolved path on this machine:

recall path
recall path --json

If the database file is missing, recall init creates the schema. It is safe to re-run.

3. Verify the install

which recall recall-mcp     # both binaries on PATH
ls -la ~/.agents/Recall/recall.db
recall stats                # record counts (zeros on a fresh install)
recall doctor               # health check: database, MCP, hooks, embeddings

recall doctor is the authoritative check. Run it first whenever something looks wrong. recall doctor --fix repairs missing or drifted install-layout symlinks and stale Claude MCP database paths. It may rewrite Claude configuration, but it does not repair or mutate memory data.

4. Seed your identity, then start a session

Supported session-start hosts inject two tiers: L0 identity (who you are) and L1 top records (importance-ranked memory). Without an identity file, L0 is empty and every new session has to re-learn the basics.

recall onboard                 # 7-question interview; writes identity.md
recall onboard --print --yes   # preview the rendered markdown, write nothing
recall onboard --project       # write ./.atlas-recall/identity.md instead

Use | (not ,) to separate values so a phrase like no force-push, ever stays one entry. Re-run whenever your role, projects, or working preferences change. Files over 1200 characters are truncated at load.

An existing user-owned ~/.claude/MEMORY/identity.md remains authoritative; otherwise the canonical file is ~/.agents/Recall/MEMORY/identity.md. RECALL_IDENTITY_PATH overrides both. Full precedence is in CLI Reference → Identity & Onboarding.

Preview what a host would inject:

recall start                     # markdown L0/L1 bundle
recall start --format cursor     # Cursor sessionStart wrapper: { "additional_context": "..." }

Empty DB plus missing identity.md still exits 0, with a short degrade line.

Then open a new session in your agent. What happens next depends on the host:

5. How MCP and hooks get wired

recall install (or ./packaging/install.sh) wires installer-owned hosts: Claude hooks, Grok, OpenCode, omp skill links, and Pi’s MCP adapter/config. Claude, Codex, and Pi skills/MCP/extensions prefer the native plugin or package. You do not register MCP or hooks by hand unless you are on a host neither the plugin nor the installer owns.

MCP (recall-mcp)

The server is named recall-memory. The spawned command is the recall-mcp binary (installer-managed Claude entries typically run bun run <path-to-recall-mcp> and pass env.RECALL_DB_PATH).

It exposes nine tools against the same SQLite file as the CLI:

memory_search, memory_hybrid_search, memory_recall, context_for_agent, memory_add, memory_stats, loa_show, memory_dump, decision_update

Per-host registration:

• Claude Code — preferred: plugin MCP (plugin:recall:recall-memory). Without the plugin, user-scope mcpServers["recall-memory"] in ~/.claude/settings.json (and/or ~/.claude.json). With the plugin active, the installer reconciles that entry under the Claude ownership rules.
• Pi — preferred: native package for extensions/skills; MCP is still pi-mcp-adapter + ~/.pi/agent/mcp.json (installer can write the owned entry).
• omp — no MCP registration. Native capture and installer-owned skills remain separate; see omp Integration.
• OpenCode — installer writes mcp.recall-memory in opencode.json when that CLI is detected. Grok — the installer does not write MCP; it only installs the lifecycle hook. Configure recall-memory yourself if you want the tools. See Grok Integration.
• Codex — .mcp.json inside the native plugin (command: recall-mcp). packaging/install.sh does not duplicate it.
• Cursor — snippets only. Copy/merge templates/cursor/mcp.json ("command": "recall-mcp"). No marketplace plugin.

Full tool reference: MCP Tools.

Lifecycle hooks

On Claude Code, the installer copies canonical hooks to ~/.agents/Recall/shared/hooks/, links them into ~/.claude/hooks/, and registers them in ~/.claude/settings.json:

Other hosts:

• Codex — Stop, PreCompact, PostCompact, and SessionEnd call recall capture. SessionStart stays hidden recall host-hook codex for L0/L1 injection only. See Capture adapter.
• Grok — installer-owned lifecycle capture only; no session-start injection. See Grok Integration.
• OpenCode — markdown drop for RecallBatchExtract.ts. Not on recall capture yet (next after v1). See optional batch extraction for scheduling.
• Pi — shutdown calls recall capture and still drops markdown under MEMORY/pi-sessions/ for batch extract. See Pi Integration.
• omp — awaited session_stop sends branch text to package-local dist/index.js capture. See omp Integration.
• Cursor — merge templates/cursor/hooks.json. Command stays recall start --format cursor. Cursor is a catalog, not a recall capture or host-hook host.

Agent skills (do-recall-*)

Recall’s nine canonical skill names, invocations, host packaging, and explicit-only dump rule live in Agent Skills. In Claude Code, invoke them as /do-recall-<name>.

6. First commands

Once the agent is restarted and identity is seeded:

recall "kubernetes auth"                 # hybrid search (keyword + semantic; default)
recall search "kubernetes auth"          # FTS5 keyword search
recall search "auth" -t decisions        # hard-filter to decisions
recall recent                            # recent records across tables
recall add decision "Use SQLite" -w "Zero-config, local-first"
recall add learning "Port 4000 busy" "Kill the process or change the port"
recall add breadcrumb "Auth refactor in progress" -i 8
recall dump "First Recall session"       # persist this session + LoA entry
recall loa list
recall stats

Bare recall "query" is hybrid search. Use recall "query" -k for keyword-only, recall "query" -v or recall semantic "query" for vector-only (needs Ollama). There is no recall embed semantic verb — embeddings are recall embed backfill / recall embed stats / recall embed reindex.

From inside Claude Code, the same workflows are the /do-recall-* skills. MCP tools (memory_search, memory_add, memory_dump, …) are what the model calls mid-session.

Next