---
title: "Getting Started"
image: "https://recall.edheltzel.codes/og.png"
---

> Documentation Index
> Fetch the complete documentation index at: https://recall.edheltzel.codes/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](https://recall.edheltzel.codes/docs/installation/). For every flag see the [CLI Reference](https://recall.edheltzel.codes/docs/reference/cli/).

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](https://bun.sh) (`bun:sqlite` and Bun-native hooks). Put Bun on `PATH` first.

Complete the canonical [Installation guide](https://recall.edheltzel.codes/docs/installation/#install-recall), which owns the supported bootstrap paths and their ordering. Then follow the applicable host guide: [Claude](https://recall.edheltzel.codes/docs/integrations/claude-code/), [Codex](https://recall.edheltzel.codes/docs/integrations/codex/), [Pi](https://recall.edheltzel.codes/docs/integrations/pi/), [omp](https://recall.edheltzel.codes/docs/integrations/omp/), or [Grok](https://recall.edheltzel.codes/docs/integrations/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](https://recall.edheltzel.codes/docs/lifecycle/).

---

## 2. Where the database lives

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

| Path | What it is |
|------|------------|
| `~/.agents/Recall/recall.db` | SQLite database (WAL mode). The only query surface. |
| `~/.agents/Recall/MEMORY/identity.md` | Canonical L0 identity file (`recall onboard` writes this). |
| `~/.agents/Recall/shared/hooks/` | Canonical lifecycle hook scripts |
| `~/.agents/Recall/shared/skills/` | Canonical `do-recall-*` Agent Skill bodies |
| `~/.agents/Recall/backups/` | Install/update/export snapshots |

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:

```bash
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

```bash
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.

```bash
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](https://recall.edheltzel.codes/docs/reference/cli/#identity--onboarding).

Preview what a host would inject:

```bash
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:

| Host | Session-start injection | How it starts |
|------|-------------------------|---------------|
| Claude Code | Yes — installer-owned `RecallStart` SessionStart hook | Preferred: native plugin for skills/MCP ([Claude Integration](https://recall.edheltzel.codes/docs/integrations/claude-code/)), plus `recall install` for hooks. Restart Claude Code. |
| Codex CLI | Yes — plugin `SessionStart` → `additionalContext` | Preferred: native plugin ([Codex Integration](https://recall.edheltzel.codes/docs/integrations/codex/)), then start a Codex session. |
| Cursor | Beta — `sessionStart` `{ additional_context }` | Merge the snippets under `templates/cursor/`. The hook command is unqualified `recall start --format cursor`. Cursor.app GUI PATH typically lacks `~/.bun/bin`, so the hook is a no-op until `recall` is on that app PATH. CLI Cursor, or a shell where `recall` resolves, is fine. Durable GUI PATH / `recall start --format cursor` accuracy is pending FM-321/327 — this table describes the as-built unqualified command, not that future fix. |
| Pi | Beta — `before_agent_start` | `pi install /absolute/path/to/Recall`. See [Pi Integration](https://recall.edheltzel.codes/docs/integrations/pi/). |
| omp | No automatic injection | Pack and link the native extension for main-session `session_stop` capture, then restart omp. See [omp Integration](https://recall.edheltzel.codes/docs/integrations/omp/). |
| OpenCode | No verified compaction injection | MCP + skills + `session.idle` capture. See [OpenCode Integration](https://recall.edheltzel.codes/docs/integrations/opencode/). |
| Grok | No automatic injection | Capture is installer-owned; search via MCP. See [Grok Integration](https://recall.edheltzel.codes/docs/integrations/grok/). |
| JCode | No | MCP and skills only. See [JCode Integration](https://recall.edheltzel.codes/docs/integrations/jcode/). |

---

## 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](https://recall.edheltzel.codes/docs/integrations/claude-code/#migrating-an-existing-install).
- **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](https://recall.edheltzel.codes/docs/integrations/omp/).
- **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](https://recall.edheltzel.codes/docs/integrations/grok/).
- **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](https://recall.edheltzel.codes/docs/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`:

| Event | Hook | What it does |
|-------|------|----------------|
| `SessionStart` | `RecallStart.ts` | Injects L0 identity + L1 top records (same assembler as `recall start`) |
| `SessionStart` | `RecallTelosSync.ts` | PAI TELOS auto-import when that directory exists; otherwise exits immediately |
| `SessionStart` (`clear`) | `RecallClearExtract.ts` | Extracts the previous session when `/clear` ends it without `Stop` |
| `Stop` | `RecallExtract.ts` | Extracts the session, and shells ambient text to `recall capture`. Without hooks, run `bun hooks/lib/hosts/claude/ambient-capture.ts` |
| `PreCompact` | `RecallPreCompact.ts` | Flushes in-flight messages before compaction |
| `PostToolUse` / `UserPromptSubmit` | `RecallInSession.ts` | Mid-session loop and correction capture; both default OFF |

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](https://recall.edheltzel.codes/docs/reference/capture-adapter/).
- **Grok** — installer-owned lifecycle capture only; no session-start injection. See [Grok Integration](https://recall.edheltzel.codes/docs/integrations/grok/).
- **OpenCode** — markdown drop for `RecallBatchExtract.ts`. Not on `recall capture` yet (next after v1). See [optional batch extraction](https://recall.edheltzel.codes/docs/installation/#optional-batch-extraction-cron) for scheduling.
- **Pi** — shutdown calls `recall capture` and still drops markdown under `MEMORY/pi-sessions/` for batch extract. See [Pi Integration](https://recall.edheltzel.codes/docs/integrations/pi/).
- **omp** — awaited `session_stop` sends branch text to package-local `dist/index.js capture`. See [omp Integration](https://recall.edheltzel.codes/docs/integrations/omp/).
- **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](https://recall.edheltzel.codes/docs/reference/agent-skills/). In Claude Code, invoke them as `/do-recall-<name>`.

---

## 6. First commands

Once the agent is restarted and identity is seeded:

```bash
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

| Guide | When to open it |
|-------|-----------------|
| [Installation](https://recall.edheltzel.codes/docs/installation/) | Prerequisites, session extraction, uninstall, env vars |
| [Score one memory item with Jev](https://recall.edheltzel.codes/docs/score-with-jev/) | Set `JEV_RECALL_KEY` and prove one score |
| [Managing Recall](https://recall.edheltzel.codes/docs/lifecycle/) | Install vs update vs uninstall, custom DB path, recovery |
| [CLI Reference](https://recall.edheltzel.codes/docs/reference/cli/) | Every subcommand and flag |
| [MCP Tools](https://recall.edheltzel.codes/docs/reference/mcp-tools/) | Tool schemas for agents |
| [Agent Skills](https://recall.edheltzel.codes/docs/reference/agent-skills/) | Canonical `/do-recall-*` skill bodies |
| [Harness API](https://recall.edheltzel.codes/docs/reference/api/) | Thin `recall-memory/api` surface: start / drop / capture / inject |
| [Troubleshooting](https://recall.edheltzel.codes/docs/troubleshooting/) | Start with `recall doctor` |
| [Claude](https://recall.edheltzel.codes/docs/integrations/claude-code/) · [Codex](https://recall.edheltzel.codes/docs/integrations/codex/) · [Pi](https://recall.edheltzel.codes/docs/integrations/pi/) · [omp](https://recall.edheltzel.codes/docs/integrations/omp/) · [Grok](https://recall.edheltzel.codes/docs/integrations/grok/) · [JCode](https://recall.edheltzel.codes/docs/integrations/jcode/) · [OpenCode](https://recall.edheltzel.codes/docs/integrations/opencode/) | Host-specific wiring |

Source: https://recall.edheltzel.codes/docs/index.mdx