feat(memory): proactive cross-project recall — opt-in injection hook (P2.2, 0.16.0)

Completes Pillar B (bd claude-memory-9z9).

- tj-core::memory: FTS5 mirror on the global index + keyword_search — a fast,
  embedding-free lookup cheap enough to run on every prompt.
- tj-cli `recall-hook`: opt-in UserPromptSubmit injector. Reads the prompt,
  keyword-searches the global index for relevant prior decisions/rejections/
  constraints across all projects, and emits a budgeted additionalContext
  block — a guardrail before the agent re-decides or repeats a dead-end.
  Never blocks the prompt (silent on miss/error). Gated by
  TJ_PROACTIVE_RECALL=0; budget via TJ_RECALL_BUDGET_CHARS / TJ_RECALL_K;
  reuses the classifier recursion guard.
- install-hooks --proactive-recall wires it into UserPromptSubmit alongside
  the nudge; OFF by default (no behaviour change unless opted in). is_tj
  uninstall filter updated so re-install stays idempotent.

Tests: keyword_search match/no-match (core), recall-hook injects + is gated
(CLI), install-hooks --proactive-recall wires it and default does not (CLI).
Green on default and --no-default-features.

Version 0.16.0; inter-crate version reqs bumped to resolve the release.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: Shahinyanm

CHANGELOG.md

@@ -7,6 +7,31 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.16.0] - 2026-06-12
+
+### Added
+- **Cross-project memory — Pillar B.** The journal now recalls relevant prior
+  reasoning across your *entire* history, not just the current repo — something
+  single-project memory tools can't do.
+  - `task-journal recall "<query>"` — semantic search over **every** project's
+    decisions, rejections and constraints. Surfaces prior choices and
+    dead-ends from anywhere you've worked.
+  - A global index (`data_dir/memory.sqlite`) mirrors high-signal events +
+    embeddings from all projects; `ask`/`embed` keep it current automatically
+    (best-effort, never failing the command). Contradicted (superseded)
+    decisions are down-ranked.
+  - **Opt-in proactive recall** (`install-hooks --proactive-recall`): a
+    UserPromptSubmit hook that injects a budgeted block of relevant prior
+    decisions/rejections/constraints **before you act** — a guardrail against
+    re-deciding or repeating a dead-end. Off by default; uses a fast keyword
+    path (no model load on the prompt path); gated by `TJ_PROACTIVE_RECALL=0`,
+    budgeted by `TJ_RECALL_BUDGET_CHARS` / `TJ_RECALL_K`.
+
+### Internal
+- `tj-core::memory` — global index schema (+ FTS5), `sync_from_project`,
+  semantic `search`, fast `keyword_search`. `paths::memory_db()`. CLI
+  `recall` / `recall-hook`; `install-hooks --proactive-recall` wiring.
+
 ## [0.15.0] - 2026-06-12
 
 ### Added

Cargo.lock

@@ -7,7 +7,7 @@ members = [
 ]
 
 [workspace.package]
-version = "0.15.0"
+version = "0.16.0"
 edition = "2021"
 rust-version = "1.88"
 license = "MIT"

Cargo.toml

@@ -23,7 +23,7 @@ default = ["embed"]
 embed = ["tj-core/embed"]
 
 [dependencies]
-tj-core = { package = "task-journal-core", version = "0.15.0", path = "../tj-core", default-features = false }
+tj-core = { package = "task-journal-core", version = "0.16.0", path = "../tj-core", default-features = false }
 anyhow = { workspace = true }
 clap = { workspace = true }
 tracing = { workspace = true }

crates/tj-cli/Cargo.toml

@@ -780,6 +780,13 @@ enum Commands {
         /// the classifier, honoring `--backend`).
         #[arg(long)]
         auto_capture: bool,
+        /// Opt in to proactive cross-project recall (Pillar B). Adds a
+        /// UserPromptSubmit hook that injects relevant prior decisions/
+        /// rejections/constraints from any project before you act. Off by
+        /// default (it surfaces extra context on every prompt). Fast keyword
+        /// path, no model; gated at runtime by TJ_PROACTIVE_RECALL=0.
+        #[arg(long)]
+        proactive_recall: bool,
     },
     /// Show local classifier and journal statistics.
     Stats,
