@gamaze/hicortex 0.13.2 → 0.14.0

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` |
 | `/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/consolidate.d.ts

@@ -12,7 +12,7 @@ import { type DomainDef } from "./domain-classify.js";
  * Minimum COSINE similarity for a link candidate.
  *
  * Calibration (2026-07): measured top-10 neighbor cosine histogram on the
- * 2945-memory production corpus (bedrock). Typical top-1 neighbor cosine:
+ * ~3000-memory production corpus. Typical top-1 neighbor cosine:
  * median 0.823, p10 0.743, p90 0.902. Threshold 0.75 combined with the
  * top-3 cap yields ≈ 2.2 candidate links/memory. The previous value (0.55)
  * lived on an accidental 1−L2 scale where it required cosine > 0.90 — a

package/dist/consolidate.js

@@ -65,7 +65,7 @@ const CONSOLIDATE_PRUNE_MIN_AGE_DAYS = 90;
  * Minimum COSINE similarity for a link candidate.
  *
  * Calibration (2026-07): measured top-10 neighbor cosine histogram on the
- * 2945-memory production corpus (bedrock). Typical top-1 neighbor cosine:
+ * ~3000-memory production corpus. Typical top-1 neighbor cosine:
  * median 0.823, p10 0.743, p90 0.902. Threshold 0.75 combined with the
  * top-3 cap yields ≈ 2.2 candidate links/memory. The previous value (0.55)
  * lived on an accidental 1−L2 scale where it required cosine > 0.90 — a

package/dist/context-cli.js

