@gamaze/hicortex 0.13.2 → 0.14.0

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

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

package/dist/recall-hook-cli.js

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

package/dist/recall-index.d.ts

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

package/dist/recall-index.js

@@ -0,0 +1,163 @@
+"use strict";
+/**
+ * POST /recall-index — pushed recall index (#192).
+ *
+ * One recall logic for every harness: CC calls it from a UserPromptSubmit
+ * hook, the Hermes/OC plugins can call it per turn. The server searches the
+ * corpus with the prompt text and returns a COMPACT INDEX (one line per
+ * memory — a menu, not the meal); the agent lazy-loads full content with
+ * `hicortex_get(id)` only when a line is actually relevant.
+ *
+ * Strengthening semantics (the recall/decay alignment):
+ *   - Appearing in the index = exposure: shown_count + last_accessed refresh
+ *     (mild, temporary strengthen — the decay clock resets) via
+ *     storage.touchMemoriesShown. NO access_count bump: hardening, the prune
+ *     shield, and the adoption metric stay driven by real use.
+ *   - hicortex_get = use: full strengthen (access_count + 1).
+ *
+ * Anti-bloat gates: relevance floor (measured cosine, or a real BM25 match),
+ * per-session TURN-based dedup (SessionRecallRegistry), short-prompt skip,
+ * and a hard item cap. On a prompt with no relevant memories the block is
+ * null and the hook prints nothing.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.memoryTitle = memoryTitle;
+exports.passesRelevanceGate = passesRelevanceGate;
+exports.handleRecallIndex = handleRecallIndex;
+const storage = __importStar(require("./storage.js"));
+const DEFAULT_MIN_SIMILARITY = 0.55;
+const DEFAULT_MAX_ITEMS = 6;
+const DEFAULT_MIN_PROMPT_LENGTH = 20;
+/** Retrieve more than maxItems so gating + dedup still leave a full menu. */
+const CANDIDATE_MULTIPLIER = 3;
+/** First content line, de-markdowned and truncated — the index line title. */
+function memoryTitle(content, maxLen = 100) {
+    const firstLine = content
+        .split("\n")
+        .map((l) => l.trim())
+        .find((l) => l.length > 0) ?? "";
+    const title = firstLine
+        .replace(/^#+\s*/, "")
+        .replace(/^Session Memory:\s*/i, "")
+        .replace(/^Lesson:\s*/i, "")
+        .trim();
+    return title.length > maxLen ? `${title.slice(0, maxLen - 1)}…` : title;
+}
+function formatDate(iso) {
+    const d = new Date(iso);
+    if (isNaN(d.getTime()))
+        return "";
+    const dd = String(d.getDate()).padStart(2, "0");
+    const mm = String(d.getMonth() + 1).padStart(2, "0");
+    return `${dd}.${mm}.${d.getFullYear()}`;
+}
+function formatIndexLine(r) {
+    const meta = [formatDate(r.created_at), r.domain ?? r.project ?? undefined, r.memory_type]
+        .filter(Boolean)
+        .join(", ");
+    return `- [${r.id}] ${memoryTitle(r.content)}${meta ? ` (${meta})` : ""}`;
+}
+/** Relevance gate: real text match, or measured cosine above the floor. */
+function passesRelevanceGate(r, minSimilarity) {
+    if (r.source === "fts" || r.source === "both")
+        return true;
+    return typeof r.similarity === "number" && r.similarity >= minSimilarity;
+}
+/**
+ * Handle a /recall-index request body. Thin Express adapter in mcp-server.ts;
+ * all behavior lives here so tests exercise it directly.
+ */
+async function handleRecallIndex(deps, body) {
+    const req = (body ?? {});
+    const sessionId = typeof req.session_id === "string" && req.session_id ? req.session_id : null;
+    if (!sessionId) {
+        return { status: 400, body: { error: "Missing 'session_id'" } };
+    }
+    // Reset: SessionStart (startup/resume/clear/compact) — fresh context, so the
+    // shown-set is stale by definition.
+    if (req.reset === true) {
+        deps.registry.reset(sessionId);
+        return { status: 200, body: { ok: true, reset: true } };
+    }
+    const prompt = typeof req.prompt === "string" ? req.prompt.trim() : "";
+    const minPromptLength = deps.options?.minPromptLength ?? DEFAULT_MIN_PROMPT_LENGTH;
+    if (prompt.length < minPromptLength) {
+        return { status: 200, body: { block: null, skipped: "short-prompt" } };
+    }
+    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);
+    let results;
+    try {
+        results = await deps.retrieveFn(prompt, maxItems * CANDIDATE_MULTIPLIER);
+    }
+    catch (err) {
+        return {
+            status: 500,
+            body: { error: err instanceof Error ? err.message : String(err) },
+        };
+    }
+    const picked = results
+        .filter((r) => passesRelevanceGate(r, minSimilarity))
+        .filter((r) => deps.registry.isShowable(sessionId, r.id))
+        .slice(0, maxItems);
+    if (picked.length === 0) {
+        return { status: 200, body: { block: null, shown: [], turn } };
+    }
+    const ids = picked.map((r) => r.id);
+    deps.registry.markShown(sessionId, ids);
+    // Exposure signal: shown_count + last_accessed refresh, NOT access_count.
+    storage.touchMemoriesShown(deps.db, ids, new Date().toISOString());
+    const lines = picked.map((r) => formatIndexLine(r));
+    const block = [
+        "## Memory recall (auto)",
+        "Possibly relevant long-term memories. Fetch full content with `hicortex_get(id)` ONLY for entries relevant to the current task:",
+        ...lines,
+    ].join("\n");
+    return { status: 200, body: { block, shown: ids, turn } };
+}
+function clampInt(v, dflt, min, max) {
+    const n = Number(v);
+    if (!Number.isFinite(n))
+        return dflt;
+    return Math.max(min, Math.min(max, Math.floor(n)));
+}
+function clampNumber(v, dflt, min, max) {
+    const n = Number(v);
+    if (!Number.isFinite(n))
+        return dflt;
+    return Math.max(min, Math.min(max, n));
+}

