@gamaze/hicortex 0.13.3 → 0.14.1

package/README.md

@@ -66,8 +66,11 @@ The plugin connects to `http://127.0.0.1:8787` by default. For a remote server,
 | When | What | How |
 |------|------|-----|
 | Agent start | Standing context (`## Context`) + recent lessons fetched fresh and injected | CC SessionStart hook (calls `hicortex lessons-context`) / Hermes plugin `system_prompt_block` (+ `prefetch` recall) / OC `before_agent_start` hook |
+| Every prompt (0.14) | A compact **recall index** of relevant memories is injected — one line per memory; the agent lazy-loads full content with `hicortex_get` only when needed | CC UserPromptSubmit hook (calls `hicortex recall-hook` → server `POST /recall-index`). Turn-based dedup per session; resets on new session/compaction. Fail-soft, 1 s timeout |
 | Nightly | Denoise sessions → POST /distill → server distills + embeds + stores → consolidate (score, reflect, link, decay) | Automatic pipeline — no manual steps |
 
+**Exposure vs use (0.14):** appearing in the recall index only marks a memory as *shown* (it stops decaying while topically active); fetching it with `hicortex_get` marks it as *used* (durable strengthening). Memory importance is driven by what agents actually use, not by what was pushed at them.
+
 ## Memory Domains & Tags
 
 Domains are your top-level memory spheres — the handful of areas your life or work actually splits into. Every memory gets **multiple weighted tags** from your domain list plus one **primary** domain, so a memory that spans areas (a work project that touches your finances) lives in both instead of being forced into one bin. Domains drive the knowledge index, graph coloring, and lesson selection.
@@ -107,9 +110,10 @@ The run is resumable — interrupt it any time and it continues where it stopped
 
 ## Agent Tools (MCP)
 
-8 tools available via MCP:
+9 tools available via MCP:
 
 - **hicortex_search** — Semantic search across all stored memories
+- **hicortex_get** — Fetch one memory's full content by id (0.14) — the lazy-load counterpart of the recall index; fetching marks the memory as used
 - **hicortex_recent** — Get recent decisions and project state (queryless recall; renamed in 0.12)
 - **hicortex_ingest** — Store a memory directly
 - **hicortex_lessons** — Get actionable lessons from reflection
