hippo-memory 0.26.0 → 0.28.0

package/dist/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,OAAO,EAAE,KAAK,aAAa,EAA8C,MAAM,qBAAqB,CAAC;AAErG,MAAM,MAAM,UAAU,GAAG,OAAO,GAAG,SAAS,GAAG,UAAU,CAAC;AAE1D,MAAM,WAAW,WAAW;IAC1B,mBAAmB,EAAE,MAAM,CAAC;IAC5B,aAAa,EAAE,MAAM,CAAC;IACtB,oBAAoB,EAAE,MAAM,CAAC;IAC7B,UAAU,EAAE,UAAU,CAAC;IACvB,gBAAgB,EAAE,OAAO,CAAC;IAC1B,gBAAgB,EAAE,OAAO,CAAC;IAC1B,SAAS,EAAE;QACT,OAAO,EAAE,OAAO,CAAC;QACjB,SAAS,EAAE,MAAM,CAAC;KACnB,CAAC;IACF,UAAU,EAAE;QACV,OAAO,EAAE,OAAO,GAAG,MAAM,CAAC;QAC1B,KAAK,EAAE,MAAM,CAAC;QACd,YAAY,EAAE,MAAM,CAAC;KACtB,CAAC;IACF,MAAM,EAAE;QACN,OAAO,EAAE,OAAO,CAAC;KAClB,CAAC;IACF,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAC3B,OAAO,EAAE,aAAa,CAAC;CACxB;AA4BD,wBAAgB,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,WAAW,CA0BzD;AAED,wBAAgB,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,GAAG,IAAI,CAGvE"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,OAAO,EAAE,KAAK,aAAa,EAA8C,MAAM,qBAAqB,CAAC;AAErG,MAAM,MAAM,UAAU,GAAG,OAAO,GAAG,SAAS,GAAG,UAAU,CAAC;AAE1D,MAAM,WAAW,WAAW;IAC1B,mBAAmB,EAAE,MAAM,CAAC;IAC5B,aAAa,EAAE,MAAM,CAAC;IACtB,oBAAoB,EAAE,MAAM,CAAC;IAC7B,UAAU,EAAE,UAAU,CAAC;IACvB,gBAAgB,EAAE,OAAO,CAAC;IAC1B,gBAAgB,EAAE,OAAO,CAAC;IAC1B,SAAS,EAAE;QACT,OAAO,EAAE,OAAO,CAAC;QACjB,SAAS,EAAE,MAAM,CAAC;KACnB,CAAC;IACF,UAAU,EAAE;QACV,OAAO,EAAE,OAAO,GAAG,MAAM,CAAC;QAC1B,KAAK,EAAE,MAAM,CAAC;QACd,YAAY,EAAE,MAAM,CAAC;KACtB,CAAC;IACF,MAAM,EAAE;QACN,OAAO,EAAE,OAAO,CAAC;KAClB,CAAC;IACF,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAC3B,OAAO,EAAE,aAAa,CAAC;IACvB;kEAC8D;IAC9D,GAAG,EAAE;QACH,OAAO,EAAE,OAAO,CAAC;QACjB;iCACyB;QACzB,MAAM,EAAE,MAAM,CAAC;KAChB,CAAC;IACF,MAAM,EAAE;QACN;mFAC2E;QAC3E,SAAS,EAAE,MAAM,CAAC;KACnB,CAAC;CACH;AAmCD,wBAAgB,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,WAAW,CA4BzD;AAED,wBAAgB,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,GAAG,IAAI,CAGvE"}

package/dist/config.js

@@ -28,6 +28,13 @@ const DEFAULT_CONFIG = {
         'refactor', 'perf', 'chore', 'breaking', 'deprecate',
     ],
     physics: { ...DEFAULT_PHYSICS_CONFIG },