package/dist/recall-registry.d.ts

@@ -0,0 +1,48 @@
+/**
+ * SessionRecallRegistry — per-session, TURN-based dedup for pushed recall
+ * (#192, POST /recall-index).
+ *
+ * Why turn-based, not time-based: suppression must track the session's
+ * CONTEXT, not the wall clock. A multi-day CC session with a 1M window can
+ * hold hundreds of turns; a shown memory is redundant while it is plausibly
+ * still in context and useful again once enough turns have passed (or the
+ * context was compacted away). Turn count is the proxy the server can own
+ * without clients reporting token volumes.
+ *
+ * Semantics:
+ *   - Every non-reset /recall-index call for a session advances its turn
+ *     counter by one.
+ *   - A memory id shown at turn T is suppressed until turn T + reshowTurns.
+ *   - reset(sessionId) clears the session's shown-set (fired by the CC
+ *     SessionStart hook — which includes source=compact, i.e. after
+ *     compaction the fresh context may legitimately re-receive everything).
+ *
+ * Purely in-memory: a server restart forgets shown-state, worst case a few
+ * early re-shows (~15 tokens each) — harmless by design. Sessions are pruned
+ * LRU beyond maxSessions so long-running servers don't accumulate state.
+ */
+export interface RecallRegistryOptions {
+    /** Turns a shown id stays suppressed. Config `recallReshowTurns`, default 30. */
+    reshowTurns?: number;
+    /** Max tracked sessions before LRU eviction. */
+    maxSessions?: number;
+}
+export declare const DEFAULT_RESHOW_TURNS = 30;
+export declare class SessionRecallRegistry {
+    private readonly reshowTurns;
+    private readonly maxSessions;
+    private readonly sessions;
+    constructor(options?: RecallRegistryOptions);
+    /** Advance the session's turn counter (one call = one turn). */
+    beginTurn(sessionId: string): number;
+    /** True when the id has not been shown within the last reshowTurns turns. */
+    isShowable(sessionId: string, memoryId: string): boolean;
+    /** Record ids as shown at the session's current turn. */
+    markShown(sessionId: string, memoryIds: string[]): void;
+    /** Forget a session's shown-set (SessionStart / compaction). */
+    reset(sessionId: string): void;
+    /** Number of tracked sessions (for /recall-index introspection + tests). */
+    size(): number;
+    private getOrCreate;
+    private evictIfNeeded;
+}