@@ -930,6 +937,14 @@ enum Commands {
     /// default. Hidden from --help; not a human command.
     #[command(hide = true)]
     Nudge,
+    /// Opt-in proactive recall hook (Pillar B). On UserPromptSubmit, injects a
+    /// budgeted additionalContext block of prior decisions/rejections/
+    /// constraints from ANY project relevant to the prompt — a guardrail
+    /// against re-deciding or repeating a dead-end. Fast keyword path, no
+    /// model. Wired only by `install-hooks --proactive-recall`. Gated by
+    /// TJ_PROACTIVE_RECALL=0. Hidden from --help; not a human command.
+    #[command(hide = true)]
+    RecallHook,
     /// Cross-task search for `rejection` events matching a topic. Helpful
     /// when the agent is about to repeat a path that was already turned
     /// down — query the topic, see the prior rejection.
@@ -1529,6 +1544,7 @@ fn main() -> Result<()> {
             backfill,
             backend,
             auto_capture,
+            proactive_recall,
         } => {
             let settings_path = match scope.as_str() {
                 "user" => {
@@ -1676,13 +1692,35 @@ fn main() -> Result<()> {
                         );
                     }
                 }
+                if proactive_recall {
+                    // Append the recall injector to the UserPromptSubmit hooks,
+                    // keeping whatever is already there (nudge, and ingest when
+                    // --auto-capture is also set).
+                    let obj = entries.as_object_mut().expect("entries is an object");
+                    let ups = obj
+                        .entry("UserPromptSubmit")
+                        .or_insert_with(|| serde_json::json!([{ "matcher": "", "hooks": [] }]));
+                    if let Some(hooks) = ups
+                        .as_array_mut()
+                        .and_then(|a| a.get_mut(0))
+                        .and_then(|e| e.get_mut("hooks"))
+                        .and_then(|h| h.as_array_mut())
+                    {
+                        hooks.push(serde_json::json!({
+                            "type": "command",
+                            "command": "task-journal recall-hook || true",
+                        }));
+                    }
+                }
                 // MERGE our entries into the existing `hooks` block — touch ONLY
                 // task-journal hooks, never clobber other plugins' hooks. For each
                 // event we (a) strip any prior task-journal entry (idempotent
                 // re-install) then (b) append ours, leaving foreign hooks and
                 // untouched events intact.
                 let is_tj = |c: &str| {
-                    c.contains("task-journal ingest-hook") || c.contains("task-journal nudge")
+                    c.contains("task-journal ingest-hook")
+                        || c.contains("task-journal nudge")
+                        || c.contains("task-journal recall-hook")
                 };
                 let hooks_block = hooks_obj
                     .entry("hooks".to_string())
@@ -3073,6 +3111,9 @@ fn main() -> Result<()> {
             });
             print!("{env}");
         }
+        Commands::RecallHook => {
+            run_recall_hook()?;
+        }
         Commands::Rejected {
             topic,
             all_projects,
@@ -3692,6 +3733,82 @@ fn sync_global_memory(project_conn: &rusqlite::Connection, project_hash: &str) {
     }
 }
 
+/// Proactive recall injector (opt-in hook). Reads the UserPromptSubmit payload
+/// from stdin, keyword-searches the global index for relevant prior
+/// decisions/rejections/constraints across all projects, and emits a budgeted
+/// `additionalContext` block. Never blocks the prompt: any miss, empty result,
+/// or error exits silently with no output.
+fn run_recall_hook() -> anyhow::Result<()> {
+    // Opt-out and recursion guard (never inject into our own classifier spawn).
+    if std::env::var("TJ_PROACTIVE_RECALL").as_deref() == Ok("0") {
+        return Ok(());
+    }
+    if std::env::var(tj_core::classifier::agent_sdk::IN_CLASSIFIER_ENV).is_ok() {
+        return Ok(());
+    }
+    let global_path = tj_core::paths::memory_db()?;
+    if !global_path.exists() {
+        return Ok(());
+    }
+
+    use std::io::Read;
+    let mut buf = String::new();
+    if std::io::stdin().read_to_string(&mut buf).is_err() || buf.trim().is_empty() {
+        return Ok(());
+    }
+    // The UserPromptSubmit payload carries the prompt under `prompt`; fall back
+    // to the raw stdin if it isn't JSON.
+    let prompt = serde_json::from_str::<serde_json::Value>(&buf)
+        .ok()
+        .and_then(|v| {
+            v.get("prompt")
+                .and_then(|p| p.as_str())
+                .map(|s| s.to_string())
+        })
+        .unwrap_or(buf);
+    if prompt.trim().is_empty() {
+        return Ok(());
+    }
+
+    let conn = tj_core::memory::open(&global_path)?;
+    let k: usize = std::env::var("TJ_RECALL_K")
+        .ok()
+        .and_then(|s| s.parse().ok())
+        .unwrap_or(3);
+    let hits = tj_core::memory::keyword_search(&conn, &prompt, k)?;
+    if hits.is_empty() {
+        return Ok(());
+    }
+
+    let budget: usize = std::env::var("TJ_RECALL_BUDGET_CHARS")
+        .ok()
+        .and_then(|s| s.parse().ok())
+        .unwrap_or(900);
+    let mut ctx = String::from(
+        "📓 task-journal — relevant prior reasoning from your history (you may have decided this before):\n",
+    );
+    for h in &hits {
+        let snippet: String = h.text.chars().take(160).collect();
+        let proj: String = h.project_hash.chars().take(8).collect();
+        let line = format!(
+            "⚠ [{}] {} (project {proj}, {})\n",
+            h.event_type, snippet, h.task_id
+        );
+        if ctx.len() + line.len() > budget {
+            break;
+        }
+        ctx.push_str(&line);
+    }
+    let env = serde_json::json!({
+        "hookSpecificOutput": {
+            "hookEventName": "UserPromptSubmit",
+            "additionalContext": ctx.trim_end(),
+        }
+    });
+    print!("{env}");
+    Ok(())
+}
+
 fn auto_open_task_from_prompt(
     events_path: &std::path::Path,
     project_hash: &str,

crates/tj-cli/src/main.rs

@@ -5008,3 +5008,134 @@ fn recall_surfaces_decision_from_another_project() {
         "cross-project recall must surface project A's refund decision first; got: {first:?}\nfull:\n{out}"
     );
 }
