@gamaze/hicortex 0.14.1 → 0.14.3

package/README.md

@@ -26,7 +26,7 @@ Connects to a remote Hicortex server. No local database or local LLM needed. The
 
 ## Install — Hermes
 
-The Hermes plugin is a recall-only adapter: it injects fresh lessons every turn and exposes the full 8-tool memory surface, backed by a Hicortex server (local or remote). Capture happens automatically — the server machine's nightly job reads each Hermes profile's `state.db`.
+The Hermes plugin is a recall-only adapter: it pushes a compact recall index every turn (lazy-loaded with `hicortex_get`), injects fresh lessons, and exposes the full 9-tool memory surface, backed by a Hicortex server (local or remote). Capture happens automatically — the server machine's nightly job reads each Hermes profile's `state.db`.
 
 ```bash
 # 1. Install the plugin (prompts for server URL + auth token; leave empty for a local server)
@@ -65,8 +65,8 @@ 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 |
+| Agent start | Standing context (`## Context`) + recent lessons fetched fresh and injected | CC SessionStart hook (calls `hicortex lessons-context`) / Hermes plugin `system_prompt_block` / 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 | All three harnesses call server `POST /recall-index` per turn: CC UserPromptSubmit hook (`hicortex recall-hook`), Hermes plugin `prefetch` (0.7.0; falls back to `/search` injection against a pre-0.14 server), OC `before_agent_start` hook (fires per inbound message). Turn-based dedup per session; resets on new session/compaction. Fail-soft |
 | 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.

package/dist/index.d.ts

@@ -9,8 +9,14 @@
  * Run server:   `npx @gamaze/hicortex init`
  *
  * Responsibilities (recall-only adapter, like the Hermes plugin):
- *   - before_agent_start  → GET /lessons (fail-soft, 3s timeout) → inject context
- *   - Tools               → HTTP proxies to /search, /recent, /ingest, /lessons
+ *   - before_agent_start  → GET /context + GET /lessons + POST /recall-index
+ *     (fail-soft, 3s timeout each, concurrent) → inject context. In OpenClaw
+ *     every inbound message spawns an embedded run, so this hook fires PER
+ *     TURN with the current prompt and session id — it is the per-turn
+ *     /recall-index surface, not just session start.
+ *   - after_compaction / before_reset → POST /recall-index {reset:true}
+ *     (context rebuilt → the server's per-session shown-set is stale)
+ *   - Tools               → HTTP proxies to /search, /memory, /recent, /ingest, /lessons
  *
  * CAPTURE IS NOT THIS PLUGIN'S JOB. OpenClaw persists sessions at
  * ~/.openclaw/agents/<agentId>/sessions/*.jsonl in the Pi v3 format; the

package/dist/index.js

@@ -10,8 +10,14 @@
  * Run server:   `npx @gamaze/hicortex init`
  *
  * Responsibilities (recall-only adapter, like the Hermes plugin):
- *   - before_agent_start  → GET /lessons (fail-soft, 3s timeout) → inject context
- *   - Tools               → HTTP proxies to /search, /recent, /ingest, /lessons
+ *   - before_agent_start  → GET /context + GET /lessons + POST /recall-index
+ *     (fail-soft, 3s timeout each, concurrent) → inject context. In OpenClaw
+ *     every inbound message spawns an embedded run, so this hook fires PER
+ *     TURN with the current prompt and session id — it is the per-turn
+ *     /recall-index surface, not just session start.
+ *   - after_compaction / before_reset → POST /recall-index {reset:true}
+ *     (context rebuilt → the server's per-session shown-set is stale)
+ *   - Tools               → HTTP proxies to /search, /memory, /recent, /ingest, /lessons
  *
  * CAPTURE IS NOT THIS PLUGIN'S JOB. OpenClaw persists sessions at
  * ~/.openclaw/agents/<agentId>/sessions/*.jsonl in the Pi v3 format; the
@@ -34,6 +40,7 @@ const node_os_1 = require("node:os");
 const DEFAULT_SERVER_URL = "http://127.0.0.1:8787";
 const LESSONS_TIMEOUT_MS = 3000;
 const CONTEXT_TIMEOUT_MS = 3000;
+const RECALL_TIMEOUT_MS = 3000;
 const HICORTEX_HOME = (0, paths_js_1.hicortexHome)();
 /** Harness name this plugin injects for — used to self-gate on GET /context `clients`. */
 const THIS_HARNESS = "oc";
@@ -43,6 +50,26 @@ const THIS_HARNESS = "oc";
 let serverUrl = DEFAULT_SERVER_URL;
 let authToken;
 let hicortexHome = HICORTEX_HOME;
+/** Old-server guard (F2): 0 = not latched; otherwise the Date.now() epoch-ms
+ *  until which /recall-index is skipped after a 404 (pre-0.14 server). The
+ *  latch EXPIRES so a client-first rollout heals itself once the server is
+ *  upgraded — a permanent latch would silently disable recall on a
+ *  long-running gateway until restart. OC has no pre-0.14 per-turn recall to
+ *  fall back to, so "skip" IS the old behavior. */
+let recallIndexRetryAtMs = 0;
+/** How long a 404 latches the guard before re-probing. Long enough not to
+ *  hammer an old server every turn, short enough that a server upgrade is
+ *  picked up within minutes. */
+const RECALL_REPROBE_INTERVAL_MS = 600_000;
+/** Warn-once flag (F5): the recall index needs ctx.sessionId from the
+ *  gateway; if a gateway variant doesn't pass it the feature must not run
+ *  silently dead. */
+let warnedMissingSessionId = false;
+/** Plugin logger captured at service start (ctx.logger or console). */
+let pluginLog = console.log;
+function recallIndexLatched() {
+    return recallIndexRetryAtMs !== 0 && Date.now() < recallIndexRetryAtMs;
+}
 // ---------------------------------------------------------------------------
 // HTTP helpers
 // ---------------------------------------------------------------------------
@@ -148,6 +175,59 @@ async function buildLessonsBlock(project) {
         formatted.join("\n"));
 }
 // ---------------------------------------------------------------------------
