hippo-memory 1.62.0 → 1.63.0

package/dist/store/entry-writes.js

@@ -10,6 +10,15 @@ import { mirrorBestEffort, writeMarkdownMirror } from './mirrors.js';
 import { openStore } from './open.js';
 export function writeEntry(hippoRoot, entry, opts) {
     const db = openStore(hippoRoot);
+    try {
+        writeEntryOn(db, hippoRoot, entry, opts);
+    }
+    finally {
+        closeHippoDb(db);
+    }
+}
+/** writeEntry on the caller's open store, so a loop of writes opens the store once; each row still commits alone. */
+export function writeEntryOn(db, hippoRoot, entry, opts) {
     try {
         const stamped = stampOriginProject(hippoRoot, entry);
         writeEntryDbOnly(db, stamped, opts);
@@ -17,18 +26,13 @@ export function writeEntry(hippoRoot, entry, opts) {
         writeEntryMirrors(hippoRoot, stamped);
     }
     catch (error) {
-        // AT1 (plan §3): writeEntryDbOnly's own SAVEPOINT has already unwound by
-        // the time this catch runs, so the refusal audit lands post-rollback in
-        // a fresh implicit transaction — then rethrow so the caller sees the
-        // refusal.
+        // writeEntryDbOnly's SAVEPOINT has already unwound here, so the refusal audit lands
+        // post-rollback in a fresh implicit transaction; then rethrow so the caller sees it.
         if (error instanceof RejectedValueError) {
             auditRejectionRefusal(db, error, opts?.actor ?? 'cli');
         }
         throw error;
     }
-    finally {
-        closeHippoDb(db);
-    }
 }
 /**
  * DB-only write path. Caller owns the open `db` handle. Runs SAVEPOINT +
@@ -58,10 +62,8 @@ export function writeEntryDbOnly(db, entry, opts) {
             kind: entry.kind ?? 'distilled',
             scope: entry.scope ?? null,
         }, opts?.actor ?? 'cli', entry.tenantId);
-        // v0.30 / E2 — DAG live-coupling: child write under a level-2 summary
-        // marks the parent dirty for E3 sleep-cycle rebuild. Early-exit on
-        // null dag_parent_id (vast majority of writes); cost is one null check
-        // on the hot path.
+        // A child write marks its summary parent dirty for the sleep-cycle rebuild; most writes
+        // have no parent, so the hot path pays one null check.
         if (entry.dag_parent_id) {
             markSummaryDirtyInTx(db, entry.dag_parent_id, entry.tenantId, opts?.actor ?? 'cli');
         }

package/dist/store/handoffs.d.ts

@@ -19,7 +19,7 @@ export declare function loadLatestHandoff(hippoRoot: string, tenantId: string, s
 export declare function loadHandoffById(hippoRoot: string, tenantId: string, id: number): SessionHandoff | null;
 /** Stamp the outcome on a session's newest handoff, only if it has none yet. Returns rows changed. */
 export declare function stampHandoffOutcome(hippoRoot: string, tenantId: string, sessionId: string, outcome: HandoffOutcome): number;
-/** Auto-write a handoff at session-end (DF1 T3) from the session's active snapshot, else from `derived`, its transcript state.
+/** Auto-write a handoff at session-end from the session's active snapshot, else from `derived`, its transcript state.
  * @param evidence best-effort git state; outcome comes from the newest session_complete event.
  * @returns null when neither source is the session's, a newer handoff covers the snapshot, or the session's latest handoff was not read off its transcript. */
 export declare function writeSessionEndHandoff(hippoRoot: string, tenantId: string, sessionId: string, evidence: HandoffEvidence | null, derived?: Pick<TaskSnapshot, 'task' | 'summary' | 'next_step'> | null): SessionHandoff | null;

package/dist/store/handoffs.js

@@ -4,8 +4,6 @@ import { RECALL_DEFAULT_DENY_SCOPES } from '../recall-scope.js';
 import { assertTenantId } from '../tenant.js';
 import { openStore } from './open.js';
 import { loadActiveTaskSnapshot } from './sessions.js';
-// W1: the nine-column SELECT was cloned four times (plan rule 8); one
-// definition so a sixth caller can't drift from the other five.
 /** Column list shared by every session_handoffs SELECT; store-cards.ts reuses it for the card handoff lookup. */
 export const HANDOFF_COLUMNS = 'id, session_id, repo_root, task_id, summary, next_action, artifacts_json, scope, created_at, constraints_json, evidence_json, outcome, target_runtime, card_id';
 /**
@@ -15,8 +13,8 @@ export function saveSessionHandoff(hippoRoot, tenantId, handoff) {
     assertTenantId('saveSessionHandoff', tenantId);
     const db = openStore(hippoRoot);
     const now = new Date().toISOString();
-    // v1.2: scope is wired through. Read-side default-deny in api.recall +
-    // cmdRecall continuity excludes slack:private:* and 'unknown:legacy'.
+    // Scope is stored as given; read-side default-deny in api.recall + cmdRecall
+    // continuity excludes slack:private:* and 'unknown:legacy'.
     try {
         const result = db.prepare(`
       INSERT INTO session_handoffs(session_id, repo_root, task_id, summary, next_action, artifacts_json, scope, tenant_id, created_at, constraints_json, evidence_json, outcome, target_runtime, card_id)
@@ -54,7 +52,7 @@ export function loadLatestHandoff(hippoRoot, tenantId, sessionId, opts = {}) {
             params.push(opts.excludeSessionId);
         }
         if (opts.unfinishedOnly) {
-            // codex P2: restrict to each session's newest revision first — stampHandoffOutcome
+            // Restrict to each session's newest revision first: stampHandoffOutcome
             // only stamps the newest row, so an older null-outcome revision must not resurrect.
             conditions.push(`id IN (SELECT MAX(id) FROM session_handoffs WHERE tenant_id = ? GROUP BY session_id)`);
             params.push(tenantId);
@@ -65,7 +63,7 @@ export function loadLatestHandoff(hippoRoot, tenantId, sessionId, opts = {}) {
             params.push(new Date(Date.now() - opts.maxAgeMs).toISOString());
         }
         if (opts.scopeFilter === 'default-deny') {
-            // codex P2: admit scope before LIMIT 1, else a newer denied row hides an older eligible one.
+            // Admit scope before LIMIT 1, else a newer denied row hides an older eligible one.
             const placeholders = RECALL_DEFAULT_DENY_SCOPES.map(() => '?').join(', ');
             conditions.push(`(scope IS NULL OR (scope NOT IN (${placeholders}) AND scope NOT LIKE '%:private:%'))`);
             params.push(...RECALL_DEFAULT_DENY_SCOPES);
@@ -123,7 +121,7 @@ export function stampHandoffOutcome(hippoRoot, tenantId, sessionId, outcome) {
         closeHippoDb(db);
     }
 }
-/** Auto-write a handoff at session-end (DF1 T3) from the session's active snapshot, else from `derived`, its transcript state.
+/** Auto-write a handoff at session-end from the session's active snapshot, else from `derived`, its transcript state.
  * @param evidence best-effort git state; outcome comes from the newest session_complete event.
  * @returns null when neither source is the session's, a newer handoff covers the snapshot, or the session's latest handoff was not read off its transcript. */
 export function writeSessionEndHandoff(hippoRoot, tenantId, sessionId, evidence, derived = null) {
@@ -160,9 +158,8 @@ export function writeSessionEndHandoff(hippoRoot, tenantId, sessionId, evidence,
     finally {
         closeHippoDb(db);
     }
-    // codex P2: same-task refresh carries forward envelope fields nobody cleared,
-    // rather than dropping them when the snapshot rewrite has no opinion on them.
-    // codex P1: a scope mismatch must not leak private metadata into an unscoped envelope.
+    // A same-task refresh carries forward envelope fields nobody cleared; a scope
+    // mismatch must not leak private metadata into an unscoped envelope.
     const carryForward = existing != null && existing.taskId === snapshot.task
         && (existing.scope ?? null) === (snapshot.scope ?? null);
     return saveSessionHandoff(hippoRoot, tenantId, {

package/dist/store/index-and-stats.d.ts

@@ -4,12 +4,8 @@ export declare function loadIndex(hippoRoot: string): HippoIndex;
 /**
  * Persist mutable index metadata. Entry rows themselves are derived from SQLite.
  *
- * LC1 F1(c) structural fix: `last_retrieval_ids` and `last_trace_id` must
- * land atomically — callers (getContext, cmdRecall) fold a freshly-written
- * trace id into `index.last_trace_id` before calling this, relying on BOTH
- * meta keys committing together. Wrapped in BEGIN/COMMIT so a crash or a
- * mid-write failure can never advance one key without the other. index.json
- * is left untouched; only `rebuildIndex` writes it.
+ * `last_retrieval_ids` and `last_trace_id` commit in one transaction: callers fold a fresh trace id
+ * into the index and rely on both keys moving together. index.json is left to `rebuildIndex`.
  */
 export declare function saveIndex(hippoRoot: string, index: HippoIndex): void;
 /**

package/dist/store/index-and-stats.js

@@ -18,12 +18,8 @@ export function loadIndex(hippoRoot) {
 /**
  * Persist mutable index metadata. Entry rows themselves are derived from SQLite.
  *
- * LC1 F1(c) structural fix: `last_retrieval_ids` and `last_trace_id` must
- * land atomically — callers (getContext, cmdRecall) fold a freshly-written
- * trace id into `index.last_trace_id` before calling this, relying on BOTH
- * meta keys committing together. Wrapped in BEGIN/COMMIT so a crash or a
- * mid-write failure can never advance one key without the other. index.json
- * is left untouched; only `rebuildIndex` writes it.
+ * `last_retrieval_ids` and `last_trace_id` commit in one transaction: callers fold a fresh trace id
+ * into the index and rely on both keys moving together. index.json is left to `rebuildIndex`.
  */
 export function saveIndex(hippoRoot, index) {
     const db = openStore(hippoRoot);
@@ -58,10 +54,8 @@ export function rebuildIndex(hippoRoot) {
         if (legacyEntries.length > 0) {
             db.exec('BEGIN');
             try {
-                // AT1 (plan §3, round-3 redesign): same guard-with-per-row-skip as
-                // bootstrapLegacyStore — rebuildIndex is the other channel through
-                // which a stale markdown mirror could resurrect a rejected value.
-                // Refusal audit written INLINE (nothing rolls back on a skip).
+                // Guard with per-row skip, like bootstrapLegacyStore: a stale markdown mirror could resurrect a
+                // rejected value here. Refusal audit is written inline because nothing rolls back on a skip.
                 let rejectedCount = 0;
                 for (const entry of legacyEntries) {
                     // v39: same store-derived origin stamp as bootstrapLegacyStore.

package/dist/store/mirrors.d.ts

@@ -9,28 +9,13 @@ export declare function writeRecentSessionMirror(hippoRoot: string, tenantId: st
 export declare function writeMarkdownMirror(hippoRoot: string, entry: MemoryEntry): void;
 export declare function removeEntryMirrors(hippoRoot: string, id: string): void;
 /**
- * AT1 mirror-purge honesty fix (docs/plans/2026-08-15-at1-rejected-value-tombstone.md):
- * the candidate markdown mirror paths still on disk for `id`, computed the
- * same way `removeEntryMirrors` walks them (one per layer: buffer/episodic/
- * semantic), filtered to the ones that still `fs.existsSync`. Used to report
- * an EXPLICIT path when a best-effort purge fails and no reaper exists to
- * retry it — plain `removeEntryMirrors` returns void, giving no way to name
- * which file is stuck.
+ * Mirror paths for `id` still on disk, walked like `removeEntryMirrors`, so a failed purge
+ * with no reaper to retry it can name the stuck file.
  */
 export declare function getExistingEntryMirrorPaths(hippoRoot: string, id: string): string[];
 /**
- * AT1 fix: best-effort markdown-mirror purge shared by `reject-flow.ts`'s
- * `rejectValue` and `resolveConflict`'s post-commit purge. Both used to log
- * "will retry via reaper on next open" for EVERY failure, but the reaper
- * (`cleanupArchivedMirrors`, raw-archive-mirror-cleanup.ts) only scans
- * `raw_archive` — that message was false for a non-raw id, which has no
- * reaper at all.
- *
- * Retries the unlink once synchronously (the common real-world failure is a
- * transient lock/AV-scanner false positive, not a permanent one). On a
- * second failure: raw ids still get the honest reaper message (true); non-raw
- * ids get the EXPLICIT leftover file path(s) and a manual-delete instruction,
- * since nothing will ever retry them automatically.
+ * Best-effort mirror purge. Retries the unlink once (most failures are transient locks); the reaper only
+ * scans `raw_archive`, so a non-raw id's second failure logs the leftover path(s) to delete by hand.
  *
  * Returns true if the mirror ended up purged (first or second attempt).
  */
@@ -46,4 +31,6 @@ export declare function writeStatsMirror(hippoRoot: string, stats: LegacyStats):
 /** Mirrors are derived from SQLite and written after COMMIT, so a failed write warns instead of failing a committed change. */
 export declare function mirrorBestEffort(what: string, write: () => void): void;
 export declare function syncMirrorFiles(hippoRoot: string, db: ReturnType<typeof openHippoDb>): void;
+/** syncMirrorFiles for a pass that changed only `changed`: the other rows' markdown is already current. */
+export declare function syncChangedMirrors(hippoRoot: string, db: ReturnType<typeof openHippoDb>, changed: readonly MemoryEntry[]): void;
 //# sourceMappingURL=mirrors.d.ts.map

package/dist/store/mirrors.js

@@ -145,15 +145,8 @@ export function writeMarkdownMirror(hippoRoot, entry) {
     fs.mkdirSync(dir, { recursive: true });
     fs.writeFileSync(path.join(dir, `${entry.id}.md`), serializeEntry(entry), 'utf8');
 }
-// AT1 P1 fix (codex): `writeMarkdownMirror` writes ANY layer's mirror,
-// including `trace/<id>.md` for Layer.Trace rows (auto-promoted traces,
-// consolidate.ts) — but this enumeration only walked
-// Buffer/Episodic/Semantic. A rejected/forgotten trace row's markdown
-// content survived on disk while the purge (and `hippo reject`/plain
-// `forget`) reported success, and a stale trace mirror is exactly the
-// resurrection channel bootstrapLegacyStore/rebuildIndex guard against.
-// Fixes BOTH the AT1 reject-flow purge and the pre-existing plain-`forget`
-// gap for trace rows (deleteEntry has always called this same function).
+// Every layer, Trace included: `writeMarkdownMirror` writes any layer, and a stale trace mirror
+// is the resurrection channel bootstrapLegacyStore/rebuildIndex guard against.
 export function removeEntryMirrors(hippoRoot, id) {
     for (const layer of [Layer.Buffer, Layer.Episodic, Layer.Semantic, Layer.Trace]) {
         const file = path.join(layerDir(hippoRoot, layer), `${id}.md`);
@@ -163,36 +156,18 @@ export function removeEntryMirrors(hippoRoot, id) {
     }
 }
 /**
- * AT1 mirror-purge honesty fix (docs/plans/2026-08-15-at1-rejected-value-tombstone.md):
- * the candidate markdown mirror paths still on disk for `id`, computed the
- * same way `removeEntryMirrors` walks them (one per layer: buffer/episodic/
- * semantic), filtered to the ones that still `fs.existsSync`. Used to report
- * an EXPLICIT path when a best-effort purge fails and no reaper exists to
- * retry it — plain `removeEntryMirrors` returns void, giving no way to name
- * which file is stuck.
+ * Mirror paths for `id` still on disk, walked like `removeEntryMirrors`, so a failed purge
+ * with no reaper to retry it can name the stuck file.
  */
 export function getExistingEntryMirrorPaths(hippoRoot, id) {
-    // AT1 P1 fix (codex): same missing Layer.Trace as removeEntryMirrors above
-    // — kept in lockstep with it since this function's whole purpose is
-    // walking the mirror paths "the same way removeEntryMirrors walks them"
-    // (see its own doc comment).
+    // Layer list kept in lockstep with removeEntryMirrors.
     return [Layer.Buffer, Layer.Episodic, Layer.Semantic, Layer.Trace]
         .map((layer) => path.join(layerDir(hippoRoot, layer), `${id}.md`))
         .filter((file) => fs.existsSync(file));
 }
 /**
- * AT1 fix: best-effort markdown-mirror purge shared by `reject-flow.ts`'s
- * `rejectValue` and `resolveConflict`'s post-commit purge. Both used to log
- * "will retry via reaper on next open" for EVERY failure, but the reaper
- * (`cleanupArchivedMirrors`, raw-archive-mirror-cleanup.ts) only scans
- * `raw_archive` — that message was false for a non-raw id, which has no
- * reaper at all.
- *
- * Retries the unlink once synchronously (the common real-world failure is a
- * transient lock/AV-scanner false positive, not a permanent one). On a
- * second failure: raw ids still get the honest reaper message (true); non-raw
- * ids get the EXPLICIT leftover file path(s) and a manual-delete instruction,
- * since nothing will ever retry them automatically.
+ * Best-effort mirror purge. Retries the unlink once (most failures are transient locks); the reaper only
+ * scans `raw_archive`, so a non-raw id's second failure logs the leftover path(s) to delete by hand.
  *
  * Returns true if the mirror ended up purged (first or second attempt).
  */
@@ -242,12 +217,8 @@ export function buildIndexFromDb(db) {
             pinned: Boolean(row.pinned),
         };
     }
-    // LC1 codex round-2 med: the two lockstep keys must be read in ONE
-    // statement. Two autocommit SELECTs leave a window where a concurrent
-    // saveIndex (which commits both keys in one transaction) lands between
-    // them, handing the reader mismatched last_retrieval_ids / last_trace_id
-    // and re-opening the mislinkage hole saveIndex's BEGIN/COMMIT closed on
-    // the write side. One SELECT = one SQLite read snapshot.
+    // Read both lockstep keys in ONE statement: two autocommit SELECTs could straddle a concurrent
+    // saveIndex and hand back a mismatched last_retrieval_ids / last_trace_id pair.
     // SAFETY: lockstepRows' shape matches the key/value columns named above.
     const lockstepRows = db.prepare(`SELECT key, value FROM meta WHERE key IN ('last_retrieval_ids', 'last_trace_id')`).all();
     const lockstep = new Map(lockstepRows.map((r) => [r.key, r.value]));
@@ -294,8 +265,12 @@ export function syncMirrorFiles(hippoRoot, db) {
     // SAFETY: this query selects exactly MEMORY_SELECT_COLUMNS, matching
     // MemoryRow's field set.
     const entries = db.prepare(`SELECT ${MEMORY_SELECT_COLUMNS} FROM memories ORDER BY created ASC, id ASC`).all();
+    syncChangedMirrors(hippoRoot, db, entries.map(rowToEntry));
+}
+/** syncMirrorFiles for a pass that changed only `changed`: the other rows' markdown is already current. */
+export function syncChangedMirrors(hippoRoot, db, changed) {
     mirrorBestEffort('markdown mirrors', () => {
-        for (const entry of entries.map(rowToEntry))
+        for (const entry of changed)
             writeMarkdownMirror(hippoRoot, entry);
     });
     // SAFETY: conflicts' shape matches the eight columns named in the SELECT

package/dist/store/open.js

@@ -16,13 +16,8 @@ export function getHippoRoot(cwd = process.cwd(), opts) {
     return findHippoStoreDir(cwd, opts) ?? path.join(realpathOrResolve(cwd), '.hippo');
 }
 export function isInitialized(hippoRoot) {
-    // A bare .hippo directory is not enough — autoInstallHooks /
-    // setupDailySchedule can create it without ever calling initStore,
-    // leaving a partial directory (integrations/, logs/, runs/) with no
-    // hippo.db. Returning true in that state caused `hippo init` to skip
-    // initStore and `hippo recall` to silently fall back to an empty store
-    // (incident 2026-04-26: ingest_direct.py against a bare .hippo).
-    // Treat the store as initialized only if hippo.db actually exists.
+    // autoInstallHooks / setupDailySchedule can create a bare .hippo with no hippo.db; counting
+    // that as initialized makes `hippo init` skip initStore, so only hippo.db counts.
     return fs.existsSync(path.join(hippoRoot, 'hippo.db'));
 }
 export function initStore(hippoRoot) {
@@ -75,15 +70,8 @@ function bootstrapLegacyStore(db, hippoRoot) {
     const memoryCount = Number(countRow?.count ?? 0);
     if (memoryCount > 0)
         return false;
-    // AT1 P2 fix: memoryCount alone is not a reliable "already bootstrapped"
-    // signal once the rejection guard exists. If EVERY legacy mirror row is
-    // rejected, memories stays at 0 rows even after a successful bootstrap
-    // pass, so the memoryCount>0 gate above never trips — every subsequent
-    // initStore() call would re-run this whole function: re-scan the legacy
-    // mirrors, re-attempt (and re-refuse, re-auditing) every row, and
-    // re-INSERT the legacy consolidation_runs rows with no dedup, duplicating
-    // them on each open. A dedicated meta flag marks bootstrap as
-    // attempted-and-settled regardless of how many rows actually landed.
+    // memoryCount misses an all-rejected bootstrap (memories stays empty), which would re-run the
+    // import on every open and duplicate consolidation_runs; this meta flag settles it.
     if (getMeta(db, 'legacy_bootstrap_completed', '0') === '1')
         return false;
     const legacyEntries = loadLegacyEntriesFromMarkdown(hippoRoot);
@@ -93,8 +81,7 @@ function bootstrapLegacyStore(db, hippoRoot) {
     try {
         importLegacyEntries(db, hippoRoot, legacyEntries);
         importLegacyIndexAndStats(db, hippoRoot);
-        // AT1 P2 fix: stamp completion regardless of how many rows actually
-        // landed (all-rejected included) — see the gate comment above.
+        // Stamp completion even when every row was rejected; see the gate above.
         setMeta(db, 'legacy_bootstrap_completed', '1');
         db.exec('COMMIT');
     }
@@ -108,14 +95,8 @@ function bootstrapLegacyStore(db, hippoRoot) {
     return true;
 }
 function importLegacyEntries(db, hippoRoot, legacyEntries) {
-    // AT1 (plan §3, round-3 redesign): run the guard LIVE per row rather
-    // than bypassing it. bootstrapLegacyStore is exactly the channel through
-    // which a stale/never-purged markdown mirror could resurrect a rejected
-    // value; a skip-and-count here closes that structurally, independent of
-    // mirror state. The refusal audit is written INLINE inside this
-    // still-open loop transaction (plain audit() — nothing is rolled back
-    // on a per-row skip, so the post-rollback auditRejectionRefusal helper
-    // is the wrong tool here).
+    // Guard live per row: a stale markdown mirror could resurrect a rejected value. Plain audit()
+    // inline, because nothing rolls back on a per-row skip.
     let rejectedCount = 0;
     for (const entry of legacyEntries) {
         // v39: legacy markdown carries no origin_project; stamp from the store
@@ -140,11 +121,8 @@ function importLegacyEntries(db, hippoRoot, legacyEntries) {
 function importLegacyIndexAndStats(db, hippoRoot) {
     const legacyIndex = loadLegacyIndexFile(hippoRoot);
     setMeta(db, 'last_retrieval_ids', JSON.stringify(legacyIndex.last_retrieval_ids ?? []));
-    // LC1: legacy index.json predates last_trace_id, so this is '' for every
-    // pre-v40 store — harmless, matches the ensureMetaDefaults default.
-    // Coerce like its neighbors below coerce theirs (independent-review-critic
-    // LOW finding): accept only a clean digit string, else fall back to ''
-    // rather than trusting whatever a hand-edited/corrupt index.json carries.
+    // Legacy index.json predates last_trace_id, so '' is normal; accept only a clean digit
+    // string rather than trusting a hand-edited or corrupt index.json.
     const legacyTraceId = String(legacyIndex.last_trace_id ?? '');
     setMeta(db, 'last_trace_id', /^\d+$/.test(legacyTraceId) ? legacyTraceId : '');
     const legacyStats = loadLegacyStatsFile(hippoRoot);

package/dist/store/rows.d.ts

@@ -1,8 +1,5 @@
 import { Layer, type MemoryEntry, type ConfidenceLevel } from '../memory.js';
-/** A value that round-trips through JSON.stringify/JSON.parse unchanged. */
-export type JsonValue = string | number | boolean | null | JsonValue[] | {
-    [key: string]: JsonValue;
-};
+import type { JsonValue } from '../json.js';
 export interface IndexEntry {
     id: string;
     file: string;
@@ -17,11 +14,8 @@ export interface HippoIndex {
     version: number;
     entries: Record<string, IndexEntry>;
     last_retrieval_ids: string[];
-    /** LC1 (docs/plans/2026-08-02-lc1-recall-trace-persistence.md): id of the
-     *  most recent recall_traces row written by getContext/cmdRecall, mirrored
-     *  from the `last_trace_id` meta key exactly like last_retrieval_ids. null
-     *  when no trace has been written yet (fresh store, pre-v40 flow, or
-     *  api.recall-only usage — api.recall never sets this). */
+    /** Id of the most recent recall_traces row written by getContext/cmdRecall, mirrored from the
+     *  `last_trace_id` meta key like last_retrieval_ids. null when none was written (api.recall never sets it). */
     last_trace_id: string | null;
 }
 export interface MemoryRow {
@@ -151,8 +145,8 @@ export declare const DEFAULT_SEARCH_CANDIDATE_LIMIT = 200;
 export declare function rowToEntry(row: MemoryRow): MemoryEntry;
 export declare function parseJsonArray(raw: string | null | undefined): string[];
 /**
- * Strict parse for the `last_trace_id` meta value (LC1 F1(d) structural
- * fix). A bare Number(raw) would turn '', whitespace, or garbage into a
+ * Strict parse for the `last_trace_id` meta value.
+ * A bare Number(raw) would turn '', whitespace, or garbage into a
  * usable-looking 0/NaN — a consumer INSERTing recall_trace_outcomes with
  * trace_id=0 would hit a masked FK violation (row id 0 never exists).
  * Require a clean positive integer string; anything else is treated as

package/dist/store/rows.js

@@ -1,11 +1,8 @@
 import { log } from '../log.js';
 export const INDEX_VERSION = 3;
 export const MEMORY_SELECT_COLUMNS = `id, created, last_retrieved, retrieval_count, strength, half_life_days, layer, tags_json, emotional_valence, schema_fit, source, outcome_score, outcome_positive, outcome_negative, conflicts_with_json, pinned, confidence, content, parents_json, starred, trace_outcome, source_session_id, valid_from, superseded_by, extracted_from, dag_level, dag_parent_id, kind, scope, owner, artifact_ref, tenant_id, origin_project, descendant_count, earliest_at, latest_at, summary_dirty, last_rebuilt_at, rebuild_count, dag_level_3_built_at`;
-// F1 (v1.7.0): qualified-and-aliased columns for the FTS join in
-// loadSearchRows. Every column is `m.<col> AS <col>` so rowToEntry's
-// unqualified field reads keep working unchanged. The trailing
-// bm25(memories_fts) AS bm25_score adds the FTS rank as a result column.
-// Only used inside the FTS path; non-FTS paths keep MEMORY_SELECT_COLUMNS.
+// FTS-join columns for loadSearchRows: each is `m.<col> AS <col>` so rowToEntry's unqualified
+// reads still work, and the trailing bm25(memories_fts) AS bm25_score carries the FTS rank.
 export const MEMORY_SEARCH_COLUMNS = `m.id AS id, m.created AS created, m.last_retrieved AS last_retrieved, m.retrieval_count AS retrieval_count, m.strength AS strength, m.half_life_days AS half_life_days, m.layer AS layer, m.tags_json AS tags_json, m.emotional_valence AS emotional_valence, m.schema_fit AS schema_fit, m.source AS source, m.outcome_score AS outcome_score, m.outcome_positive AS outcome_positive, m.outcome_negative AS outcome_negative, m.conflicts_with_json AS conflicts_with_json, m.pinned AS pinned, m.confidence AS confidence, m.content AS content, m.parents_json AS parents_json, m.starred AS starred, m.trace_outcome AS trace_outcome, m.source_session_id AS source_session_id, m.valid_from AS valid_from, m.superseded_by AS superseded_by, m.extracted_from AS extracted_from, m.dag_level AS dag_level, m.dag_parent_id AS dag_parent_id, m.kind AS kind, m.scope AS scope, m.owner AS owner, m.artifact_ref AS artifact_ref, m.tenant_id AS tenant_id, m.origin_project AS origin_project, m.descendant_count AS descendant_count, m.earliest_at AS earliest_at, m.latest_at AS latest_at, m.summary_dirty AS summary_dirty, m.last_rebuilt_at AS last_rebuilt_at, m.rebuild_count AS rebuild_count, m.dag_level_3_built_at AS dag_level_3_built_at, bm25(memories_fts) AS bm25_score`;
 /**
  * Default candidate-pool size for `loadSearchEntries` when called with
@@ -55,15 +52,13 @@ export function rowToEntry(row) {
         descendant_count: Number(row.descendant_count ?? 0),
         earliest_at: row.earliest_at ?? null,
         latest_at: row.latest_at ?? null,
-        // v0.30 / E1 of DAG live-coupling (schema v28). Symmetric with v25 cache.
         summary_dirty: (Number(row.summary_dirty ?? 0) === 1 ? 1 : 0),
         last_rebuilt_at: row.last_rebuilt_at ?? null,
         rebuild_count: Number(row.rebuild_count ?? 0),
         dag_level_3_built_at: row.dag_level_3_built_at ?? null,
     };
-    // F1 (v1.7.0): preserve bm25_score from the FTS path. `'bm25_score' in row`
-    // distinguishes "absent column" (non-FTS path) from "column present but
-    // value 0" — though FTS5 bm25() never returns 0, this is defensive.
+    // Preserve bm25_score from the FTS path; `'bm25_score' in row` tells an absent column
+    // (non-FTS path) from a present one.
     if ('bm25_score' in row && row.bm25_score !== undefined && row.bm25_score !== null) {
         entry.bm25_score = Number(row.bm25_score);
     }
@@ -82,8 +77,8 @@ export function parseJsonArray(raw) {
     }
 }
 /**
- * Strict parse for the `last_trace_id` meta value (LC1 F1(d) structural
- * fix). A bare Number(raw) would turn '', whitespace, or garbage into a
+ * Strict parse for the `last_trace_id` meta value.
+ * A bare Number(raw) would turn '', whitespace, or garbage into a
  * usable-looking 0/NaN — a consumer INSERTing recall_trace_outcomes with
  * trace_id=0 would hit a masked FK violation (row id 0 never exists).
  * Require a clean positive integer string; anything else is treated as

package/dist/store/search-rows.d.ts

@@ -1,29 +1,17 @@
 import type { MemoryEntry } from '../memory.js';
 import { type DatabaseSyncLike } from '../db.js';
 /**
- * v1.7.2 — recall-mode scope filter shape, exported so callers
- * (`loadRecallSearchEntries`) and tests can refer to it symbolically without
- * `Parameters<typeof loadSearchRows>[N]` indirection.
- *
- * Three modes:
- *   - 'default-deny' — exclude scopes in `RECALL_DEFAULT_DENY_SCOPES` (T2).
- *   - 'exact' — exact match on `m.scope = value` (api.recall's explicit-scope
- *     request semantics).
- *   - 'default-deny-or-exact' (v1.25.0) — the default-admitted set PLUS rows
- *     whose scope equals `value`. This is the CLI `--scope` semantics: the
- *     flag predates the envelope column as a TAG-boost ranking hint
- *     (`scope:<v>` tags, HIPPO_SCOPE), so an explicit flag must UNLOCK the
- *     named envelope scope in addition to the normal set rather than narrow
- *     the result to it — narrowing would return zero rows for every
- *     tag-scoped workflow (envelope scope NULL). Strictly safer than the
- *     pre-v1.25.0 CLI behavior (no filter at all): other private scopes and
- *     quarantine buckets stay denied.
+ * Recall-mode scope filter shape, exported so callers and tests can name it. Three modes:
+ *   - 'default-deny': exclude scopes in `RECALL_DEFAULT_DENY_SCOPES`.
+ *   - 'exact': exact match on `m.scope = value` (api.recall's explicit-scope request semantics).
+ *   - 'default-deny-or-exact': the default-admitted set PLUS rows whose scope equals `value` (CLI `--scope`).
+ *     The flag began as a tag-boost hint, so narrowing would return zero rows for tag-scoped workflows.
  *
  * Background pipelines (`consolidate`, `embeddings`, `refine-llm`, ...) call
  * `loadSearchEntries` (no scopeFilter arg) and see all rows including
  * quarantine.
  */
-/** @internal v1.7.2 — internal SQL-builder shape; not on the public API
+/** @internal Internal SQL-builder shape; not on the public API
  *  surface (not re-exported from `src/index.ts`). Subject to change. */
 export type RecallScopeFilter = {
     mode: 'default-deny';
@@ -34,6 +22,8 @@ export type RecallScopeFilter = {
     mode: 'default-deny-or-exact';
     value: string;
 };
+/** One project name, or every name a project's rows carry. */
+export type OriginFilter = string | readonly string[];
 /** Scope rule for recall: none requested is default-deny; 'exact' narrows to the request; 'additive' adds it to the default set. */
 export declare function recallScopeFilter(requestedScope: string | undefined, mode: 'exact' | 'additive'): RecallScopeFilter;
 /**
@@ -45,31 +35,24 @@ export declare function recallScopeFilter(requestedScope: string | undefined, mo
  */
 export declare function loadSearchEntries(hippoRoot: string, query: string, limit?: number, tenantId?: string): MemoryEntry[];
 /**
- * v1.7.1 — recall-mode loader. Pushes the recall-side scope predicate into
- * SQL so `unknown:legacy` cannot leak via any consumer that hasn't remembered
- * to re-filter (root-cause-over-patches: codex flagged this on v1.6.5 review).
+ * Recall-mode loader. Pushes the recall-side scope predicate into SQL so
+ * `unknown:legacy` cannot leak via any consumer that hasn't remembered to re-filter.
  *
  * - `requestedScope` undefined / '': default-deny on `unknown:legacy`.
  * - `requestedScope` non-empty string: exact match on `m.scope = requestedScope`.
  *
- * Private-scope (`<source>:private:*`) exclusion: SQL applies a conservative
- * pre-window approximation (`NOT LIKE '%:private:%'`, v1.25.0 — codex P2:
- * post-window-only filtering let private rows starve admitted candidates out
- * of the LIMIT window); the exact anchored regex
- * (`passesScopeFilterForRecall`) remains the authoritative JS post-filter in
- * the recall consumers.
+ * Private scopes: SQL applies a conservative `NOT LIKE '%:private:%'` before the LIMIT window so private
+ * rows cannot starve admitted ones; `passesScopeFilterForRecall` stays the exact JS post-filter.
  *
- * Consumers: `api.recall` (v1.7.1+), `cmdRecall`/`cmdExplain` direct CLI paths
- * and `searchBothHybrid` recall mode (v1.25.0). Background pipelines
+ * Consumers: `api.recall`, `cmdRecall`/`cmdExplain` direct CLI paths
+ * and `searchBothHybrid` recall mode. Background pipelines
  * (`consolidate`, `embeddings`, `refine-llm`, ...) keep using
  * `loadSearchEntries` so they can see quarantined rows when needed.
  *
- * `tenantId` widened to optional in v1.25.0 for the searchBothHybrid recall
- * mode (its `tenantId` option is optional); `loadSearchRows` already treats
- * undefined as "no tenant filter" for legacy callers.
+ * `tenantId` is optional because searchBothHybrid's is; undefined means no tenant filter.
  */
-export declare function loadRecallSearchEntries(hippoRoot: string, query: string, limit?: number, tenantId?: string, requestedScope?: string, explicitScopeMode?: 'exact' | 'additive', includeSuperseded?: boolean, originProject?: string): MemoryEntry[];
-export declare function loadRecallSearchEntriesFromDb(db: DatabaseSyncLike, query: string, limit?: number, tenantId?: string, requestedScope?: string, explicitScopeMode?: 'exact' | 'additive', includeSuperseded?: boolean, originProject?: string): MemoryEntry[];
+export declare function loadRecallSearchEntries(hippoRoot: string, query: string, limit?: number, tenantId?: string, requestedScope?: string, explicitScopeMode?: 'exact' | 'additive', includeSuperseded?: boolean, originProjects?: OriginFilter): MemoryEntry[];
+export declare function loadRecallSearchEntriesFromDb(db: DatabaseSyncLike, query: string, limit?: number, tenantId?: string, requestedScope?: string, explicitScopeMode?: 'exact' | 'additive', includeSuperseded?: boolean, originProjects?: OriginFilter): MemoryEntry[];
 /** Which rows the vector arm of hybrid search may add: the same tenant, scope and superseded rules as the lexical load. */
 export interface VectorCandidateSpec {
     tenantId?: string;