hippo-memory 1.69.0 → 1.71.0

package/dist/importers/vault.js

@@ -1,53 +1,44 @@
+import { DEFAULT_TENANT_ID } from '../util/env.js';
 import * as fs from 'fs';
 import * as path from 'path';
 import { createHash } from 'node:crypto';
-import { createMemory } from '../memory.js';
-import { initStore } from '../store/open.js';
-import { remember, archiveRaw, isPrivateScope } from '../api.js';
-import { assertClientScope } from '../recall-scope.js';
-import { openHippoDb, closeHippoDb } from '../db.js';
-import { RejectedValueError, checkRejectionGuard } from '../rejection.js';
-import { loadConfig } from '../config.js';
-import { vetSecrets } from '../secret-detect.js';
-import { log } from '../log.js';
-import { parseFrontmatter, frontmatterList, parseWikilinks, collectMarkdownFiles, realpathOrResolve } from './markdown-parse.js';
-import { isJsonString } from '../json.js';
-import { escapeLike } from '../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 { createMemory } from '../core/memory.js';
+import { loadVaultRawRows } from '../store/entry-reads.js';
+import { remember, archiveRaw, isPrivateScope } from '../api/index.js';
+import { assertClientScope } from '../store/recall-scope.js';
+import { RejectedValueError } from '../store/rejection.js';
+import { rejectionGuardRefuses } from '../store/rejected-values.js';
+import { withRequestStoresSync } from '../db/request-stores.js';
+import { loadConfig } from '../core/config.js';
+import { vetSecrets } from '../util/secret-detect.js';
+import { errorMessage, log } from '../util/log.js';
+import { splitMarkdownFrontmatter, frontmatterList, parseWikilinks, collectMarkdownFiles } from './markdown-parse.js';
+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, so two concurrent runs over one vault can double-insert. */
 export function importVault(folderPath, options) {
     const hippoRoot = options.hippoRoot;
-    const tenantId = options.tenantId ?? 'default';
-    const { vaultName, scope } = vaultIdentityOrThrow(options);
-    const extraTags = options.extraTags ?? [];
-    const dryRun = options.dryRun ?? false;
+    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)) {
         return { total: 0, imported: 0, skipped: 0, rejected: 0, archived: 0, entries: [] };
     }