+    mmr: {
+        enabled: true,
+        lambda: 0.7,
+    },
+    search: {
+        localBump: 1.2,
+    },
 };
 export function loadConfig(hippoRoot) {
     const configPath = path.join(hippoRoot, 'config.json');
@@ -49,6 +56,8 @@ export function loadConfig(hippoRoot) {
             global: { ...DEFAULT_CONFIG.global, ...(raw.global ?? {}) },
             gitLearnPatterns: raw.gitLearnPatterns ?? DEFAULT_CONFIG.gitLearnPatterns,
             physics: mergePhysicsConfig(raw.physics),
+            mmr: { ...DEFAULT_CONFIG.mmr, ...(raw.mmr ?? {}) },
+            search: { ...DEFAULT_CONFIG.search, ...(raw.search ?? {}) },
         };
     }
     catch (err) {

package/dist/config.js.map

@@ -1 +1 @@
-{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"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"}

package/dist/eval.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Recall eval harness.
+ *
+ * Given a corpus of (query, expected_memory_ids) cases, run recall against
+ * the store and report ranking-quality metrics: MRR, Recall@K, NDCG@K.
+ *
+ * The goal is to make recall quality measurable so MMR lambda, embedding
+ * weights, and future scoring tweaks can be tuned against evidence instead
+ * of intuition.
+ */
+import type { MemoryEntry } from './memory.js';
+export interface EvalCase {
+    /** Free-form ID for humans to reference the case. */
+    id: string;
+    /** The query text to run through recall. */
+    query: string;
+    /** Memory IDs considered relevant. At least one required. */
+    expectedIds: string[];
+    /** Optional short description so a failure report is self-explaining. */
+    description?: string;
+}
+export interface EvalCaseResult {
+    case: EvalCase;
+    returnedIds: string[];
+    /** 1 / rank of the first expected id, else 0. */
+    mrr: number;
+    /** |expected ∩ returned[0..K]| / |expected|, 0 when expected is empty. */
+    recallAt5: number;
+    recallAt10: number;
+    /** Normalized DCG at 10 using binary relevance (expected = 1, else 0). */
+    ndcgAt10: number;
+}
+export interface EvalSummary {
+    cases: EvalCaseResult[];
+    /** Simple arithmetic means across cases. */
+    meanMrr: number;
+    meanRecallAt5: number;
+    meanRecallAt10: number;
+    meanNdcgAt10: number;
+    /** Wall-clock runtime in ms for the whole eval. */
+    durationMs: number;
+}
+export interface RunEvalOptions {
+    mmr?: boolean;
+    mmrLambda?: number;
+    embeddingWeight?: number;
+    /** Max returned results per case. Larger than K-at-10 so metrics stay honest. */
+    budget?: number;
+    hippoRoot?: string;
+    /** When set and initialized, eval runs through searchBothHybrid so global
+     *  memories are in scope. Otherwise only the `entries` list is searched. */
+    globalRoot?: string;
+    /** Multiplier for local-over-global results when globalRoot is in play. */
+    localBump?: number;
+    now?: Date;
+}
+/** Mean Reciprocal Rank for a single ranking given expected ids. */
+export declare function mrr(returned: string[], expected: string[]): number;
+/** Recall@K — fraction of expected items found in the top-K. */
+export declare function recallAtK(returned: string[], expected: string[], k: number): number;
+/**
+ * Normalized Discounted Cumulative Gain at K with binary relevance.
+ * gain_i = 1 if returned[i] ∈ expected else 0. discount = log2(i + 2).
+ */
+export declare function ndcgAtK(returned: string[], expected: string[], k: number): number;
+export declare function runEval(cases: EvalCase[], entries: MemoryEntry[], options?: RunEvalOptions): Promise<EvalSummary>;
+export interface EvalDelta {
+    mrr: number;
+    recallAt5: number;
+    recallAt10: number;
+    ndcgAt10: number;
+}
+export interface CaseDelta {
+    id: string;
+    query: string;
+    mrrBefore: number;
+    mrrAfter: number;
+    r10Before: number;
+    r10After: number;
+    ndcgBefore: number;
+    ndcgAfter: number;
+}
+export interface EvalComparison {
+    aggregate: EvalDelta;
+    improved: CaseDelta[];
+    regressed: CaseDelta[];
+    unchanged: number;
+    onlyInBaseline: string[];
+    onlyInCurrent: string[];
+}
+/**
+ * Compute pairwise deltas between a baseline and a current eval summary.
+ * Cases are matched by EvalCase.id; any mismatch is surfaced in the onlyIn
+ * arrays so the caller knows the corpora diverged.
+ */
+export declare function compareSummaries(baseline: EvalSummary, current: EvalSummary): EvalComparison;
+/**
+ * For each memory, take its first 8 content words as a trivial query and
+ * expect that memory back. Useful as a smoke test: if recall can't find a
+ * memory by its own opening words, something is broken.
+ */
+export declare function bootstrapCorpus(entries: MemoryEntry[], maxCases?: number): EvalCase[];
+//# sourceMappingURL=eval.d.ts.map

package/dist/eval.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"eval.d.ts","sourceRoot":"","sources":["../src/eval.ts"],"names":[],"mappings":"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"}

