feat: inject fact-store memory into Codex and Cursor hook context (#229)

Implements the top-ranked design (A+B) from the agent-memory
interception audit, plus the proactive storage wording change (C):

- New hooks::memory_inject module: trust-filtered, char-budgeted,
  secret-scanned digest rendering (session digests <= 2000 chars,
  per-prompt recall <= 800 chars, one sanitized line per fact).
- Codex: SessionStart/SubagentStart inject a durable-project-memory
  digest; UserPromptSubmit injects prompt-relevance-gated recall
  (in-process FactRetriever search, lexical + score gate), deduped per
  session via .tracedecay/memory_inject_seen.json.
- Cursor: sessionStart additional_context carries the same digest, and
  an always-applied rules/tracedecay-memory.mdc is materialized from
  the fact store (content-hash gated, regenerated on sessionStart /
  workspaceOpen / post-install; embedded placeholder keeps the file
  managed for uninstall).
- Recall runs through TraceDecay's own store at injection time; no
  writes to host-native memory stores. Codex doctor now suggests
  memories.use_memories=false (advisory only).
- Config gate: user_config memory_injection_enabled (default on) with
  TRACEDECAY_MEMORY_INJECTION env override.
- Rule/skill text now instructs proactive fact storage with an explicit
  do-NOT-capture list instead of "only when the user asks".

Co-authored-by: ScriptedAlchemy <zack@module-federation.io>

Author: ScriptedAlchemy

codex-plugin/skills/recalling-project-memory/SKILL.md

@@ -16,11 +16,12 @@ Recall memory **before** reaching for external or web search — prior sessions
 2. **Durable facts → `tracedecay_fact_store`** with `action: "search"` (or `"probe"` / `"reason"`), plus `query` and `min_trust`.
 3. **If the user asks to inspect or repair memory health → `tracedecay_memory_status`** (repairs derived vectors/banks; returns fact/entity counts + trust distribution).
 4. **If the user rates a recalled fact → `tracedecay_fact_feedback`** (`helpful` / `unhelpful`) to tune its trust score.
-5. **Persist a new durable decision → `tracedecay_fact_store`** `action: "add"` (`content`, `category`, `tags`, `trust`) only when the user asks to remember it.
+5. **Persist a new durable decision → `tracedecay_fact_store`** `action: "add"` (`content`, `category`, `tags`, `trust`) proactively whenever a durable decision, user preference, correction, or pitfall surfaces — do not wait for the user to ask. The add path already rejects secrets and reports near-duplicates/conflicts.
 
 ## Guardrails
 
-- `tracedecay_message_search` and `fact_store` searches are read-only. `fact_store` adds, `fact_feedback`, and `memory_status` mutate memory state; use them only for explicit user requests or ratings.
+- `tracedecay_message_search` and `fact_store` searches are read-only. `fact_feedback` and `memory_status` mutate memory state; use them for explicit user ratings or health checks.
+- Do NOT capture: secrets/credentials, transient errors, environment-specific failures, one-off narratives, task progress, or soon-stale session outcomes — recover those from transcripts instead.
 
 ## Handoff
 

cursor-plugin/rules/tracedecay-memory.mdc

@@ -0,0 +1,12 @@
+---
+description: Durable project memory from the tracedecay fact store
+alwaysApply: true
+---
+
+<!-- generated by tracedecay from the project fact store; do not edit by hand -->
+
+# Project memory (tracedecay)
+
+No durable facts stored yet. As decisions, preferences, and corrections surface, store them with `tracedecay_fact_store` (action "add") and they will appear here.
+
+Curate via `tracedecay_fact_store` (update/remove), `tracedecay_fact_feedback`, or the tracedecay dashboard.

cursor-plugin/rules/tracedecay.mdc

@@ -11,6 +11,7 @@ alwaysApply: true
 - **Write:** before adding a new helper/util, run the `tracedecay:finding-duplicate-logic` pre-write probe — it may already exist.
 - **Edit:** for anchored or structural source edits, follow the `tracedecay:atomic-code-edits` skill (`tracedecay_str_replace`, `tracedecay_replace_symbol`, `tracedecay_ast_grep_rewrite`, …) — the graph re-indexes itself after each write.
 - **Recall:** for prior decisions or past conversations, use `tracedecay_message_search` / `tracedecay_fact_store` search (skills: `tracedecay:recalling-project-memory`, `tracedecay:recalling-session-context`); for updating, deleting, or curating stored facts, use `tracedecay:curating-project-memory`.
+- **Memory:** when a durable decision, user preference, correction, or pitfall surfaces, store it proactively with `tracedecay_fact_store` (action "add") with calibrated trust — do not wait to be asked. Do NOT store secrets/credentials, transient errors, environment-specific failures, one-off narratives, or task progress.
 - **Truncated MCP responses:** if a tracedecay response has `truncated: true` plus `handle`, narrow the query first when that answers the task; if the omitted details are needed, call `tracedecay_retrieve` with the `handle` instead of guessing or re-running a broad query.
 - **MCP errors/timeouts:** if a tracedecay MCP call errors, times out, or the server is disconnected, every tool is also available as a shell command — `tracedecay tool <name> --key value` (`tracedecay tool` lists all tools, `tracedecay tool <name> --help` shows parameters; see `tracedecay:using-the-cli`). Do not query `.tracedecay` databases directly and do not abandon tracedecay because the MCP transport failed.
 - Every common workflow has a `tracedecay:*` skill (searching-for-code, tracing-functions, finding-impacted-areas, running-impacted-tests, reviewing-a-diff, code-health-report, …) — reach for the matching skill before improvising.

cursor-plugin/skills/recalling-project-memory/SKILL.md

@@ -16,11 +16,12 @@ Recall memory **before** reaching for external or web search — prior sessions
 2. **Durable facts → `tracedecay_fact_store`** with `action: "search"` (or `"probe"` / `"reason"`), plus `query` and `min_trust`.
 3. **If the user asks to inspect or repair memory health → `tracedecay_memory_status`** (repairs derived vectors/banks; returns fact/entity counts + trust distribution).
 4. **If the user rates a recalled fact → `tracedecay_fact_feedback`** (`helpful` / `unhelpful`) to tune its trust score.
-5. **Persist a new durable decision → `tracedecay_fact_store`** `action: "add"` (`content`, `category`, `tags`, `trust`) only when the user asks to remember it.
+5. **Persist a new durable decision → `tracedecay_fact_store`** `action: "add"` (`content`, `category`, `tags`, `trust`) proactively whenever a durable decision, user preference, correction, or pitfall surfaces — do not wait for the user to ask. The add path already rejects secrets and reports near-duplicates/conflicts.
 
 ## Guardrails
 
-- `tracedecay_message_search` and `fact_store` searches are read-only. `fact_store` adds, `fact_feedback`, and `memory_status` mutate memory state; use them only for explicit user requests or ratings.
+- `tracedecay_message_search` and `fact_store` searches are read-only. `fact_feedback` and `memory_status` mutate memory state; use them for explicit user ratings or health checks.
+- Do NOT capture: secrets/credentials, transient errors, environment-specific failures, one-off narratives, task progress, or soon-stale session outcomes — recover those from transcripts instead.
 
 ## Handoff
 

src/agents/codex.rs

@@ -162,6 +162,7 @@ impl AgentIntegration for CodexIntegration {
         } else {
             doctor_check_plugin(dc, &ctx.home);
         }
+        doctor_suggest_native_memories_off(dc, &ctx.home);
     }
 
     fn is_detected(&self, home: &Path) -> bool {
@@ -1386,6 +1387,51 @@ fn doctor_check_hooks(dc: &mut DoctorCounters, hooks_path: &Path) {
     }
 }
 