+
+#[test]
+fn install_hooks_proactive_recall_wires_recall_hook() {
+    // --proactive-recall adds the recall injector to UserPromptSubmit alongside
+    // the nudge; the default install must NOT wire it (off by default).
+    let dir = assert_fs::TempDir::new().unwrap();
+    Command::cargo_bin("task-journal")
+        .unwrap()
+        .env("HOME", dir.path())
+        .args(["install-hooks", "--scope", "user", "--proactive-recall"])
+        .assert()
+        .success();
+    let content =
+        std::fs::read_to_string(dir.path().join(".claude").join("settings.json")).unwrap();
+    assert!(
+        content.contains("task-journal recall-hook"),
+        "--proactive-recall must wire the recall-hook; got: {content}"
+    );
+    assert!(
+        content.contains("task-journal nudge"),
+        "nudge must remain alongside recall-hook"
+    );
+
+    let dir2 = assert_fs::TempDir::new().unwrap();
+    Command::cargo_bin("task-journal")
+        .unwrap()
+        .env("HOME", dir2.path())
+        .args(["install-hooks", "--scope", "user"])
+        .assert()
+        .success();
+    let c2 = std::fs::read_to_string(dir2.path().join(".claude").join("settings.json")).unwrap();
+    assert!(
+        !c2.contains("recall-hook"),
+        "default install must not wire proactive recall"
+    );
+}
+
+#[test]
+fn recall_hook_injects_relevant_prior_reasoning() {
+    // Pillar B proactive injection: a decision recorded in a project must be
+    // surfaced as additionalContext when a later prompt (anywhere) shares its
+    // terms. Gated by TJ_PROACTIVE_RECALL=0.
+    let xdg = assert_fs::TempDir::new().unwrap();
+    let proj = assert_fs::TempDir::new().unwrap();
+
+    let tid = String::from_utf8(
+        Command::cargo_bin("task-journal")
+            .unwrap()
+            .current_dir(proj.path())
+            .env("XDG_DATA_HOME", xdg.path())
+            .args(["create", "Payments"])
+            .assert()
+            .success()
+            .get_output()
+            .stdout
+            .clone(),
+    )
+    .unwrap()
+    .trim()
+    .to_string();
+    Command::cargo_bin("task-journal")
+        .unwrap()
+        .current_dir(proj.path())
+        .env("XDG_DATA_HOME", xdg.path())
+        .args([
+            "event",
+            &tid,
+            "--type",
+            "decision",
+            "--text",
+            "chose the idempotent payment ledger for refunds",
+        ])
+        .assert()
+        .success();
+    Command::cargo_bin("task-journal")
+        .unwrap()
+        .current_dir(proj.path())
+        .env("XDG_DATA_HOME", xdg.path())
+        .env("TJ_EMBED", "hash")
+        .args(["embed", "--backfill"])
+        .assert()
+        .success();
+
+    let payload = serde_json::json!({
+        "hook_event_name": "UserPromptSubmit",
+        "prompt": "should we add a refund ledger to billing?"
+    })
+    .to_string();
+
+    let body = String::from_utf8(
+        Command::cargo_bin("task-journal")
+            .unwrap()
+            .env("XDG_DATA_HOME", xdg.path())
+            .args(["recall-hook"])
+            .write_stdin(payload.clone())
+            .assert()
+            .success()
+            .get_output()
+            .stdout
+            .clone(),
+    )
+    .unwrap();
+    assert!(
+        body.contains("additionalContext"),
+        "recall-hook must emit additionalContext; got: {body:?}"
+    );
+    assert!(
+        body.contains("ledger"),
+        "must surface the ledger decision; got: {body}"
+    );
+
+    // Gate: TJ_PROACTIVE_RECALL=0 suppresses all output.
+    let gated = String::from_utf8(
+        Command::cargo_bin("task-journal")
+            .unwrap()
+            .env("XDG_DATA_HOME", xdg.path())
+            .env("TJ_PROACTIVE_RECALL", "0")
+            .args(["recall-hook"])
+            .write_stdin(payload)
+            .assert()
+            .success()
+            .get_output()
+            .stdout
+            .clone(),
+    )
+    .unwrap();
+    assert!(
+        gated.trim().is_empty(),
+        "TJ_PROACTIVE_RECALL=0 must suppress injection; got: {gated:?}"
+    );
+}