@gamaze/hicortex 0.13.2 → 0.14.0

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;
 }>;
 /**

package/dist/storage.js

@@ -9,6 +9,7 @@ exports.insertMemory = insertMemory;
 exports.getMemory = getMemory;
 exports.updateMemory = updateMemory;
 exports.strengthenMemory = strengthenMemory;
+exports.touchMemoriesShown = touchMemoriesShown;
 exports.deleteMemory = deleteMemory;
 exports.setMemoryTags = setMemoryTags;
 exports.getMemoryTags = getMemoryTags;
@@ -130,6 +131,24 @@ function strengthenMemory(db, memoryId, nowIsoStr) {
      SET access_count = access_count + 1, last_accessed = ?
      WHERE id = ?`).run(nowIsoStr, memoryId);
 }
+/**
+ * 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).
+ */
+function touchMemoriesShown(db, memoryIds, nowIsoStr) {
+    if (memoryIds.length === 0)
+        return;
+    const stmt = db.prepare(`UPDATE memories
+     SET shown_count = COALESCE(shown_count, 0) + 1, last_accessed = ?
+     WHERE id = ?`);
+    const run = db.transaction((ids) => {
+        for (const id of ids)
+            stmt.run(nowIsoStr, id);
+    });
+    run(memoryIds);
+}
 /**
  * Delete a memory, its vector, its tags, and all its links.
  */