package/dist/eval.js

@@ -0,0 +1,187 @@
+/**
+ * Recall eval harness.
+ *
+ * Given a corpus of (query, expected_memory_ids) cases, run recall against
+ * the store and report ranking-quality metrics: MRR, Recall@K, NDCG@K.
+ *
+ * The goal is to make recall quality measurable so MMR lambda, embedding
+ * weights, and future scoring tweaks can be tuned against evidence instead
+ * of intuition.
+ */
+import { hybridSearch } from './search.js';
+import { searchBothHybrid } from './shared.js';
+import { isInitialized } from './store.js';
+// ---------------------------------------------------------------------------
+// Metrics — pure functions. K is inclusive of position K.
+// ---------------------------------------------------------------------------
+/** Mean Reciprocal Rank for a single ranking given expected ids. */
+export function mrr(returned, expected) {
+    if (expected.length === 0)
+        return 0;
+    const expectedSet = new Set(expected);
+    for (let i = 0; i < returned.length; i++) {
+        if (expectedSet.has(returned[i]))
+            return 1 / (i + 1);
+    }
+    return 0;
+}
+/** Recall@K — fraction of expected items found in the top-K. */
+export function recallAtK(returned, expected, k) {
+    if (expected.length === 0)
+        return 0;
+    const expectedSet = new Set(expected);
+    const topK = returned.slice(0, k);
+    let hits = 0;
+    for (const id of topK) {
+        if (expectedSet.has(id))
+            hits++;
+    }
+    return hits / expected.length;
+}
+/**
+ * Normalized Discounted Cumulative Gain at K with binary relevance.
+ * gain_i = 1 if returned[i] ∈ expected else 0. discount = log2(i + 2).
+ */
+export function ndcgAtK(returned, expected, k) {
+    if (expected.length === 0)
+        return 0;
+    const expectedSet = new Set(expected);
+    let dcg = 0;
+    for (let i = 0; i < Math.min(k, returned.length); i++) {
+        if (expectedSet.has(returned[i])) {
+            dcg += 1 / Math.log2(i + 2);
+        }
+    }
+    // Ideal DCG: all relevant items at top positions.
+    const idealHits = Math.min(k, expected.length);
+    let idcg = 0;
+    for (let i = 0; i < idealHits; i++) {
+        idcg += 1 / Math.log2(i + 2);
+    }
+    return idcg === 0 ? 0 : dcg / idcg;
+}
+// ---------------------------------------------------------------------------
+// Runner
+// ---------------------------------------------------------------------------
+export async function runEval(cases, entries, options = {}) {
+    const budget = options.budget ?? 100_000; // generous so metrics aren't truncated
+    const start = Date.now();
+    const results = [];
+    const useBothStores = Boolean(options.globalRoot && options.hippoRoot && isInitialized(options.globalRoot));
+    for (const c of cases) {
+        const ranked = useBothStores
+            ? await searchBothHybrid(c.query, options.hippoRoot, options.globalRoot, {
+                budget,
+                now: options.now,
+                embeddingWeight: options.embeddingWeight,
+                mmr: options.mmr,
+                mmrLambda: options.mmrLambda,
+                localBump: options.localBump,
+            })
+            : await hybridSearch(c.query, entries, {
+                budget,
+                now: options.now,
+                hippoRoot: options.hippoRoot,
+                embeddingWeight: options.embeddingWeight,
+                mmr: options.mmr,
+                mmrLambda: options.mmrLambda,
+            });
+        const returnedIds = ranked.map((r) => r.entry.id);
+        results.push({
+            case: c,
+            returnedIds,
+            mrr: mrr(returnedIds, c.expectedIds),
+            recallAt5: recallAtK(returnedIds, c.expectedIds, 5),
+            recallAt10: recallAtK(returnedIds, c.expectedIds, 10),
+            ndcgAt10: ndcgAtK(returnedIds, c.expectedIds, 10),
+        });
+    }
+    const n = Math.max(1, results.length);
+    const meanMrr = results.reduce((s, r) => s + r.mrr, 0) / n;
+    const meanRecallAt5 = results.reduce((s, r) => s + r.recallAt5, 0) / n;
+    const meanRecallAt10 = results.reduce((s, r) => s + r.recallAt10, 0) / n;
+    const meanNdcgAt10 = results.reduce((s, r) => s + r.ndcgAt10, 0) / n;
+    return {
+        cases: results,
+        meanMrr,
+        meanRecallAt5,
+        meanRecallAt10,
+        meanNdcgAt10,
+        durationMs: Date.now() - start,
+    };
+}
+/**
+ * Compute pairwise deltas between a baseline and a current eval summary.
+ * Cases are matched by EvalCase.id; any mismatch is surfaced in the onlyIn
+ * arrays so the caller knows the corpora diverged.
+ */
+export function compareSummaries(baseline, current) {
+    const aggregate = {
+        mrr: current.meanMrr - baseline.meanMrr,
+        recallAt5: current.meanRecallAt5 - baseline.meanRecallAt5,
+        recallAt10: current.meanRecallAt10 - baseline.meanRecallAt10,
+        ndcgAt10: current.meanNdcgAt10 - baseline.meanNdcgAt10,
+    };
+    const baseById = new Map(baseline.cases.map((c) => [c.case.id, c]));
+    const curById = new Map(current.cases.map((c) => [c.case.id, c]));
+    const improved = [];
+    const regressed = [];
+    let unchanged = 0;
+    for (const [id, cur] of curById) {
+        const base = baseById.get(id);
+        if (!base)
+            continue;
+        const delta = {
+            id,
+            query: cur.case.query,
+            mrrBefore: base.mrr,
+            mrrAfter: cur.mrr,
+            r10Before: base.recallAt10,
+            r10After: cur.recallAt10,
+            ndcgBefore: base.ndcgAt10,
+            ndcgAfter: cur.ndcgAt10,
+        };
+        const ndcgDelta = delta.ndcgAfter - delta.ndcgBefore;
+        if (ndcgDelta > 1e-6)
+            improved.push(delta);
+        else if (ndcgDelta < -1e-6)
+            regressed.push(delta);
+        else
+            unchanged++;
+    }
+    return {
+        aggregate,
+        improved: improved.sort((a, b) => (b.ndcgAfter - b.ndcgBefore) - (a.ndcgAfter - a.ndcgBefore)),
+        regressed: regressed.sort((a, b) => (a.ndcgAfter - a.ndcgBefore) - (b.ndcgAfter - b.ndcgBefore)),
+        unchanged,
+        onlyInBaseline: [...baseById.keys()].filter((id) => !curById.has(id)),
+        onlyInCurrent: [...curById.keys()].filter((id) => !baseById.has(id)),
+    };
+}
+// ---------------------------------------------------------------------------
+// Bootstrap — generate a synthetic corpus from current memories
+// ---------------------------------------------------------------------------
+/**
+ * For each memory, take its first 8 content words as a trivial query and
+ * expect that memory back. Useful as a smoke test: if recall can't find a
+ * memory by its own opening words, something is broken.
+ */
+export function bootstrapCorpus(entries, maxCases = 50) {
+    const cases = [];
+    for (const e of entries) {
+        if (cases.length >= maxCases)
+            break;
+        const words = e.content.trim().split(/\s+/).filter((w) => w.length > 2);
+        if (words.length < 3)
+            continue;
+        const query = words.slice(0, 8).join(' ');
+        cases.push({
+            id: `bootstrap_${e.id}`,
+            query,
+            expectedIds: [e.id],
+            description: `trivial self-query on memory ${e.id}`,
+        });
+    }
+    return cases;
+}
+//# sourceMappingURL=eval.js.map