package/dist/recall-registry.js

@@ -0,0 +1,99 @@
+"use strict";
+/**
+ * SessionRecallRegistry — per-session, TURN-based dedup for pushed recall
+ * (#192, POST /recall-index).
+ *
+ * Why turn-based, not time-based: suppression must track the session's
+ * CONTEXT, not the wall clock. A multi-day CC session with a 1M window can
+ * hold hundreds of turns; a shown memory is redundant while it is plausibly
+ * still in context and useful again once enough turns have passed (or the
+ * context was compacted away). Turn count is the proxy the server can own
+ * without clients reporting token volumes.
+ *
+ * Semantics:
+ *   - Every non-reset /recall-index call for a session advances its turn
+ *     counter by one.
+ *   - A memory id shown at turn T is suppressed until turn T + reshowTurns.
+ *   - reset(sessionId) clears the session's shown-set (fired by the CC
+ *     SessionStart hook — which includes source=compact, i.e. after
+ *     compaction the fresh context may legitimately re-receive everything).
+ *
+ * Purely in-memory: a server restart forgets shown-state, worst case a few
+ * early re-shows (~15 tokens each) — harmless by design. Sessions are pruned
+ * LRU beyond maxSessions so long-running servers don't accumulate state.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SessionRecallRegistry = exports.DEFAULT_RESHOW_TURNS = void 0;
+exports.DEFAULT_RESHOW_TURNS = 30;
+const DEFAULT_MAX_SESSIONS = 500;
+class SessionRecallRegistry {
+    reshowTurns;
+    maxSessions;
+    sessions = new Map();
+    constructor(options) {
+        const turns = Number(options?.reshowTurns);
+        this.reshowTurns =
+            Number.isFinite(turns) && turns > 0 ? Math.floor(turns) : exports.DEFAULT_RESHOW_TURNS;
+        const max = Number(options?.maxSessions);
+        this.maxSessions =
+            Number.isFinite(max) && max > 0 ? Math.floor(max) : DEFAULT_MAX_SESSIONS;
+    }
+    /** Advance the session's turn counter (one call = one turn). */
+    beginTurn(sessionId) {
+        const s = this.getOrCreate(sessionId);
+        s.turn += 1;
+        s.lastUsedAt = Date.now();
+        return s.turn;
+    }
+    /** True when the id has not been shown within the last reshowTurns turns. */
+    isShowable(sessionId, memoryId) {
+        const s = this.sessions.get(sessionId);
+        if (!s)
+            return true;
+        const shownAt = s.shown.get(memoryId);
+        if (shownAt === undefined)
+            return true;
+        return s.turn - shownAt >= this.reshowTurns;
+    }
+    /** Record ids as shown at the session's current turn. */
+    markShown(sessionId, memoryIds) {
+        if (memoryIds.length === 0)
+            return;
+        const s = this.getOrCreate(sessionId);
+        for (const id of memoryIds)
+            s.shown.set(id, s.turn);
+        s.lastUsedAt = Date.now();
+    }
+    /** Forget a session's shown-set (SessionStart / compaction). */
+    reset(sessionId) {
+        this.sessions.delete(sessionId);
+    }
+    /** Number of tracked sessions (for /recall-index introspection + tests). */
+    size() {
+        return this.sessions.size;
+    }
+    getOrCreate(sessionId) {
+        let s = this.sessions.get(sessionId);
+        if (!s) {
+            this.evictIfNeeded();
+            s = { turn: 0, shown: new Map(), lastUsedAt: Date.now() };
+            this.sessions.set(sessionId, s);
+        }
+        return s;
+    }
+    evictIfNeeded() {
+        if (this.sessions.size < this.maxSessions)
+            return;
+        let oldestId = null;
+        let oldestAt = Infinity;
+        for (const [id, s] of this.sessions) {
+            if (s.lastUsedAt < oldestAt) {
+                oldestAt = s.lastUsedAt;
+                oldestId = id;
+            }
+        }
+        if (oldestId)
+            this.sessions.delete(oldestId);
+    }
+}
+exports.SessionRecallRegistry = SessionRecallRegistry;