@@ -234,7 +253,7 @@ function vectorSearch(db, queryEmbedding, limit = 10, excludeIds = []) {
  * Full-text search using FTS5 BM25 ranking.
  * Returns memories with a rank field (lower is better).
  */
-function searchFts(db, query, limit = 10, privacy, sourceAgent) {
+function searchFts(db, query, limit = 10, privacy, sourceAgent, project) {
     const conditions = ["memories_fts MATCH ?"];
     const params = [query];
     if (privacy && privacy.length > 0) {
@@ -246,6 +265,13 @@ function searchFts(db, query, limit = 10, privacy, sourceAgent) {
         conditions.push("m.source_agent = ?");
         params.push(sourceAgent);
     }
+    // #192: project is pushed into SQL (like privacy/sourceAgent) instead of
+    // being post-filtered by the caller — post-filtering a global top-N against
+    // a small project starves the result set regardless of corpus content.
+    if (project) {
+        conditions.push("m.project = ?");
+        params.push(project);
+    }
     const where = conditions.join(" AND ");
     params.push(limit);
     const rows = db

package/dist/transcript-reader.d.ts

@@ -15,7 +15,7 @@ export interface TranscriptBatch {
     date: string;
     entries: unknown[];
     /**
-     * Optional source-agent label (e.g. "hermes/lenny"). When set, the nightly
+     * Optional source-agent label (e.g. "hermes/alice"). When set, the nightly
      * pipeline uses it verbatim for provenance instead of the default
      * `claude-code/<project>`. Lets per-harness readers stamp their own origin.
      */

package/dist/transcript-reader.js

@@ -159,12 +159,12 @@ function parseTranscriptFile(filePath, projectName, cursorKey, startCursor, gene
 }
 /**
  * Decode CC project directory name to a human-readable project name.
- * CC uses path-based hashing: "-Users-mattias-Development-Tools-hicortex"
+ * CC uses path-based hashing: "-Users-alice-Development-Tools-hicortex"
  * becomes "hicortex" (last path component).
  */
 function decodeProjectDirName(dirName) {
     // CC encodes paths by replacing / with -
-    // e.g. "-Users-mattias-Development-Tools-hicortex"
+    // e.g. "-Users-alice-Development-Tools-hicortex"
     const parts = dirName.split("-").filter(Boolean);
     if (parts.length === 0)
         return dirName;

package/dist/types.d.ts

@@ -42,6 +42,12 @@ export interface MemorySearchResult {
     project: string | null;
     created_at: string;
     connections: number;
+    /** True cosine similarity to the query for vector-matched candidates; null
+     *  for FTS-only and graph-discovered hits (no measured distance). */
+    similarity?: number | null;
+    /** Which retrieval channel produced the candidate (vector KNN, BM25 FTS,
+     *  both, or graph traversal). Used by the /recall-index relevance gate. */
+    source?: "vector" | "fts" | "both" | "graph";
 }
 /** Report returned by the consolidation pipeline. */
 export interface ConsolidationReport {

package/domains.example.json

@@ -9,11 +9,26 @@
     "Backfill an existing corpus with: hicortex classify-domains"
   ],
   "domains": [
-    { "name": "Work", "description": "Your job and professional life — employer, clients, workstreams" },
-    { "name": "Personal", "description": "Private life — home, hobbies, everyday matters" },
-    { "name": "People", "description": "Relationships — family, friends, social life, network" },
-    { "name": "Health", "description": "Fitness, wellbeing, medical" },
-    { "name": "Finance", "description": "Money — budgeting, spending, investing" }
+    {
+      "name": "Work",
+      "description": "Your job and professional life — employer, clients, workstreams"
+    },
+    {
+      "name": "Personal",
+      "description": "Private life — home, hobbies, everyday matters"
+    },
+    {
+      "name": "People",
+      "description": "Relationships — family, friends, social life, network"
+    },
+    {
+      "name": "Health",
+      "description": "Fitness, wellbeing, medical"
+    },
+    {
+      "name": "Finance",
+      "description": "Money — budgeting, spending, investing"
+    }
   ],
   "_powerUserExample": {
     "_readme": [
@@ -22,14 +37,39 @@
       "`weakPrimaryFloor` (default 0.45) is the minimum embedding similarity for a no-fit memory to earn a weak primary; tune it from your corpus."
     ],
     "domains": [
-      { "name": "Work", "description": "Employer, day job, client projects, workstreams", "compartment": true },
-      { "name": "Personal", "description": "Private life — home, hobbies, everyday matters" },
-      { "name": "People", "description": "Relationships — family, friends, social life, network" },
-      { "name": "Health", "description": "Fitness, wellbeing, medical" },
-      { "name": "Finance", "description": "Money — budgeting, spending, investing" },
-      { "name": "Boating", "description": "Boats — maintenance, gear, trips, harbour life" },
-      { "name": "Property", "description": "House and land — renovation, upkeep, garden" },
-      { "name": "Vehicles", "description": "Cars and other vehicles — service, repairs, purchases" }
+      {
+        "name": "Work",
+        "description": "Employer, day job, client projects, workstreams",
+        "compartment": true
+      },
+      {
+        "name": "Personal",
+        "description": "Private life — home, hobbies, everyday matters"
+      },
+      {
+        "name": "People",
+        "description": "Relationships — family, friends, social life, network"
+      },
+      {
+        "name": "Health",
+        "description": "Fitness, wellbeing, medical"
+      },
+      {
+        "name": "Finance",
+        "description": "Money — budgeting, spending, investing"
+      },
+      {
+        "name": "Photography",
+        "description": "Camera gear, shoots, editing workflow, photo projects"
+      },
+      {
+        "name": "Home",
+        "description": "House, renovation projects, maintenance, garden"
+      },
+      {
+        "name": "Travel",
+        "description": "Trips, destinations, bookings, travel plans"
+      }
     ],
     "weakPrimaryFloor": 0.5
   }

package/hermes-plugin/hicortex/provider.py

@@ -33,8 +33,8 @@ _INJECT_CONTENT_CAP = 500
 
 # 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 "nano\n" would pass and go out as
-# agent=nano%0A → a 400 the fail-soft path silently swallows.
+# matches just before a trailing "\n", so "alice\n" would pass and go out as
+# agent=alice%0A → a 400 the fail-soft path silently swallows.
 _AGENT_ID_RE = re.compile(r"^[a-z0-9][a-z0-9_-]*\Z")
 
 
@@ -48,7 +48,7 @@ def _sanitize_agent_id(raw: Optional[str]) -> Optional[str]:
     EXACTLY so a profile resolves to the SAME id on both harnesses (a mismatch
     would make one honor the persona firewall and the other leak global context
     into an ``off``/``override`` persona): lowercase → collapse invalid runs to
-    "-" → strip leading -/_ → truncate 64 → validate. "Lenny" → "lenny";
+    "-" → strip leading -/_ → truncate 64 → validate. "Alice" → "alice";
     "MacBook-Pro.local" → "macbook-pro-local"; all-symbols → None."""
     if not isinstance(raw, str):
         return None
@@ -73,7 +73,7 @@ def _resolve_agent_name(cfg: Dict[str, Any]) -> Optional[str]:
       2. ``HERMES_PROFILE`` env;
       3. parse ``HERMES_HOME`` when it ends ``profiles/<name>``;
       4. None → bare fetch → the global set.
-    Each source is stripped then SANITIZED (not rejected) so "Lenny" → "lenny"
+    Each source is stripped then SANITIZED (not rejected) so "Alice" → "alice"
     matches the TS contract; a source that sanitizes to None yields None (bare
     fetch), never a fall-through to another identity."""
     configured = (cfg.get("agent_name") or "").strip()

package/openclaw.plugin.json

@@ -11,7 +11,7 @@
       "serverUrl": {
         "type": "string",
         "default": "http://127.0.0.1:8787",
-        "description": "Hicortex server URL. Defaults to localhost (co-located server). For multi-machine setups, point this at the remote server (e.g. http://bedrock:8787 or a Tailscale HTTPS URL)."
+        "description": "Hicortex server URL. Defaults to localhost (co-located server). For multi-machine setups, point this at the remote server (e.g. http://your-server:8787 or an HTTPS URL)."
       },
       "authToken": {
         "type": "string",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gamaze/hicortex",
-  "version": "0.13.2",
+  "version": "0.14.0",
   "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.",
   "main": "dist/index.js",
   "bin": {