+    return syncVaultFolder(folderPath, options, identity);
+}
+function syncVaultFolder(folderPath, options, { vaultName, scope }) {
+    const hippoRoot = options.hippoRoot;
+    const tenantId = options.tenantId ?? DEFAULT_TENANT_ID;
+    const extraTags = options.extraTags ?? [];
+    const dryRun = options.dryRun ?? false;
     const ctx = {
         hippoRoot,
         tenantId,
@@ -60,26 +51,20 @@ export function importVault(folderPath, options) {
     const tally = { total: 0, imported: 0, skipped: 0, rejected: 0, archived: 0, redacted: 0, entries: [] };
     const baseHalfLifeDays = loadConfig(hippoRoot).defaultHalfLifeDays;
     const seen = new Set();
-    // AT1 P2 fix: dry-run never called remember(), so it never probed
-    // tombstones — every note that reached the write step counted as
-    // `imported` even when a real run would refuse it. Probe (read-only) via
-    // the same guard remember()/writeEntry uses, without ever writing.
-    const dryRunDb = dryRun ? openHippoDb(hippoRoot) : null;
-    try {
-        const run = {
-            ctx, folderPath, vaultName, scope, extraTags, dryRun, dryRunDb, existing, seen, baseHalfLifeDays, tally,
-        };
+    const run = {
+        ctx, folderPath, vaultName, scope, extraTags, dryRun, existing, seen, baseHalfLifeDays, tally,
+    };
+    const importNotes = () => {
         for (const relpath of relpaths)
             importVaultNote(run, relpath);
-    }
-    finally {
-        if (dryRunDb)
-            closeHippoDb(dryRunDb);
-    }
-    // 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).
+    };
+    // A dry run probes the rejection guard once per changed note; one scope lets every probe share a handle.
+    if (dryRun)
+        withRequestStoresSync(importNotes);
+    else
+        importNotes();
+    // 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;
@@ -93,32 +78,19 @@ export function importVault(folderPath, options) {
     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}'.`);
@@ -126,69 +98,42 @@ function vaultIdentityOrThrow(options) {
     return { vaultName, scope };
 }
 function loadVaultRows(hippoRoot, tenantId, vaultName) {
-    // Load ONCE: every existing raw row for this vault, tenant-scoped. The same
-    // Map serves both per-file idempotency AND the deletion diff (no second
-    // query). LIKE-escape the vault name so a `%`/`_` in it can't over-match.
-    initStore(hippoRoot);
-    // artifactRef -> ALL its live raw rows. >1 only after a concurrent double-insert
-    // (the importer is not re-entrant; see the JSDoc). The buckets matter: a later
-    // changed/deletion pass must archive EVERY matching row, not just the last one
-    // scanned, or older raw vault content lingers live + searchable (codex P2).
+    // One load serves both per-file idempotency and the deletion diff; the vault name is
+    // LIKE-escaped so a `%` or `_` in it cannot over-match.
+    const rows = loadVaultRawRows(hippoRoot, `vault:${escapeLike(vaultName)}:%`, tenantId);
+    // Every live row per artifactRef (more than one only after a concurrent double-insert), because a
+    // later changed or deletion pass must archive them all or older raw vault content stays searchable.
     const existing = new Map();
-    const db = openHippoDb(hippoRoot);
-    try {
-        const likeParam = `vault:${escapeLike(vaultName)}:%`;
-        // SAFETY: query selects exactly the columns of VaultRow, in the same
-        // names, from the memories table this module owns.
-        const rows = db
-            .prepare(`SELECT id, artifact_ref, tags_json, scope FROM memories
-           WHERE artifact_ref LIKE ? ESCAPE '\\' AND tenant_id = ? AND kind = 'raw'`)
-            .all(likeParam, tenantId);
-        // SQLite LIKE is case-insensitive for ASCII, so the query over-fetches
-        // (vault 'A' also matches 'vault:a:%'). Filter to the EXACT-case prefix in
-        // JS so deletion-sync never archives a different-cased vault's rows (codex P2).
-        const exactPrefix = `vault:${vaultName}:`;
-        for (const row of rows) {
-            if (row.artifact_ref && row.artifact_ref.startsWith(exactPrefix)) {
-                const bucket = existing.get(row.artifact_ref);
-                if (bucket)
-                    bucket.push(row);
-                else
-                    existing.set(row.artifact_ref, [row]);
-            }
+    // LIKE folds ASCII case (vault 'A' also matches 'vault:a:%'), so the exact-case prefix is checked
+    // here; without it deletion-sync would archive a different-cased vault's rows.
+    const exactPrefix = `vault:${vaultName}:`;
+    for (const row of rows) {
+        if (row.artifact_ref && row.artifact_ref.startsWith(exactPrefix)) {
+            const bucket = existing.get(row.artifact_ref);
+            if (bucket)
+                bucket.push(row);
+            else
+                existing.set(row.artifact_ref, [row]);
         }
     }
-    finally {
-        closeHippoDb(db);
-    }
     return existing;
 }
 function importVaultNote(run, relpath) {
-    const { ctx, tally } = run;
+    const { tally } = run;
     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 } = parseFrontmatter(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.
+    const { fm, body } = splitMarkdownFrontmatter(rawFileContent);
+    // 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++;
@@ -200,15 +145,14 @@ function importVaultNote(run, relpath) {
         tally.skipped++;
         return;
     }
-    // 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).
+    writeChangedNote(run, artifactRef, priors, body, tags);
+}
+function writeChangedNote(run, artifactRef, priors, body, tags) {
+    const { ctx, tally } = 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',
@@ -232,10 +176,9 @@ function readVaultNote(run, relpath) {
     try {
         return fs.readFileSync(path.join(run.folderPath, relpath), 'utf8');
     }
-    catch {
-        // File vanished between enumeration and read (TOCTOU), or a transient
-        // IO/permission error. Skip this one file rather than aborting the whole
-        // import (incl. the deletion-sync pass); an idempotent re-run picks it up.
+    catch (err) {
+        // One unreadable note (gone since the listing, or a transient IO error) must not abort the import; a re-run picks it up.
+        log.debug(`vault note skipped: ${relpath}: ${errorMessage(err)}`);
         run.tally.skipped++;
         return null;
     }
@@ -248,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}`),
@@ -267,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) => {
@@ -286,30 +220,21 @@ function vaultEnvelopeUnchanged(priors, tags, scope) {
 }
 /** Returns false when the rejection guard refuses the note; any other error propagates. */
 function storeVaultNote(run, echo, content, tags, artifactRef) {
+    // A dry run writes nothing; it asks the guard remember() uses, so its `rejected` count matches what a real run would refuse.
+    if (run.dryRun)
+        return !rejectionGuardRefuses(run.ctx.hippoRoot, run.ctx.tenantId, echo.id, echo.content);
     try {
-        // dryRun preview: count what WOULD import, but make no writes (codex P2).
-        if (!run.dryRun) {
-            // AT1 (plan §3 containment): a rejected note must not abort the rest
-            // of the vault scan (deletion-sync pass included). The priors above
-            // are already archived by this point — same self-heal story as any
-            // other crash between archiveRaw and remember() (comment above): a
-            // re-run with the file still rejected hits the same refusal again,
-            // loud each time via the rejected count.
-            const result = remember(run.ctx, {
-                content,
-                kind: 'raw',
-                artifactRef,
-                owner: 'agent:vault-import',
-                scope: run.scope ?? undefined,
-                tags,
-            });
-            echo.id = result.id;
-        }
-        else if (run.dryRunDb) {
-            // AT1 P2 fix: probe the tombstone without writing so the preview's
-            // `rejected` count matches what a real run would refuse.
-            checkRejectionGuard(run.dryRunDb, run.ctx.tenantId, echo.id, echo.content);
-        }
+        // A rejected note must not stop the scan or the deletion sync. Its priors are archived by now, so a rerun meets
+        // the same refusal and counts it again.
+        const result = remember(run.ctx, {
+            content,
+            kind: 'raw',
+            artifactRef,
+            owner: 'agent:vault-import',
+            scope: run.scope ?? undefined,
+            tags,
+        });
+        echo.id = result.id;
         return true;
     }
     catch (err) {
@@ -318,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 [];
@@ -329,7 +252,7 @@ function parseJsonArrayLoose(value) {
         return Array.isArray(parsed) ? parsed.filter(isJsonString) : [];
     }
     catch (err) {
-        log.debug(`import: unreadable tags_json read as no tags: ${err instanceof Error ? err.message : String(err)}`);
+        log.debug(`import: unreadable tags_json read as no tags: ${errorMessage(err)}`);
         return [];
     }
 }

package/dist/index.d.ts

@@ -1,8 +1,8 @@
 /**
  * Hippo public API  - re-exports for programmatic use.
  */
-import { type CreateMemoryOptions, type MemoryEntry } from './memory.js';
-export { MemoryEntry, Layer, EmotionalValence, ConfidenceLevel, DecayOptions, calculateStrength, resolveConfidence, confidenceFacets, type ConfidenceFacets, applyOutcome, generateId, computeSchemaFit } from './memory.js';
+import { type CreateMemoryOptions, type MemoryEntry } from './core/memory.js';
+export { MemoryEntry, Layer, EmotionalValence, ConfidenceLevel, DecayOptions, calculateStrength, resolveConfidence, confidenceFacets, type ConfidenceFacets, applyOutcome, generateId, computeSchemaFit } from './core/memory.js';
 /** Published signature, so `baseHalfLifeDays` stays optional here; hippo's own writers use the strict one in memory.ts. */
 export declare function createMemory(content: string, options?: Partial<CreateMemoryOptions>): MemoryEntry;
 export { search } from './search/bm25-search.js';
@@ -10,12 +10,12 @@ export { hybridSearch } from './search/hybrid.js';
 export { physicsSearch } from './search/physics-search.js';
 export { explainMatch, MatchExplanation } from './search/explain.js';
 export { detectTemporalDirection, temporalBoost, computeTemporalRange } from './search/temporal.js';
-export { SearchResult } from './search/types.js';
-export { estimateTokens } from './token-ledger.js';
-export { tokenize, textOverlap } from './tokenize.js';
-export { markRetrieved } from './memory.js';
-export { multihopSearch } from './multihop.js';
-export { graphExpandRecall, MAX_HOPS, DEFAULT_MAX_NEIGHBORS, type GraphExpandOpts } from './graph-recall.js';
+export { SearchResult } from './core/search-types.js';
+export { estimateTokens } from './util/token-text.js';
+export { tokenize, textOverlap } from './util/tokenize.js';
+export { markRetrieved } from './core/memory.js';
+export { multihopSearch } from './search/multihop.js';
+export { graphExpandRecall, MAX_HOPS, DEFAULT_MAX_NEIGHBORS, type GraphExpandOpts } from './graph/recall.js';
 export { initStore } from './store/open.js';
 export { writeEntry } from './store/entry-writes.js';
 export { loadAllEntries, readEntry } from './store/entry-reads.js';
@@ -25,25 +25,29 @@ export { loadIndex, rebuildIndex, loadSessionDecayContext, SessionDecayContext }
 export { saveActiveTaskSnapshot, loadActiveTaskSnapshot, loadFreshActiveTaskSnapshot, SNAPSHOT_AMBIENT_MAX_AGE_MS, closeTaskSnapshotsForSession, clearActiveTaskSnapshot, appendSessionEvent, listSessionEvents, type ContinuityKey, } from './store/sessions.js';
 export { listMemoryConflicts, replaceDetectedConflicts, resolveConflict } from './store/conflicts.js';
 export { saveSessionHandoff, loadLatestHandoff, loadHandoffById, stampHandoffOutcome, writeSessionEndHandoff, } from './store/handoffs.js';
-export { createCard, loadCard, listCards, loadCardDeps, loadCardRuns, loadCardComments, claimCard, heartbeatCard, blockCard, reviewCard, completeCard, reclaimExpiredCards, addCardComment, loadLatestHandoffForCard, } from './store-cards.js';
-export { SessionHandoff, HandoffOutcome, HandoffEvidence, isHandoffOutcome } from './handoff.js';
-export { Card, CardStatus, CardRun, CardComment, CardTransitions, isCardStatus, CARD_TRANSITIONS, CARD_LEASE_MS } from './card.js';
+export { createCard, loadCard, listCards, loadCardDeps, loadCardRuns, loadCardComments, claimCard, heartbeatCard, blockCard, reviewCard, completeCard, reclaimExpiredCards, addCardComment, loadLatestHandoffForCard, } from './store/cards.js';
+export { SessionHandoff, HandoffOutcome, HandoffEvidence, isHandoffOutcome } from './core/handoff.js';
+export { Card, CardStatus, CardRun, CardComment, CardTransitions, isCardStatus, CARD_TRANSITIONS, CARD_LEASE_MS } from './core/card.js';
 export { consolidate } from './consolidate/sleep.js';
 export { ConsolidationResult } from './consolidate/run.js';
 export { sleep, type SleepOpts, type SleepResult } from './api/sleep.js';
-export { strengthBucket } from './dedupe.js';
-export { isEmbeddingAvailable, getEmbedding } from './local-embedding.js';
-export { cosineSimilarity, loadEmbeddingIndex, saveEmbeddingIndex, embedMemory, embedAll, } from './embeddings.js';
-export { captureError, extractLessons, partitionLessons, deduplicateLesson, runWatched, fetchGitLog, } from './autolearn.js';
-export { getGlobalRoot, initGlobal, promoteToGlobal, searchBoth, searchBothHybrid, syncGlobalToLocal, HybridSearchOptions, transferScore, shareMemory, listPeers, autoShare, } from './shared.js';
-export { wmPush, wmRead, wmClear, wmFlush, WorkingMemoryItem, WM_MAX_ENTRIES, } from './working-memory.js';
+export { strengthBucket } from './consolidate/dedupe.js';
+export { isEmbeddingAvailable, getEmbedding } from './store/embeddings/local.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 } 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';
 export { importVault } from './importers/vault.js';
 export { importEntries, ImportResult, ImportOptions } from './importers/core.js';
-export { runFeatureEval, formatResult, resultToBaseline, detectRegressions, buildSyntheticCorpus, } from './eval-suite.js';
-export { computeSalience, SalienceDecision, SalienceResult, SalienceOptions, } from './salience.js';
-export { computeAmbientState, renderAmbientSummary, formatAmbientVector, AmbientState, } from './ambient.js';
-export { appendAuditEvent, queryAuditEvents, listAuditEventsAfter, AUDIT_OPS, type AuditEvent, type AuditOp, type QueryAuditOpts, type ListAuditAfterOpts, } from './audit.js';
-export { openHippoDb, openHippoDbReadOnly, closeHippoDb, type DatabaseSyncLike } from './db.js';
+export { runFeatureEval, formatResult, resultToBaseline, detectRegressions, buildSyntheticCorpus, } from './eval/eval-suite.js';
+export { computeSalience, SalienceDecision, SalienceResult, SalienceOptions, } from './core/salience.js';
+export { computeAmbientState, renderAmbientSummary, formatAmbientVector, AmbientState, } from './core/ambient.js';
+export { appendAuditEvent, queryAuditEvents, listAuditEventsAfter, AUDIT_OPS, type AuditEvent, type AuditOp, type QueryAuditOpts, type ListAuditAfterOpts, } from './store/audit.js';
+export { openHippoDb, openHippoDbReadOnly, closeHippoDb, type DatabaseSyncLike } from './db/index.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -1,8 +1,8 @@
 /**
  * Hippo public API  - re-exports for programmatic use.
  */
-import { createMemory as createStoreMemory, DEFAULT_HALF_LIFE_DAYS } from './memory.js';
-export { Layer, calculateStrength, resolveConfidence, confidenceFacets, applyOutcome, generateId, computeSchemaFit } from './memory.js';
+import { createMemory as createStoreMemory, DEFAULT_HALF_LIFE_DAYS } from './core/memory.js';
+export { Layer, calculateStrength, resolveConfidence, confidenceFacets, applyOutcome, generateId, computeSchemaFit } from './core/memory.js';
 /** Published signature, so `baseHalfLifeDays` stays optional here; hippo's own writers use the strict one in memory.ts. */
 export function createMemory(content, options = {}) {
     return createStoreMemory(content, { ...options, baseHalfLifeDays: options.baseHalfLifeDays ?? DEFAULT_HALF_LIFE_DAYS });
@@ -12,11 +12,11 @@ export { hybridSearch } from './search/hybrid.js';
 export { physicsSearch } from './search/physics-search.js';
 export { explainMatch } from './search/explain.js';
 export { detectTemporalDirection, temporalBoost, computeTemporalRange } from './search/temporal.js';
-export { estimateTokens } from './token-ledger.js';
-export { tokenize, textOverlap } from './tokenize.js';
-export { markRetrieved } from './memory.js';
-export { multihopSearch } from './multihop.js';
-export { graphExpandRecall, MAX_HOPS, DEFAULT_MAX_NEIGHBORS } from './graph-recall.js';
+export { estimateTokens } from './util/token-text.js';
+export { tokenize, textOverlap } from './util/tokenize.js';
+export { markRetrieved } from './core/memory.js';
+export { multihopSearch } from './search/multihop.js';
+export { graphExpandRecall, MAX_HOPS, DEFAULT_MAX_NEIGHBORS } from './graph/recall.js';
 export { initStore } from './store/open.js';
 export { writeEntry } from './store/entry-writes.js';
 export { loadAllEntries, readEntry } from './store/entry-reads.js';
@@ -26,35 +26,39 @@ export { loadIndex, rebuildIndex, loadSessionDecayContext } from './store/index-
 export { saveActiveTaskSnapshot, loadActiveTaskSnapshot, loadFreshActiveTaskSnapshot, SNAPSHOT_AMBIENT_MAX_AGE_MS, closeTaskSnapshotsForSession, clearActiveTaskSnapshot, appendSessionEvent, listSessionEvents, } from './store/sessions.js';
 export { listMemoryConflicts, replaceDetectedConflicts, resolveConflict } from './store/conflicts.js';
 export { saveSessionHandoff, loadLatestHandoff, loadHandoffById, stampHandoffOutcome, writeSessionEndHandoff, } from './store/handoffs.js';
-export { createCard, loadCard, listCards, loadCardDeps, loadCardRuns, loadCardComments, claimCard, heartbeatCard, blockCard, reviewCard, completeCard, reclaimExpiredCards, addCardComment, loadLatestHandoffForCard, } from './store-cards.js';
+export { createCard, loadCard, listCards, loadCardDeps, loadCardRuns, loadCardComments, claimCard, heartbeatCard, blockCard, reviewCard, completeCard, reclaimExpiredCards, addCardComment, loadLatestHandoffForCard, } from './store/cards.js';
 // Feature 5: Session handoff
-export { isHandoffOutcome } from './handoff.js';
+export { isHandoffOutcome } from './core/handoff.js';
 // W2a: work-queue cards
-export { isCardStatus, CARD_TRANSITIONS, CARD_LEASE_MS } from './card.js';
+export { isCardStatus, CARD_TRANSITIONS, CARD_LEASE_MS } from './core/card.js';
 export { consolidate } from './consolidate/sleep.js';
 export { sleep } from './api/sleep.js';
 // Announced public in CHANGELOG 1.26.3 but never re-exported; the rest of dedupe.js stays internal.
-export { strengthBucket } from './dedupe.js';
+export { strengthBucket } from './consolidate/dedupe.js';
 // Feature 1: Embedding search
-export { isEmbeddingAvailable, getEmbedding } from './local-embedding.js';
-export { cosineSimilarity, loadEmbeddingIndex, saveEmbeddingIndex, embedMemory, embedAll, } from './embeddings.js';
+export { isEmbeddingAvailable, getEmbedding } from './store/embeddings/local.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 './autolearn.js';
+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 './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 './working-memory.js';
+export { wmPush, wmRead, wmClear, wmFlush, WM_MAX_ENTRIES, } from './store/working-memory.js';
 // Feature 4: Memory importers
 export { importChatGPT, importClaude, importCursor, importGenericFile, } from './importers/sources.js';
 export { importMarkdown } from './importers/markdown.js';
 export { importVault } from './importers/vault.js';
 export { importEntries } from './importers/core.js';
 // Feature eval suite
-export { runFeatureEval, formatResult, resultToBaseline, detectRegressions, buildSyntheticCorpus, } from './eval-suite.js';
+export { runFeatureEval, formatResult, resultToBaseline, detectRegressions, buildSyntheticCorpus, } from './eval/eval-suite.js';
 // Pineal gland: salience gate
-export { computeSalience, } from './salience.js';
+export { computeSalience, } from './core/salience.js';
 // Pineal gland: ambient state vector
-export { computeAmbientState, renderAmbientSummary, formatAmbientVector, } from './ambient.js';
-export { appendAuditEvent, queryAuditEvents, listAuditEventsAfter, AUDIT_OPS, } from './audit.js';
-export { openHippoDb, openHippoDbReadOnly, closeHippoDb } from './db.js';
+export { computeAmbientState, renderAmbientSummary, formatAmbientVector, } from './core/ambient.js';
+export { appendAuditEvent, queryAuditEvents, listAuditEventsAfter, AUDIT_OPS, } from './store/audit.js';
+export { openHippoDb, openHippoDbReadOnly, closeHippoDb } from './db/index.js';
 //# sourceMappingURL=index.js.map

package/dist/learn/autolearn.d.ts

@@ -0,0 +1,29 @@
+/** 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>"; `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. */
+export declare function extractLessons(gitLog: string, customPatterns?: string[]): string[];
+/** 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: 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 }. */
+export declare function runWatched(command: string): Promise<{
+    exitCode: number;
+    stderr: string;
+}>;
+/** 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. */
+export declare function fetchGitLog(cwd: string, days: number): string;
+//# sourceMappingURL=autolearn.d.ts.map