hippo-memory 1.60.0 → 1.62.0

package/dist/eval.js

@@ -8,9 +8,9 @@
  * weights, and future scoring tweaks can be tuned against evidence instead
  * of intuition.
  */
-import { hybridSearch } from './search.js';
+import { hybridSearch } from './search/hybrid.js';
 import { searchBothHybrid } from './shared.js';
-import { isInitialized } from './store.js';
+import { isInitialized } from './store/open.js';
 // ---------------------------------------------------------------------------
 // Metrics — pure functions. K is inclusive of position K.
 // ---------------------------------------------------------------------------

package/dist/extract.js

@@ -1,5 +1,5 @@
 import { Layer, createMemory } from './memory.js';
-import { writeEntry } from './store.js';
+import { writeEntry } from './store/entry-writes.js';
 import { loadConfig } from './config.js';
 import { RejectedValueError } from './rejection.js';
 import { redactSecretsStrict } from './secret-detect.js';

package/dist/gated-write.js

@@ -2,7 +2,9 @@
 import { isContentWorthStoring } from './audit.js';
 import { RejectedValueError } from './rejection.js';
 import { detectSecret } from './secret-detect.js';
-import { auditRejectionRefusal, stampOriginProject, writeEntryDbOnly } from './store.js';
+import { auditRejectionRefusal } from './store/audit-event.js';
+import { stampOriginProject } from './store/entry-row.js';
+import { writeEntryDbOnly } from './store/entry-writes.js';
 /** Runs on the caller's handle so it nests in the caller's transaction (writeEntry would open a second handle and wait on that lock); the caller mirrors after commit with an entry it stamped itself. The rejection audit lands inside that transaction, which is safe because a batch that rolls back stays `summarised` and replay writes the audit again. */
 export function gatedWrite(db, hippoRoot, entry, opts) {
     // Off for imported agent memories: a person wrote those notes, and a one-line preference fails the check.

package/dist/goals.d.ts

@@ -1,6 +1,6 @@
 import { type DatabaseSyncLike } from './db.js';
 import type { MemoryEntry } from './memory.js';
-import type { RerankStep } from './search.js';
+import type { RerankStep } from './search/types.js';
 export type GoalStatus = 'active' | 'suspended' | 'completed';
 export type PolicyType = 'schema-fit-biased' | 'error-prioritized' | 'recency-first' | 'hybrid';
 export interface GoalRow {
@@ -78,6 +78,8 @@ export interface GetActiveGoalsOpts {
     tenantId: string;
 }
 export declare function getActiveGoals(hippoRoot: string, opts: GetActiveGoalsOpts): Goal[];
+/** Every goal of a (tenant, session), whatever its status, oldest first. */
+export declare function getSessionGoals(hippoRoot: string, opts: GetActiveGoalsOpts): Goal[];
 export declare function getActiveGoalsWithDb(db: DatabaseSyncLike, opts: GetActiveGoalsOpts): Goal[];
 /** One `goal_recall_log` row: a boosted local memory recalled while its goal was active. */
 export interface GoalRecallLogRow {

package/dist/goals.js

@@ -129,6 +129,24 @@ export function getActiveGoals(hippoRoot, opts) {
         closeHippoDb(db);
     }
 }
+/** Every goal of a (tenant, session), whatever its status, oldest first. */
+export function getSessionGoals(hippoRoot, opts) {
+    const db = openHippoDb(hippoRoot);
+    try {
+        // SAFETY: rows come from the SELECT below, which projects exactly GoalRow's columns.
+        const rows = db.prepare(`
+      SELECT id, session_id, tenant_id, goal_name, level, parent_goal_id, status,
+             success_condition, retrieval_policy_id, created_at, completed_at, outcome_score
+      FROM goal_stack
+      WHERE tenant_id = ? AND session_id = ?
+      ORDER BY created_at ASC
+    `).all(opts.tenantId, opts.sessionId);
+        return rows.map(rowToGoal);
+    }
+    finally {
+        closeHippoDb(db);
+    }
+}
 export function getActiveGoalsWithDb(db, opts) {
     // SAFETY: rows come from the SELECT above, which projects exactly
     // GoalRow's columns (in the same order goal_stack defines them).
@@ -141,6 +159,101 @@ export function getActiveGoalsWithDb(db, opts) {
   `).all(opts.tenantId, opts.sessionId);
     return rows.map(rowToGoal);
 }
+// Load retrieval_policy rows for active goals so per-policy multipliers
+// can compose onto the base goal-tag boost. Composed result is hard-capped
+// at MAX_FINAL_MULTIPLIER (3.0x) BEFORE applying to score -- even an
+// `errorPriority: 9.0` policy cannot exceed 3.0x.
+function loadGoalPolicies(db, active) {
+    const policiesByGoalId = new Map();
+    for (const g of active) {
+        if (!g.retrievalPolicyId)
+            continue;
+        // SAFETY: the row comes from the SELECT above, which projects exactly
+        // these seven retrieval_policy columns.
+        const row = db.prepare(`
+      SELECT id, goal_id, policy_type, weight_schema_fit, weight_recency, weight_outcome, error_priority
+      FROM retrieval_policy WHERE id = ?
+    `).get(g.retrievalPolicyId);
+        if (row) {
+            policiesByGoalId.set(g.id, {
+                id: row.id,
+                goalId: row.goal_id,
+                policyType: row.policy_type,
+                weightSchemaFit: row.weight_schema_fit,
+                weightRecency: row.weight_recency,
+                weightOutcome: row.weight_outcome,
+                errorPriority: row.error_priority,
+            });
+        }
+    }
+    return policiesByGoalId;
+}
+/** The capped boost for one row whose tags match `matches` active goals. */
+function goalBoostMultiplier(entry, tags, matches, goalsByTag, policiesByGoalId) {
+    // Base 2.0x for first match, +0.5x per additional, capped at 3.0x.
+    let multiplier = Math.min(2.0 + 0.5 * (matches.length - 1), MAX_FINAL_MULTIPLIER);
+    // Compose per-policy multipliers per matched tag.
+    for (const tag of matches) {
+        const goal = goalsByTag.get(tag);
+        const policy = policiesByGoalId.get(goal.id);
+        if (!policy)
+            continue;
+        if (policy.policyType === 'error-prioritized' && tags.includes('error')) {
+            multiplier *= policy.errorPriority;
+        }
+        else if (policy.policyType === 'schema-fit-biased') {
+            // Linearly weight schema_fit in [0,1] up to (weightSchemaFit)x.
+            // Default 1.0 is a no-op.
+            multiplier *=
+                1.0 +
+                    Math.max(0, policy.weightSchemaFit - 1.0) *
+                        (entry.schema_fit ?? 0.5);
+        }
+        else if (policy.policyType === 'recency-first') {
+            multiplier *= policy.weightRecency;
+        }
+        else if (policy.policyType === 'hybrid') {
+            multiplier *= policy.weightOutcome;
+        }
+    }
+    // Hard cap AFTER all composition.
+    return Math.min(multiplier, MAX_FINAL_MULTIPLIER);
+}
+/** Log rows for the top `limit` boosted rows, one per matched goal. */
+function buildGoalRecallLog(db, boosted, matchesByEntryId, goalsByTag, opts) {
+    const { sessionId, tenantId, limit } = opts;
+    // Filter to local memories only -- global memory IDs aren't in this DB's
+    // memories table, so the FK on goal_recall_log.memory_id would fail.
+    // dlPFC depth's outcome propagation is session-scoped to local; boost on
+    // ranking still applies to global results, just no log row -> no
+    // propagation.
+    const topKIds = boosted.slice(0, limit).map((r) => r.entry.id);
+    const localIds = new Set();
+    if (topKIds.length > 0) {
+        const placeholders = topKIds.map(() => '?').join(',');
+        // SAFETY: rows come from the SELECT above, which projects exactly one
+        // column, `id`, from memories.
+        const localRows = db.prepare(`SELECT id FROM memories WHERE id IN (${placeholders})`).all(...topKIds);
+        for (const row of localRows)
+            localIds.add(row.id);
+    }
+    const recalledAt = new Date().toISOString();
+    const log = [];
+    for (const r of boosted.slice(0, limit)) {
+        if (!localIds.has(r.entry.id))
+            continue; // global -> skip log insert
+        const matches = matchesByEntryId.get(r.entry.id);
+        if (!matches || matches.length === 0)
+            continue;
+        for (const tag of matches) {
+            const goal = goalsByTag.get(tag);
+            if (!goal)
+                continue;
+            log.push({ goalId: goal.id, memoryId: r.entry.id, tenantId, sessionId, recalledAt, score: r.score });
+        }
+    }
+    return log;
+}
 /**
  * dlPFC goal-stack boost. Applies the multi-goal boost to entry-backed scored
  * rows when (tenant, session) has active goals and returns the log rows to
@@ -161,37 +274,12 @@ export function getActiveGoalsWithDb(db, opts) {
  * @internal Recall ranking helper. Subject to change.
  */
 export function computeGoalStackBoost(db, results, opts) {
-    const { sessionId, tenantId, limit, trace } = opts;
+    const { sessionId, tenantId, trace } = opts;
     const active = getActiveGoalsWithDb(db, { sessionId, tenantId });
     if (active.length === 0)
         return { results, log: [] };
     const goalsByTag = new Map(active.map((g) => [g.goalName, g]));
-    // Load retrieval_policy rows for active goals so per-policy multipliers
-    // can compose onto the base goal-tag boost. Composed result is hard-capped
-    // at MAX_FINAL_MULTIPLIER (3.0x) BEFORE applying to score -- even an
-    // `errorPriority: 9.0` policy cannot exceed 3.0x.
-    const policiesByGoalId = new Map();
-    for (const g of active) {
-        if (!g.retrievalPolicyId)
-            continue;
-        // SAFETY: the row comes from the SELECT above, which projects exactly
-        // these seven retrieval_policy columns.
-        const row = db.prepare(`
-      SELECT id, goal_id, policy_type, weight_schema_fit, weight_recency, weight_outcome, error_priority
-      FROM retrieval_policy WHERE id = ?
-    `).get(g.retrievalPolicyId);
-        if (row) {
-            policiesByGoalId.set(g.id, {
-                id: row.id,
-                goalId: row.goal_id,
-                policyType: row.policy_type,
-                weightSchemaFit: row.weight_schema_fit,
-                weightRecency: row.weight_recency,
-                weightOutcome: row.weight_outcome,
-                errorPriority: row.error_priority,
-            });
-        }
-    }
+    const policiesByGoalId = loadGoalPolicies(db, active);
     // Goal-tag matches per boosted row, keyed by entry id. Kept as a side table
     // (rather than a spread-on `_goalMatches` marker property) so `boosted`
     // stays exactly R[] end to end, with no cast-tag-then-strip round trip.
@@ -202,34 +290,7 @@ export function computeGoalStackBoost(db, results, opts) {
         const matches = tags.filter((t) => goalsByTag.has(t));
         if (matches.length === 0)
             return r;
-        // Base 2.0x for first match, +0.5x per additional, capped at 3.0x.
-        let multiplier = Math.min(2.0 + 0.5 * (matches.length - 1), MAX_FINAL_MULTIPLIER);
-        // Compose per-policy multipliers per matched tag.
-        for (const tag of matches) {
-            const goal = goalsByTag.get(tag);
-            const policy = policiesByGoalId.get(goal.id);
-            if (!policy)
-                continue;
-            if (policy.policyType === 'error-prioritized' && tags.includes('error')) {
-                multiplier *= policy.errorPriority;
-            }
-            else if (policy.policyType === 'schema-fit-biased') {
-                // Linearly weight schema_fit in [0,1] up to (weightSchemaFit)x.
-                // Default 1.0 is a no-op.
-                multiplier *=
-                    1.0 +
-                        Math.max(0, policy.weightSchemaFit - 1.0) *
-                            (r.entry.schema_fit ?? 0.5);
-            }
-            else if (policy.policyType === 'recency-first') {
-                multiplier *= policy.weightRecency;
-            }
-            else if (policy.policyType === 'hybrid') {
-                multiplier *= policy.weightOutcome;
-            }
-        }
-        // Hard cap AFTER all composition.
-        multiplier = Math.min(multiplier, MAX_FINAL_MULTIPLIER);
+        const multiplier = goalBoostMultiplier(r.entry, tags, matches, goalsByTag, policiesByGoalId);
         // A7 recall-trace side-channel: record the goal-boost step BEFORE the
         // score is mutated, keyed by entry id. Pure read of r.score here; the
         // mutation below is byte-identical to pre-A7.
@@ -253,37 +314,7 @@ export function computeGoalStackBoost(db, results, opts) {
         // inherits its determinism via sort stability, and ties preserve the
         // prior (meaningful) rank instead of reordering by content.
         .sort((a, b) => b.score - a.score);
-    // Filter to local memories only -- global memory IDs aren't in this DB's
-    // memories table, so the FK on goal_recall_log.memory_id would fail.
-    // dlPFC depth's outcome propagation is session-scoped to local; boost on
-    // ranking still applies to global results, just no log row -> no
-    // propagation.
-    const topKIds = boosted.slice(0, limit).map((r) => r.entry.id);
-    const localIds = new Set();
-    if (topKIds.length > 0) {
-        const placeholders = topKIds.map(() => '?').join(',');
-        // SAFETY: rows come from the SELECT above, which projects exactly one
-        // column, `id`, from memories.
-        const localRows = db.prepare(`SELECT id FROM memories WHERE id IN (${placeholders})`).all(...topKIds);
-        for (const row of localRows)
-            localIds.add(row.id);
-    }
-    const recalledAt = new Date().toISOString();
-    const log = [];
-    for (const r of boosted.slice(0, limit)) {
-        if (!localIds.has(r.entry.id))
-            continue; // global -> skip log insert
-        const matches = matchesByEntryId.get(r.entry.id);
-        if (!matches || matches.length === 0)
-            continue;
-        for (const tag of matches) {
-            const goal = goalsByTag.get(tag);
-            if (!goal)
-                continue;
-            log.push({ goalId: goal.id, memoryId: r.entry.id, tenantId, sessionId, recalledAt, score: r.score });
-        }
-    }
-    return { results: boosted, log };
+    return { results: boosted, log: buildGoalRecallLog(db, boosted, matchesByEntryId, goalsByTag, opts) };
 }
 /**
  * Writes goal-boost log rows. INSERT OR IGNORE because UNIQUE(memory_id, goal_id)

package/dist/graph/read.d.ts

@@ -0,0 +1,73 @@
+import { type GraphTxDb, type EntityType, type GraphQueueStatus, type Entity, type Relation, type GraphQueueItem } from './types.js';
+export declare function loadEntityById(hippoRoot: string, tenantId: string, id: number): Entity | null;
+/** Entities with an exact `name` (read), bounded by `limit` in SQL with a
+ *  deterministic order. Lets the graph-view focus query find the `--entity NAME`
+ *  entity DIRECTLY (not from a globally-capped list) WITHOUT materializing every
+ *  same-name row when a name maps to many entities. */
+export declare function loadEntitiesByName(hippoRoot: string, tenantId: string, name: string, opts?: {
+    limit?: number;
+}, txDb?: GraphTxDb): Entity[];
+export declare function loadEntities(hippoRoot: string, tenantId: string, opts?: {
+    entityType?: EntityType;
+    limit?: number;
+}, txDb?: GraphTxDb): Entity[];
+export declare function loadRelations(hippoRoot: string, tenantId: string, opts?: {
+    fromEntityId?: number;
+    limit?: number;
+}, txDb?: GraphTxDb): Relation[];
+/**
+ * Map consolidated source memory ids -> their graph entities. The SEED step of E3.2
+ * multi-hop recall (recall result memory ids -> entities to traverse from). Tenant-
+ * scoped, read-only; chunks the IN-list under the SQLite variable cap.
+ */
+export declare function loadEntitiesByMemoryId(hippoRoot: string, tenantId: string, memoryIds: string[]): Entity[];
+/**
+ * Load entities by their primary ids. Resolves the entity rows reached during the BFS
+ * (whose `memory_id` maps back to a recall result). Tenant-scoped, read-only.
+ */
+export declare function loadEntitiesByIds(hippoRoot: string, tenantId: string, ids: number[], txDb?: GraphTxDb): Entity[];
+/**
+ * All relations touching ANY of `entityIds` in EITHER direction (from OR to) — the
+ * per-hop neighbour query for E3.2 multi-hop traversal. ONE query for the whole frontier
+ * (not one per node): this is the bidirectional read `loadRelations` (from-only) lacks,
+ * and avoids an N+1 across BFS frontier nodes. `limit` caps rows for the frontier and
+ * must be a non-negative integer (the raw `LIMIT ?` rejects a fractional value).
+ */
+export declare function loadNeighborRelations(hippoRoot: string, tenantId: string, entityIds: number[], opts?: {
+    limit?: number;
+}, txDb?: GraphTxDb): Relation[];
+/**
+ * Relations with BOTH endpoints in `entityIds` (edges AMONG the set, not merely
+ * touching it). Read. Used by the graph-view focus subgraph so the displayed
+ * edges are exactly the intra-union edges: the `LIMIT` only caps genuinely-many
+ * intra-union edges — no out-of-union row can evict a valid in-set edge. The
+ * caller bounds `entityIds` (<= the view limit), so a single query is safe.
+ */
+export declare function loadRelationsAmong(hippoRoot: string, tenantId: string, entityIds: number[], opts?: {
+    limit?: number;
+}, txDb?: GraphTxDb): Relation[];
+/**
+ * Run `fn` inside ONE read transaction (a single WAL snapshot) so every graph read
+ * it performs — pass the supplied `txDb` to the `load*` functions — sees a consistent
+ * view, even if a `graph extract` / sleep-drain rebuild commits concurrently between
+ * reads (the rebuild clears + reinserts entities, so separate reads could otherwise
+ * mix old entity ids with new relation ids). Reads only; the connection is opened
+ * once and closed after.
+ */
+export declare function withGraphReadSnapshot<T>(hippoRoot: string, fn: (txDb: GraphTxDb) => T): T;
+export declare function loadExtractionQueue(hippoRoot: string, tenantId: string, opts?: {
+    status?: GraphQueueStatus;
+    limit?: number;
+}): GraphQueueItem[];
+/**
+ * The dirty tenants awaiting graph re-extraction, each with the MAX pending
+ * queue id at read time (a watermark). The sleep drain rebuilds each tenant's
+ * graph, then marks only items at or below the watermark processed, so items
+ * enqueued DURING the rebuild stay pending for the next sleep (no lost-update
+ * race). Host-wide read (the queue is per-tenant but sleep is cross-tenant).
+ */
+export declare function loadPendingExtractionTenants(hippoRoot: string): {
+    tenantId: string;
+    maxPendingId: number;
+}[];
+//# sourceMappingURL=read.d.ts.map