feat: automatic per-turn recall (UserPromptSubmit) for Claude Code

[ccf]

Automatic per-turn recall (Claude Code)

Closes the gap where agentcairn was write-mostly on Claude Code: sessions were captured and the index stayed healthy, but the semantic recall tool was almost never invoked — the usage ledger sat frozen for days. SessionStart only injected a recency digest (recent -n 5, time-ordered, not relevance-ranked), and the recall MCP tool / skill were LLM-discretion-gated, so targeted recall just never happened. OpenCode and Hermes already do per-turn recall; this brings Claude Code to parity.

What this adds

• UserPromptSubmit hook → a thin shell wrapper (plugin/scripts/user-prompt-submit.sh) that synchronously runs cairn recall-hook, whose stdout is injected as additionalContext for that turn.
• cairn recall-hook — a new CLI command: reads the hook JSON from stdin, runs a hybrid recall against the prompt, prints the injection envelope (or nothing). Always exits 0.
• src/cairn/recall_hook.py — the logic: trivial-prompt gate, config gate, hybrid recall (rerank off on the hot path), ## Relevant memories (agentcairn) formatting with [[permalink]] citations, and fail-open behavior (never raises / blocks a prompt). Fires usage.record so the savings ledger moves again.
• Config (default on; flat keys in ~/.agentcairn/config.toml, env-overridable): auto_recall / auto_recall_k / auto_recall_scope → CAIRN_AUTO_RECALL, CAIRN_AUTO_RECALL_K, CAIRN_AUTO_RECALL_SCOPE.
• SessionStart pre-warm — a detached, best-effort cairn warm on the warm path so the per-prompt recall stays fast; BM25 cold-fallback if the embedder can't load.
• The SessionStart recency digest is unchanged — this is additive (recency orientation + per-turn relevance).
• Plugin bumped to 0.4.0; README + CHANGELOG updated.

Design + process

Built spec-first (docs/specs/2026-06-29-auto-recall-userpromptsubmit-design.md) → plan (docs/plans/2026-06-29-auto-recall-userpromptsubmit.md) → subagent-driven TDD, one task per commit with spec+quality review between each and a whole-branch review at the end. The final review caught one real bug (now fixed): recall-hook ignored CAIRN_EMBEDDER — non-default-embedder users would have gotten silent fail-open + a cold model download in the synchronous hook; it now resolves the configured embedder like every other command.

Tests

Full suite 697 passed / 5 skipped; plugin tests 23/23 (incl. the fresh-install ${user_config} guard and the new UserPromptSubmit wiring test). New coverage: config resolvers, the gate, format/empty, fail-open (missing index / malformed + non-dict JSON), CAIRN_EMBEDDER honored, BM25 cold-fallback, CLI stdin wiring.

⚠️ Release ordering (post-merge)

The wrapper invokes cairn recall-hook via uvx --from agentcairn>=0.2, so the subcommand must exist in an installed/cached build. Plugin 0.4.0 only takes effect once a PyPI release containing recall-hook is published — cut a release after merge (bump src/cairn/__init__.py, move the CHANGELOG [Unreleased] section, tag → PyPI). Fail-open covers the interim: users simply get no auto-recall until the release lands, never a broken prompt.

🤖 Generated with Claude Code

---

Note

Medium Risk
Default-on context injection on every substantive prompt adds latency and could surface wrong memories; mitigated by fail-open hooks, trivial-prompt skip, and no rerank on the hot path. Plugin calls uvx recall-hook, so auto-recall is inactive until a PyPI release ships the subcommand.

Overview
Claude Code gets automatic per-turn memory recall, closing the gap where capture worked but semantic recall almost never ran. A new UserPromptSubmit hook runs cairn recall-hook synchronously on each substantive user prompt (skips very short text like "yes"/"go"), runs hybrid search with rerank off for latency, and injects a ## Relevant memories (agentcairn) block with [[permalink]] citations as additionalContext. Session-start recency digest is unchanged; this is additive relevance per turn.

Core logic lives in recall_hook.py (config gate, length gate, search, formatting, usage.record). Config adds flat auto_recall, auto_recall_k, and auto_recall_scope (default on). Project boost uses the hook JSON cwd, not the hook process cwd. recall-hook resolves CAIRN_EMBEDDER when --embedder is omitted; embedder load failures fall back to BM25. Everything is fail-open (empty output, exit 0) so hooks never block prompts.