package/dist/retrieval.d.ts

@@ -6,7 +6,8 @@
  *   score = similarity * 0.4 + effective_strength * 0.3 + connection_score * 0.2 + recency * 0.1
  *
  * Decay model (B+E+D):
- *   base_decay = 0.0005 (~60-day half-life at importance 0.5)
+ *   base_decay = derived from decayHalfLifeDays (config; default 365 → ~1-year
+ *                half-life at importance 0.5, importance-scaled either way)
  *   decay_rate = 1 - base_decay * (1 - importance)
  *   decay_rate = 1 - (1 - decay_rate) * 0.7^access_count
  *   decay_rate = 1 - (1 - decay_rate) * 0.7^link_count
@@ -15,6 +16,39 @@
  */
 import type Database from "better-sqlite3";
 import type { Memory, MemorySearchResult } from "./types.js";
+/** Default decay half-life (days) at importance 0.5. #192: was 0.0005/h
+ *  (~115-day half-life at base 0.5) — aggressive enough to bury the long tail
+ *  in ranking. Long-term remembering is the product; time preference stays,
+ *  but mild. */
+export declare const DEFAULT_DECAY_HALF_LIFE_DAYS = 365;
+/**
+ * Derive the per-hour base decay constant from a half-life target: for the
+ * decayable portion, retention^hours = 0.5 at `days`, evaluated at the
+ * reference importance 0.5 (the model scales the rate by (1 − importance)).
+ * decay_rate = 1 − λ(1 − imp) ⇒ half-life ≈ ln2 / (λ·(1 − imp)), so
+ * λ = ln2 / (24·days·0.5).
+ */
+export declare function decayConstantForHalfLife(days: number): number;
+/**
+ * Configure the decay speed from config (`decayHalfLifeDays`). Called at boot
+ * by the server and the nightly so both processes score with the same clock.
+ * Invalid/absent values keep the default. Exported value for tests.
+ */
+export declare function configureDecay(options?: {
+    halfLifeDays?: unknown;
+}): number;
+interface RecallDefaults {
+    searchLimit: number;
+    recentLimit: number;
+    recentWindowDays: number;
+    coldExposureSlots: number;
+}
+/**
+ * Configure recall breadth from config. Called at boot next to
+ * configureDecay(); invalid/absent values keep the shipped defaults.
+ * Returns the resolved values (for logging + tests).
+ */
+export declare function configureRecall(config?: Record<string, unknown> | null): RecallDefaults;
 /**
  * Convert an L2 distance (as returned by sqlite-vec's vec0 `distance`) to
  * cosine similarity. Valid because our embeddings are L2-normalized
@@ -51,6 +85,9 @@ export declare function retrieve(db: Database.Database, embedFn: EmbedFn, query:
     project?: string | null;
     privacy?: string[];
     sourceAgent?: string;
+    /** #192: skip access strengthening — for pushed recall (/recall-index),
+     *  where appearing in results must not count as use. */
+    noStrengthen?: boolean;
 }): Promise<MemorySearchResult[]>;
 /**
  * Get recent context, optionally filtered by project and privacy.
@@ -60,3 +97,4 @@ export declare function searchRecent(db: Database.Database, options?: {
     limit?: number;
     privacy?: string[];
 }): MemorySearchResult[];
+export {};