@@ -261,7 +261,7 @@ function extractAgentFlag(args) {
             // A missing value (end of args) or the next token being another flag is a
             // typo — never let it silently fall through to the global scope.
             if (val === undefined || val.startsWith("-")) {
-                throw new ContextCliError("--agent requires a value, e.g. --agent lenny");
+                throw new ContextCliError("--agent requires a value, e.g. --agent alice");
             }
             agent = val;
             i++;

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/domain-classify.d.ts

@@ -5,13 +5,13 @@
  * ---------------
  * The nightly's legacy `stageDomainCuration` groups PROJECTS into domains and
  * assigns every memory its project's domain. For an owner whose "projects" are
- * often AGENT names (lenny, nano, ...), one agent produces memories spanning
+ * often AGENT names (alice, bob, ...), one agent produces memories spanning
  * many life areas, so life-memories get smeared under the agent. This module
  * classifies a single memory into life-spheres by its CONTENT, drawn from a
  * user-curated vocabulary in ~/.hicortex/config.json (`domains`).
  *
  * GRADED SCHEMA TAGS (spec 2026-07-07, supersedes the LLM-picked primary from
- * PR #152/#153): a memory genuinely spans spheres — "set up bedrock for the
+ * PR #152/#153): a memory genuinely spans spheres — "set up the server for the
  * agent fleet" is both Hardware AND Ventures. The classifier now returns ONLY
  * the discrete part:
  *   - `tags`: 0..N vocabulary names that genuinely apply, MOST-RELEVANT FIRST
@@ -31,7 +31,7 @@
  *
  * The `project` name is passed to the classifier as a HINT (content wins;
  * project only breaks ties). This rescues terse technical memories from
- * projects like raider/hiops/catalyst whose content alone reads as ambiguous.
+ * projects whose content alone reads as ambiguous.
  *
  * The classifier makes ONE constrained LLM call per memory (via the classify
  * tier — classifyModel/classifyBaseUrl when configured, else the reflect

package/dist/domain-classify.js

@@ -6,13 +6,13 @@
  * ---------------
  * The nightly's legacy `stageDomainCuration` groups PROJECTS into domains and
  * assigns every memory its project's domain. For an owner whose "projects" are
- * often AGENT names (lenny, nano, ...), one agent produces memories spanning
+ * often AGENT names (alice, bob, ...), one agent produces memories spanning
  * many life areas, so life-memories get smeared under the agent. This module
  * classifies a single memory into life-spheres by its CONTENT, drawn from a
  * user-curated vocabulary in ~/.hicortex/config.json (`domains`).
  *
  * GRADED SCHEMA TAGS (spec 2026-07-07, supersedes the LLM-picked primary from
- * PR #152/#153): a memory genuinely spans spheres — "set up bedrock for the
+ * PR #152/#153): a memory genuinely spans spheres — "set up the server for the
  * agent fleet" is both Hardware AND Ventures. The classifier now returns ONLY
  * the discrete part:
  *   - `tags`: 0..N vocabulary names that genuinely apply, MOST-RELEVANT FIRST
@@ -32,7 +32,7 @@
  *
  * The `project` name is passed to the classifier as a HINT (content wins;
  * project only breaks ties). This rescues terse technical memories from
- * projects like raider/hiops/catalyst whose content alone reads as ambiguous.
+ * projects whose content alone reads as ambiguous.
  *
  * The classifier makes ONE constrained LLM call per memory (via the classify
  * tier — classifyModel/classifyBaseUrl when configured, else the reflect

package/dist/hermes-transcript-reader.d.ts

@@ -2,7 +2,7 @@
  * Hermes transcript reader — the nightly capture path for Nous Research Hermes.
  *
  * Hermes stores conversation in a SQLite state DB, one per profile:
- *   ~/.hermes/profiles/<profile>/state.db   (per-profile agents: lenny, raider, nano)
+ *   ~/.hermes/profiles/<profile>/state.db   (per-profile agents: alice, bob, carol)
  *   ~/.hermes/state.db                       (global, non-profile setups)
  *
  * Schema (relevant columns):

package/dist/hermes-transcript-reader.js

@@ -3,7 +3,7 @@
  * Hermes transcript reader — the nightly capture path for Nous Research Hermes.
  *
  * Hermes stores conversation in a SQLite state DB, one per profile:
- *   ~/.hermes/profiles/<profile>/state.db   (per-profile agents: lenny, raider, nano)
+ *   ~/.hermes/profiles/<profile>/state.db   (per-profile agents: alice, bob, carol)
  *   ~/.hermes/state.db                       (global, non-profile setups)
  *
  * Schema (relevant columns):

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").
@@ -69,7 +83,7 @@ export declare function renderContextBlock(sections: Record<string, string>): st
  *     into every persona; on a bare fetch (no id) the guard is off (amendment
  *     A2).
  *   - CC passes `false` ALWAYS and deliberately (see the call site): a thin CC
- *     client auto-upgrades via npx BEFORE bedrock does, so during the upgrade
+ *     client auto-upgrades via npx BEFORE the server does, so during the upgrade
  *     window it talks to a 0.12 server that cannot hold ANY per-agent config —
  *     global IS the operator's intended state there, and a guard would instead
  *     blank ALL context for every CC session in that window.

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)();
@@ -180,7 +183,7 @@ function renderContextBlock(sections) {
  *     into every persona; on a bare fetch (no id) the guard is off (amendment
  *     A2).
  *   - CC passes `false` ALWAYS and deliberately (see the call site): a thin CC
- *     client auto-upgrades via npx BEFORE bedrock does, so during the upgrade
+ *     client auto-upgrades via npx BEFORE the server does, so during the upgrade
  *     window it talks to a 0.12 server that cannot hold ANY per-agent config —
  *     global IS the operator's intended state there, and a guard would instead
  *     blank ALL context for every CC session in that window.
@@ -216,7 +219,7 @@ async function fetchContextBlock(cfg) {
         return null;
     const data = await resp.json();
     // CC deliberately passes requireAgentEcho: false (NOT the OC/Hermes old-server
-    // guard). A thin CC client auto-upgrades via npx BEFORE bedrock does, so
+    // guard). A thin CC client auto-upgrades via npx BEFORE the server does, so
     // mid-upgrade it may hit a 0.12 server that returns global context with no
     // `agent` echo — and a 0.12 server cannot hold per-agent config, so global is
     // the intended state. Guarding here would blank ALL CC context in that window.

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,29 @@ 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.", {
+        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());
+            const header = `[${mem.memory_type ?? "episode"}] ${mem.project ?? ""} ${mem.created_at ?? ""}`.trim();
+            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 +470,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 +621,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 +635,50 @@ 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());
+            res.json({ memory: mem });
+        }
+        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 +686,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/pi-transcript-reader.d.ts

@@ -16,14 +16,14 @@
  *
  * Directory layout:
  *   ~/.pi/agent/sessions/
- *     --home-agents-Agents-raider--/
+ *     --home-alice-projects-myagent--/
  *       2026-04-10T18-37-44-615Z_<uuid>.jsonl
  *       2026-04-11T07-51-28-282Z_<uuid>.jsonl
  *     --home-agents-Development-MAIC--/
  *       ...
  *
- * The encoded-cwd uses double-dash separators: /home/agents/Agents/raider
- * becomes --home-agents-Agents-raider--. The session header's `cwd` field
+ * The encoded-cwd uses double-dash separators: /home/alice/projects/myagent
+ * becomes --home-alice-projects-myagent--. The session header's `cwd` field
  * is the canonical path; the directory name is a filesystem-safe encoding.
  */
 import type { TranscriptBatch, CursorMap } from "./transcript-reader.js";

package/dist/pi-transcript-reader.js

@@ -17,14 +17,14 @@
  *
  * Directory layout:
  *   ~/.pi/agent/sessions/
- *     --home-agents-Agents-raider--/
+ *     --home-alice-projects-myagent--/
  *       2026-04-10T18-37-44-615Z_<uuid>.jsonl
  *       2026-04-11T07-51-28-282Z_<uuid>.jsonl
  *     --home-agents-Development-MAIC--/
  *       ...
  *
- * The encoded-cwd uses double-dash separators: /home/agents/Agents/raider
- * becomes --home-agents-Agents-raider--. The session header's `cwd` field
+ * The encoded-cwd uses double-dash separators: /home/alice/projects/myagent
+ * becomes --home-alice-projects-myagent--. The session header's `cwd` field
  * is the canonical path; the directory name is a filesystem-safe encoding.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
@@ -157,7 +157,7 @@ function readPiTranscripts(since, sessionsDir = DEFAULT_PI_SESSIONS_DIR, cursors
 }
 /**
  * Extract the last path segment from a cwd as the project name.
- * /home/agents/Agents/raider → "raider"
+ * /home/alice/projects/myagent → "myagent"
  * Falls back to decoding the directory name if cwd is empty.
  */
 function deriveProjectName(cwd, encodedDir) {
@@ -165,7 +165,7 @@ function deriveProjectName(cwd, encodedDir) {
         const segments = cwd.split("/").filter(Boolean);
         return segments[segments.length - 1] ?? "unknown";
     }
-    // Decode the Pi directory encoding: --home-agents-Agents-raider-- → raider
+    // Decode the Pi directory encoding: --home-alice-projects-myagent-- → myagent
     const decoded = encodedDir.replace(/^--/, "").replace(/--$/, "").split("-");
     return decoded[decoded.length - 1] ?? "unknown";
 }