ccrecall

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. By default, storage, sync, deterministic summaries, and semantic search all run on your machine. Optional LLM summary enrichment is separate: if you explicitly opt in and pass its capability check, ccrecall sends a branch-scoped packet through your installed Claude CLI using your Claude auth.

ccrecall is an independent, community project for Claude Code. It is not affiliated with, endorsed by, or sponsored by Anthropic.

What it does

Every time a Claude Code session ends, 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.

Install

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-recall and /ccrecall:ccr-resume. The hook commands degrade gracefully — each is guarded by command -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.

First-run setup

No manual setup is needed. ccrecall uses built-in defaults unless you create ~/.ccrecall/config.json with overrides.

Semantic search

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.

Optional LLM summary enrichment

LLM enrichment adds a Branch Resume Brief above the deterministic summary when a branch has a valid cached enrichment. It is off by default and never replaces the deterministic baseline.

When you enable it, ccrecall sends only the selected branch packet through your installed claude CLI using your Claude Code auth:

• selected branch-scoped transcript content
• branch/session metadata
• source-path provenance

ccrecall does not enable this automatically. You must opt in, and the claude CLI must first pass a --no-session-persistence capability check so the enrichment call does not create importable Claude transcripts of its own.

Capability check and manual backfill

Run the capability check first:

ccrecall backfill llm-summaries --check-capability

Expected outcome: a pass/fail result that updates ccrecall's local capability sidecar without reading your real conversation transcripts.

Then run the canonical manual backfill command:

ccrecall backfill llm-summaries

Common selectors:

ccrecall backfill llm-summaries --days 14
ccrecall backfill llm-summaries --limit 50
ccrecall backfill llm-summaries --session <session-uuid>
ccrecall backfill llm-summaries --force

Use --force only when you want to rerun the selected branches even after an earlier enrichment attempt or when you intentionally want a manual run to bypass the llm_summary_min_exchanges filter.

Expected outcome: progress/completion output only. ccrecall does not print transcript text, raw prompts, or raw model responses.

Automatic current-session enrichment

llm_summaries_enabled controls only the automatic post-sync worker. When it is true, ccrecall sync-current may spawn a detached enrichment worker after a successful Stop-hook sync when:

• the current session produced new messages

The worker checks the capability sidecar and branch eligibility itself. If the capability check is missing or invalid, it exits without calling Claude. If the branch does not meet the minimum-exchange threshold, it remains eligible for a later manual backfill.

If any of those gates fail, or if Claude is unavailable, unauthenticated, rate-limited, over budget, times out, or returns invalid output, ccrecall keeps the deterministic summary and injected context exactly as before.

Budget behavior

llm_summary_max_budget_usd defaults to $1.00. ccrecall passes that value through to the Claude CLI unchanged as an upstream stop threshold. It is useful spend control, but it is not a guaranteed maximum charge: Claude can cross the threshold before stopping.

Embedding coverage and backfill

Coverage

New sessions are embedded automatically as they sync (embed-on-write), so coverage builds forward on its own. 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.

Optional: seed historical conversations

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.

Flags

Runtime deps

The semantic search path requires three extra packages beyond the base install:

• sqlite-vec — SQLite extension for vector KNN queries
• fastembed — 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.

Degradation

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)
• fastembed cannot be imported
• sqlite-vec cannot 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. Use ccrecall search --status to check which path is active.

When ccrecall speaks up

ccrecall is meant to be invisible — it runs in the background and Claude consumes its output. It will interrupt you, once, only when something is actually broken and only you can fix it:

• 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.

When either condition 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. Coverage that's merely catching up is never surfaced this way — only genuine, unrecoverable failures earn the interruption.

Skills

Entry points

Hooks (run automatically — don't call these manually)

These are wired by the plugin's hooks/hooks.json and fire on their respective Claude Code events.

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.

Internal helpers (spawned by hooks — don't call these manually)

Skill CLIs (called from skill files — can also be used directly)

These are the ccrecall subcommands the /ccr-* skills invoke. You can run them from the terminal too.

Data flow

Session ends
  └─ ccrecall-sync (Stop hook)
       └─ ccrecall sync-current (background)
             └─ writes to ~/.ccrecall/conversations.db
             └─ embeds the active leaf via jina if model available (drops silently on failure)
             └─ optionally spawns ccrecall-llm-summaries after sync
                  (only when explicitly enabled; worker checks the capability gate)

/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 (background, first run / new files)
  │         └─ embeds each new active leaf via jina if model available
  │    └─ ccrecall backfill summaries (background, if summaries missing)
  │    └─ (embedding backfill is NOT auto-spawned — opt-in via ccrecall backfill embeddings)
  └─ ccrecall-context (SessionStart, startup + clear)
       └─ injects deterministic context, plus a Branch Resume Brief above it when a current valid enrichment exists

Config file

~/.ccrecall/config.json is an optional user-created override file. ccrecall uses these defaults when a key is absent:

Example config:

{
  "llm_summaries_enabled": true,
  "llm_summary_model": "sonnet",
  "llm_summary_effort": "medium",
  "llm_summary_timeout_seconds": 180,
  "llm_summary_max_budget_usd": 1.0,
  "llm_summary_min_exchanges": 9
}

The deterministic baseline remains local-only. Opt-in LLM enrichment is the only path in this release that sends selected transcript-derived data through Claude Code auth.

Database

~/.ccrecall/conversations.db — SQLite, WAL mode. Tables:

• sessions — one row per conversation session
• branches — one row per conversation branch (rewinding creates new branches)
• messages — all messages, stored once per session regardless of branch
• branch_messages — join table linking messages to branches
• import_log — tracks which JSONL files have been imported and their hashes
• chunks — one row per exchange (user turn + following assistant turns), carrying bounded display text and embedding bookkeeping
• chunk_vec — sqlite-vec virtual table storing 512-dim jina embeddings keyed by chunk rowid, used for KNN search

Development

uv sync                       # install package + dev dependencies
uv run pytest                 # run the test suite
uvx prek run --all-files      # run the lint/format/type hooks

License

MIT