+// Pushed recall index (#193) — per-turn POST /recall-index
+// ---------------------------------------------------------------------------
+/**
+ * Fetch the pushed recall index for this turn, or null when there is nothing
+ * to inject (null block, no session id, failure, or a pre-0.14 server). The
+ * server does all relevance gating and per-session TURN-based dedup — the
+ * plugin sends every turn and carries no tuning constants. A 404 flips the
+ * module-level guard so an old server is probed once per gateway process.
+ */
+async function fetchRecallIndexBlock(sessionId, prompt) {
+    if (recallIndexLatched())
+        return null;
+    if (!sessionId || !prompt) {
+        // Verified against the installed OpenClaw gateway dist (auth-profiles
+        // bundle, runEmbeddedPiAgent → hookCtx): before_agent_start receives
+        // {agentId, sessionKey, sessionId, workspaceDir, …} on every run. If a
+        // gateway variant does NOT pass sessionId, the feature would run silently
+        // dead behind fail-soft — warn once per process so it is diagnosable.
+        if (!sessionId && prompt && !warnedMissingSessionId) {
+            warnedMissingSessionId = true;
+            pluginLog("[hicortex] WARNING: before_agent_start ctx has no sessionId — " +
+                "per-turn memory recall is disabled. Upgrade OpenClaw (the gateway " +
+                "must pass sessionId to plugin hooks).");
+        }
+        return null;
+    }
+    const { ok, status, data } = await serverPost("/recall-index", { session_id: sessionId, prompt }, RECALL_TIMEOUT_MS);
+    if (status === 404) {
+        recallIndexRetryAtMs = Date.now() + RECALL_REPROBE_INTERVAL_MS;
+        return null;
+    }
+    if (!ok || !data)
+        return null;
+    recallIndexRetryAtMs = 0;
+    return typeof data.block === "string" && data.block.trim() !== "" ? data.block : null;
+}
+/**
+ * Reset the session's server-side recall dedup — the context window was
+ * rebuilt (compaction or session reset), so the shown-set is stale by
+ * definition. Fire-and-forget fail-soft: a reset that is lost only means some
+ * memories stay suppressed until the re-show window (`recallReshowTurns`)
+ * passes.
+ */
+async function postRecallReset(sessionId) {
+    if (recallIndexLatched())
+        return;
+    if (!sessionId)
+        return;
+    const { status } = await serverPost("/recall-index", { session_id: sessionId, reset: true }, RECALL_TIMEOUT_MS);
+    if (status === 404)
+        recallIndexRetryAtMs = Date.now() + RECALL_REPROBE_INTERVAL_MS;
+}
+// ---------------------------------------------------------------------------
 // Tool result formatter
 // ---------------------------------------------------------------------------
 function formatToolResults(results) {
@@ -182,6 +262,11 @@ exports.default = {
                 authToken = config.authToken;
                 // Use stateDir from context so tests can redirect state writes
                 hicortexHome = ctx.stateDir ?? HICORTEX_HOME;
+                // Re-probe /recall-index support on every (re)start — the server may
+                // have been upgraded while the gateway was down.
+                recallIndexRetryAtMs = 0;
+                warnedMissingSessionId = false;
+                pluginLog = log;
                 log(`[hicortex] Thin-client mode — server: ${serverUrl}`);
                 // License: init feature cache (only needs licenseKey, no DB access)
                 await (0, features_js_1.initFeatures)(config.licenseKey, hicortexHome);
@@ -211,9 +296,11 @@ exports.default = {
             },
         });
         // -----------------------------------------------------------------------
-        // Hook: before_agent_start — fetch context + lessons from server (fail-soft)
+        // Hook: before_agent_start — fetch context + lessons + recall index
+        // (fail-soft). Fires per embedded run = per inbound message in OpenClaw,
+        // so the recall index rides the same hook as the per-turn surface.
         // -----------------------------------------------------------------------