@@ -203,6 +207,14 @@ Config at `~/.hicortex/config.json`. Created by `init`. Key options:
 | `contextAgents` | Per-agent context modes (0.13): `{ "<id>": "override" \| "global" \| "off" }`. Absent + no `agents/<id>/` dir → every agent gets the global set. Boot-time (restart to apply) — see [Per-agent context](#per-agent-context-013) |
 | `agentName` | This install's per-agent context id sent as `?agent=`. **Unset by default** (CC shares the global context — no `?agent=` sent). Explicit opt-in via `init --agent-name <name>`; `init --agent-name ""` clears it. An empty/whitespace value equals unset |
 | `nightlyHour` | Local hour (0–23) for the nightly job installed by `init` (defaults: client 2, server 3). Applied on fresh installs; existing schedules are never overwritten |
+| `decayHalfLifeDays` | Memory decay half-life in days at reference importance (default: 365). Larger = slower forgetting; importance, access, and links slow it further |
+| `searchLimit` / `recentLimit` | Default result counts for search (8) and recent (12) |
+| `recentWindowDays` | Candidate window for recent recall (default: 180) |
+| `coldExposureSlots` | Top-k slots reservable for never-accessed memories so the long tail gets exposure (default: 2) |
+| `recallMaxItems` | Max lines in the pushed recall index (default: 6) |
+| `recallMinSimilarity` | Relevance floor for index entries (default: 0.55; text-search matches always pass) |
+| `recallReshowTurns` | Turns before an already-shown memory may reappear in the same session (default: 30) |
+| `recallMinPromptChars` | Prompts shorter than this skip the recall index (default: 20) |
 | `telemetry` | Anonymous usage telemetry, `false` to opt out |
 
 Full docs: [hicortex.gamaze.com/docs/configuration.html](https://hicortex.gamaze.com/docs/configuration.html)
@@ -214,6 +226,8 @@ Full docs: [hicortex.gamaze.com/docs/configuration.html](https://hicortex.gamaze
 | `/health` | GET | No | Server status, memory count, version |
 | `/distill` | POST | Yes | Canonical capture endpoint (0.9.0+). Accepts denoised session text (`text` string or `messages` array), distills server-side, stores. Used by both server-mode and client-mode nightly jobs. |
 | `/search` | GET | Yes | Semantic memory search |
+| `/recall-index` | POST | Yes | Pushed recall index (0.14): `{session_id, prompt}` → compact one-line-per-memory block (or `null`); `{session_id, reset: true}` clears the session's dedup state. Appearing in the index marks memories *shown*, never *used* |
+| `/memory` | GET | Yes | Fetch one memory by `?id=` (0.14). Marks it as used (strengthens) — the lazy-load counterpart of `/recall-index`. Response includes a server-rendered `citation` (id, date, origin agent) — agents are instructed to cite memories that shape their answers, so memory influence is always visible to the user (0.14.1) |
 | `/recent` | GET | Yes | Recent memories, queryless recall (renamed from `/context` in 0.12) |
 | `/context` | GET / PUT | Yes | Standing [context layer](#context-layer): read all sections / partial-upsert named sections. `?agent=<id>` selects a [per-agent scope](#per-agent-context-013) (server resolves override/global/off + merge); invalid id → 400. Recall-style query params on GET → 400 (use `/recent`) |
 | `/context/ui` | GET | No* | Web editor for the context layer (shell served without auth, like `/viz`; data via `/context`) |

package/dist/cli.js

@@ -165,6 +165,17 @@ switch (command) {
             });
         });
         break;
+    case "recall-hook":
+        // CC UserPromptSubmit + SessionStart hook: pushed recall index (#192).
+        // Reads the CC hook payload from stdin, POSTs to the server, prints the
+        // index block (UserPromptSubmit) or resets session dedup (SessionStart).
+        // Fail-soft — any error = silent exit 0, never blocks a CC session.
+        import("./recall-hook-cli.js").then(({ runRecallHook }) => {
+            runRecallHook()
+                .then(() => process.exit(0))
+                .catch(() => process.exit(0));
+        }).catch(() => process.exit(0));
+        break;
     case "lessons-context":
         // CC SessionStart hook: fetch lessons from the configured server and print
         // a Markdown block to stdout. Fail-soft — any error = silent exit 0 so a
@@ -196,6 +207,7 @@ Commands:
   relink          Resumable link-discovery pass over the ENTIRE corpus (server mode)
   classify-domains  Backfill content-based domain tags over the corpus (server mode, needs config.domains)
   lessons-context Fetch lessons and print Markdown to stdout (CC SessionStart hook)
+  recall-hook    Pushed recall index for the current prompt (CC UserPromptSubmit/SessionStart hook)
   context         Standing context layer (show|edit) against the configured server
   status          Show current configuration and stats
   uninstall       Remove CC integration (preserves DB)

package/dist/db.js

@@ -321,6 +321,20 @@ const MIGRATIONS = [
       `);
         },
     },
+    {
+        version: 8,
+        name: "add_shown_count",
+        up: (db) => {
+            // #192 recall alignment: exposure tracking separate from use. shown_count
+            // counts appearances in the pushed recall index (/recall-index), which
+            // refreshes last_accessed (mild strengthen: decay clock resets) but does
+            // NOT touch access_count — hardening, the prune shield, and the adoption
+            // metric (uses per showing) stay driven by real use only.
+            if (!hasColumn(db, "memories", "shown_count")) {
+                db.exec("ALTER TABLE memories ADD COLUMN shown_count INTEGER DEFAULT 0");
+            }
+        },
+    },
 ];
 /**
  * Run all pending migrations against the database.

package/dist/init.d.ts

@@ -119,6 +119,13 @@ export declare function isEphemeralNpxPath(binPath: string): boolean;
  * @param settingsPath Override for the settings.json path (used in tests; defaults to CC_SETTINGS).
  */
 export declare function installSessionStartHook(settingsPath?: string): void;
+/**
+ * Install (or verify) the #192 pushed-recall hooks: `hicortex recall-hook`
+ * under UserPromptSubmit (per-prompt recall index) AND under SessionStart
+ * (per-session dedup reset — the CLI dispatches on the payload's
+ * hook_event_name, so one command serves both events).
+ */
+export declare function installRecallHooks(settingsPath?: string): void;
 export declare function runInit(options?: {
     serverUrl?: string;
     agentName?: string;

package/dist/init.js

@@ -27,6 +27,7 @@ exports.decideAgentName = decideAgentName;
 exports.scaffoldDefaultDomains = scaffoldDefaultDomains;
 exports.isEphemeralNpxPath = isEphemeralNpxPath;
 exports.installSessionStartHook = installSessionStartHook;
+exports.installRecallHooks = installRecallHooks;
 exports.runInit = runInit;
 exports.resolveNightlyHour = resolveNightlyHour;
 const paths_js_1 = require("./paths.js");
@@ -960,10 +961,30 @@ function resolveBinaryArgs() {
  * @param settingsPath Override for the settings.json path (used in tests; defaults to CC_SETTINGS).
  */
 function installSessionStartHook(settingsPath) {
+    installCcHook("SessionStart", "lessons-context", 10, settingsPath);
+}
+/**
+ * Install (or verify) the #192 pushed-recall hooks: `hicortex recall-hook`
+ * under UserPromptSubmit (per-prompt recall index) AND under SessionStart
+ * (per-session dedup reset — the CLI dispatches on the payload's
+ * hook_event_name, so one command serves both events).
+ */
+function installRecallHooks(settingsPath) {
+    installCcHook("UserPromptSubmit", "recall-hook", 3, settingsPath);
+    installCcHook("SessionStart", "recall-hook", 3, settingsPath);
+}
+/**
+ * Shared CC-hook installer: add `hicortex <subcommand>` under the given hook
+ * event in ~/.claude/settings.json. Idempotent per (event, subcommand): skips
+ * if any existing entry for that event already runs the subcommand. `timeout`
+ * is CC's hook-process kill timeout in SECONDS (the network timeout inside the
+ * command is separate and shorter).
+ */
+function installCcHook(eventName, subcommand, timeout, settingsPath) {
     const targetPath = settingsPath ?? CC_SETTINGS;
     const binaryArgs = resolveBinaryArgs();
-    // Build the command string: "/path/to/hicortex lessons-context" or "npx -y @gamaze/hicortex lessons-context"
-    const command = [...binaryArgs, "lessons-context"].join(" ");
+    // e.g. "/path/to/hicortex lessons-context" or "npx -y @gamaze/hicortex recall-hook"
+    const command = [...binaryArgs, subcommand].join(" ");
     let settings = {};
     if ((0, node_fs_1.existsSync)(targetPath)) {
         try {
@@ -971,23 +992,26 @@ function installSessionStartHook(settingsPath) {
         }
         catch {
             // File exists but is malformed — do NOT overwrite (would destroy the user's entire CC config).
-            console.log(`  ⚠ ${targetPath} exists but is not valid JSON — skipping SessionStart hook.`);
+            console.log(`  ⚠ ${targetPath} exists but is not valid JSON — skipping ${eventName} hook.`);
             console.log(`    Fix the file, then re-run init, or add the hook manually:`);
             console.log(`    command: "${command}"`);
             return;
         }
     }
-    // Ensure hooks object and SessionStart array exist
+    // Ensure hooks object and the event array exist
     if (!settings.hooks || typeof settings.hooks !== "object") {
         settings.hooks = {};
     }
     const hooks = settings.hooks;
-    if (!Array.isArray(hooks.SessionStart)) {
-        hooks.SessionStart = [];
-    }
-    const sessionStart = hooks.SessionStart;
-    // Idempotent: skip if any existing entry's command contains "lessons-context"
-    const alreadyInstalled = sessionStart.some((entry) => {
+    if (!Array.isArray(hooks[eventName])) {
+        hooks[eventName] = [];
+    }
+    const entries = hooks[eventName];
+    // Idempotent: skip if any existing entry's command runs this subcommand.
+    // Word-boundary guard so "recall-hook" never matches a hypothetical
+    // "recall-hook-foo" command.
+    const subcommandRe = new RegExp(`(^|\\s)${subcommand}(\\s|$)`);
+    const alreadyInstalled = entries.some((entry) => {
         if (typeof entry !== "object" || entry === null)
             return false;
         const e = entry;
@@ -997,21 +1021,21 @@ function installSessionStartHook(settingsPath) {
                 if (typeof h !== "object" || h === null)
                     return false;
                 const hook = h;
-                return typeof hook.command === "string" && hook.command.includes("lessons-context");
+                return typeof hook.command === "string" && subcommandRe.test(hook.command);
             });
         }
         return false;
     });
     if (alreadyInstalled) {
-        console.log(`  ✓ SessionStart hook already installed`);
+        console.log(`  ✓ ${eventName} hook (${subcommand}) already installed`);
         return;
     }
-    sessionStart.push({
-        hooks: [{ type: "command", command, timeout: 10 }],
+    entries.push({
+        hooks: [{ type: "command", command, timeout }],
     });
     (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(targetPath), { recursive: true });
     (0, node_fs_1.writeFileSync)(targetPath, JSON.stringify(settings, null, 2));
-    console.log(`  ✓ Installed SessionStart hook: ${command}`);
+    console.log(`  ✓ Installed ${eventName} hook: ${command}`);
 }
 function installLaunchd(binaryArgs) {
     const plistDir = (0, node_path_1.join)((0, node_os_1.homedir)(), "Library", "LaunchAgents");
@@ -1263,6 +1287,8 @@ async function runInit(options = {}) {
     // Install CC SessionStart hook for query-time lesson injection.
     // Lessons are now fetched live at session start — no static CLAUDE.md block needed.
     installSessionStartHook();
+    // #192: per-prompt pushed recall index + session dedup reset.
+    installRecallHooks();
     // Strip the old static lessons block from CLAUDE.md (0.9.0 migration).
     // Lessons are now delivered via the SessionStart hook instead.
     const claudeMdPath = (0, node_path_1.join)((0, node_os_1.homedir)(), ".claude", "CLAUDE.md");
@@ -1418,8 +1444,10 @@ async function runClientInit(serverUrl, agentName) {
     allowHicortexTools();
     // Step 5: Install CC commands
     installCcCommands();
-    // Step 6: Install SessionStart hook for query-time lessons.
+    // Step 6: Install SessionStart hook for query-time lessons + the #192
+    // per-prompt pushed-recall hooks.
     installSessionStartHook();
+    installRecallHooks();
     // Strip the old static CLAUDE.md lessons block if present (0.9.0 migration).
     const claudeMdPath = (0, node_path_1.join)((0, node_os_1.homedir)(), ".claude", "CLAUDE.md");
     if ((0, claude_md_js_1.removeLessonsBlock)(claudeMdPath)) {

package/dist/lessons-context.d.ts

@@ -33,6 +33,20 @@ export interface ContextResponse {
     agent?: string;
     mode?: string;
 }
+export interface ResolvedConfig {
+    serverUrl: string;
+    authToken: string | undefined;
+    home: string;
+    /** Per-agent context id sent as ?agent= (0.13); null → global (no param). */
+    agentName: string | null;
+}
+/**
+ * Read ~/.hicortex/config.json and resolve the server URL + auth token, or
+ * null when there is no usable config (server not set up yet — fail soft).
+ * Exported for reuse by the recall-hook CLI (#192) so the two CC hooks can
+ * never resolve the server differently.
+ */
+export declare function resolveConfig(): ResolvedConfig | null;
 /**
  * Title-case a section name for its heading: split on `-`/`_`, capitalize each
  * word ("user" → "User", "my_notes" → "My Notes").

package/dist/lessons-context.js

@@ -23,6 +23,7 @@
  * CC session, and a broken /context fetch must never blank the whole output.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveConfig = resolveConfig;
 exports.titleCaseSection = titleCaseSection;
 exports.orderSectionNames = orderSectionNames;
 exports.renderContextBlock = renderContextBlock;
@@ -41,6 +42,8 @@ const THIS_HARNESS = "cc";
 /**
  * Read ~/.hicortex/config.json and resolve the server URL + auth token, or
  * null when there is no usable config (server not set up yet — fail soft).
+ * Exported for reuse by the recall-hook CLI (#192) so the two CC hooks can
+ * never resolve the server differently.
  */
 function resolveConfig() {
     const home = (0, paths_js_1.hicortexHome)();

package/dist/mcp-server.js

@@ -64,6 +64,8 @@ const graph_js_1 = require("./graph.js");
 const viz_js_1 = require("./viz.js");
 const context_store_js_1 = require("./context-store.js");
 const retrieval = __importStar(require("./retrieval.js"));
+const recall_registry_js_1 = require("./recall-registry.js");
+const recall_index_js_1 = require("./recall-index.js");
 const seed_lesson_js_1 = require("./seed-lesson.js");
 const distiller_js_1 = require("./distiller.js");
 // ---------------------------------------------------------------------------
@@ -85,6 +87,9 @@ let contextClients = ["cc"];
 // Read once at boot (like contextClients); the drop-in-a-dir presence path is
 // per-request, so only explicit config entries need a daemon restart to apply.
 let contextAgents = {};
+// Pushed-recall dedup registry (#192) + options; configured at boot.
+let recallRegistry = new recall_registry_js_1.SessionRecallRegistry();
+let recallIndexOptions = {};
 // Cache detectChunkSize results keyed by "<provider>/<model>@<baseUrl>" so we
 // probe each endpoint once per server boot rather than once per /distill request.
 const chunkSizeCache = new Map();
@@ -103,9 +108,9 @@ function createMcpServer() {
         version: VERSION,
     });
     // -- hicortex_search --
-    server.tool("hicortex_search", "Search long-term memory using semantic similarity. Returns the most relevant memories from past sessions.", {
+    server.tool("hicortex_search", "Search shared long-term memory (all agents, all sessions). CALL THIS BEFORE assuming, guessing, or asking the user about anything that may have come up before: prior decisions, preferences, project facts, people, hardware, past incidents. If you are about to write 'I don't have information about…', search first.", {
         query: zod_1.z.string().describe("Search query text"),
-        limit: zod_1.z.coerce.number().optional().describe("Max results (default 5)"),
+        limit: zod_1.z.coerce.number().optional().describe("Max results (default: server config searchLimit)"),
         project: zod_1.z.string().optional().describe("Filter by project name"),
     }, async ({ query, limit, project }) => {
         if (!db)
@@ -118,10 +123,34 @@ function createMcpServer() {
             return { content: [{ type: "text", text: `Search failed: ${err instanceof Error ? err.message : String(err)}` }], isError: true };
         }
     });
+    // -- hicortex_get --
+    server.tool("hicortex_get", "Fetch ONE memory's full content by id — use this to lazy-load entries from the '## Memory recall (auto)' index or from search results whose snippet was not enough. Fetching a memory marks it as used (strengthens it), so only fetch what you actually need. When the memory shapes your answer, cite it to the user (id + date + origin agent).", {
+        id: zod_1.z.string().describe("Memory id (as shown in recall index/search results)"),
+    }, async ({ id }) => {
+        if (!db)
+            return { content: [{ type: "text", text: "Hicortex not initialized" }], isError: true };
+        try {
+            const mem = storage.getMemory(db, id);
+            if (!mem)
+                return { content: [{ type: "text", text: `No memory with id ${id}` }], isError: true };
+            // Real use → full strengthen (access_count + hardening + prune shield).
+            storage.strengthenMemory(db, id, new Date().toISOString());
+            // Provenance header (built-in citing norm, 0.14.1): id, type, project,
+            // ORIGIN AGENT (shared brain — the memory may come from another
+            // agent's session), and date, plus the explicit citation instruction.
+            const date = (mem.created_at ?? "").slice(0, 10);
+            const header = `[memory ${mem.id} | ${mem.memory_type ?? "episode"} | ${mem.project ?? "-"} | from ${mem.source_agent ?? "unknown"} | ${date}]\n` +
+                `Cite as (memory ${String(mem.id).slice(0, 8)}, ${date}) where this shapes your answer; it may be stale — newer memories supersede older.`;
+            return { content: [{ type: "text", text: `${header}\n\n${mem.content ?? ""}` }] };
+        }
+        catch (err) {
+            return { content: [{ type: "text", text: `Get failed: ${err instanceof Error ? err.message : String(err)}` }], isError: true };
+        }
+    });
     // -- hicortex_recent --
-    server.tool("hicortex_recent", "Get recent memories, optionally filtered by project. Queryless recall of the latest memories by project, ranked by importance. Useful to catch up on what happened recently.", {
+    server.tool("hicortex_recent", "Get recent memories, optionally filtered by project. CALL THIS AT THE START of substantive work on a project to catch up on its latest state — cheaper than asking the user what happened.", {
         project: zod_1.z.string().optional().describe("Filter by project name"),
-        limit: zod_1.z.coerce.number().optional().describe("Max results (default 10)"),
+        limit: zod_1.z.coerce.number().optional().describe("Max results (default: server config recentLimit)"),
     }, async ({ project, limit }) => {
         if (!db)
             return { content: [{ type: "text", text: "Hicortex not initialized" }], isError: true };
@@ -446,6 +475,21 @@ async function startServer(options = {}) {
     // agents/<id> dir onto disk takes effect immediately (per-request presence).
     const resolvedAgents = (0, context_store_js_1.resolveContextAgents)(savedConfig?.contextAgents);
     contextAgents = resolvedAgents.agents;
+    // #192 recall/decay alignment: decay speed + recall breadth + pushed-recall
+    // knobs, ALL from config (see retrieval.ts configureRecall for the key list)
+    // so calibration is a config edit + restart, never a release.
+    retrieval.configureDecay({ halfLifeDays: savedConfig?.decayHalfLifeDays });
+    const recallCfg = retrieval.configureRecall(savedConfig);
+    console.log(`[hicortex] Recall: k=${recallCfg.searchLimit}/recent=${recallCfg.recentLimit}` +
+        `/window=${recallCfg.recentWindowDays}d/cold=${recallCfg.coldExposureSlots}`);
+    recallRegistry = new recall_registry_js_1.SessionRecallRegistry({
+        reshowTurns: savedConfig?.recallReshowTurns,
+    });
+    recallIndexOptions = {
+        minSimilarity: savedConfig?.recallMinSimilarity,
+        maxItems: savedConfig?.recallMaxItems,
+        minPromptLength: savedConfig?.recallMinPromptChars,
+    };
     if (resolvedAgents.dropped.length > 0) {
         console.warn(`[hicortex] Ignoring invalid contextAgents entries: ${resolvedAgents.dropped.join(", ")} ` +
             `(keys must match ^[a-z0-9][a-z0-9_-]*$; modes must be override|global|off)`);
@@ -582,7 +626,8 @@ async function startServer(options = {}) {
             res.status(400).json({ error: "Missing 'query'" });
             return;
         }
-        const limit = req.query.limit ? Number(req.query.limit) : 5;
+        // No hardcoded default: absent limit → config-driven (searchLimit).
+        const limit = req.query.limit ? Number(req.query.limit) : undefined;
         const project = typeof req.query.project === "string" && req.query.project ? req.query.project : undefined;
         const privacy = typeof req.query.privacy === "string" && req.query.privacy
             ? req.query.privacy.split(",").map((s) => s.trim()).filter(Boolean)
@@ -595,6 +640,56 @@ async function startServer(options = {}) {
             res.status(500).json({ error: err instanceof Error ? err.message : String(err) });
         }
     });
+    // REST /recall-index — pushed recall index (#192). One recall logic for all
+    // harnesses: CC UserPromptSubmit hook, Hermes/OC per-turn plugins. Returns a
+    // compact index block (or null); exposure is recorded as shown_count +
+    // last_accessed, NOT access_count (that stays reserved for hicortex_get /
+    // GET /memory — real use). {reset: true} clears the session's dedup state
+    // (SessionStart/compaction).
+    app.post("/recall-index", async (req, res) => {
+        if (!db) {
+            res.status(503).json({ error: "Server not initialized" });
+            return;
+        }
+        const r = await (0, recall_index_js_1.handleRecallIndex)({
+            db,
+            registry: recallRegistry,
+            retrieveFn: (query, limit) => retrieval.retrieve(db, embedder_js_1.embed, query, { limit, noStrengthen: true }),
+            options: recallIndexOptions,
+        }, req.body);
+        res.status(r.status).json(r.body);
+    });
+    // REST /memory?id= — fetch one memory's full content (lazy-load counterpart
+    // of /recall-index for REST clients: Hermes/OC plugins). Marks it as used.
+    app.get("/memory", (req, res) => {
+        if (!db) {
+            res.status(503).json({ error: "Server not initialized" });
+            return;
+        }
+        const id = typeof req.query.id === "string" ? req.query.id : "";
+        if (!id) {
+            res.status(400).json({ error: "Missing 'id'" });
+            return;
+        }
+        try {
+            const mem = storage.getMemory(db, id);
+            if (!mem) {
+                res.status(404).json({ error: `No memory with id ${id}` });
+                return;
+            }
+            storage.strengthenMemory(db, id, new Date().toISOString());
+            // `citation` is server-rendered so every plugin surfaces the same
+            // built-in provenance norm (owner directive 27.07) — see #193.
+            const date = (mem.created_at ?? "").slice(0, 10);
+            res.json({
+                memory: mem,
+                citation: `(memory ${String(mem.id).slice(0, 8)}, ${date}, from ${mem.source_agent ?? "unknown"})`,
+            });
+        }
+        catch (err) {
+            res.status(500).json({ error: err instanceof Error ? err.message : String(err) });
+        }
+    });
     // REST /recent — recent memories, optionally filtered by project.
     app.get("/recent", (req, res) => {
         if (!db) {
@@ -602,7 +697,8 @@ async function startServer(options = {}) {
             return;
         }
         const project = typeof req.query.project === "string" && req.query.project ? req.query.project : undefined;
-        const limit = req.query.limit ? Number(req.query.limit) : 10;
+        // No hardcoded default: absent limit → config-driven (recentLimit).
+        const limit = req.query.limit ? Number(req.query.limit) : undefined;
         const privacy = typeof req.query.privacy === "string" && req.query.privacy
             ? req.query.privacy.split(",").map((s) => s.trim()).filter(Boolean)
             : undefined;

package/dist/nightly.js

@@ -66,6 +66,7 @@ const hermes_transcript_reader_js_1 = require("./hermes-transcript-reader.js");
 const pi_transcript_reader_js_1 = require("./pi-transcript-reader.js");
 const oc_transcript_reader_js_1 = require("./oc-transcript-reader.js");
 const features_js_1 = require("./features.js");
+const retrieval_js_1 = require("./retrieval.js");
 const state_js_1 = require("./state.js");
 const capture_cursors_js_1 = require("./capture-cursors.js");
 const capture_js_1 = require("./capture.js");
@@ -209,6 +210,10 @@ async function runNightly(options = {}) {
     }
     const dbPath = (0, db_js_1.resolveDbPath)(options.dbPath);
     const port = savedConfig?.port ?? 8787;
+    // #192: consolidation's decay/prune stage must score with the same clock as
+    // the server's retrieval path (config decayHalfLifeDays, default 365).
+    (0, retrieval_js_1.configureDecay)({ halfLifeDays: savedConfig?.decayHalfLifeDays });
+    (0, retrieval_js_1.configureRecall)(savedConfig);
     const modeLabel = captureOnly ? " (capture-only)" : dryRun ? " (dry run)" : "";
     console.log(`[hicortex] Nightly pipeline starting${modeLabel}`);
     if (captureOnly) {

package/dist/recall-hook-cli.d.ts

@@ -0,0 +1,28 @@
+/**
+ * `hicortex recall-hook` — CC-side client for pushed recall (#192).
+ *
+ * Installed by init under TWO Claude Code hook events (one command, the CLI
+ * dispatches on the payload):
+ *   - UserPromptSubmit: POST the prompt to the server's /recall-index; print
+ *     the returned index block to stdout (CC injects hook stdout as context).
+ *   - SessionStart (startup/resume/clear/compact): POST a reset so the
+ *     server's per-session shown-set matches the fresh context window.
+ *
+ * Fail-soft like lessons-context: ANY failure (no config, timeout, non-2xx,
+ * parse error) prints nothing and exits 0 — a broken hook must never block or
+ * slow a CC session beyond the fetch timeout (1000 ms, owner-set).
+ */
+interface HookPayload {
+    session_id?: string;
+    hook_event_name?: string;
+    prompt?: string;
+    source?: string;
+}
+/**
+ * Build the /recall-index request body from a CC hook payload, or null when
+ * there is nothing to send (no session id, or an unhandled event). Exported
+ * for tests.
+ */
+export declare function buildHookRequest(payload: HookPayload): Record<string, unknown> | null;
+export declare function runRecallHook(): Promise<void>;
+export {};

package/dist/recall-hook-cli.js

@@ -0,0 +1,77 @@
+"use strict";
+/**
+ * `hicortex recall-hook` — CC-side client for pushed recall (#192).
+ *
+ * Installed by init under TWO Claude Code hook events (one command, the CLI
+ * dispatches on the payload):
+ *   - UserPromptSubmit: POST the prompt to the server's /recall-index; print
+ *     the returned index block to stdout (CC injects hook stdout as context).
+ *   - SessionStart (startup/resume/clear/compact): POST a reset so the
+ *     server's per-session shown-set matches the fresh context window.
+ *
+ * Fail-soft like lessons-context: ANY failure (no config, timeout, non-2xx,
+ * parse error) prints nothing and exits 0 — a broken hook must never block or
+ * slow a CC session beyond the fetch timeout (1000 ms, owner-set).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildHookRequest = buildHookRequest;
+exports.runRecallHook = runRecallHook;
+const lessons_context_js_1 = require("./lessons-context.js");
+const FETCH_TIMEOUT_MS = 1000;
+/** Read all of stdin (CC pipes the hook payload JSON). */
+async function readStdin() {
+    const chunks = [];
+    for await (const chunk of process.stdin) {
+        chunks.push(Buffer.from(chunk));
+    }
+    return Buffer.concat(chunks).toString("utf-8");
+}
+/**
+ * Build the /recall-index request body from a CC hook payload, or null when
+ * there is nothing to send (no session id, or an unhandled event). Exported
+ * for tests.
+ */
+function buildHookRequest(payload) {
+    const sessionId = typeof payload.session_id === "string" && payload.session_id
+        ? payload.session_id
+        : null;
+    if (!sessionId)
+        return null;
+    if (payload.hook_event_name === "SessionStart") {
+        return { session_id: sessionId, reset: true };
+    }
+    const prompt = typeof payload.prompt === "string" ? payload.prompt : "";
+    if (!prompt)
+        return null;
+    return { session_id: sessionId, prompt };
+}
+async function runRecallHook() {
+    const cfg = (0, lessons_context_js_1.resolveConfig)();
+    if (!cfg)
+        return;
+    let payload;
+    try {
+        payload = JSON.parse(await readStdin());
+    }
+    catch {
+        return;
+    }
+    const body = buildHookRequest(payload);
+    if (!body)
+        return;
+    const headers = { "Content-Type": "application/json" };
+    if (cfg.authToken)
+        headers["Authorization"] = `Bearer ${cfg.authToken}`;
+    const resp = await fetch(`${cfg.serverUrl}/recall-index`, {
+        method: "POST",
+        headers,
+        body: JSON.stringify(body),
+        signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
+    });
+    if (!resp.ok)
+        return;
+    const data = (await resp.json());
+    if (typeof data.block === "string" && data.block.trim() !== "") {
+        process.stdout.write(data.block + "\n");
+    }
+}

package/dist/recall-index.d.ts

@@ -0,0 +1,54 @@
+/**
+ * POST /recall-index — pushed recall index (#192).
+ *
+ * One recall logic for every harness: CC calls it from a UserPromptSubmit
+ * hook, the Hermes/OC plugins can call it per turn. The server searches the
+ * corpus with the prompt text and returns a COMPACT INDEX (one line per
+ * memory — a menu, not the meal); the agent lazy-loads full content with
+ * `hicortex_get(id)` only when a line is actually relevant.
+ *
+ * Strengthening semantics (the recall/decay alignment):
+ *   - Appearing in the index = exposure: shown_count + last_accessed refresh
+ *     (mild, temporary strengthen — the decay clock resets) via
+ *     storage.touchMemoriesShown. NO access_count bump: hardening, the prune
+ *     shield, and the adoption metric stay driven by real use.
+ *   - hicortex_get = use: full strengthen (access_count + 1).
+ *
+ * Anti-bloat gates: relevance floor (measured cosine, or a real BM25 match),
+ * per-session TURN-based dedup (SessionRecallRegistry), short-prompt skip,
+ * and a hard item cap. On a prompt with no relevant memories the block is
+ * null and the hook prints nothing.
+ */
+import type Database from "better-sqlite3";
+import type { MemorySearchResult } from "./types.js";
+import { SessionRecallRegistry } from "./recall-registry.js";
+export interface RecallIndexOptions {
+    /** Minimum measured cosine for vector-only candidates (config
+     *  `recallMinSimilarity`). FTS-matched candidates pass regardless — a BM25
+     *  text match is direct evidence of relevance. Default 0.55 (the neutral
+     *  placeholder similarity is 0.5; anything at/below that is noise). */
+    minSimilarity?: number;
+    /** Max index lines per response (config `recallMaxItems`). Default 6. */
+    maxItems?: number;
+    /** Prompts shorter than this are skipped (continuations, "yes", "do it"). */
+    minPromptLength?: number;
+}
+export interface RecallIndexResult {
+    status: number;
+    body: Record<string, unknown>;
+}
+/** First content line, de-markdowned and truncated — the index line title. */
+export declare function memoryTitle(content: string, maxLen?: number): string;
+/** Relevance gate: real text match, or measured cosine above the floor. */
+export declare function passesRelevanceGate(r: MemorySearchResult, minSimilarity: number): boolean;
+export interface RecallIndexDeps {
+    db: Database.Database;
+    registry: SessionRecallRegistry;
+    retrieveFn: (query: string, limit: number) => Promise<MemorySearchResult[]>;
+    options?: RecallIndexOptions;
+}
+/**
+ * Handle a /recall-index request body. Thin Express adapter in mcp-server.ts;
+ * all behavior lives here so tests exercise it directly.
+ */
+export declare function handleRecallIndex(deps: RecallIndexDeps, body: unknown): Promise<RecallIndexResult>;