+/// Suggests turning off Codex's native memories *injection* when tracedecay's
+/// fact-store injection is active, so the model does not receive two parallel
+/// memory systems built from the same sessions. This is advisory only: the
+/// user's `config.toml` is never edited, and tracedecay never writes into
+/// `~/.codex/memories/` — the holographic fact store stays the single source
+/// of truth and delivery is rendered prompt context only.
+fn doctor_suggest_native_memories_off(dc: &mut DoctorCounters, home: &Path) {
+    if !crate::hooks::memory_inject::memory_injection_enabled() {
+        return;
+    }
+    let config_path = home.join(".codex/config.toml");
+    let Ok(config) = load_toml_file(&config_path) else {
+        return;
+    };
+    if codex_native_memories_injection_enabled(&config) {
+        dc.info(
+            "Codex native memories injection is enabled alongside tracedecay's \
+             fact-store injection; consider setting `memories.use_memories = false` \
+             in ~/.codex/config.toml so per-project memory comes from the tracedecay \
+             fact store only (tracedecay never edits this setting itself)",
+        );
+    }
+}
+
+/// True when Codex's experimental memories feature is on and session-start
+/// memory injection (`memories.use_memories`, default true) is not disabled.
+fn codex_native_memories_injection_enabled(config: &toml::Value) -> bool {
+    let memories_feature_on = config
+        .get("features")
+        .and_then(|features| features.get("memories"))
+        .is_some_and(|memories| {
+            // `memories = true` (bool) or the nested `[features.memories]` table
+            // form both mean the feature is enabled.
+            memories.as_bool().unwrap_or(memories.is_table())
+        });
+    if !memories_feature_on {
+        return false;
+    }
+    config
+        .get("memories")
+        .and_then(|memories| memories.get("use_memories"))
+        .and_then(toml::Value::as_bool)
+        .unwrap_or(true)
+}
+
 fn codex_hook_present(hooks: &serde_json::Value, event: &str, command: &str) -> bool {
     hooks["hooks"][event].as_array().is_some_and(|groups| {
         groups.iter().any(|group| {
@@ -1409,6 +1455,28 @@ mod tests {
         Path::new(env!("CARGO_MANIFEST_DIR")).to_path_buf()
     }
 
+    #[test]
+    fn native_memories_injection_detection_covers_config_shapes() {
+        let parse = |raw: &str| toml::from_str::<toml::Value>(raw).unwrap();
+        // Feature on (bool form), use_memories defaulting to true.
+        assert!(codex_native_memories_injection_enabled(&parse(
+            "[features]\nmemories = true\n"
+        )));
+        // Feature on (nested table form).
+        assert!(codex_native_memories_injection_enabled(&parse(
+            "[features.memories]\ncustom_tools = true\n"
+        )));
+        // Injection explicitly disabled.
+        assert!(!codex_native_memories_injection_enabled(&parse(
+            "[features]\nmemories = true\n[memories]\nuse_memories = false\n"
+        )));
+        // Feature off or absent.
+        assert!(!codex_native_memories_injection_enabled(&parse(
+            "[features]\nmemories = false\n"
+        )));
+        assert!(!codex_native_memories_injection_enabled(&parse("")));
+    }
+
     #[test]
     fn remove_legacy_codex_native_automation_deletes_stale_record() {
         let home = tempfile::tempdir().expect("tempdir should create");

src/agents/cursor.rs

@@ -141,6 +141,11 @@ async fn track_branch_after_install(project_path: Option<&Path>) {
     let Some(project_path) = project_path else {
         return;
     };
+    // Materialize the always-applied memory rule from this project's fact
+    // store so install/update-plugin leaves fresh memory in place instead of
+    // waiting for the first sessionStart hook. Fail-open, no-op when the
+    // project has no initialized store.
+    crate::hooks::memory_inject::regenerate_cursor_memory_rule(project_path).await;
     let Some(branch_name) = crate::branch::current_branch(project_path) else {
         return;
     };
@@ -189,6 +194,10 @@ const EMBEDDED_PLUGIN_FILES: &[(&str, &str)] = &[
         "rules/tracedecay.mdc",
         include_str!("../../cursor-plugin/rules/tracedecay.mdc"),
     ),
+    (
+        "rules/tracedecay-memory.mdc",
+        include_str!("../../cursor-plugin/rules/tracedecay-memory.mdc"),
+    ),
     (
         "skills/architecture-overview/SKILL.md",
         include_str!("../../cursor-plugin/skills/architecture-overview/SKILL.md"),
@@ -379,6 +388,14 @@ fn cursor_plugin_manifest_path(home: &Path) -> PathBuf {
     cursor_plugin_install_dir(home).join(".cursor-plugin/plugin.json")
 }
 
+/// Path of the materialized always-applied memory rule rendered from the
+/// project fact store (see `hooks::memory_inject::regenerate_cursor_memory_rule`).
+/// The install path writes the embedded placeholder; hooks rewrite it in
+/// place with rendered facts.
+pub fn cursor_memory_rule_path(home: &Path) -> PathBuf {
+    cursor_plugin_install_dir(home).join("rules/tracedecay-memory.mdc")
+}
+
 fn install_cursor_plugin(home: &Path, tracedecay_bin: &str) -> Result<()> {
     let install_dir = cursor_plugin_install_dir(home);
     if let Some(parent) = install_dir.parent() {

src/hook_cmd.rs

@@ -57,7 +57,7 @@ pub(crate) async fn handle_hook_command(command: Commands) -> tracedecay::errors
             exit_if_nonzero(tracedecay::hooks::hook_codex_user_prompt_submit().await);
         }
         Commands::HookCodexSubagentStart => {
-            exit_if_nonzero(tracedecay::hooks::hook_codex_subagent_start());
+            exit_if_nonzero(tracedecay::hooks::hook_codex_subagent_start().await);
         }
         Commands::HookCodexPostToolUse => {
             exit_if_nonzero(tracedecay::hooks::hook_codex_post_tool_use().await);