hippo-memory 1.70.0 → 1.71.0

package/dist/importers/vault.js

@@ -1,3 +1,4 @@
+import { DEFAULT_TENANT_ID } from '../util/env.js';
 import * as fs from 'fs';
 import * as path from 'path';
 import { createHash } from 'node:crypto';
@@ -15,33 +16,17 @@ import { splitMarkdownFrontmatter, frontmatterList, parseWikilinks, collectMarkd
 import { realpathOrResolve } from '../util/real-path.js';
 import { isJsonString } from '../util/json.js';
 import { escapeLike } from '../util/escape.js';
-/**
- * Import a markdown vault FOLDER as `kind='raw'` memories.
- *
- * NOT re-entrant: idempotency rests on the in-memory `existing` Map loaded once
- * at the top. Two concurrent importVault runs over the same vault could both see
- * a note as absent and double-insert (the connector pattern relies on a single
- * sequential writer; same caveat applies here).
- */
+/** Import a markdown vault FOLDER as `kind='raw'` memories.
+ *  NOT re-entrant: idempotency rests on the in-memory `existing` Map loaded once, so two concurrent runs over one vault can double-insert. */
 export function importVault(folderPath, options) {
     const hippoRoot = options.hippoRoot;
     const identity = vaultIdentityOrThrow(options);
     if (options.global) {
-        // The raw-archive path is tenant-local; global mode would put raw vault rows
-        // in the wrong store. Reject for SDK callers too (the CLI also rejects
-        // --global) rather than silently writing local (codex P2).
+        // The raw-archive path is tenant-local, so global mode would put raw vault rows in the wrong store; reject for SDK callers too, not only the CLI.
         throw new Error('importVault does not support global mode (raw rows are tenant-local).');
     }
-    // Self-store no-op guard (codex R8 P1). MUST run BEFORE the existing-rows load
-    // and the deletion-sync pass below. If the vault folder IS the store (or lives
-    // inside it), there are no real vault notes - only the store's own markdown
-    // mirror files. Letting collectMarkdownFiles return [] for this case is NOT
-    // safe: an empty scan is indistinguishable from "every note was deleted", so
-    // deletion-sync would archive every live vault:<name>:* row, and raw-archive
-    // content redaction makes that loss IRREVERSIBLE. The only safe reading of
-    // "import the store into itself" is "do nothing". Canonicalize both paths
-    // (realpath: dereference junctions/symlinks + normalize Windows case) so an
-    // aliased path to the store is still caught (codex R9 P2).
+    // Self-store no-op guard: MUST run before the existing-rows load and the deletion-sync. If the vault IS (or sits inside) the store, an empty scan looks like
+    // "every note deleted" and deletion-sync would irreversibly archive every live row, so do nothing. Canonicalize both paths (realpath) to catch aliased paths.
     const resolvedStore = realpathOrResolve(hippoRoot);
     const resolvedFolder = realpathOrResolve(folderPath);
     if (resolvedFolder === resolvedStore || resolvedFolder.startsWith(resolvedStore + path.sep)) {
@@ -51,7 +36,7 @@ export function importVault(folderPath, options) {
 }
 function syncVaultFolder(folderPath, options, { vaultName, scope }) {
     const hippoRoot = options.hippoRoot;
-    const tenantId = options.tenantId ?? 'default';
+    const tenantId = options.tenantId ?? DEFAULT_TENANT_ID;
     const extraTags = options.extraTags ?? [];
     const dryRun = options.dryRun ?? false;
     const ctx = {
@@ -78,10 +63,8 @@ function syncVaultFolder(folderPath, options, { vaultName, scope }) {
         withRequestStoresSync(importNotes);
     else
         importNotes();
-    // Deletion-sync: any artifactRef present in the Map but NOT seen this run is a
-    // note that vanished from the source folder → archive its raw row. Per-file
-    // archiveRaw (own handle); no outer SAVEPOINT (no cross-file idempotency row
-    // to commit atomically, unlike github's multi-row case).
+    // Deletion-sync: an artifactRef in the Map but not seen this run vanished from the source, so archive its raw row.
+    // Per-file archiveRaw, no outer SAVEPOINT: there is no cross-file idempotency row to commit atomically.
     for (const [artifactRef, rows] of existing) {
         if (seen.has(artifactRef))
             continue;
@@ -95,32 +78,19 @@ function syncVaultFolder(folderPath, options, { vaultName, scope }) {
     return { total, imported, skipped, rejected, archived, redacted, entries };
 }
 function vaultIdentityOrThrow(options) {
-    // Vault NAME is the identity key for the destructive deletion-sync below, so it
-    // must be explicit. Defaulting to the folder basename meant two unrelated vaults
-    // sharing a basename (e.g. work/notes and personal/notes) collided on the same
-    // `vault:<name>:*` prefix - importing the second loaded the first's rows and the
-    // deletion-sync archived them (codex R10 P2). Require a deliberate name instead
-    // of inferring a path-unstable one.
+    // The vault NAME keys the destructive deletion-sync, so it must be explicit: defaulting to the folder basename made two vaults
+    // sharing a basename collide on the same `vault:<name>:*` prefix and the sync archived the first one's rows.
     const vaultName = options.name?.trim();
     if (!vaultName) {
         throw new Error('importVault requires an explicit vault name (options.name): it is the identity key for source-deletion sync and must not be inferred from the folder basename.');
     }
     if (vaultName.includes(':')) {
-        // ':' is the artifactRef delimiter (vault:<name>:<relpath>); a name
-        // containing it lets a different vault's prefix scan over-match and archive
-        // its rows (codex P2). Reject rather than silently corrupt the keys.
+        // ':' delimits the artifactRef (vault:<name>:<relpath>); a name containing it lets another vault's prefix scan over-match and archive its rows.
         throw new Error(`vault name must not contain ':' (artifactRef delimiter): ${vaultName}`);
     }
     const scope = options.scope ?? null;
-    // Privacy footgun guard (codex R13 P2): hippo's recall filter only default-denies
-    // scopes shaped `<source>:private:*` (see isPrivateScope / PRIVATE_SCOPE_RE in
-    // scope.ts). A bare `private` (or `private:<x>`) first segment is NOT recognized
-    // as private, so notes a user believes are private would still be returned to
-    // no-scope recall callers. Reject the alias and point at the source-prefixed form
-    // rather than silently storing public-visible "private" notes. Use recall's own
-    // isPrivateScope as the single source of truth: reject a scope that names a
-    // `private` segment yet is NOT a valid `<source>:private:*` (catches `private`,
-    // `private:x`, and `vault:private` with a missing trailing segment).
+    // Privacy guard: recall only default-denies scopes shaped `<source>:private:*` (isPrivateScope in src/store/recall-scope.ts), so a bare `private`
+    // alias would be returned to no-scope callers. Reject any scope naming a `private` segment that is not a valid `<source>:private:*`.
     assertClientScope(scope);
     if (scope !== null && scope.split(':').includes('private') && !isPrivateScope(scope)) {
         throw new Error(`vault scope '${scope}' is not recognized as private by recall (only '<source>:private:*' scopes are default-denied). Use a source-prefixed scope such as 'vault:private:${vaultName}'.`);
@@ -153,27 +123,17 @@ function importVaultNote(run, relpath) {
     tally.total++;
     const artifactRef = `vault:${run.vaultName}:${relpath}`;
     run.seen.add(artifactRef);
-    // Content-hash is computed from the RAW file bytes (deterministic; no
-    // Date/random in the content path) so idempotency survives frontmatter
-    // edits identically to body edits.
+    // The content hash covers the RAW file bytes (deterministic, no Date/random) so frontmatter edits are idempotent like body edits.
     const rawFileContent = readVaultNote(run, relpath);
     if (rawFileContent === null)
         return;
     const hash = createHash('sha256').update(rawFileContent).digest('hex');
     const hashTag = `content-hash:${hash}`;
-    // Load every live raw row for this ref (>1 only after a concurrent double-
-    // insert). The idempotency decision happens below, AFTER the full tag set is
-    // built, so it can compare the complete envelope rather than a subset.
+    // Load every live raw row for this ref (>1 only after a concurrent double-insert); decide idempotency below, once the full tag set is built.
     const priors = run.existing.get(artifactRef) ?? [];
     const { fm, body } = splitMarkdownFrontmatter(rawFileContent);
-    // Empty / frontmatter-only note: nothing storable (createMemory enforces a
-    // min content length). The note's CONTENT was deleted at source, so this is a
-    // content-deletion: archive any prior row(s) - the old body must not stay live
-    // and searchable after the source no longer holds it (codex R12 P2) - then
-    // skip the write. Archiving here is safe precisely because we then skip
-    // remember() entirely: there is no archive-then-throw-on-empty-body hazard
-    // (the original reason this branch did not archive). The note stays in `seen`
-    // so deletion-sync does not double-process it.
+    // Empty or frontmatter-only note: nothing storable, and the content was deleted at source, so archive prior rows (the old body must not stay searchable)
+    // and skip the write. Safe because remember() is skipped, so there is no archive-then-throw hazard; the note stays in `seen` so deletion-sync skips it.
     if (body.trim().length < 3) {
         archivePriors(run, priors, `emptied:${artifactRef}`);
         tally.skipped++;
@@ -189,15 +149,10 @@ function importVaultNote(run, relpath) {
 }
 function writeChangedNote(run, artifactRef, priors, body, tags) {
     const { ctx, tally } = run;
-    // Changed file → archive EVERY old raw row for this ref (normally one; >1
-    // only after a concurrent double-insert), then append the new one. NEVER
-    // supersede (would yield kind='distilled'). archiveRaw commits + closes its
-    // handle before remember() runs, so there is no double-live row; a crash
-    // between them self-heals (file re-imported as fresh raw next run).
+    // Changed file: archive EVERY old raw row for this ref (>1 only after a concurrent double-insert), then append the new one; NEVER supersede.
+    // archiveRaw commits before remember() runs, so no double-live row; a crash between them self-heals on the next import.
     archivePriors(run, priors, `changed:${artifactRef}`);
-    // remember() owns the actual write. We build an `echo` of the SAME content +
-    // tags via createMemory purely for the ImportResult, then reconcile its id to
-    // remember()'s real row id so entries[] reflects the row that landed.
+    // remember() owns the write; the `echo` from createMemory only fills the ImportResult, with its id reconciled to the row that landed.
     const content = vetSecrets(body, tags, true).content;
     const echo = createMemory(content, {
         kind: 'raw',
@@ -236,10 +191,7 @@ function archivePriors(run, priors, reason) {
     }
 }
 function vaultNoteTags(run, hashTag, fm, body) {
-    // Build the FULL tag envelope this import would write, BEFORE the idempotency
-    // decision. De-duplicate (createMemory stores tags verbatim, so a collision
-    // between, e.g., a frontmatter tag and an extraTag would otherwise produce a
-    // duplicate). Order-preserving.
+    // Build the FULL tag envelope before the idempotency decision, de-duplicated and order-preserving (createMemory stores tags verbatim).
     const frontmatterTags = [
         ...frontmatterList(fm['tags']),
         ...frontmatterList(fm['aliases']).map((a) => `alias:${a}`),
@@ -255,14 +207,8 @@ function vaultNoteTags(run, hashTag, fm, body) {
     ]));
 }
 function vaultEnvelopeUnchanged(priors, tags, scope) {
-    // Unchanged iff EVERY live raw row carries the EXACT same tag set AND scope.
-    // Comparing the COMPLETE set (not the content-hash + a subset of extra tags)
-    // means every envelope change registers: content (via the content-hash tag),
-    // frontmatter, wikilinks, an ADDED extra tag, or a REMOVED one - the earlier
-    // piecemeal checks missed scope (R10 P2) then tag removal (R11 P2). Set
-    // equality is order-independent and both sides are deduped. (`length > 0`
-    // guard: a never-seen file must import, not skip; archiving ALL priors on a
-    // mismatch also clears any concurrent-double-insert duplicates.)
+    // Unchanged iff EVERY live raw row carries the EXACT same tag set AND scope; comparing the complete envelope (not hash plus a subset) catches
+    // scope, added and removed tags. `length > 0` guards a never-seen file; archiving all priors on a mismatch also clears concurrent double-inserts.
     const wantTags = new Set(tags);
     return (priors.length > 0 &&
         priors.every((p) => {
@@ -297,9 +243,7 @@ function storeVaultNote(run, echo, content, tags, artifactRef) {
         throw err;
     }
 }
-/** Local tolerant JSON-array parse for the loader's `tags_json` column. The
- *  store's own `parseJsonArray` is not exported; this matches its contract
- *  (returns [] on null/garbage). */
+/** Tolerant JSON-array parse for the loader's `tags_json` column (the store's `parseJsonArray` is not exported); returns [] on null or garbage. */
 function parseJsonArrayLoose(value) {
     if (!value)
         return [];

package/dist/index.d.ts

@@ -33,9 +33,13 @@ export { ConsolidationResult } from './consolidate/run.js';
 export { sleep, type SleepOpts, type SleepResult } from './api/sleep.js';
 export { strengthBucket } from './consolidate/dedupe.js';
 export { isEmbeddingAvailable, getEmbedding } from './store/embeddings/local.js';
-export { cosineSimilarity, loadEmbeddingIndex, saveEmbeddingIndex, embedMemory, embedAll, } from './store/embeddings/index.js';
+export { cosineSimilarity, embedMemory, embedAll, } from './store/embeddings/index.js';
+export { loadEmbeddingIndex, saveEmbeddingIndex } from './store/vector-index.js';
 export { captureError, extractLessons, partitionLessons, deduplicateLesson, runWatched, fetchGitLog, } from './learn/autolearn.js';
-export { getGlobalRoot, initGlobal, promoteToGlobal, searchBoth, searchBothHybrid, syncGlobalToLocal, HybridSearchOptions, transferScore, shareMemory, listPeers, autoShare, } from './sharing/shared.js';
+export { getGlobalRoot, initGlobal, promoteToGlobal } from './sharing/global-store.js';
+export { searchBoth, searchBothHybrid, HybridSearchOptions } from './sharing/search-both.js';
+export { syncGlobalToLocal } from './sharing/global-sync.js';
+export { transferScore, shareMemory, listPeers, autoShare } from './sharing/share.js';
 export { wmPush, wmRead, wmClear, wmFlush, WorkingMemoryItem, WM_MAX_ENTRIES, } from './store/working-memory.js';
 export { importChatGPT, importClaude, importCursor, importGenericFile, } from './importers/sources.js';
 export { importMarkdown } from './importers/markdown.js';

package/dist/index.js

@@ -37,11 +37,15 @@ export { sleep } from './api/sleep.js';
 export { strengthBucket } from './consolidate/dedupe.js';
 // Feature 1: Embedding search
 export { isEmbeddingAvailable, getEmbedding } from './store/embeddings/local.js';
-export { cosineSimilarity, loadEmbeddingIndex, saveEmbeddingIndex, embedMemory, embedAll, } from './store/embeddings/index.js';
+export { cosineSimilarity, embedMemory, embedAll, } from './store/embeddings/index.js';
+export { loadEmbeddingIndex, saveEmbeddingIndex } from './store/vector-index.js';
 // Feature 2: Auto-learn from errors
 export { captureError, extractLessons, partitionLessons, deduplicateLesson, runWatched, fetchGitLog, } from './learn/autolearn.js';
 // Feature 3: Cross-agent shared memory
-export { getGlobalRoot, initGlobal, promoteToGlobal, searchBoth, searchBothHybrid, syncGlobalToLocal, transferScore, shareMemory, listPeers, autoShare, } from './sharing/shared.js';
+export { getGlobalRoot, initGlobal, promoteToGlobal } from './sharing/global-store.js';
+export { searchBoth, searchBothHybrid } from './sharing/search-both.js';
+export { syncGlobalToLocal } from './sharing/global-sync.js';
+export { transferScore, shareMemory, listPeers, autoShare } from './sharing/share.js';
 // Feature 5: Working memory
 export { wmPush, wmRead, wmClear, wmFlush, WM_MAX_ENTRIES, } from './store/working-memory.js';
 // Feature 4: Memory importers

package/dist/learn/autolearn.d.ts

@@ -1,56 +1,29 @@
-/**
- * Auto-learn from errors and git history.
- * Agents learn from failures without explicit hippo remember calls.
- */
+/** Auto-learn from errors and git history.
+ *  Agents learn from failures without explicit hippo remember calls. */
 import { MemoryEntry } from '../core/memory.js';
-/** A memory of a failed command, "Command '<cmd>' failed: <truncated stderr>"; no store is in reach, so `hippo watch` re-derives its half-life from the store's config. */
+/** A memory of a failed command, "Command '<cmd>' failed: <truncated stderr>"; `hippo watch` stores its text and tags through remember. */
 export declare function captureError(exitCode: number, stderr: string, command: string, tenantId?: string): MemoryEntry;
-/**
- * Parse git log output for actionable lessons.
- * Looks for fix:, revert:, bug:, error:, hotfix: commit messages.
- */
+/** Parse git log output for actionable lessons.
+ *  Looks for fix:, revert:, bug:, error:, hotfix: commit messages. */
 export declare function extractLessons(gitLog: string, customPatterns?: string[]): string[];
-/**
- * Split parsed lessons into ones worth storing and low-information ones.
- *
- * `extractLessons` is a published API surface (exported from src/index.ts)
- * and does one job: parse a git log into candidate lesson strings. Adding a
- * quality check inside it would break that contract and silently change
- * what external callers get back. So parsing and admission are separate
- * steps: this function is the write-path gate, called by each caller that
- * actually stores a lesson, not by the parser itself.
- *
- * Order is preserved in both output arrays; both hold lessons with secret shapes redacted.
- */
+/** Split parsed lessons into ones worth storing and low-information ones; kept out of `extractLessons` so that published parser's output cannot change.
+ *  Order is preserved in both arrays, and both hold lessons with secret shapes redacted. */
 export declare function partitionLessons(lessons: string[]): {
     kept: string[];
     dropped: string[];
 };
-/**
- * Check if a substantially similar memory already exists.
- * Returns true if overlap > threshold (default 0.7).
- *
- * `tenantId` is opt-in. Only takes effect when the first argument is a
- * root string (string-overload path). When the first argument is a
- * pre-loaded MemoryEntry[], the caller has already scoped — tenantId is
- * ignored on that path.
- */
+/** Check if a substantially similar memory already exists: true if overlap > threshold (default 0.7).
+ *  `tenantId` applies only on the root-string overload; a pre-loaded MemoryEntry[] is already scoped, so it is ignored there. */
 export declare function deduplicateLesson(hippoRootOrEntries: string | MemoryEntry[], lesson: string, threshold?: number, tenantId?: string): boolean;
-/**
- * Run a command in a shell, streaming stderr live; never pass text the caller did not write.
- * Returns: { exitCode, stderr }.
- */
+/** Run a command in a shell, streaming stderr live; never pass text the caller did not write.
+ *  Returns: { exitCode, stderr }. */
 export declare function runWatched(command: string): Promise<{
     exitCode: number;
     stderr: string;
 }>;
-/**
- * Check whether a directory is a git work tree.
- */
+/** Check whether a directory is a git work tree. */
 export declare function isGitRepo(cwd: string): boolean;
-/**
- * Fetch recent git log lines (subject lines only).
- * days: how many days of history to include.
- */
+/** Fetch recent git log lines (subject lines only).
+ *  days: how many days of history to include. */
 export declare function fetchGitLog(cwd: string, days: number): string;
 //# sourceMappingURL=autolearn.d.ts.map

package/dist/learn/autolearn.js

@@ -1,7 +1,5 @@
-/**
- * Auto-learn from errors and git history.
- * Agents learn from failures without explicit hippo remember calls.
- */
+/** Auto-learn from errors and git history.
+ *  Agents learn from failures without explicit hippo remember calls. */
 import { execSync, execFileSync, spawn } from 'child_process';
 import { createMemory, Layer, DEFAULT_HALF_LIFE_DAYS } from '../core/memory.js';
 import { loadAllEntries } from '../store/entry-reads.js';
@@ -11,7 +9,7 @@ import { redactSecretsStrict } from '../util/secret-detect.js';
 import { errorMessage, log } from '../util/log.js';
 const AUTOLEARN_TEXT_CHARS = 500;
 const AUTOLEARN_TAG_CHARS = 30;
-/** A memory of a failed command, "Command '<cmd>' failed: <truncated stderr>"; no store is in reach, so `hippo watch` re-derives its half-life from the store's config. */
+/** A memory of a failed command, "Command '<cmd>' failed: <truncated stderr>"; `hippo watch` stores its text and tags through remember. */
 export function captureError(exitCode, stderr, command, tenantId) {
     // Truncate to first 500 chars to avoid storing megabytes of build logs
     const clean = redactSecretsStrict(stderr);
@@ -35,10 +33,8 @@ export function captureError(exitCode, stderr, command, tenantId) {
         baseHalfLifeDays: DEFAULT_HALF_LIFE_DAYS,
     });
 }
-/**
- * Parse git log output for actionable lessons.
- * Looks for fix:, revert:, bug:, error:, hotfix: commit messages.
- */
+/** Parse git log output for actionable lessons.
+ *  Looks for fix:, revert:, bug:, error:, hotfix: commit messages. */
 export function extractLessons(gitLog, customPatterns) {
     const lessons = [];
     const lines = gitLog.split('\n');
@@ -73,18 +69,8 @@ export function extractLessons(gitLog, customPatterns) {
     // Deduplicate exact matches at extraction time
     return [...new Set(lessons)];
 }
-/**
- * Split parsed lessons into ones worth storing and low-information ones.
- *
- * `extractLessons` is a published API surface (exported from src/index.ts)
- * and does one job: parse a git log into candidate lesson strings. Adding a
- * quality check inside it would break that contract and silently change
- * what external callers get back. So parsing and admission are separate
- * steps: this function is the write-path gate, called by each caller that
- * actually stores a lesson, not by the parser itself.
- *
- * Order is preserved in both output arrays; both hold lessons with secret shapes redacted.
- */
+/** Split parsed lessons into ones worth storing and low-information ones; kept out of `extractLessons` so that published parser's output cannot change.
+ *  Order is preserved in both arrays, and both hold lessons with secret shapes redacted. */
 export function partitionLessons(lessons) {
     const kept = [];
     const dropped = [];
@@ -98,15 +84,8 @@ export function partitionLessons(lessons) {
     }
     return { kept, dropped };
 }
-/**
- * Check if a substantially similar memory already exists.
- * Returns true if overlap > threshold (default 0.7).
- *
- * `tenantId` is opt-in. Only takes effect when the first argument is a
- * root string (string-overload path). When the first argument is a
- * pre-loaded MemoryEntry[], the caller has already scoped — tenantId is
- * ignored on that path.
- */
+/** Check if a substantially similar memory already exists: true if overlap > threshold (default 0.7).
+ *  `tenantId` applies only on the root-string overload; a pre-loaded MemoryEntry[] is already scoped, so it is ignored there. */
 export function deduplicateLesson(hippoRootOrEntries, lesson, threshold = 0.7, tenantId) {
     const entries = Array.isArray(hippoRootOrEntries)
         ? hippoRootOrEntries
@@ -118,10 +97,8 @@ export function deduplicateLesson(hippoRootOrEntries, lesson, threshold = 0.7, t
     }
     return false;
 }
-/**
- * Run a command in a shell, streaming stderr live; never pass text the caller did not write.
- * Returns: { exitCode, stderr }.
- */
+/** Run a command in a shell, streaming stderr live; never pass text the caller did not write.
+ *  Returns: { exitCode, stderr }. */
 export function runWatched(command) {
     return new Promise((resolve) => {
         // Use shell: true so the command string is handled by the shell as-is
@@ -143,9 +120,7 @@ export function runWatched(command) {
         });
     });
 }
-/**
- * Check whether a directory is a git work tree.
- */
+/** Check whether a directory is a git work tree. */
 export function isGitRepo(cwd) {
     try {
         const raw = execSync('git rev-parse --is-inside-work-tree', {
@@ -162,10 +137,8 @@ export function isGitRepo(cwd) {
         return false;
     }
 }
-/**
- * Fetch recent git log lines (subject lines only).
- * days: how many days of history to include.
- */
+/** Fetch recent git log lines (subject lines only).
+ *  days: how many days of history to include. */
 export function fetchGitLog(cwd, days) {
     try {
         const raw = execFileSync('git', [

package/dist/learn/extract.js

@@ -4,7 +4,7 @@ import { loadConfig } from '../core/config.js';
 import { RejectedValueError } from '../store/rejection.js';
 import { redactSecretsStrict } from '../util/secret-detect.js';
 import { describeMessageFailure, sendAnthropicMessage } from '../util/anthropic-messages.js';
-import { neverAutoShareTags } from '../sharing/shared.js';
+import { neverAutoShareTags } from '../sharing/share.js';
 import { errorMessage, log } from '../util/log.js';
 import { isJsonString } from '../util/json.js';
 import { certainDefect } from '../core/memory-quality.js';
@@ -86,9 +86,7 @@ export function storeExtractedFacts(hippoRoot, source, facts) {
             continue;
         }
         const entry = buildExtractedEntry(fact, source, inheritedTags, baseHalfLifeDays);
-        // A refusal is per-VALUE: one rejected fact must not
-        // drop the rest of this batch. writeEntry has already audited the
-        // refusal (reject_refusal) before rethrowing, so skip-and-count here.
+        // A refusal is per-VALUE: one rejected fact must not drop the rest of the batch; writeEntry already audited it (reject_refusal), so skip and count.
         try {
             writeEntry(hippoRoot, entry);
         }

package/dist/learn/forward-claim-detector.d.ts

@@ -1,36 +1,12 @@
-/**
- * Forward-claim detector: pure-function regex set + token extraction.
- *
- * No DB. No state. No dependencies beyond stdlib regex + String.
- *
- * The detector's job is to decide whether a recall query carries a
- * forward-prediction phrase ("will take ~3 days", "ship by Friday",
- * "ETA in 2 weeks"). Calibration is intentionally HIGH-PRECISION /
- * LOW-RECALL: better to fire on 20% of real forward-claims than 80% with
- * 40% noise. Cry-wolf failure dominates planning-fallacy hint UX (Lovallo-
- * Kahneman 2003 inside-vs-outside view).
- *
- * Iteration signal: the `recall_autodebias_hint_no_class_match` audit op
- * (emitted by recall when a phrase matches but no class
- * resolves) is the telemetry channel for deciding whether to add an
- * embedding-based detector.
- */
+/** Forward-claim detector: a pure regex set plus token extraction deciding whether a recall query carries a forward-prediction phrase.
+ *  Calibration is HIGH-PRECISION / LOW-RECALL, since cry-wolf noise dominates hint UX; `recall_autodebias_hint_no_class_match` audits are the telemetry. */
 export interface ForwardClaimMatch {
-    /** The regex match snippet, e.g. "will take" or "~3 days". Surfaced
-     *  to the calling agent in `PlanningFallacyHint.detectedPhrase` so they
-     *  see WHY the hint appeared. */
+    /** The regex match snippet (e.g. "will take"), surfaced in `PlanningFallacyHint.detectedPhrase` so the agent sees WHY the hint appeared. */
     phrase: string;
-    /** Lower-cased non-stop-word tokens (len >= 3, alpha or alphanumeric)
-     *  extracted from the FULL query, NOT just the match. Used by the
-     *  orchestrator's class resolver to score overlap with class_tag tokens. */
+    /** Lower-cased non-stop-word tokens (len >= 3) from the FULL query, not just the match; the class resolver scores them against class_tag tokens. */
     classQueryTokens: string[];
 }
-/**
- * Detect whether a recall query carries a forward-prediction phrase.
- *
- * @returns first-match phrase + extracted class-resolution tokens when
- *   any pattern matches; null otherwise. Token extraction runs only on a
- *   match — non-forward queries pay zero work beyond the regex gate.
- */
+/** Detect whether a recall query carries a forward-prediction phrase; returns the first-match phrase plus class-resolution tokens, else null.
+ *  Token extraction runs only on a match, so non-forward queries pay nothing beyond the regex gate. */
 export declare function detectForwardClaim(queryText: string): ForwardClaimMatch | null;
 //# sourceMappingURL=forward-claim-detector.d.ts.map

package/dist/learn/forward-claim-detector.js

@@ -1,91 +1,41 @@
-/**
- * Forward-claim detector: pure-function regex set + token extraction.
- *
- * No DB. No state. No dependencies beyond stdlib regex + String.
- *
- * The detector's job is to decide whether a recall query carries a
- * forward-prediction phrase ("will take ~3 days", "ship by Friday",
- * "ETA in 2 weeks"). Calibration is intentionally HIGH-PRECISION /
- * LOW-RECALL: better to fire on 20% of real forward-claims than 80% with
- * 40% noise. Cry-wolf failure dominates planning-fallacy hint UX (Lovallo-
- * Kahneman 2003 inside-vs-outside view).
- *
- * Iteration signal: the `recall_autodebias_hint_no_class_match` audit op
- * (emitted by recall when a phrase matches but no class
- * resolves) is the telemetry channel for deciding whether to add an
- * embedding-based detector.
- */
-/**
- * Each pattern is intentionally narrow:
- * adding a pattern should require evidence from the
- * `recall_autodebias_hint_no_class_match` audit channel that real forward-
- * claims are slipping through, NOT speculative "this might match more".
- *
- * Word boundaries (`\b`) are mandatory: prevent `~5 days` inside
- * `~5 days_ago` from matching, and prevent `ETA` substring matches inside
- * a longer token (e.g. `BETAtesting`).
- */
-// Reused fragment for ALL duration-suffix patterns. Requires a digit + unit
-// so 'will take ownership' / 'ship in Docker' (no time component) don't
-// match: verb-only patterns fire on everyday non-estimate queries that share a class-token.
-// Accepts `<N> unit` (3 days), `a/an unit` (a week — implicit 1), and
-// `one unit` so natural English forward-claims aren't lost.
+/** Forward-claim detector: a pure regex set plus token extraction deciding whether a recall query carries a forward-prediction phrase.
+ *  Calibration is HIGH-PRECISION / LOW-RECALL, since cry-wolf noise dominates hint UX; `recall_autodebias_hint_no_class_match` audits are the telemetry. */
+/** Each pattern is deliberately narrow (add one only on audit evidence); word boundaries are mandatory so `ETA` never matches inside `BETAtesting`. */
+// Shared duration suffix: needs a digit + unit (`<N> unit`, `a/an unit`, `one unit`) so 'will take ownership' and 'ship in Docker' do not match.
 const DURATION_TAIL = String.raw `(?:about|around|~|≈)?\s*(?:\d+|a|an|one)\s*(?:day|week|month|hour|hr|min(?:ute)?|sec(?:ond)?)s?\b`;
 const FORWARD_CLAIM_PATTERNS = [
-    // Verb + duration tail. Old pattern `/\b(?:will|should...) take\b/i`
-    // matched `who will take ownership of auth?` because there was no
-    // quantifier requirement. Now requires `<verb> take <N> <unit>`.
+    // Verb + duration tail: requires `<verb> take <N> <unit>`, because a bare `will take` matched `who will take ownership of auth?`.
     new RegExp(String.raw `\b(?:will|should|gonna|going\s+to)\s+take\s+${DURATION_TAIL}`, 'i'),
-    // Ship + by/in + duration-or-day. Old pattern `/\bship(?:ping)?\s+(?:by|in)\b/i`
-    // matched `how does this ship in Docker?`. Now requires either a
-    // duration tail OR a literal day-of-week reference.
+    // Ship + by/in + duration-or-day: a bare `ship in` matched `how does this ship in Docker?`, so a duration tail or literal day-of-week is required.
     new RegExp(String.raw `\bship(?:ping|s)?\s+(?:by|in)\s+(?:(?:about|around)\s+)?(?:next\s+)?(?:${DURATION_TAIL}|(?:monday|tuesday|wednesday|thursday|friday|saturday|sunday))\b`, 'i'),
     /\bestimate(?:d)?\s+(?:at\s+)?(?:~|≈|about|around)?\s*\d+/i,
     /\b(?:by|in|within)\s+(?:about|around|~)?\s*\d+\s*(?:day|week|month|hour)s?\b/i,
     /\bETA\s*(?:is|:)?\s*\d+/i,
     /\b(?:by|before)\s+next\s+(?:week|month|sprint|monday|tuesday|wednesday|thursday|friday|saturday|sunday)\b/i,
-    // Standalone tilde duration: '~3 days for migration', 'estimate ~3 days'.
-    // Lookbehind asserts start-of-string OR whitespace before the tilde
-    // because \b before ~ requires a word char immediately preceding (~ is
-    // not a word character), so /\b~/ would only match in 'foo~3 days'
-    // (malformed) and silently miss the legitimate cases.
+    // Standalone tilde duration ('~3 days for migration'): the lookbehind asserts start-of-string or whitespace because `\b` before `~` needs a word char
+    // and /\b~/ would only match 'foo~3 days', silently missing the real cases.
     /(?<=^|\s)~\s*\d+\s*(?:day|week|month|hour)s?\b/i,
     // Should + verb + duration tail. Same tightening as the leading 'will
     // take' rule: 'should ship by EOD' must include a quantifier.
     new RegExp(String.raw `\bshould\s+(?:be|ship|finish|complete|land)\s+(?:by|in|within)\s+(?:(?:about|around)\s+)?(?:next\s+)?(?:${DURATION_TAIL}|(?:monday|tuesday|wednesday|thursday|friday|saturday|sunday))\b`, 'i'),
 ];
-/**
- * Pronouns + function words + modal verbs the regex set already gates on.
- * Dropped before class-resolution so the overlap signal comes from
- * domain tokens ("migration", "auth", "refactor") rather than connectives.
- */
+/** Pronouns, function words and modal verbs the regex set already gates on; dropped before class resolution so overlap comes from domain tokens. */
 const STOP_WORDS = new Set([
     'the', 'a', 'an', 'and', 'or', 'but', 'for', 'to', 'in', 'on', 'at', 'of',
     'by', 'with', 'my', 'your', 'our', 'their', 'its', 'it', 'this', 'that',
     'these', 'those', 'will', 'should', 'can', 'i', 'we', 'they', 'he', 'she',
     'is', 'be', 'was', 'are', 'were', 'has', 'have', 'had', 'do', 'does', 'did',
     'from', 'as', 'so', 'than', 'then',
-    // Verbs that appear inside FORWARD_CLAIM_PATTERNS themselves — they're
-    // signal for the regex gate but NOT signal for class resolution (you
-    // wouldn't name a prediction class "take" or "ship"). Listing here so
-    // they don't pollute the classQueryTokens overlap score.
+    // Verbs inside FORWARD_CLAIM_PATTERNS gate the regex but are no signal for class resolution; listing them keeps them out of the classQueryTokens overlap.
     'take', 'taken', 'takes', 'ship', 'ships', 'finish', 'complete', 'land',
     'eta', 'estimate', 'estimated', 'next', 'about', 'around',
-    // Duration units appear in every forward-claim phrase by design (the
-    // regex set REQUIRES a `<N> <unit>` quantifier after the verb). Letting
-    // them through to class resolution lets a class tag containing 'days'
-    // win or tie on the unit token instead of the domain token.
+    // Every forward-claim phrase contains a duration unit by design; letting it through would let a class tag containing 'days' win or tie on the unit.
     'day', 'days', 'week', 'weeks', 'month', 'months',
     'hour', 'hours', 'hr', 'hrs',
     'min', 'mins', 'minute', 'minutes', 'sec', 'secs', 'second', 'seconds',
 ]);
-/**
- * Detect whether a recall query carries a forward-prediction phrase.
- *
- * @returns first-match phrase + extracted class-resolution tokens when
- *   any pattern matches; null otherwise. Token extraction runs only on a
- *   match — non-forward queries pay zero work beyond the regex gate.
- */
+/** Detect whether a recall query carries a forward-prediction phrase; returns the first-match phrase plus class-resolution tokens, else null.
+ *  Token extraction runs only on a match, so non-forward queries pay nothing beyond the regex gate. */
 export function detectForwardClaim(queryText) {
     if (!queryText)
         return null;
@@ -103,9 +53,7 @@ function extractClassQueryTokens(queryText) {
         .toLowerCase()
         // Strip everything that's not alphanum or whitespace or hyphen / underscore.
         .replace(/[^a-z0-9\s_-]/g, ' ')
-        // Split on whitespace AND hyphen AND underscore so `migration-effort`
-        // produces ['migration', 'effort'] — matching the class-tag split
-        // pattern in resolveClassFromTokens (split on /[-_\s]+/).
+        // Split on whitespace, hyphen and underscore so `migration-effort` yields ['migration', 'effort'], matching the class-tag split in resolveClassFromTokens.
         .split(/[\s_-]+/)
         .filter((t) => t.length >= 3 && !STOP_WORDS.has(t) && !/^\d+$/.test(t));
 }