package/dist/eval.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"eval.js","sourceRoot":"","sources":["../src/eval.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAuD3C,8EAA8E;AAC9E,0DAA0D;AAC1D,8EAA8E;AAE9E,oEAAoE;AACpE,MAAM,UAAU,GAAG,CAAC,QAAkB,EAAE,QAAkB;IACxD,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,CAAC,CAAC;IACpC,MAAM,WAAW,GAAG,IAAI,GAAG,CAAC,QAAQ,CAAC,CAAC;IACtC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,QAAQ,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACzC,IAAI,WAAW,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC;YAAE,OAAO,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IACvD,CAAC;IACD,OAAO,CAAC,CAAC;AACX,CAAC;AAED,gEAAgE;AAChE,MAAM,UAAU,SAAS,CAAC,QAAkB,EAAE,QAAkB,EAAE,CAAS;IACzE,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,CAAC,CAAC;IACpC,MAAM,WAAW,GAAG,IAAI,GAAG,CAAC,QAAQ,CAAC,CAAC;IACtC,MAAM,IAAI,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IAClC,IAAI,IAAI,GAAG,CAAC,CAAC;IACb,KAAK,MAAM,EAAE,IAAI,IAAI,EAAE,CAAC;QACtB,IAAI,WAAW,CAAC,GAAG,CAAC,EAAE,CAAC;YAAE,IAAI,EAAE,CAAC;IAClC,CAAC;IACD,OAAO,IAAI,GAAG,QAAQ,CAAC,MAAM,CAAC;AAChC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,OAAO,CAAC,QAAkB,EAAE,QAAkB,EAAE,CAAS;IACvE,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,CAAC,CAAC;IACpC,MAAM,WAAW,GAAG,IAAI,GAAG,CAAC,QAAQ,CAAC,CAAC;IACtC,IAAI,GAAG,GAAG,CAAC,CAAC;IACZ,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QACtD,IAAI,WAAW,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;YACjC,GAAG,IAAI,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;QAC9B,CAAC;IACH,CAAC;IACD,kDAAkD;IAClD,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IAC/C,IAAI,IAAI,GAAG,CAAC,CAAC;IACb,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,SAAS,EAAE,CAAC,EAAE,EAAE,CAAC;QACnC,IAAI,IAAI,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IAC/B,CAAC;IACD,OAAO,IAAI,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,GAAG,IAAI,CAAC;AACrC,CAAC;AAED,8EAA8E;AAC9E,SAAS;AACT,8EAA8E;AAE9E,MAAM,CAAC,KAAK,UAAU,OAAO,CAC3B,KAAiB,EACjB,OAAsB,EACtB,UAA0B,EAAE;IAE5B,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,OAAO,CAAC,CAAG,uCAAuC;IACnF,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IACzB,MAAM,OAAO,GAAqB,EAAE,CAAC;IAErC,MAAM,aAAa,GAAG,OAAO,CAC3B,OAAO,CAAC,UAAU,IAAI,OAAO,CAAC,SAAS,IAAI,aAAa,CAAC,OAAO,CAAC,UAAU,CAAC,CAC7E,CAAC;IAEF,KAAK,MAAM,CAAC,IAAI,KAAK,EAAE,CAAC;QACtB,MAAM,MAAM,GAAG,aAAa;YAC1B,CAAC,CAAC,MAAM,gBAAgB,CAAC,CAAC,CAAC,KAAK,EAAE,OAAO,CAAC,SAAU,EAAE,OAAO,CAAC,UAAW,EAAE;gBACvE,MAAM;gBACN,GAAG,EAAE,OAAO,CAAC,GAAG;gBAChB,eAAe,EAAE,OAAO,CAAC,eAAe;gBACxC,GAAG,EAAE,OAAO,CAAC,GAAG;gBAChB,SAAS,EAAE,OAAO,CAAC,SAAS;gBAC5B,SAAS,EAAE,OAAO,CAAC,SAAS;aAC7B,CAAC;YACJ,CAAC,CAAC,MAAM,YAAY,CAAC,CAAC,CAAC,KAAK,EAAE,OAAO,EAAE;gBACnC,MAAM;gBACN,GAAG,EAAE,OAAO,CAAC,GAAG;gBAChB,SAAS,EAAE,OAAO,CAAC,SAAS;gBAC5B,eAAe,EAAE,OAAO,CAAC,eAAe;gBACxC,GAAG,EAAE,OAAO,CAAC,GAAG;gBAChB,SAAS,EAAE,OAAO,CAAC,SAAS;aAC7B,CAAC,CAAC;QACP,MAAM,WAAW,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;QAClD,OAAO,CAAC,IAAI,CAAC;YACX,IAAI,EAAE,CAAC;YACP,WAAW;YACX,GAAG,EAAE,GAAG,CAAC,WAAW,EAAE,CAAC,CAAC,WAAW,CAAC;YACpC,SAAS,EAAE,SAAS,CAAC,WAAW,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC;YACnD,UAAU,EAAE,SAAS,CAAC,WAAW,EAAE,CAAC,CAAC,WAAW,EAAE,EAAE,CAAC;YACrD,QAAQ,EAAE,OAAO,CAAC,WAAW,EAAE,CAAC,CAAC,WAAW,EAAE,EAAE,CAAC;SAClD,CAAC,CAAC;IACL,CAAC;IAED,MAAM,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;IACtC,MAAM,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC;IAC3D,MAAM,aAAa,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,SAAS,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC;IACvE,MAAM,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,UAAU,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC;IACzE,MAAM,YAAY,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC;IAErE,OAAO;QACL,KAAK,EAAE,OAAO;QACd,OAAO;QACP,aAAa;QACb,cAAc;QACd,YAAY;QACZ,UAAU,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK;KAC/B,CAAC;AACJ,CAAC;AAiCD;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAAC,QAAqB,EAAE,OAAoB;IAC1E,MAAM,SAAS,GAAc;QAC3B,GAAG,EAAE,OAAO,CAAC,OAAO,GAAG,QAAQ,CAAC,OAAO;QACvC,SAAS,EAAE,OAAO,CAAC,aAAa,GAAG,QAAQ,CAAC,aAAa;QACzD,UAAU,EAAE,OAAO,CAAC,cAAc,GAAG,QAAQ,CAAC,cAAc;QAC5D,QAAQ,EAAE,OAAO,CAAC,YAAY,GAAG,QAAQ,CAAC,YAAY;KACvD,CAAC;IAEF,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAC,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;IACpE,MAAM,OAAO,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;IAElE,MAAM,QAAQ,GAAgB,EAAE,CAAC;IACjC,MAAM,SAAS,GAAgB,EAAE,CAAC;IAClC,IAAI,SAAS,GAAG,CAAC,CAAC;IAElB,KAAK,MAAM,CAAC,EAAE,EAAE,GAAG,CAAC,IAAI,OAAO,EAAE,CAAC;QAChC,MAAM,IAAI,GAAG,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAC9B,IAAI,CAAC,IAAI;YAAE,SAAS;QACpB,MAAM,KAAK,GAAc;YACvB,EAAE;YACF,KAAK,EAAE,GAAG,CAAC,IAAI,CAAC,KAAK;YACrB,SAAS,EAAE,IAAI,CAAC,GAAG;YACnB,QAAQ,EAAE,GAAG,CAAC,GAAG;YACjB,SAAS,EAAE,IAAI,CAAC,UAAU;YAC1B,QAAQ,EAAE,GAAG,CAAC,UAAU;YACxB,UAAU,EAAE,IAAI,CAAC,QAAQ;YACzB,SAAS,EAAE,GAAG,CAAC,QAAQ;SACxB,CAAC;QACF,MAAM,SAAS,GAAG,KAAK,CAAC,SAAS,GAAG,KAAK,CAAC,UAAU,CAAC;QACrD,IAAI,SAAS,GAAG,IAAI;YAAE,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;aACtC,IAAI,SAAS,GAAG,CAAC,IAAI;YAAE,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;;YAC7C,SAAS,EAAE,CAAC;IACnB,CAAC;IAED,OAAO;QACL,SAAS;QACT,QAAQ,EAAE,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,SAAS,GAAG,CAAC,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,SAAS,GAAG,CAAC,CAAC,UAAU,CAAC,CAAC;QAC9F,SAAS,EAAE,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,SAAS,GAAG,CAAC,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,SAAS,GAAG,CAAC,CAAC,UAAU,CAAC,CAAC;QAChG,SAAS;QACT,cAAc,EAAE,CAAC,GAAG,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACrE,aAAa,EAAE,CAAC,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;KACrE,CAAC;AACJ,CAAC;AAED,8EAA8E;AAC9E,gEAAgE;AAChE,8EAA8E;AAE9E;;;;GAIG;AACH,MAAM,UAAU,eAAe,CAAC,OAAsB,EAAE,QAAQ,GAAG,EAAE;IACnE,MAAM,KAAK,GAAe,EAAE,CAAC;IAC7B,KAAK,MAAM,CAAC,IAAI,OAAO,EAAE,CAAC;QACxB,IAAI,KAAK,CAAC,MAAM,IAAI,QAAQ;YAAE,MAAM;QACpC,MAAM,KAAK,GAAG,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;QACxE,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC;YAAE,SAAS;QAC/B,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAC1C,KAAK,CAAC,IAAI,CAAC;YACT,EAAE,EAAE,aAAa,CAAC,CAAC,EAAE,EAAE;YACvB,KAAK;YACL,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACnB,WAAW,EAAE,gCAAgC,CAAC,CAAC,EAAE,EAAE;SACpD,CAAC,CAAC;IACL,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/refine-llm.d.ts

@@ -0,0 +1,53 @@
+/**
+ * LLM-powered refinement of consolidated semantic memories.
+ *
+ * The rule-based `mergeContents` in consolidate.ts produces functional but
+ * ugly semantic memories — typically "[Consolidated from N related memories]"
+ * prepended to the longest source, or a bulleted list. `hippo refine` takes
+ * those and asks Claude to synthesize a clean, generalized principle.
+ *
+ * Design choices:
+ * - Separate command (not baked into `hippo sleep`) so API-key users opt in.
+ * - Idempotent via the `llm-refined` tag — re-running skips already-refined.
+ * - Uses fetch directly so no SDK dependency.
+ * - On failure (API error, bad response), the original memory is untouched.
+ */
+import { MemoryEntry } from './memory.js';
+export interface RefineOptions {
+    apiKey: string;
+    model?: string;
+    limit?: number;
+    dryRun?: boolean;
+    /** Ignore the llm-refined tag and re-refine everything eligible. */
+    all?: boolean;
+    /** Injected for testing — defaults to the real fetch. */
+    fetcher?: typeof fetch;
+}
+export interface RefineResult {
+    scanned: number;
+    refined: number;
+    skipped: number;
+    failed: number;
+    details: Array<{
+        id: string;
+        status: 'refined' | 'skipped' | 'failed';
+        reason?: string;
+    }>;
+}
+/**
+ * Ask Claude to synthesize a clean semantic memory from the merged content
+ * plus the original source memories. Returns the refined content string or
+ * `null` when the API call failed.
+ */
+export declare function refineSemanticMemory(merged: string, sources: MemoryEntry[], opts: {
+    apiKey: string;
+    model?: string;
+    fetcher?: typeof fetch;
+}): Promise<string | null>;
+/**
+ * Scan the store for consolidated semantic memories, refine each with the
+ * LLM, and write the refined content back. Tags with `llm-refined` so
+ * repeated runs are idempotent (unless `all` is set).
+ */
+export declare function refineStore(hippoRoot: string, opts: RefineOptions): Promise<RefineResult>;
+//# sourceMappingURL=refine-llm.d.ts.map

package/dist/refine-llm.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"refine-llm.d.ts","sourceRoot":"","sources":["../src/refine-llm.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,WAAW,EAAS,MAAM,aAAa,CAAC;AASjD,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,oEAAoE;IACpE,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,yDAAyD;IACzD,OAAO,CAAC,EAAE,OAAO,KAAK,CAAC;CACxB;AAED,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,SAAS,GAAG,SAAS,GAAG,QAAQ,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAC3F;AAED;;;;GAIG;AACH,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,WAAW,EAAE,EACtB,IAAI,EAAE;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,OAAO,KAAK,CAAA;CAAE,GAC/D,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAqDxB;AAOD;;;;GAIG;AACH,wBAAsB,WAAW,CAC/B,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,aAAa,GAClB,OAAO,CAAC,YAAY,CAAC,CA+DvB"}

package/dist/refine-llm.js

@@ -0,0 +1,147 @@
+/**
+ * LLM-powered refinement of consolidated semantic memories.
+ *
+ * The rule-based `mergeContents` in consolidate.ts produces functional but
+ * ugly semantic memories — typically "[Consolidated from N related memories]"
+ * prepended to the longest source, or a bulleted list. `hippo refine` takes
+ * those and asks Claude to synthesize a clean, generalized principle.
+ *
+ * Design choices:
+ * - Separate command (not baked into `hippo sleep`) so API-key users opt in.
+ * - Idempotent via the `llm-refined` tag — re-running skips already-refined.
+ * - Uses fetch directly so no SDK dependency.
+ * - On failure (API error, bad response), the original memory is untouched.
+ */
+import { Layer } from './memory.js';
+import { loadAllEntries, readEntry, writeEntry } from './store.js';
+const REFINED_TAG = 'llm-refined';
+const CONSOLIDATED_MARKERS = [
+    '[Consolidated from',
+    '[Consolidated pattern from',
+];
+/**
+ * Ask Claude to synthesize a clean semantic memory from the merged content
+ * plus the original source memories. Returns the refined content string or
+ * `null` when the API call failed.
+ */
+export async function refineSemanticMemory(merged, sources, opts) {
+    const model = opts.model ?? 'claude-sonnet-4-6';
+    const fetchFn = opts.fetcher ?? fetch;
+    const sourceBlock = sources
+        .slice(0, 8)
+        .map((s, i) => `[source ${i + 1}] ${s.content.slice(0, 400)}`)
+        .join('\n\n');
+    const prompt = `You are refining a semantic memory in an agent's memory store. The rule-based consolidator merged several related episodic memories into one, but the output is clumsy. Produce a single coherent semantic memory that captures the underlying principle.
+
+Rules:
+- Output ONLY the refined content — no preamble, no quote marks, no "Here is...".
+- Keep it concise: one paragraph, no headers, no bullet lists unless the sources are inherently a list.
+- Preserve specific facts (names, numbers, paths, IDs) from the sources.
+- Generalize: state the pattern, not each instance.
+- Do NOT include the "[Consolidated from N ...]" marker.
+
+Current merged content:
+${merged}
+
+Source memories (up to 8 shown):
+${sourceBlock}`;
+    let res;
+    try {
+        res = await fetchFn('https://api.anthropic.com/v1/messages', {
+            method: 'POST',
+            headers: {
+                'content-type': 'application/json',
+                'x-api-key': opts.apiKey,
+                'anthropic-version': '2023-06-01',
+            },
+            body: JSON.stringify({
+                model,
+                max_tokens: 800,
+                messages: [{ role: 'user', content: prompt }],
+            }),
+        });
+    }
+    catch {
+        return null;
+    }
+    if (!res.ok)
+        return null;
+    try {
+        const data = await res.json();
+        const text = data.content?.[0]?.text?.trim() ?? '';
+        if (text.length < 10)
+            return null;
+        return text;
+    }
+    catch {
+        return null;
+    }
+}
+function isConsolidated(entry) {
+    if (entry.layer !== Layer.Semantic)
+        return false;
+    return CONSOLIDATED_MARKERS.some((m) => entry.content.startsWith(m));
+}
+/**
+ * Scan the store for consolidated semantic memories, refine each with the
+ * LLM, and write the refined content back. Tags with `llm-refined` so
+ * repeated runs are idempotent (unless `all` is set).
+ */
+export async function refineStore(hippoRoot, opts) {
+    const result = {
+        scanned: 0,
+        refined: 0,
+        skipped: 0,
+        failed: 0,
+        details: [],
+    };
+    const entries = loadAllEntries(hippoRoot);
+    let processed = 0;
+    for (const entry of entries) {
+        if (!isConsolidated(entry))
+            continue;
+        result.scanned++;
+        if (!opts.all && entry.tags.includes(REFINED_TAG)) {
+            result.skipped++;
+            result.details.push({ id: entry.id, status: 'skipped', reason: 'already refined' });
+            continue;
+        }
+        if (opts.limit !== undefined && processed >= opts.limit)
+            break;
+        processed++;
+        // Best-effort: walk parents_json (schema v9) to fetch originals. When
+        // parents aren't recorded we still refine using just the merged content.
+        const sources = [];
+        const parentIds = Array.isArray(entry.parents) ? entry.parents : [];
+        for (const pid of parentIds) {
+            const p = readEntry(hippoRoot, pid);
+            if (p)
+                sources.push(p);
+        }
+        const refined = await refineSemanticMemory(entry.content, sources, {
+            apiKey: opts.apiKey,
+            model: opts.model,
+            fetcher: opts.fetcher,
+        });
+        if (refined === null) {
+            result.failed++;
+            result.details.push({ id: entry.id, status: 'failed', reason: 'api error or empty response' });
+            continue;
+        }
+        if (opts.dryRun) {
+            result.refined++;
+            result.details.push({ id: entry.id, status: 'refined', reason: 'dry-run (no write)' });
+            continue;
+        }
+        const updated = {
+            ...entry,
+            content: refined,
+            tags: entry.tags.includes(REFINED_TAG) ? entry.tags : [...entry.tags, REFINED_TAG],
+        };
+        writeEntry(hippoRoot, updated);
+        result.refined++;
+        result.details.push({ id: entry.id, status: 'refined' });
+    }
+    return result;
+}
+//# sourceMappingURL=refine-llm.js.map

package/dist/refine-llm.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"refine-llm.js","sourceRoot":"","sources":["../src/refine-llm.ts"],"names":[],"mappings":"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"}