-        api.on("before_agent_start", async (_event, ctx) => {
+        api.on("before_agent_start", async (event, ctx) => {
             // Outer guard: the hook must NEVER throw (a rejection could block the
             // agent). `ctx` itself can be nullish on some gateway variants, and the
             // synchronous sanitize below runs before any per-fetch .catch — so the
@@ -223,15 +310,16 @@ exports.default = {
                 // sanitizes to null → bare /context → global set). Null id never sends
                 // ?agent=, so an old server behaves exactly as before.
                 const agentId = (0, context_store_js_1.sanitizeAgentId)(ctx?.agentId ?? "");
-                // Fetch both concurrently with INDEPENDENT fail-soft: a /context
-                // failure must never cost the lessons block, and vice versa. The
-                // `## Context` block (standing context, 0.13) is prepended before
-                // `## Hicortex Lessons`, mirroring the CC hook.
-                const [contextBlock, lessonsBlock] = await Promise.all([
+                // Fetch all three concurrently with INDEPENDENT fail-soft: no block
+                // may ever cost another. Order in the injected context: `## Context`
+                // (standing context, 0.13) → `## Hicortex Lessons` → the per-turn
+                // `## Memory recall (auto)` index (#193, closest to the prompt).
+                const [contextBlock, lessonsBlock, recallBlock] = await Promise.all([
                     fetchOcContextBlock(agentId).catch(() => null),
                     buildLessonsBlock(ctx?.project).catch(() => null),
+                    fetchRecallIndexBlock(ctx?.sessionId, event?.prompt).catch(() => null),
                 ]);
-                const blocks = [contextBlock, lessonsBlock].filter((b) => b !== null && b !== "");
+                const blocks = [contextBlock, lessonsBlock, recallBlock].filter((b) => b !== null && b !== "");
                 if (blocks.length === 0)
                     return {};
                 return { appendSystemContext: `\n\n${blocks.join("\n\n")}\n` };
@@ -241,6 +329,22 @@ exports.default = {
             }
         });
         // -----------------------------------------------------------------------
+        // Hooks: after_compaction / before_reset — reset the session's recall
+        // dedup (#193). Both rebuild the context window, so the server's
+        // per-session shown-set no longer reflects what the agent can see.
+        // Unknown hook names are ignored by older gateways (typed-hook registry
+        // warns and drops them), so registering both is safe everywhere.
+        // -----------------------------------------------------------------------
+        const recallResetHook = (_event, ctx) => {
+            // Genuinely fire-and-forget (F9): no await — a slow server must never
+            // add latency to compaction or session reset in the gateway.
+            void postRecallReset(ctx?.sessionId).catch(() => {
+                /* fail-soft — never surface into the gateway */
+            });
+        };
+        api.on("after_compaction", recallResetHook);
+        api.on("before_reset", recallResetHook);
+        // -----------------------------------------------------------------------
         // Tools — HTTP proxies to server REST API
         // -----------------------------------------------------------------------
         api.registerTool((_ctx) => ({
@@ -272,6 +376,39 @@ exports.default = {
                 }
             },
         }), { name: "hicortex_search" });
+        api.registerTool((_ctx) => ({
+            name: "hicortex_get",
+            description: "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 as given in the response.",
+            parameters: {
+                type: "object",
+                properties: {
+                    id: { type: "string", description: "Memory ID (as shown in the recall index or search results)" },
+                },
+                required: ["id"],
+            },
+            async execute(_callId, args, _ctx) {
+                try {
+                    if (!args?.id)
+                        return { error: "id is required" };
+                    const params = new URLSearchParams({ id: String(args.id) });
+                    const { data, status } = await serverGet(`/memory?${params}`, 10000);
+                    if (status === 404) {
+                        // Either no such memory (0.14+) or a pre-0.14 server with no
+                        // /memory endpoint — the id hint covers the common case.
+                        return { error: `Memory not found: ${args.id} (or the server predates 0.14 — upgrade the server)` };
+                    }
+                    if (!data)
+                        return { error: `Get failed: ${describeGetFailure(status, "/memory")}` };
+                    // Render the content BEHIND the server's citation string — the
+                    // server-side rendering is the single provenance norm (0.14.1).
+                    const text = `${data.citation ?? ""}\n\n${data.memory?.content ?? ""}`.trim();
+                    return { content: [{ type: "text", text }] };
+                }
+                catch (err) {
+                    return { error: `Get failed: ${err instanceof Error ? err.message : String(err)}` };
+                }
+            },
+        }), { name: "hicortex_get" });
         api.registerTool((_ctx) => ({
             name: "hicortex_recent",
             description: "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.",
@@ -495,6 +632,7 @@ exports.default = {
 // ---------------------------------------------------------------------------
 const HICORTEX_TOOLS = [
     "hicortex_search",
+    "hicortex_get",
     "hicortex_recent",
     "hicortex_ingest",
     "hicortex_lessons",

package/dist/mcp-server.js

@@ -130,11 +130,14 @@ function createMcpServer() {
         if (!db)
             return { content: [{ type: "text", text: "Hicortex not initialized" }], isError: true };
         try {
-            const mem = storage.getMemory(db, id);
+            // Prefix ids resolve (F6): citations show the 8-char id, so this tool
+            // must accept it like /update and /delete do.
+            const fullId = storage.resolveMemoryId(db, id);
+            const mem = fullId ? storage.getMemory(db, fullId) : null;
             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());
+            storage.strengthenMemory(db, mem.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.
@@ -654,37 +657,30 @@ async function startServer(options = {}) {
         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 }),
+            // Client-pushed project/privacy scoping (F1) rides through to
+            // retrieval, which handles the filtered over-fetch itself.
+            retrieveFn: (query, limit, filters) => retrieval.retrieve(db, embedder_js_1.embed, query, {
+                limit,
+                noStrengthen: true,
+                project: filters?.project,
+                privacy: filters?.privacy,
+            }),
             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.
+    // REST /memory?id=[&privacy=] — fetch one memory's full content (lazy-load
+    // counterpart of /recall-index for REST clients: Hermes/OC plugins). Marks
+    // it as used. Prefix ids resolve; a privacy filter miss reads as 404 (no
+    // existence leak). Logic in handleMemoryGet (recall-index.ts).
     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"})`,
-            });
+            const r = (0, recall_index_js_1.handleMemoryGet)(db, { id: req.query.id, privacy: req.query.privacy });
+            res.status(r.status).json(r.body);
         }
         catch (err) {
             res.status(500).json({ error: err instanceof Error ? err.message : String(err) });
@@ -1201,21 +1197,9 @@ async function startServer(options = {}) {
 // ---------------------------------------------------------------------------
 /**
  * Resolve a short ID prefix (e.g. "a1b2c3d4") to a full memory UUID.
+ * Canonical implementation lives in storage.ts (shared with handleMemoryGet).
  */
-function resolveMemoryId(database, idPrefix) {
-    if (idPrefix.length >= 36) {
-        // Full UUID — check existence
-        const row = database.prepare("SELECT id FROM memories WHERE id = ?").get(idPrefix);
-        return row?.id ?? null;
-    }
-    // Short prefix — find matching memory
-    const rows = database.prepare("SELECT id FROM memories WHERE id LIKE ?").all(`${idPrefix}%`);
-    if (rows.length === 1)
-        return rows[0].id;
-    if (rows.length > 1)
-        return null; // Ambiguous
-    return null;
-}
+const resolveMemoryId = storage.resolveMemoryId;
 /**
  * Read ~/.hicortex/config.json (persisted by init with LLM and license config).
  */
@@ -1271,7 +1255,10 @@ function fixDaemonVersionPin() {
 function formatResults(results) {
     if (results.length === 0)
         return "No memories found.";
+    // The id makes every recall surface feed the rest of the toolset: cite-on-use
+    // (id + date), hicortex_get lazy-load of truncated content, hicortex_graph
+    // entry points, and hicortex_update/delete self-correction (#192).
     return results
-        .map((r) => `[${r.memory_type}] (score: ${r.score.toFixed(3)}, strength: ${r.effective_strength.toFixed(3)}) ${r.content.slice(0, 500)}`)
+        .map((r) => `[${r.id}] [${r.memory_type}] (${(r.created_at ?? "").slice(0, 10)}, score: ${r.score.toFixed(3)}, strength: ${r.effective_strength.toFixed(3)}) ${r.content.slice(0, 500)}`)
         .join("\n\n");
 }

package/dist/recall-index.d.ts

@@ -41,14 +41,42 @@ export interface RecallIndexResult {
 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;
+/** Recall filters a client may push per request (#193 review F1): a scoped
+ *  plugin (Hermes privacy_filter / default_project) must be able to narrow
+ *  recall exactly like the legacy /search prefetch did — dropping them
+ *  silently would leak out-of-scope memory titles into the injected index. */
+export interface RecallFilters {
+    project?: string;
+    privacy?: string[];
+}
 export interface RecallIndexDeps {
     db: Database.Database;
     registry: SessionRecallRegistry;
-    retrieveFn: (query: string, limit: number) => Promise<MemorySearchResult[]>;
+    retrieveFn: (query: string, limit: number, filters?: RecallFilters) => Promise<MemorySearchResult[]>;
     options?: RecallIndexOptions;
 }
+/** Normalize a request-supplied privacy filter: array of strings or a CSV
+ *  string → string[] | undefined. Anything else (or an empty result) means
+ *  "no filter" — never a partial guess. */
+export declare function parsePrivacyParam(v: unknown): string[] | undefined;
 /**
  * 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>;
+/**
+ * Handle a GET /memory request (lazy-load counterpart of the recall index for
+ * REST clients). Thin Express adapter in mcp-server.ts; behavior lives here so
+ * tests exercise it directly.
+ *
+ *   - Short/prefix ids resolve via storage.resolveMemoryId (F6) — the 8-char
+ *     citation ids agents are taught must work here like on /update, /delete.
+ *   - Optional `privacy` filter (array or CSV): when present and the memory's
+ *     privacy level is not in the allowed set, respond 404 with the SAME
+ *     not-found message — a scoped client must not learn the memory exists.
+ *   - A successful fetch is real use: access_count + 1 (strengthen).
+ */
+export declare function handleMemoryGet(db: Database.Database, query: {
+    id?: unknown;
+    privacy?: unknown;
+}): RecallIndexResult;

package/dist/recall-index.js

@@ -56,7 +56,9 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.memoryTitle = memoryTitle;
 exports.passesRelevanceGate = passesRelevanceGate;
+exports.parsePrivacyParam = parsePrivacyParam;
 exports.handleRecallIndex = handleRecallIndex;
+exports.handleMemoryGet = handleMemoryGet;
 const storage = __importStar(require("./storage.js"));
 const DEFAULT_MIN_SIMILARITY = 0.55;
 const DEFAULT_MAX_ITEMS = 6;
@@ -96,6 +98,18 @@ function passesRelevanceGate(r, minSimilarity) {
         return true;
     return typeof r.similarity === "number" && r.similarity >= minSimilarity;
 }
+/** Normalize a request-supplied privacy filter: array of strings or a CSV
+ *  string → string[] | undefined. Anything else (or an empty result) means
+ *  "no filter" — never a partial guess. */
+function parsePrivacyParam(v) {
+    const items = Array.isArray(v)
+        ? v.filter((x) => typeof x === "string")
+        : typeof v === "string"
+            ? v.split(",")
+            : [];
+    const cleaned = items.map((s) => s.trim()).filter(Boolean);
+    return cleaned.length > 0 ? cleaned : undefined;
+}
 /**
  * Handle a /recall-index request body. Thin Express adapter in mcp-server.ts;
  * all behavior lives here so tests exercise it directly.
@@ -120,9 +134,15 @@ async function handleRecallIndex(deps, body) {
     const maxItems = clampInt(deps.options?.maxItems, DEFAULT_MAX_ITEMS, 1, 20);
     const minSimilarity = clampNumber(deps.options?.minSimilarity, DEFAULT_MIN_SIMILARITY, 0, 1);
     const turn = deps.registry.beginTurn(sessionId);
+    // Optional client-side scoping (F1): project + privacy ride the body and
+    // are pushed into retrieval (which handles filtered over-fetch itself).
+    const filters = {
+        project: typeof req.project === "string" && req.project ? req.project : undefined,
+        privacy: parsePrivacyParam(req.privacy),
+    };
     let results;
     try {
-        results = await deps.retrieveFn(prompt, maxItems * CANDIDATE_MULTIPLIER);
+        results = await deps.retrieveFn(prompt, maxItems * CANDIDATE_MULTIPLIER, filters);
     }
     catch (err) {
         return {
@@ -155,6 +175,47 @@ async function handleRecallIndex(deps, body) {
     ].join("\n");
     return { status: 200, body: { block, shown: ids, turn } };
 }
+/**
+ * Handle a GET /memory request (lazy-load counterpart of the recall index for
+ * REST clients). Thin Express adapter in mcp-server.ts; behavior lives here so
+ * tests exercise it directly.
+ *
+ *   - Short/prefix ids resolve via storage.resolveMemoryId (F6) — the 8-char
+ *     citation ids agents are taught must work here like on /update, /delete.
+ *   - Optional `privacy` filter (array or CSV): when present and the memory's
+ *     privacy level is not in the allowed set, respond 404 with the SAME
+ *     not-found message — a scoped client must not learn the memory exists.
+ *   - A successful fetch is real use: access_count + 1 (strengthen).
+ */
+function handleMemoryGet(db, query) {
+    const id = typeof query.id === "string" ? query.id : "";
+    if (!id)
+        return { status: 400, body: { error: "Missing 'id'" } };
+    const notFound = {
+        status: 404,
+        body: { error: `No memory with id ${id}` },
+    };
+    const fullId = storage.resolveMemoryId(db, id);
+    if (!fullId)
+        return notFound;
+    const mem = storage.getMemory(db, fullId);
+    if (!mem)
+        return notFound;
+    const privacy = parsePrivacyParam(query.privacy);
+    if (privacy && !privacy.includes(mem.privacy))
+        return notFound;
+    storage.strengthenMemory(db, fullId, 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);
+    return {
+        status: 200,
+        body: {
+            memory: mem,
+            citation: `(memory ${String(mem.id).slice(0, 8)}, ${date}, from ${mem.source_agent ?? "unknown"})`,
+        },
+    };
+}
 function clampInt(v, dflt, min, max) {
     const n = Number(v);
     if (!Number.isFinite(n))

package/dist/storage.d.ts

@@ -18,6 +18,11 @@ export declare function embedToBlob(embedding: Float32Array): Buffer;
  * omit sourceSession (NULL — nightly distillation, tests) never collide.
  */
 export declare function insertMemory(db: Database.Database, content: string, embedding: Float32Array, opts?: InsertMemoryOptions): string;
+/**
+ * Resolve a short ID prefix (e.g. the 8-char id shown in citations and the
+ * recall index) to a full memory UUID. Null when unknown or ambiguous.
+ */
+export declare function resolveMemoryId(db: Database.Database, idPrefix: string): string | null;
 /**
  * Get a single memory by ID. Returns null if not found.
  */

package/dist/storage.js

@@ -6,6 +6,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.embedToBlob = embedToBlob;
 exports.insertMemory = insertMemory;
+exports.resolveMemoryId = resolveMemoryId;
 exports.getMemory = getMemory;
 exports.updateMemory = updateMemory;
 exports.strengthenMemory = strengthenMemory;
@@ -83,6 +84,22 @@ function insertMemory(db, content, embedding, opts = {}) {
     }
     return id;
 }
+/**
+ * Resolve a short ID prefix (e.g. the 8-char id shown in citations and the
+ * recall index) to a full memory UUID. Null when unknown or ambiguous.
+ */
+function resolveMemoryId(db, idPrefix) {
+    if (idPrefix.length >= 36) {
+        const row = db
+            .prepare("SELECT id FROM memories WHERE id = ?")
+            .get(idPrefix);
+        return row?.id ?? null;
+    }
+    const rows = db
+        .prepare("SELECT id FROM memories WHERE id LIKE ?")
+        .all(`${idPrefix}%`);
+    return rows.length === 1 ? rows[0].id : null;
+}
 /**
  * Get a single memory by ID. Returns null if not found.
  */

package/hermes-plugin/hicortex/README.md

@@ -12,13 +12,18 @@ Gives [Hermes](https://github.com/nousresearch/hermes-agent) agents self-learnin
 
 | Hermes hook | What it does | Hicortex call |
 |---|---|---|
-| `prefetch(query)` | recall relevant memories before each turn | `GET /search` |
-| `queue_prefetch(query)` | background recall for the next turn | `GET /search` |
+| `prefetch(query)` | pushed **recall index** each turn — a compact one-line-per-memory menu; the agent lazy-loads full content with `hicortex_get` | `POST /recall-index` (falls back to `GET /search` full-content injection on a pre-0.14 server) |
+| `queue_prefetch(query)` | no-op on the recall-index path (the server dedups per turn; a client cache would double-suppress). Background `GET /search` only on the pre-0.14 fallback path | — / `GET /search` |
+| `initialize(session_id)` | reset the session's server-side recall dedup (new session = fresh context) | `POST /recall-index` `{reset: true}` |
 | `system_prompt_block()` | inject per-agent standing context + distilled lessons + memory index | `GET /context`, `GET /lessons` |
-| `get_tool_schemas()` | exposes the 8 unified tools | see tool table below |
+| `get_tool_schemas()` | exposes the 9 unified tools | see tool table below |
 
 That's the whole surface. No `sync_turn`, no compaction/session-end capture — those are intentionally absent.
 
+### Pushed recall index (0.7.0, server ≥ 0.14)
+
+Instead of injecting full memory content every turn, `prefetch` sends the user's message to the server's `POST /recall-index` and injects the returned **index block** verbatim — one line per memory (id, title, date), capped and relevance-gated server-side. The agent fetches full content with `hicortex_get(id)` only when a line is actually relevant; that fetch is what strengthens the memory (exposure ≠ use). All tuning knobs (`recallMaxItems`, `recallMinSimilarity`, `recallReshowTurns`, `recallMinPromptChars`, …) live in the **server** config — the plugin carries none. Dedup is turn-based and server-side per session; the plugin resets it at `initialize` (the Hermes `MemoryProvider` interface exposes no compaction signal, so a mid-session context rebuild cannot trigger a reset — the server's turn-based re-show window covers that gap). Against a pre-0.14 server (404) the plugin falls back to the 0.6.x `GET /search` full-content prefetch, fail-soft, re-probing the endpoint every 10 minutes so a later server upgrade is picked up without a gateway restart. The recall calls carry the profile's configured `privacy_filter`/`default_project` and use a short dedicated timeout (1.5 s) so a slow server can never stall a turn.
+
 ### Per-agent standing context (0.13)
 
 `system_prompt_block()` also injects the hand-edited **standing context layer** (`## Context`, above the lessons block) — "who you are + how to work", distinct from episodic memory. The server resolves it **per agent**: this profile's own sections override the global set (`override`), or it can be `global` or `off`. See the main repo's `/context` layer docs.
@@ -32,11 +37,12 @@ The plugin sends its **profile name** as `?agent=`, resolved in this order:
 
 Leave `agent_name` blank to auto-derive (2–4). Context injection needs a Hicortex server **≥ 0.13**; against an older server the plugin detects the missing per-agent support and injects no context (lessons are unaffected). Context and lessons fail soft independently — a context failure never costs the lessons block.
 
-### Tools (unified 8)
+### Tools (unified 9)
 
 | Tool | REST call | Description |
 |---|---|---|
 | `hicortex_search` | `GET /search` | Semantic search over long-term memory |
+| `hicortex_get` | `GET /memory` | Fetch one memory's full content by id (lazy-load counterpart of the recall index; marks the memory as used) |
 | `hicortex_recent` | `GET /recent` | Recent memories by project (queryless recall; was `hicortex_context`/`hicortex_recall_recent` before 0.12) |
 | `hicortex_ingest` | `POST /ingest` | Store a new memory |
 | `hicortex_lessons` | `GET /lessons` | Get distilled lessons |
@@ -48,7 +54,7 @@ Leave `agent_name` blank to auto-derive (2–4). Context injection needs a Hicor
 ## Prerequisites
 
 - A reachable Hicortex server (default `http://localhost:8787`). Stand one up with `npx @gamaze/hicortex init`.
-- The server needs the REST `/search`, `/recent`, `/lessons` endpoints (Hicortex ≥ 0.12 — this plugin version does not talk to older servers; upgrade the server first).
+- Hicortex ≥ **0.14** for the pushed recall index and `hicortex_get` (`POST /recall-index`, `GET /memory`). Against a 0.12/0.13 server the plugin falls back to the 0.6.x `/search` prefetch; servers < 0.12 are not supported — upgrade the server first.
 
 ## Install
 

package/hermes-plugin/hicortex/__init__.py

@@ -1,7 +1,8 @@
 """Hicortex memory provider plugin for Hermes — recall-only.
 
-Recall:   prefetch()          -> GET /search   (relevant memories before each turn)
-          tools               -> hicortex_search / hicortex_recent
+Recall:   prefetch()          -> POST /recall-index (pushed recall index; falls
+                                 back to GET /search on a pre-0.14 server)
+          tools               -> hicortex_search / hicortex_get / hicortex_recent / …
           system_prompt_block -> lessons injected into the system prompt
 
 Capture is NOT the plugin's job. A nightly reader on the Hicortex server

package/hermes-plugin/hicortex/client.py

@@ -39,32 +39,69 @@ class HicortexClient:
             h["Authorization"] = f"Bearer {self.auth_token}"
         return h
 
-    def _get(self, path: str, params: Optional[dict[str, Any]] = None) -> Any:
+    def _build_url(self, path: str, params: Optional[dict[str, Any]] = None) -> str:
         url = f"{self.base_url}{path}"
         if params:
             qs = urllib.parse.urlencode(
                 {k: v for k, v in params.items() if v is not None}
             )
-            url = f"{url}?{qs}"
-        req = urllib.request.Request(url, headers=self._headers(), method="GET")
-        with urllib.request.urlopen(req, timeout=self.timeout) as resp:
-            return json.loads(resp.read().decode("utf-8"))
+            if qs:
+                url = f"{url}?{qs}"
+        return url
+
+    @staticmethod
+    def _parse_http_error(e: urllib.error.HTTPError) -> Any:
+        """Parse an HTTPError body: JSON when possible, else {'error': text}."""
+        body_bytes = e.read()
+        try:
+            return json.loads(body_bytes.decode("utf-8"))
+        except Exception:
+            return {"error": body_bytes.decode("utf-8", errors="replace")}
 
-    def _post(self, path: str, body: dict[str, Any]) -> tuple[int, Any]:
-        """POST JSON body; returns (status_code, parsed_response)."""
-        url = f"{self.base_url}{path}"
-        data = json.dumps(body).encode("utf-8")
-        req = urllib.request.Request(url, data=data, headers=self._headers(), method="POST")
+    def _request(
+        self,
+        method: str,
+        url: str,
+        data: Optional[bytes] = None,
+        timeout: Optional[float] = None,
+    ) -> tuple[int, Any]:
+        """Perform a request; returns (status_code, parsed_response) with HTTP
+        errors converted to statuses (never raised)."""
+        req = urllib.request.Request(url, data=data, headers=self._headers(), method=method)
         try:
-            with urllib.request.urlopen(req, timeout=self.timeout) as resp:
+            with urllib.request.urlopen(req, timeout=timeout or self.timeout) as resp:
                 return resp.status, json.loads(resp.read().decode("utf-8"))
         except urllib.error.HTTPError as e:
-            body_bytes = e.read()
-            try:
-                parsed = json.loads(body_bytes.decode("utf-8"))
-            except Exception:
-                parsed = {"error": body_bytes.decode("utf-8", errors="replace")}
-            return e.code, parsed
+            return e.code, self._parse_http_error(e)
+
+    def _get(self, path: str, params: Optional[dict[str, Any]] = None) -> Any:
+        status, parsed = self._get_with_status(path, params)
+        if status >= 400:
+            err = parsed.get("error") if isinstance(parsed, dict) else None
+            raise RuntimeError(f"HTTP {status}: {err or 'request failed'}")
+        return parsed
+
+    def _post(
+        self,
+        path: str,
+        body: dict[str, Any],
+        timeout: Optional[float] = None,
+    ) -> tuple[int, Any]:
+        """POST JSON body; returns (status_code, parsed_response)."""
+        return self._request(
+            "POST", self._build_url(path), json.dumps(body).encode("utf-8"), timeout
+        )
+
+    def _get_with_status(
+        self,
+        path: str,
+        params: Optional[dict[str, Any]] = None,
+        timeout: Optional[float] = None,
+    ) -> tuple[int, Any]:
+        """GET returning (status_code, parsed_response) — unlike ``_get``, an
+        HTTP error is returned as a status, not raised. Needed where the caller
+        must tell a 404 apart from other failures (old-server guards)."""
+        return self._request("GET", self._build_url(path, params), None, timeout)
 
     # -- endpoints ------------------------------------------------------------
 
@@ -167,3 +204,46 @@ class HicortexClient:
 
     def delete(self, id: str) -> tuple[int, dict[str, Any]]:
         return self._post("/delete", {"id": id})
+
+    # Per-turn hot path (F4): /recall-index runs synchronously inside every
+    # prefetch and /memory inside an agent tool call — a slow/wedged server
+    # must cost at most this much per turn, NOT the general default timeout
+    # (5 s) meant for background/tool traffic.
+    RECALL_TIMEOUT: float = 1.5
+
+    def recall_index(
+        self,
+        session_id: str,
+        prompt: Optional[str] = None,
+        reset: bool = False,
+        project: Optional[str] = None,
+        privacy: Optional[str] = None,
+    ) -> tuple[int, dict[str, Any]]:
+        """Pushed recall index (0.14). ``prompt`` → ``{block, shown, turn}``
+        where ``block`` is None when nothing is new/relevant; ``reset=True``
+        clears the session's server-side dedup (context rebuilt). ``project``
+        and ``privacy`` (CSV accepted server-side) scope the recall exactly
+        like the legacy /search prefetch did. Returns the status so the caller
+        can old-server-guard on 404 (pre-0.14)."""
+        body: dict[str, Any] = {"session_id": session_id}
+        if reset:
+            body["reset"] = True
+        else:
+            body["prompt"] = prompt or ""
+            if project:
+                body["project"] = project
+            if privacy:
+                body["privacy"] = privacy
+        return self._post("/recall-index", body, timeout=self.RECALL_TIMEOUT)
+
+    def get_memory(
+        self, id: str, privacy: Optional[str] = None
+    ) -> tuple[int, dict[str, Any]]:
+        """Fetch ONE memory's full content (lazy-load counterpart of the recall
+        index). The server marks it as USED (access_count + 1) and returns
+        ``{memory, citation}`` — citation is server-rendered so every harness
+        surfaces the same provenance norm. ``privacy`` (CSV) makes an
+        out-of-scope memory read as 404 (the server never reveals existence)."""
+        return self._get_with_status(
+            "/memory", {"id": id, "privacy": privacy}, timeout=self.RECALL_TIMEOUT
+        )

package/hermes-plugin/hicortex/config.py

@@ -46,7 +46,11 @@ CONFIG_SCHEMA: list[dict[str, Any]] = [
     {
         "key": "recall_limit",
         "label": "Recall limit",
-        "description": "Max memories returned per recall (default 5).",
+        "description": (
+            "Max memories returned per recall (default 5). Applies to the "
+            "tools and the legacy pre-0.14 /search prefetch fallback only — "
+            "the pushed recall index is sized by SERVER config (recallMaxItems)."
+        ),
         "default": "5",
         "required": False,
     },

package/hermes-plugin/hicortex/plugin.yaml

@@ -1,6 +1,6 @@
 name: hicortex
-version: 0.6.0
-description: "Self-learning memory for Hermes agents — every session is distilled into lessons overnight, and your agent wakes up wiser. Injects fresh lessons each turn plus a per-agent standing context block, and exposes the full 8-tool memory surface (search, recent, ingest, lessons, index, graph, update, delete) via a shared Hicortex server. Stdlib-only."
+version: 0.7.0
+description: "Self-learning memory for Hermes agents — every session is distilled into lessons overnight, and your agent wakes up wiser. Pushes a compact per-turn recall index (lazy-loaded with hicortex_get), injects fresh lessons plus a per-agent standing context block, and exposes the full 9-tool memory surface (search, get, recent, ingest, lessons, index, graph, update, delete) via a shared Hicortex server. Stdlib-only."
 pip_dependencies: []
 hooks: []
 requires_env:

package/hermes-plugin/hicortex/provider.py

@@ -1,9 +1,28 @@
 """Hicortex MemoryProvider for Hermes — recall-only.
 
-Recall:   prefetch()          -> GET /search   (relevant memories before each turn)
-          queue_prefetch()    -> GET /search   (background recall for the next turn)
-          tools               -> hicortex_search / hicortex_recent
+Recall:   prefetch()          -> POST /recall-index (pushed recall index, 0.14 —
+                                 compact one-line-per-memory menu; the agent
+                                 lazy-loads full content with hicortex_get).
+                                 Falls back to GET /search full-content
+                                 injection against a pre-0.14 server (404).
+          queue_prefetch()    -> no-op on the recall-index path (the server
+                                 dedups per turn; a client-side cache would
+                                 double-suppress). Legacy background GET /search
+                                 only on the 404 fallback path.
+          tools               -> hicortex_search / hicortex_get / hicortex_recent / …
           system_prompt_block -> lessons + memory index injected into the prompt
+          initialize()        -> POST /recall-index {reset:true} (new session =
+                                 fresh context, so the server's per-session
+                                 shown-set is cleared). Synchronous with the
+                                 short recall timeout so it can never land
+                                 AFTER the first turn's prefetch and wipe the
+                                 registry state that turn just built. The
+                                 MemoryProvider interface exposes NO
+                                 compaction/context-rebuild signal, so a
+                                 mid-session compaction cannot trigger a reset
+                                 — the server's turn-based re-show window
+                                 (recallReshowTurns) covers that gap by
+                                 re-showing after enough turns.
 
 Capture is NOT the plugin's job. A nightly reader on the Hicortex server
 distills each agent's own session store (Hermes: ~/.hermes/profiles/<agent>/
@@ -19,8 +38,10 @@ import logging
 import os
 import re
 import threading
+import time
+import uuid
 from concurrent.futures import ThreadPoolExecutor
-from typing import Any, Dict, Iterable, List, Optional
+from typing import Any, Dict, Iterable, List, Optional, Set
 
 from agent.memory_provider import MemoryProvider
 
@@ -31,6 +52,14 @@ logger = logging.getLogger(__name__)
 
 _INJECT_CONTENT_CAP = 500
 
+# How long a /recall-index 404 latches the legacy-fallback path before the
+# endpoint is re-probed. The latch must EXPIRE (review F2): during a
+# client-first rollout the plugin may probe a still-0.13 server once and would
+# otherwise stay on the legacy path until a gateway restart nobody knows to do.
+# Long enough not to hammer an old server every turn, short enough that a
+# server upgrade is picked up within minutes.
+_FALLBACK_RETRY_SECONDS = 600.0
+
 # Agent ids are joined into a filesystem path server-side, so they share the
 # section-name allowlist. \Z (NOT $) anchors the END OF STRING: Python's $ also
 # matches just before a trailing "\n", so "alice\n" would pass and go out as
@@ -126,6 +155,17 @@ class HicortexProvider(MemoryProvider):
         self._agent_name: Optional[str] = None
         self._prefetch_cache: Dict[str, str] = {}
         self._bg_threads: List[threading.Thread] = []
+        self._session_id: Optional[str] = None
+        # /recall-index 404 latch: 0.0 = not latched; otherwise the
+        # time.monotonic() deadline until which the legacy /search prefetch is
+        # used. Expires (re-probe) per _FALLBACK_RETRY_SECONDS. Only a
+        # definitive 404 latches; network errors stay fail-soft per turn.
+        self._recall_index_retry_at: float = 0.0
+        # Warn-once bookkeeping (review F3): a persistent non-404 HTTP error —
+        # especially 401/403 from a bad token — must surface at WARNING level
+        # once per distinct status, not vanish at debug level (the class of
+        # silent auth failure that once hid a dead recall path for days).
+        self._warned_recall_statuses: Set[int] = set()
 
     @property
     def name(self) -> str:
@@ -173,6 +213,26 @@ class HicortexProvider(MemoryProvider):
             self._client = self._build_client()
         except Exception as e:
             logger.warning("hicortex: init client build failed: %s", e)
+        # New session = fresh context window, so the server's per-session
+        # shown-set is stale by definition. SYNCHRONOUS (review F8): a
+        # background reset could land AFTER the first turn's prefetch and wipe
+        # the shown-set/turn counter that turn just built. The client's short
+        # recall timeout (1.5 s) bounds the startup cost; fail-soft. The id
+        # goes through the SAME resolver as prefetch (review F7) so the reset
+        # hits the key the turns will accumulate under.
+        sid = self._resolve_session_id(session_id)
+        client = self._client
+        if client is not None:
+            try:
+                status, _ = client.recall_index(sid, reset=True)
+                if status == 404:
+                    # Pre-0.14 server — latch the legacy path now rather than
+                    # paying another probe on the first turn; the TTL heals it.
+                    self._recall_index_retry_at = (
+                        time.monotonic() + _FALLBACK_RETRY_SECONDS
+                    )
+            except Exception as e:
+                logger.debug("hicortex recall reset failed: %s", e)
 
     # ------------------------------------------------------------------- recall
     def _format_hits(self, hits: list[dict]) -> str:
@@ -191,14 +251,95 @@ class HicortexProvider(MemoryProvider):
             lines.append(f"- [{date}, {proj}] {content}")
         return "\n".join(lines)
 
+    def _resolve_session_id(self, session_id: str) -> str:
+        """Session id for /recall-index, unified across initialize() and
+        prefetch() (review F7). Precedence: an explicit non-empty id ALWAYS
+        wins and becomes the stored id (so a Hermes that hands initialize an
+        empty id but passes real ids per turn converges on the real id — the
+        turns and any later reset then share one registry key); else the
+        stored id; else a generated ``hermes-<uuid4>`` stored once (dedup
+        degrades from session to provider-instance scope — still correct,
+        never a shared "" that would merge every session on the server)."""
+        if session_id:
+            self._session_id = session_id
+            return session_id
+        if not self._session_id:
+            self._session_id = f"hermes-{uuid.uuid4()}"
+        return self._session_id
+
+    def _recall_index_latched(self) -> bool:
+        """True while the /recall-index 404 latch is active (legacy path)."""
+        return (
+            self._recall_index_retry_at > 0
+            and time.monotonic() < self._recall_index_retry_at
+        )
+
     def prefetch(self, query: str, *, session_id: str = "") -> str:
+        client = self._client_or_none()
+        if client is None:
+            return ""
+        # Pushed recall index (0.14): the server does relevance gating and
+        # TURN-based dedup — every user turn is sent, the server decides what
+        # is new. The sha1 prefetch cache is deliberately NOT consulted on this
+        # path: replaying a cached block would skip the server call, so the
+        # registry's turn counter would drift and dedup would double-suppress.
+        if not self._recall_index_latched():
+            try:
+                status, resp = client.recall_index(
+                    self._resolve_session_id(session_id),
+                    prompt=query,
+                    project=self._project,
+                    privacy=self._privacy,
+                )
+                if status == 404:
+                    # Old-server guard: pre-0.14 has no /recall-index. Latch
+                    # the legacy /search prefetch, re-probe after the TTL.
+                    logger.info(
+                        "hicortex: server has no /recall-index (pre-0.14) — "
+                        "falling back to /search prefetch for %.0f s",
+                        _FALLBACK_RETRY_SECONDS,
+                    )
+                    self._recall_index_retry_at = (
+                        time.monotonic() + _FALLBACK_RETRY_SECONDS
+                    )
+                elif status == 200:
+                    self._recall_index_retry_at = 0.0
+                    block = resp.get("block") if isinstance(resp, dict) else None
+                    # block is None when nothing is new/relevant → inject nothing.
+                    return block if isinstance(block, str) else ""
+                else:
+                    # Auth/5xx/…: not a version signal — fail soft this turn
+                    # (legacy /search would hit the same wall anyway), but
+                    # surface it ONCE per status at WARNING: a persistent 401
+                    # from a bad token must never hide at debug level.
+                    if status not in self._warned_recall_statuses:
+                        self._warned_recall_statuses.add(status)
+                        hint = (
+                            " — check hicortex_auth_token/HICORTEX_AUTH_TOKEN"
+                            if status in (401, 403)
+                            else ""
+                        )
+                        logger.warning(
+                            "hicortex: /recall-index returned HTTP %s; recall "
+                            "injection is disabled while this persists%s",
+                            status,
+                            hint,
+                        )
+                    else:
+                        logger.debug("hicortex recall-index HTTP %s", status)
+                    return ""
+            except Exception as e:
+                logger.debug("hicortex recall-index failed: %s", e)
+                return ""
+        return self._legacy_search_prefetch(client, query)
+
+    def _legacy_search_prefetch(self, client: HicortexClient, query: str) -> str:
+        """Pre-0.14 behavior: full-content /search injection with the one-shot
+        sha1 cache warmed by queue_prefetch."""
         key = hashlib.sha1(query.encode("utf-8")).hexdigest()
         cached = self._prefetch_cache.pop(key, None)
         if cached is not None:
             return cached
-        client = self._client_or_none()
-        if client is None:
-            return ""
         try:
             hits = client.search(
                 query, limit=self._recall_limit, project=self._project, privacy=self._privacy
@@ -209,6 +350,13 @@ class HicortexProvider(MemoryProvider):
             return ""
 
     def queue_prefetch(self, query: str, *, session_id: str = "") -> None:
+        # Recall-index path: no background warm-up. One /recall-index POST per
+        # turn (from prefetch) is the contract — a queued call here would burn
+        # a registry turn AND cache a block the server thinks it already
+        # showed. Only the latched (confirmed-404) legacy path keeps the old
+        # behavior.
+        if not self._recall_index_latched():
+            return
         client = self._client_or_none()
         if client is None:
             return
@@ -285,7 +433,8 @@ class HicortexProvider(MemoryProvider):
         lines = [
             "## Hicortex long-term memory",
             "You have shared long-term memory across sessions. Use `hicortex_search` "
-            "for specific recall and `hicortex_recent` for recent memories by project.",
+            "for specific recall, `hicortex_get` to fetch one memory by id (e.g. from "
+            "the recall index), and `hicortex_recent` for recent memories by project.",
         ]
         if lessons:
             lines.append("Lessons:")
@@ -320,6 +469,26 @@ class HicortexProvider(MemoryProvider):
                     "required": ["query"],
                 },
             },
+            {
+                "name": "hicortex_get",
+                "description": (
+                    "Fetch ONE memory's full content by id — use this to lazy-load "
+                    "entries from the recall 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 as given in the response."
+                ),
+                "parameters": {
+                    "type": "object",
+                    "properties": {
+                        "id": {
+                            "type": "string",
+                            "description": "Memory ID (as shown in the recall index or search results)",
+                        },
+                    },
+                    "required": ["id"],
+                },
+            },
             {
                 "name": "hicortex_recent",
                 "description": (
@@ -455,6 +624,29 @@ class HicortexProvider(MemoryProvider):
                 )
                 return json.dumps(hits)
 
+            elif tool_name == "hicortex_get":
+                id_val = args.get("id", "")
+                if not id_val:
+                    return json.dumps({"error": "id is required"})
+                # The configured privacy filter rides along (review F1): an
+                # out-of-scope memory reads as 404 server-side.
+                status, resp = client.get_memory(id_val, privacy=self._privacy)
+                if status == 404:
+                    # Either no such memory (0.14+) or a pre-0.14 server with
+                    # no /memory endpoint — the id hint covers the common case.
+                    return json.dumps(
+                        {"error": f"Memory not found: {id_val} (or the server predates 0.14)"}
+                    )
+                if status != 200 or not isinstance(resp, dict):
+                    err = resp.get("error") if isinstance(resp, dict) else None
+                    return json.dumps({"error": err or f"HTTP {status}"})
+                memory = resp.get("memory") or {}
+                content = memory.get("content") or ""
+                citation = resp.get("citation") or ""
+                # Render the content BEHIND the server's citation string — the
+                # server-side rendering is the single provenance norm (0.14.1).
+                return f"{citation}\n\n{content}".strip()
+
             elif tool_name == "hicortex_recent":
                 hits = client.recent(
                     project=args.get("project") or self._project,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@gamaze/hicortex",
-  "version": "0.14.1",
-  "description": "Self-learning memory for AI agents \u2014 experience captured automatically, distilled into lessons overnight, shared across your whole fleet. Works with Hermes, OpenClaw, Claude Code, and Pi.",
+  "version": "0.14.3",
+  "description": "Self-learning memory for AI agents — experience captured automatically, distilled into lessons overnight, shared across your whole fleet. Works with Hermes, OpenClaw, Claude Code, and Pi.",
   "main": "dist/index.js",
   "bin": {
     "hicortex": "dist/cli.js"