@gamaze/hicortex 0.13.3 → 0.14.0

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 {};

package/dist/retrieval.js

@@ -7,7 +7,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
@@ -48,13 +49,67 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_DECAY_HALF_LIFE_DAYS = void 0;
+exports.decayConstantForHalfLife = decayConstantForHalfLife;
+exports.configureDecay = configureDecay;
+exports.configureRecall = configureRecall;
 exports.l2ToCosine = l2ToCosine;
 exports.effectiveStrength = effectiveStrength;
 exports.computeScore = computeScore;
 exports.retrieve = retrieve;
 exports.searchRecent = searchRecent;
 const storage = __importStar(require("./storage.js"));
-const BASE_DECAY = 0.0005;
+/** 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. */
+exports.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).
+ */
+function decayConstantForHalfLife(days) {
+    return Math.LN2 / (24 * days * 0.5);
+}
+let BASE_DECAY = decayConstantForHalfLife(exports.DEFAULT_DECAY_HALF_LIFE_DAYS);
+/**
+ * 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.
+ */
+function configureDecay(options) {
+    const days = Number(options?.halfLifeDays);
+    BASE_DECAY = decayConstantForHalfLife(Number.isFinite(days) && days > 0 ? days : exports.DEFAULT_DECAY_HALF_LIFE_DAYS);
+    return BASE_DECAY;
+}
+const RECALL_DEFAULTS = {
+    searchLimit: 8,
+    recentLimit: 12,
+    recentWindowDays: 180,
+    coldExposureSlots: 2,
+};
+let recallDefaults = { ...RECALL_DEFAULTS };
+/**
+ * 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).
+ */
+function configureRecall(config) {
+    const pick = (key) => {
+        const v = Number(config?.[key]);
+        return Number.isFinite(v) && v >= 0 ? Math.floor(v) : RECALL_DEFAULTS[key];
+    };
+    recallDefaults = {
+        searchLimit: Math.max(1, pick("searchLimit")),
+        recentLimit: Math.max(1, pick("recentLimit")),
+        recentWindowDays: Math.max(1, pick("recentWindowDays")),
+        coldExposureSlots: pick("coldExposureSlots"),
+    };
+    return { ...recallDefaults };
+}
 /**
  * Placeholder L2 distance for candidates that have no measured vector
  * distance (FTS-only hits and graph-discovered neighbors). Chosen so that
@@ -177,7 +232,7 @@ function collectLinks(db, seedIds, maxHops = 2) {
 // ---------------------------------------------------------------------------
 // Formatting
 // ---------------------------------------------------------------------------
-function formatResult(memory, score, effStr, connections) {
+function formatResult(memory, score, effStr, connections, provenance) {
     return {
         id: memory.id,
         content: memory.content ?? "",
@@ -188,6 +243,8 @@ function formatResult(memory, score, effStr, connections) {
         project: memory.project ?? null,
         created_at: memory.created_at ?? "",
         connections,
+        similarity: provenance ? provenance.similarity : undefined,
+        source: provenance ? provenance.source : undefined,
     };
 }
 // ---------------------------------------------------------------------------
@@ -224,19 +281,24 @@ function reciprocalRankFusion(rankedLists, k = RRF_K) {
  * and composite scoring. Strengthens accessed memories.
  */
 async function retrieve(db, embedFn, query, options) {
-    const limit = options?.limit ?? 5;
+    const limit = options?.limit ?? recallDefaults.searchLimit;
     const project = options?.project;
     const privacy = options?.privacy;
     const sourceAgent = options?.sourceAgent;
     const now = new Date();
     // 1. Embed
     const queryEmbedding = await embedFn(query);
-    // 2. Dual retrieval — vector + BM25
-    const fetchLimit = limit * 3;
+    // 2. Dual retrieval — vector + BM25.
+    // #192: sqlite-vec can't push filters into the KNN, so filtered queries must
+    // over-fetch — the old flat limit*3 intersected a global top-15 with (for the
+    // median project) ~1% of the corpus, starving every filtered query.
+    const filtered = Boolean(project || privacy || sourceAgent);
+    const fetchLimit = filtered ? Math.min(limit * 20, 200) : limit * 3;
     let vecCandidates = storage.vectorSearch(db, queryEmbedding, fetchLimit, []);
     let ftsCandidates = [];
     try {
-        ftsCandidates = storage.searchFts(db, query, fetchLimit, privacy, sourceAgent);
+        // privacy/sourceAgent/project are all pushed into the FTS SQL.
+        ftsCandidates = storage.searchFts(db, query, fetchLimit, privacy, sourceAgent, project ?? undefined);
     }
     catch {
         // FTS5 search can fail on special characters; fall back to vector-only
@@ -247,7 +309,6 @@ async function retrieve(db, embedFn, query, options) {
     // Post-filter vector candidates (sqlite-vec can't filter)
     if (project) {
         vecCandidates = vecCandidates.filter((c) => c.project === project);
-        ftsCandidates = ftsCandidates.filter((c) => c.project === project);
     }
     if (privacy) {
         vecCandidates = vecCandidates.filter((c) => privacy.includes(c.privacy));
@@ -259,14 +320,18 @@ async function retrieve(db, embedFn, query, options) {
     const vecRanked = vecCandidates.map((c) => c.id);
     const ftsRanked = ftsCandidates.map((c) => c.id);
     const rrfScores = reciprocalRankFusion([vecRanked, ftsRanked]);
-    // Build unified candidate map
+    // Build unified candidate map (with retrieval-channel provenance, #192)
     const candidateMap = new Map();
     for (const c of vecCandidates) {
-        candidateMap.set(c.id, { mem: c, distance: c.distance });
+        candidateMap.set(c.id, { mem: c, distance: c.distance, source: "vector" });
     }
     for (const c of ftsCandidates) {
-        if (!candidateMap.has(c.id)) {
-            candidateMap.set(c.id, { mem: c, distance: DEFAULT_GRAPH_DISTANCE });
+        const existing = candidateMap.get(c.id);
+        if (existing) {
+            existing.source = "both";
+        }
+        else {
+            candidateMap.set(c.id, { mem: c, distance: DEFAULT_GRAPH_DISTANCE, source: "fts" });
         }
     }
     // 4. Graph traversal
@@ -284,7 +349,7 @@ async function retrieve(db, embedFn, query, options) {
             continue;
         if (sourceAgent && mem.source_agent !== sourceAgent)
             continue;
-        candidateMap.set(gid, { mem, distance: DEFAULT_GRAPH_DISTANCE });
+        candidateMap.set(gid, { mem, distance: DEFAULT_GRAPH_DISTANCE, source: "graph" });
     }
     // 5. Compute composite scores
     const maxConnections = Math.max(...([...connectionCounts.values()].length > 0
@@ -292,7 +357,7 @@ async function retrieve(db, embedFn, query, options) {
         : [0]));
     const scored = [];
     const maxRrf = Math.max(...([...rrfScores.values()].length > 0 ? [...rrfScores.values()] : [1]));
-    for (const [mid, { mem, distance }] of candidateMap) {
+    for (const [mid, { mem, distance, source }] of candidateMap) {
         const connCount = connectionCounts.get(mid) ?? 0;
         const composite = computeScore(mem, distance, connCount, maxConnections, now);
         const effStr = effectiveStrength(mem.base_strength ?? 0.5, mem.last_accessed, now, {
@@ -302,25 +367,60 @@ async function retrieve(db, embedFn, query, options) {
         const rrf = rrfScores.get(mid) ?? 0;
         const normalizedRrf = maxRrf > 0 ? rrf / maxRrf : 0;
         const finalScore = composite * 0.8 + normalizedRrf * 0.2;
-        scored.push({ mem, finalScore, effStr, connCount });
+        // Measured cosine only for vector-matched candidates; FTS/graph hits carry
+        // the neutral placeholder distance, which is not a real similarity.
+        const similarity = source === "vector" || source === "both"
+            ? Math.round(l2ToCosine(distance) * 1e6) / 1e6
+            : null;
+        scored.push({ mem, finalScore, effStr, connCount, similarity, source });
     }
-    // 6. Sort and take top N
+    // 6. Sort and take top N — with cold-exposure slots (#192).
+    // Access hardening + effective strength make past winners self-reinforcing:
+    // 88% of the production corpus had never been returned by any query. Reserve
+    // up to 2 of k for the best-scoring never-accessed candidates so the long
+    // tail gets nonzero exposure whenever it is semantically in range. Slots are
+    // only "reserved" when cold candidates exist; otherwise the top-k is the
+    // plain score order.
     scored.sort((a, b) => b.finalScore - a.finalScore);
-    const top = scored.slice(0, limit);
-    const results = top.map((t) => formatResult(t.mem, t.finalScore, t.effStr, t.connCount));
-    // 7. Strengthen
-    strengthen(db, top.map((t) => t.mem), now);
+    const coldSlots = limit >= 4 ? recallDefaults.coldExposureSlots : 0;
+    let top = scored.slice(0, limit);
+    if (coldSlots > 0 && scored.length > limit) {
+        const coldInTop = top.filter((t) => (t.mem.access_count ?? 0) === 0).length;
+        const wanted = coldSlots - coldInTop;
+        if (wanted > 0) {
+            const coldExtras = scored
+                .slice(limit)
+                .filter((t) => (t.mem.access_count ?? 0) === 0)
+                .slice(0, wanted);
+            if (coldExtras.length > 0) {
+                top = [...top.slice(0, limit - coldExtras.length), ...coldExtras];
+            }
+        }
+    }
+    const results = top.map((t) => formatResult(t.mem, t.finalScore, t.effStr, t.connCount, {
+        similarity: t.similarity,
+        source: t.source,
+    }));
+    // 7. Strengthen — skipped for pushed recall (#192): appearing in a pushed
+    // index is exposure, not use; the /recall-index path records shown_count +
+    // last_accessed via storage.touchMemoriesShown instead.
+    if (!options?.noStrengthen) {
+        strengthen(db, top.map((t) => t.mem), now);
+    }
     return results;
 }
 /**
  * Get recent context, optionally filtered by project and privacy.
  */
 function searchRecent(db, options) {
-    const limit = options?.limit ?? 10;
+    const limit = options?.limit ?? recallDefaults.recentLimit;
     const project = options?.project;
     const privacy = options?.privacy;
     const now = new Date();
-    let candidates = storage.getRecentMemories(db, 30, limit * 3);
+    // #192 breadth: 30 → 180-day default window (config recentWindowDays).
+    // "Recent" for a long-lived corpus is a season, not a month; the narrow
+    // window kept queryless recall re-serving the same few weeks.
+    let candidates = storage.getRecentMemories(db, recallDefaults.recentWindowDays, limit * 3);
     if (project) {
         candidates = candidates.filter((c) => c.project === project);
     }

package/dist/storage.d.ts

@@ -30,6 +30,13 @@ export declare function updateMemory(db: Database.Database, memoryId: string, fi
  * Atomically increment access_count and reset last_accessed.
  */
 export declare function strengthenMemory(db: Database.Database, memoryId: string, nowIsoStr: string): void;
+/**
+ * Record that memories appeared in a pushed recall index (#192): bump
+ * shown_count and refresh last_accessed (a mild strengthen — the decay clock
+ * resets so topically-live memories stop sinking) WITHOUT touching
+ * access_count, which stays reserved for real use (hardening + prune shield).
+ */
+export declare function touchMemoriesShown(db: Database.Database, memoryIds: string[], nowIsoStr: string): void;
 /**
  * Delete a memory, its vector, its tags, and all its links.
  */
@@ -87,7 +94,7 @@ export declare function vectorSearch(db: Database.Database, queryEmbedding: Floa
  * Full-text search using FTS5 BM25 ranking.
  * Returns memories with a rank field (lower is better).
  */
-export declare function searchFts(db: Database.Database, query: string, limit?: number, privacy?: string[], sourceAgent?: string): Array<Memory & {
+export declare function searchFts(db: Database.Database, query: string, limit?: number, privacy?: string[], sourceAgent?: string, project?: string): Array<Memory & {
     rank: number;
 }>;
 /**