Conversation history and semantic search for Claude Code.
ccrecall stores your Claude Code sessions in a local SQLite database so you can recall past conversations, search across them by keyword and meaning, and get automatic context on session start. Storage, sync, summaries, and semantic search all run entirely on your machine, and no data leaves it. The one exception is opt-in: ccrecall backfill recaps sends a session's prose to Anthropic, the same party that received it when the session ran, to write a short recap. Projects in exclude_projects are never sent.
ccrecall is an independent, community project for Claude Code. It is not affiliated with, endorsed by, or sponsored by Anthropic.
Every time Claude finishes a response, the conversation is synced to ~/.ccrecall/conversations.db. On your next session start, Claude automatically gets a summary of what you were last working on. You can also search past sessions by keyword or pull recent ones at any time.
Supported platforms: Linux (including WSL2) and macOS. Windows is not supported.
ccrecall has two parts: a Python package (the ccrecall CLI plus the hook binaries) and a Claude Code plugin (the /ccr-* skills and the hook wiring). Install both.
1. Install the package — puts ccrecall and the hook commands on your PATH:
uv tool install ccrecall(pipx install ccrecall or pip install ccrecall work too.)
2. Enable the plugin — ccrecall ships as a Claude Code plugin. The repo doubles as a single-plugin marketplace, so from inside Claude Code:
/plugin marketplace add NodeJSmith/claude-code-recall
/plugin install ccrecall@claude-code-recall
That registers the skills and wires the SessionStart / Stop / SessionEnd hooks (hooks/hooks.json) — both are auto-discovered from the plugin's directory layout. Reload with /reload-plugins if they don't appear immediately.
Plugin skills are namespaced under the plugin name, so the skills below are invoked as
/ccrecall:ccr-recalland/ccrecall:ccr-resume. The hook commands degrade gracefully — each is guarded bycommand -v … || true, so if the package isn't installed (or isn't yet on PATH) the hook is a silent no-op rather than a broken session.
No manual setup is needed. ccrecall uses built-in defaults unless you create ~/.ccrecall/config.json with overrides.
ccrecall statusis the glance: a verdict (healthy, working on it, or needs attention) and a line of numbers, such as7,514 sessions · 98% embedded · last sync 2 min ago. It exits 0 for any verdict, and 1 only when the database is missing or unreadable.ccrecall doctoris the diagnosis. It reads without changing anything and lists every finding under what to do about it (needs action, working on it, nothing to do), each with how to fix it.ccrecall doctor --list <finding-id>lists the sessions behind a finding. It exits 0 when healthy or working on it, 1 when something needs attention, and 2 when the database can't be read at all, so scripts can gate on it.doctor --listexits 0 whatever the verdict.
Each checks every session against its transcript, so they take a few seconds, and longer on a large database that isn't in the OS cache.
Queued embedding work counts as overdue once no full backfill has succeeded in backfill_stale_hours and a waiting session ended longer ago than that. Set it a little above how often your backfill runs: with a nightly job, 36.
status and doctor both take the global --json flag and print the same shape: verdict, findings (each with id, group, message, count, fix, listable) and summary (sessions, embedded_pct, last_sync). These values are stable; scripts can match on them.
verdict:healthy,working, orneeds-attention. It is the worstgrouppresent.group:action(needs action),working(working on it), ornone(nothing to do). A finding'sidis stable, but itsgroupcan change with circumstances. For example,embedding-backlogisworkingwhile a backfill drains it andactiononce it is overdue, and<kind>-failedisworkingwhen the cause was a busy database.id: one ofno-database,schema-behind,schema-ahead,not-writable,embedding-unavailable,embedding-backlog,fixable-sessions,unfixable-sessions,sessions-in-progress,deleted-transcripts,draft-sessions,unembeddable-sessions,tool-content-pending,skipped-by-design,duplicate-active-branch,check-failed, and per background run<kind>-failed(import,repair,sync,backfill,recaps),<kind>-killed(import,sync,backfill,recaps), and<kind>-running/<kind>-stuck(import,backfill).check-failedcan appear more than once, one per check that raised.fix: a command, a sentence of instructions, ornullwhen there's nothing to do. Don't execute it blindly.summary:sessions,embedded_pct, andlast_syncare eachnullwhen unknown (for example,sessionsbefore a pending schema upgrade has run). With no database,sessionsis0.sessions: present only withdoctor --list <id>, on that finding, when the finding is present andlistable. A missing array means the finding isn't there or names no sessions.
Everything below runs in the background, started by a Claude Code hook, except the backfills and recap generation, which run only when you start them. Each background job holds a lock while it runs, so a second copy skips instead of running twice. Logs go to ~/.ccrecall/ccrecall-<process>.log.
| Work | When it runs | How you'd know it failed |
|---|---|---|
Sync the current session (ccrecall sync-current) |
Every time Claude finishes a response (the Stop hook) | doctor reports sync-failed or sync-killed. Log: ccrecall-sync.log |
| Embed that session's exchanges | Right after its sync, in the same process. Long exchanges are embedded at draft quality (capped at 4,096 tokens). Skipped while an embedding backfill is running | A SessionStart alert if embedding keeps failing, and doctor's embedding-unavailable. Skipped sessions show as embedding-backlog |
Import and repair (ccrecall import --repair-gaps) |
SessionStart, when there's no database yet or a session has synced since the last import, which in practice is most session starts. Runs at low priority. Never embeds | A SessionStart alert if the last import failed or skipped projects, and doctor reports import-failed, repair-failed, import-killed or import-stuck, and fixable-sessions for gaps it hasn't repaired. Log: ccrecall-import.log |
Summaries (ccrecall backfill summaries) |
SessionStart, when a session has no summary or an outdated one | Only its log, ccrecall-backfill-summary.log |
Model warm-up (ccrecall-warm-model) |
Every SessionStart. Downloads the embedding model the first time, then returns at once | Its log, ccrecall-warm-model.log. If the model stays unavailable, sync's embedding fails and raises the alert above |
Embedding backfill (ccrecall backfill embeddings) |
Only when you run it. It embeds imported history, which sync never embedded, and upgrades draft-quality vectors to full quality | doctor reports backfill-failed, backfill-killed or backfill-stuck, and embedding-backlog turns into needs-action once it's overdue (see backfill_stale_hours). Log: ccrecall-backfill-embed.log |
Tool-content backfill (ccrecall backfill tool-content) |
Only when you run it. A one-time pass over sessions synced before ccrecall indexed tool calls | A SessionStart alert while sessions are left, and doctor's tool-content-pending. Log: ccrecall-backfill-tool-content.log |
Recap generation (ccrecall backfill recaps) |
Only when you run it or schedule it. See Session recaps | doctor reports recaps-failed or recaps-killed. Log: ccrecall-backfill-recaps.log |
ccrecall backfill schedule write doesn't schedule anything. It records that you have set up your own scheduled embedding backfill (cron, a systemd timer), which silences the draft-quality alert. backfill schedule clear removes that record and backfill schedule status shows it, along with how many draft-quality vectors remain.
ccrecall is meant to be invisible — it runs in the background and Claude consumes its output. It will interrupt you, once, only when something needs you:
- It can't save your history — the data directory or database is unwritable (disk full, permissions, corruption). Left unsaid, a working install would silently stop recording sessions.
- Embeddings are persistently failing — the vector extension or embedding model is unavailable, so semantic search is degraded until you fix the environment.
- Your install is older than your database — another, newer ccrecall has already migrated the database, so imports and sync may fail until you upgrade.
ccrecallcommands also print this as a one-line warning on stderr. - The last import failed — it aborted, or one or more projects failed to import, so recent conversations may be missing from search. A busy database doesn't count; the next run retries it. Fix: check
ccrecall-import.log, thenccrecall import. - Older sessions' tool calls aren't searchable — sessions synced before ccrecall indexed tool calls haven't been backfilled. Fix:
ccrecall backfill tool-content. - Some conversations have draft-quality embeddings — long exchanges embedded at sync time were capped at 4,096 tokens, so search can miss their later parts. Fix:
ccrecall backfill embeddings. Once you run it on a schedule,ccrecall backfill schedule writesilences this alert;ccrecall backfill embeddings --dismisssilences it without a schedule.
When any of these holds, the next session injects a short alert for Claude to relay to you in plain language. It's told once, then goes quiet for ~24h (tunable via alert_snooze_hours in the config file) even if still broken, and clears itself the moment the condition resolves. Sessions that are merely waiting to be embedded don't alert: a recall adds a one-line caveat to its results instead, and ccrecall status shows the coverage.
- Excluded projects. Projects listed in
exclude_projectsare never imported or synced. Conversations stored before you excluded a project stay stored. - Subagent transcripts. Claude Code writes each subagent's conversation to its own file under
<session-id>/subagents/, which ccrecall doesn't read. The parent session is stored, including the prompt it gave each subagent (as part of the tool call), but not the subagent's own turns.
Claude Code deletes old transcripts on its own schedule (its cleanupPeriodDays setting). Once a session is stored, deleting its transcript doesn't remove it from ccrecall: its messages stay stored and searchable, and doctor lists it under deleted-transcripts with nothing to do. What you lose is anything that reads the transcript itself: the session can't be re-imported or repaired, and /ccr-resume can't read its tail.
A recap is one or two sentences saying what a session was for and where it stopped, for a session picker or anything else that lists past sessions. Claude Code writes its own when you step away from a session, and ccrecall stores the latest one. ccrecall backfill recaps writes one for sessions that lack a current recap:
ccrecall backfill recaps # up to 20 sessions idle 30+ minutes, active in the last 7 days
ccrecall backfill recaps --limit 100 # at most 100 Claude calls this run (default 20)
ccrecall backfill recaps --idle-minutes 0 # at boot: catch sessions a shutdown cut offIt imports first, then makes one Claude call per session, newest first and at most --limit (default 20) per run, through your Claude Code login (the bundled claude CLI; ccrecall sets no API key, though one already in your environment takes precedence). A session is recapped once it has at least three user turns, has been idle for --idle-minutes, and has moved on since its last recap. Each call sends the session's prose (your messages and Claude's replies, without tool calls or subagent reports) to Anthropic, the same party that received it when the session ran. Sessions in projects listed in exclude_projects are never sent, including ones stored before the project was excluded.
A failure that would hit every session, such as being logged out or rate limited, stops the run, and the next run retries. A failure specific to one session skips that session for a day. The run exits 1 when any session failed, and doctor reports recaps-failed until a later run finishes cleanly. A typical timer runs it every 20 minutes, plus once at boot with --idle-minutes 0.
ccrecall show-recaps <id>... reads recaps from the database without calling Claude. It takes full session ids or 8-character prefixes. With --json it prints {"recaps": [{"session_id", "text", "source", "current", "as_of"}]}, where source is claude_code or generated, the newer of the two wins (Claude Code's on a tie), and current is false once the session has moved past the recap. An unknown id, or a session with no recap, gets a row with text, source and as_of null.
Search results are fused from two signals: keyword full-text search (FTS5 → FTS4 → LIKE fallback) and vector similarity from a locally-running embedding model. The two ranked lists are merged with Reciprocal Rank Fusion (RRF), so results that rank well in both signals appear first.
The embedding model is jina-embeddings-v2-small-en (512-dim), running entirely on your machine via fastembed. No data leaves your machine on this path.
New sessions are embedded automatically as they sync (embed-on-write), so coverage builds forward on its own. Long exchanges are embedded at draft quality on this path (capped at 4,096 tokens, to bound memory), and history brought in by ccrecall import isn't embedded at all; a backfill covers both. Only active-leaf branches are embedded — at most one active leaf per session (maintained by sync/import), not its abandoned forks/retries. The flag isn't DB-enforced, but sync/import marks exactly one branch is_active=1 per session. The search path only ever returns active leaves, so embedding inactive forks would just produce vectors that can never surface.
Embedding runs on CPU via fastembed. jina-v2-small-en is light — a few milliseconds for a short summary, up to ~400ms for a long one — but seeding a large history (~2k active leaves) is still a bounded chunk of work, and a parallel run can thrash a small or shared box. It is therefore opt-in — it is not auto-spawned on SessionStart — so it never fires unbidden. Run it yourself when you want to seed:
ccrecall backfill embeddings # all active leaves, all history
ccrecall backfill embeddings --days 14 # only the last 14 days
ccrecall backfill embeddings --limit 500 # cap this run at 500 branches
ccrecall backfill embeddings --threads 4 # use 4 inference threads (idle machine)It runs at low scheduling priority (nice) and a single inference thread by default so it yields to interactive work. Tune the thread count with --threads (e.g. --threads 4 on an idle workstation to finish faster). Progress prints to stderr (one line per batch); the run is resumable — re-running skips already-embedded branches. Each run also starts by checking that branches marked as embedded really have all their exchanges, and picks up any that don't.
| Flag | Effect |
|---|---|
--keyword-only |
Skip the embedding step entirely, use keyword search only |
To see embedding coverage and whether semantic search is available, run ccrecall status or ccrecall doctor.
The semantic search path requires three extra packages beyond the base install:
sqlite-vec— SQLite extension for vector KNN queriesfastembed— downloads and runs the embedding model (manages onnxruntime + tokenization)numpy— vector math (normalization)
These are included in the package dependencies. If fastembed fails to import (e.g. ABI mismatch on an unusual platform), search falls back silently to keyword-only mode.
Semantic fusion is automatically disabled when:
- The embedding model can't be loaded (e.g. a first-run download failed and no cached copy exists)
fastembedcannot be importedsqlite-veccannot be loaded on the connection (e.g. Python built without loadable extensions)
In all cases, search falls back to keyword-only and returns results normally. When this happens (or when embedding coverage is still catching up below ~95%), a recall appends a one-line caveat to its own results so you know they may be partial — surfaced only when you actually run a recall, never as a standalone nag. ccrecall doctor reports embedding-unavailable when semantic search is off.
| Skill | Trigger | What it does |
|---|---|---|
/ccr-recall |
"what did we discuss", "continue where we left off", "search my conversations" | Lets Claude search or browse your past sessions on demand |
/ccr-resume |
After a /clear, a crash or shutdown, or to get a summary of a finished session while you wait on CI or review |
Reconstructs where the prior session stood from its transcript tail, checks it against the repo, and surfaces any decision it left open |
These are wired by the plugin's hooks/hooks.json and fire on their respective Claude Code events.
| Entry point | Event | What it does |
|---|---|---|
ccrecall-setup |
SessionStart | Creates ~/.ccrecall/ if needed and starts background work: ccrecall import --repair-gaps when there's no database yet or a session has synced since the last import, ccrecall backfill summaries when a session's summary is missing or outdated, and ccrecall-warm-model every time. See What runs when |
ccrecall-context |
SessionStart (startup + clear) | Injects a summary of your most recent session into Claude's context so it knows what you were working on. On /clear, reads a handoff file to link directly to the session you just cleared from |
ccrecall-clear-handoff |
SessionEnd (clear only) | Writes a small handoff file so the next session start knows which session to link to after a /clear. Without this, context injection falls back to a "most recent session" heuristic |
ccrecall-sync |
Stop | Syncs the current session to the DB in a detached background process. Runs every time Claude finishes a response |
These are kept as separate console scripts (rather than
ccrecall hook …subcommands) on purpose: hooks fire on every session boundary, and a direct entry point avoids eagerly importing the full CLI command surface on the hot path.
| Entry point | What it does |
|---|---|
ccrecall sync-current |
Syncs a single session file to the DB. Called by ccrecall-sync with the session ID from stdin |
The hooks start these on their own (see What runs when), but running one yourself is safe, and it's what ccrecall doctor tells you to do when one is needed. If the same job is already running, a manual run skips and exits 0.
| Entry point | What it does |
|---|---|
ccrecall import |
Full import of all JSONL files in ~/.claude/projects/. Skips files that haven't changed since last import (size and modified time, then file hash). With --repair-gaps, it also re-imports sessions whose stored history is missing messages from the transcript. doctor's fix for no-database and fixable-sessions |
ccrecall backfill summaries |
Generates context summaries for any DB branches that don't have a current one |
These are the ccrecall subcommands the /ccr-* skills invoke. You can run them from the terminal too.
| Entry point | What it does |
|---|---|
ccrecall recent |
Prints recent sessions from the DB in markdown (default) or JSON. Used by /ccr-recall |
ccrecall search |
Searches sessions by keyword fused with vector similarity (FTS5 → FTS4 → LIKE fallback, RRF-fused with jina embeddings when available). Used by /ccr-recall |
ccrecall search-messages |
Searches individual exchanges by semantic similarity and returns short excerpts with their session handle. Used by /ccr-recall |
ccrecall tail |
Reads the tail of a prior session's transcript to recover the last instruction and any unanswered question. Used by /ccr-resume and /ccr-recall |
ccrecall backfill embeddings |
Opt-in seeding of embeddings for historical active-leaf branches (jina-v2-small-en via fastembed). Not auto-spawned. Supports --days N / --limit N / --threads N; throttled via nice + a single inference thread by default. Resumable |
ccrecall backfill recaps |
Opt-in recap generation for stopped sessions (one Claude call each, through your Claude Code login). Supports --days N / --limit N / --idle-minutes N. See Session recaps |
ccrecall show-recaps |
Prints each given session's recap from the database, without calling Claude |
ccrecall backfill tool-content |
Opt-in re-parse of already-synced sessions' JSONL files to populate messages.tool_content for rows synced before tool-content extraction existed. Not auto-spawned. Supports --days N / --limit N; resets embedding_version on touched branches so backfill embeddings re-embeds them. Resumable |
Claude finishes a response
└─ ccrecall-sync (Stop hook)
└─ ccrecall sync-current (background)
└─ writes to ~/.ccrecall/conversations.db
└─ embeds the active leaf via jina at draft quality
(skipped while an embedding backfill runs; a failure is recorded for the SessionStart alert)
/clear (SessionEnd)
└─ ccrecall-clear-handoff
└─ writes a handoff file naming the session being cleared
(so the next SessionStart links to it instead of guessing)
Session starts
└─ ccrecall-setup (SessionStart)
│ └─ ccrecall import --repair-gaps (background, if no DB yet or a session synced since the last import)
│ └─ never embeds; imported history waits for an embedding backfill
│ └─ ccrecall backfill summaries (background, if summaries missing or outdated)
│ └─ ccrecall-warm-model (background, every time)
│ └─ (embedding backfill is NOT auto-spawned — opt-in via ccrecall backfill embeddings)
└─ ccrecall-context (SessionStart, startup + clear)
└─ injects deterministic context
~/.ccrecall/config.json is an optional user-created override file. ccrecall uses these defaults when a key is absent:
| Key | Type | Default | Effect |
|---|---|---|---|
auto_inject_context |
bool | true |
Inject a summary of your previous session at session start. |
max_context_sessions |
int | 2 |
How many recent sessions to include in that injected context. |
exclude_projects |
list[str] | [] |
Project names to skip when storing conversations — excluded projects are not imported or synced. Matched against the project's directory name. This is write-side only: it prevents new data from being indexed; it does not remove or hide conversations already stored before the project was excluded. |
logging_enabled |
bool | true |
Write hook diagnostics (including swallowed hook exceptions) to per-process files such as ~/.ccrecall/ccrecall-sync.log. Set to false to suppress logging. |
log_level |
str | "INFO" |
Logging verbosity when logging_enabled is true. Accepts standard Python level names: DEBUG, INFO, WARNING, ERROR. |
alert_snooze_hours |
int | 24 |
After surfacing a SessionStart alert (see When ccrecall speaks up), suppress the same alert for this many hours. |
backfill_stale_hours |
number | 72 |
How long ccrecall doctor lets queued embedding work wait, and a running import or backfill run, before calling it overdue or stuck. |
Example config:
{
"auto_inject_context": true,
"max_context_sessions": 2,
"exclude_projects": ["work-secret"]
}ccrecall is local-only, with one opt-in exception:
ccrecall backfill recapssends session prose to Anthropic, which received it when the session ran, to write recaps. It never sends a project listed inexclude_projects. Nothing else it stores or derives is sent anywhere.
~/.ccrecall/conversations.db — SQLite, WAL mode. Tables:
sessions— one row per conversation sessionbranches— one row per conversation branch (rewinding creates new branches)messages— all messages, stored once per session regardless of branchbranch_messages— join table linking messages to branchesimport_log— tracks which JSONL files have been imported and their hasheschunks— one row per exchange (user turn + following assistant turns), carrying bounded display text and embedding bookkeepingchunk_vec— sqlite-vec virtual table storing 512-dim jina embeddings keyed by chunk rowid, used for KNN search
Two small files sit beside it, both safe to delete: conversations.db.runs.json records the newest and the last successful import, gap repair, sync and embedding backfill, and conversations.db.unrepairable.json lists sessions whose transcript is itself missing messages, so doctor doesn't offer a repair that can't help. Each can have a .lock file beside it, also safe to delete.
uv sync # install package + dev dependencies
uv run pytest # run the test suite
uvx prek run --all-files # run the lint/format/type hooks