The plugin ships user-prompt-submit.sh, a 10s hook timeout, detached cairn warm on session start for steady-state speed, and bumps to 0.4.0. README/CHANGELOG and design/plan docs are included; tests cover resolvers, hook behavior, CLI stdin, and hook wiring.

^{Reviewed by Cursor Bugbot for commit 4e2bb37. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cursor]

Cursor Bugbot has reviewed your changes and found 2 potential issues.

Bugbot Autofix prepared fixes for both issues found in the latest run.

• ✅ Fixed: Hook cwd ignored for project
  • Extracted cwd from the hook JSON payload in run() and passed it to _recall, which now calls resolve_current_project(project_from_cwd(cwd)) instead of resolve_current_project(None), ensuring project boost uses the session workspace rather than the process working directory.
• ✅ Fixed: Search failure breaks recall return
  • Initialized notes: list[dict] = [] before the try block so that if search() raises, _recall returns an empty list instead of raising UnboundLocalError.

Or push these changes by commenting:

@cursor push 80b825be28

Preview (80b825be28)

diff --git a/src/cairn/recall_hook.py b/src/cairn/recall_hook.py
--- a/src/cairn/recall_hook.py
+++ b/src/cairn/recall_hook.py
@@ -21,6 +21,7 @@
     resolve_auto_recall_scope,
 )
 from cairn.embed import get_embedder
+from cairn.ingest.events import project_from_cwd
 from cairn.search import open_search, resolve_current_project, search
 
 _DEFAULT_MIN_CHARS = 12
@@ -69,7 +70,9 @@
     }
 
 
-def _recall(prompt: str, *, vault, index, embedder_name: str, k: int, scope: str) -> list[dict]:
+def _recall(
+    prompt: str, *, vault, index, embedder_name: str, k: int, scope: str, cwd: str | None = None
+) -> list[dict]:
     """Run one hybrid recall; returns note dicts (possibly empty). Falls back to
     BM25-only if the embedder cannot load. Records the savings ledger
     best-effort (this is the observability that proves recall fired)."""
@@ -80,8 +83,9 @@
         emb = None if embedder_name == "none" else get_embedder(embedder_name)
     except Exception:
         emb = None  # BM25-only fallback when the embedder can't load
-    current = resolve_current_project(None)
+    current = resolve_current_project(project_from_cwd(cwd))
     con = open_search(str(idx))
+    notes: list[dict] = []
     try:
         hits = search(con, prompt, embedder=emb, k=k, rerank=False, project=current, scope=scope)
         notes = [
@@ -120,8 +124,10 @@
         try:
             obj = json.loads(stdin_text)
             prompt = obj.get("prompt") or "" if isinstance(obj, dict) else ""
+            hook_cwd = obj.get("cwd") if isinstance(obj, dict) else None
         except (ValueError, TypeError):
             prompt = ""
+            hook_cwd = None
         if not should_recall(prompt, env):
             return ""
         notes = _recall(
@@ -131,6 +137,7 @@
             embedder_name=name,
             k=resolve_auto_recall_k(env),
             scope=resolve_auto_recall_scope(env),
+            cwd=hook_cwd,
         )
         block = format_block(notes)
         return json.dumps(build_hook_output(block)) if block else ""

_{You can send follow-ups to the cloud agent here.}

^{Reviewed by Cursor Bugbot for commit 21aa1b5. Configure here.}

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Preview URL	Updated (UTC)
✅ Deployment successful! View logs	agentcairn	4e2bb37	Commit Preview URL Branch Preview URL	Jun 29 2026, 02:06 PM

[ccf]

Addressed Bugbot's review in 4e2bb37:

• Hook cwd ignored (Medium): recall-hook now resolves the project from the UserPromptSubmit payload's cwd (via project_from_cwd), falling back to the process cwd only when absent — so project boost and auto_recall_scope=project target the session workspace, matching the design and session-end.sh. Added a test asserting the payload cwd drives the project passed to search().
• Search failure / UnboundLocalError (Low): initialized notes = [] so the return is always bound. Note the literal UnboundLocalError doesn't actually occur — a search() exception propagates to run()'s outer fail-open except → "" before return notes is reached — but the init removes the latent smell.

The earlier format · lint · test failure was an unrelated transient: fastembed couldn't download nomic-embed-text-v1.5 from HuggingFace in CI (retried 3×, gave up), failing the Hermes provider tests, which use the real model. My changes use FakeEmbedder; the full suite passes locally (698/5). The new CI run should clear it.