@mneme-ai/core 0.22.2 → 0.24.0

package/dist/htc/storage.test.js

@@ -0,0 +1,327 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { mkdtempSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { MnemeStore } from "../store/sqlite.js";
+import { upsertAbstract, upsertAbstracts, getAbstract, getAllAbstracts, deleteOldAbstracts, upsertClusterSummary, getAllClusterSummaries, upsertMemoir, getMemoir, getHtcStats, } from "./storage.js";
+let tmpDir;
+let store;
+beforeEach(() => {
+    tmpDir = mkdtempSync(join(tmpdir(), "mneme-htc-storage-"));
+    store = new MnemeStore(join(tmpDir, "mneme.db"));
+});
+afterEach(() => {
+    store.close();
+    rmSync(tmpDir, { recursive: true, force: true });
+});
+const seedCommit = (over = {}) => ({
+    hash: "c".repeat(40),
+    shortHash: "ccccccc",
+    authorName: "Alice",
+    authorEmail: "a@x.io",
+    authorDate: "2025-01-01T00:00:00Z",
+    committerDate: "2025-01-01T00:00:00Z",
+    subject: "test commit",
+    body: "some body text",
+    parents: [],
+    files: ["src/foo.ts"],
+    ...over,
+});
+describe("HTC storage — schema migration", () => {
+    it("bumps schema_version to 4", () => {
+        expect(store.getMeta("schema_version")).toBe("4");
+    });
+    it("creates htc_abstracts, htc_clusters, htc_memoir tables", () => {
+        const tables = store.db
+            .prepare("SELECT name FROM sqlite_master WHERE type='table' ORDER BY name")
+            .all();
+        const names = tables.map((t) => t.name);
+        expect(names).toContain("htc_abstracts");
+        expect(names).toContain("htc_clusters");
+        expect(names).toContain("htc_memoir");
+    });
+    it("migration is idempotent — re-opening doesn't error or duplicate", () => {
+        store.close();
+        // Re-open same DB; should succeed without throwing.
+        store = new MnemeStore(join(tmpDir, "mneme.db"));
+        expect(store.getMeta("schema_version")).toBe("4");
+        // Re-open AGAIN to be sure.
+        store.close();
+        store = new MnemeStore(join(tmpDir, "mneme.db"));
+        expect(store.getMeta("schema_version")).toBe("4");
+    });
+});
+describe("HTC storage — Layer 1 abstracts", () => {
+    beforeEach(() => {
+        store.upsertCommits([seedCommit({ hash: "a".repeat(40) })]);
+    });
+    it("upsertAbstract round-trips", () => {
+        upsertAbstract(store, {
+            hash: "a".repeat(40),
+            abstract: "auth: replaced session cookies with JWT for stateless deploys",
+            tokenCount: 12,
+            generationMs: 350,
+            generator: "ollama:qwen2.5:3b",
+            generatedAt: "2025-05-01T00:00:00.000Z",
+        });
+        const got = getAbstract(store, "a".repeat(40));
+        expect(got).not.toBeNull();
+        expect(got.abstract).toContain("JWT");
+        expect(got.tokenCount).toBe(12);
+        expect(got.generator).toBe("ollama:qwen2.5:3b");
+        expect(got.generatedAt).toBe("2025-05-01T00:00:00.000Z");
+    });
+    it("upsertAbstract is idempotent (re-insert overwrites)", () => {
+        const base = {
+            hash: "a".repeat(40),
+            abstract: "first version",
+            tokenCount: 2,
+            generationMs: 100,
+            generator: "ollama:qwen2.5:3b",
+            generatedAt: "2025-05-01T00:00:00.000Z",
+        };
+        upsertAbstract(store, base);
+        upsertAbstract(store, { ...base, abstract: "second version", tokenCount: 3 });
+        const got = getAbstract(store, "a".repeat(40));
+        expect(got.abstract).toBe("second version");
+        expect(got.tokenCount).toBe(3);
+        // Still only one row.
+        const count = store.db.prepare("SELECT COUNT(*) AS n FROM htc_abstracts").get().n;
+        expect(count).toBe(1);
+    });
+    it("upsertAbstracts batch round-trips", () => {
+        store.upsertCommits([
+            seedCommit({ hash: "b".repeat(40) }),
+            seedCommit({ hash: "d".repeat(40) }),
+        ]);
+        upsertAbstracts(store, [
+            {
+                hash: "a".repeat(40),
+                abstract: "alpha",
+                tokenCount: 1,
+                generationMs: 10,
+                generator: "test",
+            },
+            {
+                hash: "b".repeat(40),
+                abstract: "bravo",
+                tokenCount: 1,
+                generationMs: 10,
+                generator: "test",
+            },
+            {
+                hash: "d".repeat(40),
+                abstract: "delta",
+                tokenCount: 1,
+                generationMs: 10,
+                generator: "test",
+            },
+        ]);
+        const all = getAllAbstracts(store);
+        expect(all.size).toBe(3);
+        expect(all.get("b".repeat(40)).abstract).toBe("bravo");
+    });
+    it("getAbstract returns null for missing commit", () => {
+        expect(getAbstract(store, "f".repeat(40))).toBeNull();
+    });
+    it("deleteOldAbstracts removes rows older than cutoff", () => {
+        upsertAbstract(store, {
+            hash: "a".repeat(40),
+            abstract: "old",
+            tokenCount: 1,
+            generationMs: 1,
+            generator: "test",
+            generatedAt: new Date(Date.now() - 30 * 24 * 60 * 60 * 1000).toISOString(),
+        });
+        const removed = deleteOldAbstracts(store, 7);
+        expect(removed).toBe(1);
+        expect(getAbstract(store, "a".repeat(40))).toBeNull();
+    });
+    it("deleteOldAbstracts keeps fresh rows", () => {
+        upsertAbstract(store, {
+            hash: "a".repeat(40),
+            abstract: "fresh",
+            tokenCount: 1,
+            generationMs: 1,
+            generator: "test",
+            generatedAt: new Date().toISOString(),
+        });
+        expect(deleteOldAbstracts(store, 7)).toBe(0);
+    });
+    it("ON DELETE CASCADE removes abstracts when commit is deleted", () => {
+        upsertAbstract(store, {
+            hash: "a".repeat(40),
+            abstract: "x",
+            tokenCount: 1,
+            generationMs: 1,
+            generator: "test",
+        });
+        store.db.prepare("DELETE FROM commits WHERE hash = ?").run("a".repeat(40));
+        expect(getAbstract(store, "a".repeat(40))).toBeNull();
+    });
+});
+describe("HTC storage — Layer 2 clusters", () => {
+    it("upsertClusterSummary round-trips with JSON memberHashes", () => {
+        upsertClusterSummary(store, {
+            clusterId: "c1",
+            label: "auth refactor",
+            summary: "Group of auth-related commits…",
+            memberHashes: ["aaa", "bbb", "ccc"],
+            tokenCount: 50,
+            generationMs: 1200,
+            generator: "groq:llama-3.3-70b",
+            generatedAt: "2025-05-01T00:00:00.000Z",
+        });
+        const all = getAllClusterSummaries(store);
+        expect(all).toHaveLength(1);
+        expect(all[0].label).toBe("auth refactor");
+        expect(all[0].memberHashes).toEqual(["aaa", "bbb", "ccc"]);
+    });
+    it("upsertClusterSummary is idempotent on cluster_id", () => {
+        upsertClusterSummary(store, {
+            clusterId: "c1",
+            label: "first",
+            summary: "v1",
+            memberHashes: ["a"],
+            tokenCount: 1,
+            generationMs: 1,
+            generator: "test",
+        });
+        upsertClusterSummary(store, {
+            clusterId: "c1",
+            label: "second",
+            summary: "v2",
+            memberHashes: ["a", "b"],
+            tokenCount: 2,
+            generationMs: 1,
+            generator: "test",
+        });
+        const all = getAllClusterSummaries(store);
+        expect(all).toHaveLength(1);
+        expect(all[0].label).toBe("second");
+        expect(all[0].memberHashes).toEqual(["a", "b"]);
+    });
+    it("getAllClusterSummaries returns [] when none stored", () => {
+        expect(getAllClusterSummaries(store)).toEqual([]);
+    });
+});
+describe("HTC storage — Layer 3 memoir", () => {
+    it("upsertMemoir round-trips on singleton id=1", () => {
+        upsertMemoir(store, {
+            narrative: "This repo is a TypeScript library that…",
+            totalCommits: 1234,
+            totalClusters: 27,
+            tokenCount: 500,
+            generationMs: 4200,
+            generator: "groq:llama-3.3-70b",
+            generatedAt: "2025-05-07T00:00:00.000Z",
+        });
+        const m = getMemoir(store);
+        expect(m).not.toBeNull();
+        expect(m.totalCommits).toBe(1234);
+        expect(m.totalClusters).toBe(27);
+        expect(m.narrative).toContain("TypeScript");
+    });
+    it("upsertMemoir replaces previous memoir (single row)", () => {
+        upsertMemoir(store, {
+            narrative: "v1",
+            totalCommits: 10,
+            totalClusters: 2,
+            tokenCount: 1,
+            generationMs: 1,
+            generator: "test",
+        });
+        upsertMemoir(store, {
+            narrative: "v2",
+            totalCommits: 20,
+            totalClusters: 4,
+            tokenCount: 1,
+            generationMs: 1,
+            generator: "test",
+        });
+        const count = store.db.prepare("SELECT COUNT(*) AS n FROM htc_memoir").get().n;
+        expect(count).toBe(1);
+        expect(getMemoir(store).narrative).toBe("v2");
+    });
+    it("getMemoir returns null when none stored", () => {
+        expect(getMemoir(store)).toBeNull();
+    });
+});
+describe("HTC storage — getHtcStats", () => {
+    it("returns zeros for empty store", () => {
+        const s = getHtcStats(store);
+        expect(s.totalCommits).toBe(0);
+        expect(s.abstractsGenerated).toBe(0);
+        expect(s.abstractsCoverage).toBe(0);
+        expect(s.clustersGenerated).toBe(0);
+        expect(s.memoirGenerated).toBe(false);
+        expect(s.totalCachedTokens).toBe(0);
+        expect(s.compressionRatio).toBe(0);
+    });
+    it("computes coverage = abstracts / commits", () => {
+        store.upsertCommits([
+            seedCommit({ hash: "a".repeat(40), subject: "one" }),
+            seedCommit({ hash: "b".repeat(40), subject: "two" }),
+            seedCommit({ hash: "d".repeat(40), subject: "three" }),
+            seedCommit({ hash: "e".repeat(40), subject: "four" }),
+        ]);
+        upsertAbstract(store, {
+            hash: "a".repeat(40),
+            abstract: "abstract one",
+            tokenCount: 30,
+            generationMs: 1,
+            generator: "test",
+        });
+        upsertAbstract(store, {
+            hash: "b".repeat(40),
+            abstract: "abstract two",
+            tokenCount: 30,
+            generationMs: 1,
+            generator: "test",
+        });
+        const s = getHtcStats(store);
+        expect(s.totalCommits).toBe(4);
+        expect(s.abstractsGenerated).toBe(2);
+        expect(s.abstractsCoverage).toBeCloseTo(0.5, 4);
+        expect(s.totalCachedTokens).toBe(60);
+    });
+    it("sums tokens across all three layers + compression ratio is raw/cached", () => {
+        store.upsertCommits([
+            seedCommit({ hash: "a".repeat(40), subject: "x".repeat(100), body: "y".repeat(300) }),
+        ]);
+        upsertAbstract(store, {
+            hash: "a".repeat(40),
+            abstract: "tiny abstract",
+            tokenCount: 30,
+            generationMs: 1,
+            generator: "test",
+        });
+        upsertClusterSummary(store, {
+            clusterId: "c1",
+            label: "x",
+            summary: "y",
+            memberHashes: ["a".repeat(40)],
+            tokenCount: 100,
+            generationMs: 1,
+            generator: "test",
+        });
+        upsertMemoir(store, {
+            narrative: "memoir",
+            totalCommits: 1,
+            totalClusters: 1,
+            tokenCount: 500,
+            generationMs: 1,
+            generator: "test",
+        });
+        const s = getHtcStats(store);
+        expect(s.totalCachedTokens).toBe(630);
+        // Raw = 400 chars / 4 = 100 tokens. Cached = 630. Ratio raw/cached < 1
+        // (i.e. the cache here is bigger than the raw — synthetic test). Just
+        // assert the formula is applied.
+        expect(s.compressionRatio).toBeCloseTo(100 / 630, 2);
+        expect(s.memoirGenerated).toBe(true);
+        expect(s.memoirAgeDays).toBeDefined();
+        expect(s.memoirAgeDays).toBeGreaterThanOrEqual(0);
+    });
+});
+//# sourceMappingURL=storage.test.js.map

package/dist/htc/storage.test.js.map

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

package/dist/htc/types.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Hierarchical Token Cache (HTC) — shared types.
+ *
+ * The big idea: Mneme pre-compresses an entire codebase's git history into
+ * LLM-consumable form at index-time. 50,000 commits fit in one Claude prompt.
+ * Token cost paid ONCE; reused forever.
+ *
+ * Three layers:
+ *   Layer 1 — Semantic abstracts (~30 tok/commit, LLM-generated once, cached)
+ *   Layer 2 — Topic clusters     (~100 tok/cluster, summarized from Layer 1)
+ *   Layer 3 — Repo memoir        (~500 tok, generated from Layer 2)
+ */
+/**
+ * Subset of EnricherProvider needed by HTC. We avoid a hard dependency on
+ * @mneme-ai/embeddings to keep core dep-free; callers pass an enricher in.
+ */
+export interface HtcEnricher {
+    readonly name: string;
+    enrich(input: {
+        system: string;
+        user: string;
+        temperature?: number;
+        maxTokens?: number;
+    }): Promise<{
+        text: string;
+    }>;
+}
+/** Layer 1 result: ~30-token abstract for a single commit. */
+export interface AbstractResult {
+    hash: string;
+    /** ~30-token plain-English condensation of WHAT changed + WHY. */
+    abstract: string;
+    /** Estimated token count (text.split / words × 1.3). */
+    tokenCount: number;
+    generationMs: number;
+    /** Provider name + model for provenance, e.g. "ollama:qwen2.5:3b". */
+    generator: string;
+    /** ISO timestamp; populated by storage layer when reading back. */
+    generatedAt?: string;
+}
+/** Layer 2 result: ~100-token summary for a group of related commits. */
+export interface ClusterSummary {
+    clusterId: string;
+    /** Short topic name, e.g. "auth refactor". */
+    label: string;
+    /** ~100-token paragraph: topic + major changes + sequence. */
+    summary: string;
+    memberHashes: string[];
+    tokenCount: number;
+    generationMs: number;
+    generator: string;
+    generatedAt?: string;
+}
+/** Layer 3 result: ~500-token narrative of the entire repo. */
+export interface Memoir {
+    /** ~500-token plain-English narrative covering opening, topics, current state. */
+    narrative: string;
+    totalCommits: number;
+    totalClusters: number;
+    tokenCount: number;
+    generationMs: number;
+    generator: string;
+    generatedAt?: string;
+}
+/** Aggregate stats / coverage for the HTC across all three layers. */
+export interface HtcStats {
+    totalCommits: number;
+    abstractsGenerated: number;
+    /** Fraction of commits with a Layer-1 abstract (0..1). */
+    abstractsCoverage: number;
+    clustersGenerated: number;
+    memoirGenerated: boolean;
+    /** Days since the memoir was last generated; undefined when no memoir exists. */
+    memoirAgeDays?: number;
+    /** Sum of token_count across abstracts + clusters + memoir. */
+    totalCachedTokens: number;
+    /** Estimated tokens of raw commit bodies+subjects — for compression comparison. */
+    estimatedRawTokens: number;
+    /** estimatedRawTokens / totalCachedTokens; 0 when nothing cached yet. */
+    compressionRatio: number;
+}
+/** Estimate token count without pulling a tokenizer dependency.
+ *  Heuristic: words × 1.3 (rounds up sub-word breaks for typical English/code).
+ */
+export declare function estimateTokens(text: string): number;
+//# sourceMappingURL=types.d.ts.map

package/dist/htc/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/htc/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,MAAM,CAAC,KAAK,EAAE;QACZ,MAAM,EAAE,MAAM,CAAC;QACf,IAAI,EAAE,MAAM,CAAC;QACb,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,SAAS,CAAC,EAAE,MAAM,CAAC;KACpB,GAAG,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAC/B;AAED,8DAA8D;AAC9D,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,kEAAkE;IAClE,QAAQ,EAAE,MAAM,CAAC;IACjB,wDAAwD;IACxD,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,sEAAsE;IACtE,SAAS,EAAE,MAAM,CAAC;IAClB,mEAAmE;IACnE,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,yEAAyE;AACzE,MAAM,WAAW,cAAc;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,8CAA8C;IAC9C,KAAK,EAAE,MAAM,CAAC;IACd,8DAA8D;IAC9D,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,+DAA+D;AAC/D,MAAM,WAAW,MAAM;IACrB,kFAAkF;IAClF,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,sEAAsE;AACtE,MAAM,WAAW,QAAQ;IACvB,YAAY,EAAE,MAAM,CAAC;IACrB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,0DAA0D;IAC1D,iBAAiB,EAAE,MAAM,CAAC;IAC1B,iBAAiB,EAAE,MAAM,CAAC;IAC1B,eAAe,EAAE,OAAO,CAAC;IACzB,iFAAiF;IACjF,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,+DAA+D;IAC/D,iBAAiB,EAAE,MAAM,CAAC;IAC1B,mFAAmF;IACnF,kBAAkB,EAAE,MAAM,CAAC;IAC3B,yEAAyE;IACzE,gBAAgB,EAAE,MAAM,CAAC;CAC1B;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAInD"}

package/dist/htc/types.js

@@ -0,0 +1,22 @@
+/**
+ * Hierarchical Token Cache (HTC) — shared types.
+ *
+ * The big idea: Mneme pre-compresses an entire codebase's git history into
+ * LLM-consumable form at index-time. 50,000 commits fit in one Claude prompt.
+ * Token cost paid ONCE; reused forever.
+ *
+ * Three layers:
+ *   Layer 1 — Semantic abstracts (~30 tok/commit, LLM-generated once, cached)
+ *   Layer 2 — Topic clusters     (~100 tok/cluster, summarized from Layer 1)
+ *   Layer 3 — Repo memoir        (~500 tok, generated from Layer 2)
+ */
+/** Estimate token count without pulling a tokenizer dependency.
+ *  Heuristic: words × 1.3 (rounds up sub-word breaks for typical English/code).
+ */
+export function estimateTokens(text) {
+    if (!text)
+        return 0;
+    const words = text.trim().split(/\s+/).filter(Boolean).length;
+    return Math.ceil(words * 1.3);
+}
+//# sourceMappingURL=types.js.map

package/dist/htc/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/htc/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AA0EH;;GAEG;AACH,MAAM,UAAU,cAAc,CAAC,IAAY;IACzC,IAAI,CAAC,IAAI;QAAE,OAAO,CAAC,CAAC;IACpB,MAAM,KAAK,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC;IAC9D,OAAO,IAAI,CAAC,IAAI,CAAC,KAAK,GAAG,GAAG,CAAC,CAAC;AAChC,CAAC"}

package/dist/index.d.ts

@@ -12,4 +12,5 @@ export * as insights from "./insights/index.js";
 export * as quant from "./quant/index.js";
 export * as guardian from "./guardian/index.js";
 export * as forensics from "./forensics/index.js";
+export * as htc from "./htc/index.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,OAAO,KAAK,GAAG,MAAM,gBAAgB,CAAC;AACtC,OAAO,KAAK,KAAK,MAAM,kBAAkB,CAAC;AAC1C,OAAO,KAAK,OAAO,MAAM,oBAAoB,CAAC;AAC9C,OAAO,KAAK,QAAQ,MAAM,qBAAqB,CAAC;AAChD,OAAO,KAAK,SAAS,MAAM,sBAAsB,CAAC;AAClD,OAAO,KAAK,QAAQ,MAAM,qBAAqB,CAAC;AAChD,OAAO,KAAK,MAAM,MAAM,mBAAmB,CAAC;AAC5C,OAAO,KAAK,IAAI,MAAM,iBAAiB,CAAC;AACxC,OAAO,KAAK,MAAM,MAAM,mBAAmB,CAAC;AAC5C,OAAO,KAAK,QAAQ,MAAM,qBAAqB,CAAC;AAChD,OAAO,KAAK,KAAK,MAAM,kBAAkB,CAAC;AAC1C,OAAO,KAAK,QAAQ,MAAM,qBAAqB,CAAC;AAChD,OAAO,KAAK,SAAS,MAAM,sBAAsB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,OAAO,KAAK,GAAG,MAAM,gBAAgB,CAAC;AACtC,OAAO,KAAK,KAAK,MAAM,kBAAkB,CAAC;AAC1C,OAAO,KAAK,OAAO,MAAM,oBAAoB,CAAC;AAC9C,OAAO,KAAK,QAAQ,MAAM,qBAAqB,CAAC;AAChD,OAAO,KAAK,SAAS,MAAM,sBAAsB,CAAC;AAClD,OAAO,KAAK,QAAQ,MAAM,qBAAqB,CAAC;AAChD,OAAO,KAAK,MAAM,MAAM,mBAAmB,CAAC;AAC5C,OAAO,KAAK,IAAI,MAAM,iBAAiB,CAAC;AACxC,OAAO,KAAK,MAAM,MAAM,mBAAmB,CAAC;AAC5C,OAAO,KAAK,QAAQ,MAAM,qBAAqB,CAAC;AAChD,OAAO,KAAK,KAAK,MAAM,kBAAkB,CAAC;AAC1C,OAAO,KAAK,QAAQ,MAAM,qBAAqB,CAAC;AAChD,OAAO,KAAK,SAAS,MAAM,sBAAsB,CAAC;AAClD,OAAO,KAAK,GAAG,MAAM,gBAAgB,CAAC"}

package/dist/index.js

@@ -12,4 +12,5 @@ export * as insights from "./insights/index.js";
 export * as quant from "./quant/index.js";
 export * as guardian from "./guardian/index.js";
 export * as forensics from "./forensics/index.js";
+export * as htc from "./htc/index.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,OAAO,KAAK,GAAG,MAAM,gBAAgB,CAAC;AACtC,OAAO,KAAK,KAAK,MAAM,kBAAkB,CAAC;AAC1C,OAAO,KAAK,OAAO,MAAM,oBAAoB,CAAC;AAC9C,OAAO,KAAK,QAAQ,MAAM,qBAAqB,CAAC;AAChD,OAAO,KAAK,SAAS,MAAM,sBAAsB,CAAC;AAClD,OAAO,KAAK,QAAQ,MAAM,qBAAqB,CAAC;AAChD,OAAO,KAAK,MAAM,MAAM,mBAAmB,CAAC;AAC5C,OAAO,KAAK,IAAI,MAAM,iBAAiB,CAAC;AACxC,OAAO,KAAK,MAAM,MAAM,mBAAmB,CAAC;AAC5C,OAAO,KAAK,QAAQ,MAAM,qBAAqB,CAAC;AAChD,OAAO,KAAK,KAAK,MAAM,kBAAkB,CAAC;AAC1C,OAAO,KAAK,QAAQ,MAAM,qBAAqB,CAAC;AAChD,OAAO,KAAK,SAAS,MAAM,sBAAsB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,OAAO,KAAK,GAAG,MAAM,gBAAgB,CAAC;AACtC,OAAO,KAAK,KAAK,MAAM,kBAAkB,CAAC;AAC1C,OAAO,KAAK,OAAO,MAAM,oBAAoB,CAAC;AAC9C,OAAO,KAAK,QAAQ,MAAM,qBAAqB,CAAC;AAChD,OAAO,KAAK,SAAS,MAAM,sBAAsB,CAAC;AAClD,OAAO,KAAK,QAAQ,MAAM,qBAAqB,CAAC;AAChD,OAAO,KAAK,MAAM,MAAM,mBAAmB,CAAC;AAC5C,OAAO,KAAK,IAAI,MAAM,iBAAiB,CAAC;AACxC,OAAO,KAAK,MAAM,MAAM,mBAAmB,CAAC;AAC5C,OAAO,KAAK,QAAQ,MAAM,qBAAqB,CAAC;AAChD,OAAO,KAAK,KAAK,MAAM,kBAAkB,CAAC;AAC1C,OAAO,KAAK,QAAQ,MAAM,qBAAqB,CAAC;AAChD,OAAO,KAAK,SAAS,MAAM,sBAAsB,CAAC;AAClD,OAAO,KAAK,GAAG,MAAM,gBAAgB,CAAC"}

package/dist/retrieve/ddtree.d.ts

@@ -0,0 +1,67 @@
+/**
+ * DDTree — Best-First Search through a commit ancestor tree.
+ *
+ * Inspired by KAT-0B's DDTree (a BinaryHeap-driven candidate exploration
+ * loop bounded by an exploration budget). Mneme uses it under `mneme why`
+ * to walk *back* through parent commits looking for the deepest plausible
+ * "this is why X exists" answer — strictly better than flat semantic
+ * retrieval, which can't follow causal ancestry.
+ *
+ * Semantics:
+ *   1. Caller supplies a `scoreFn(commit, depth, parentScore)` — typically
+ *      relevance × depth-decay × parent-score.
+ *   2. We maintain a max-heap keyed by score and pop the best candidate
+ *      until either the budget is exhausted or the heap is empty.
+ *   3. Each pop is classified: accepted, pruned-floor, pruned-depth, or
+ *      pruned-budget (for nodes still on the heap when budget runs out).
+ *   4. Parents of an accepted node are scored and pushed back in.
+ *
+ * Heap implementation: a simple binary max-heap on a flat array. We avoid
+ * Node v22's experimental `node:priority-queue` for portability — Mneme
+ * supports Node 18+. See `MaxHeap` below.
+ *
+ * Cycle handling: merge commits can — in theory — produce diamond-shaped
+ * ancestry where the same hash appears twice. We track a `visited` Set so
+ * each commit is processed at most once (the first/highest-score path wins).
+ */
+import type { Commit } from "../types.js";
+export interface DDTreeOptions {
+    /** Max nodes to explore (controls cost). Default 32. */
+    budget?: number;
+    /** Max depth from root before pruning. Default 6. */
+    maxDepth?: number;
+    /** Score floor — nodes below this are pruned. Default 0.05. */
+    scoreFloor?: number;
+}
+export interface DDTreeNode {
+    commit: Commit;
+    depth: number;
+    /** Combined score: relevance × decay-by-depth × parent score. */
+    score: number;
+    /** Parent commit hash (the *child* in graph terms — i.e. the node we
+     *  expanded from to reach this commit). Undefined for root nodes. */
+    parent?: string;
+    /** Why this node was pruned, or "accepted". */
+    status: "accepted" | "pruned-floor" | "pruned-depth" | "pruned-budget";
+}
+export interface DDTreeResult {
+    /** All explored nodes with verdict (in pop order). */
+    visited: DDTreeNode[];
+    /** Accepted nodes only, sorted by score (highest first). */
+    accepted: DDTreeNode[];
+    budgetUsed: number;
+}
+/** Score function: relevance × decay-by-depth × log_priors etc. Caller provides. */
+export type ScoreFn = (commit: Commit, depth: number, parentScore: number) => number;
+/** Look up a commit's parent hashes. Caller provides (typically from store). */
+export type ParentResolver = (hash: string) => string[];
+/** Look up a commit by hash. Caller provides. */
+export type CommitResolver = (hash: string) => Commit | undefined;
+/**
+ * Best-First Search through commit ancestors. See module docstring.
+ *
+ * Returns every node we touched (with verdict), the sorted list of
+ * accepted nodes, and how much of the budget we consumed.
+ */
+export declare function exploreDDTree(rootHashes: string[], scoreFn: ScoreFn, parents: ParentResolver, commits: CommitResolver, opts?: DDTreeOptions): DDTreeResult;
+//# sourceMappingURL=ddtree.d.ts.map

package/dist/retrieve/ddtree.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ddtree.d.ts","sourceRoot":"","sources":["../../src/retrieve/ddtree.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAE1C,MAAM,WAAW,aAAa;IAC5B,wDAAwD;IACxD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,qDAAqD;IACrD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,+DAA+D;IAC/D,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,iEAAiE;IACjE,KAAK,EAAE,MAAM,CAAC;IACd;yEACqE;IACrE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,+CAA+C;IAC/C,MAAM,EAAE,UAAU,GAAG,cAAc,GAAG,cAAc,GAAG,eAAe,CAAC;CACxE;AAED,MAAM,WAAW,YAAY;IAC3B,sDAAsD;IACtD,OAAO,EAAE,UAAU,EAAE,CAAC;IACtB,4DAA4D;IAC5D,QAAQ,EAAE,UAAU,EAAE,CAAC;IACvB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,oFAAoF;AACpF,MAAM,MAAM,OAAO,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,KAAK,MAAM,CAAC;AAErF,gFAAgF;AAChF,MAAM,MAAM,cAAc,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,EAAE,CAAC;AAExD,iDAAiD;AACjD,MAAM,MAAM,cAAc,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,CAAC;AAqElE;;;;;GAKG;AACH,wBAAgB,aAAa,CAC3B,UAAU,EAAE,MAAM,EAAE,EACpB,OAAO,EAAE,OAAO,EAChB,OAAO,EAAE,cAAc,EACvB,OAAO,EAAE,cAAc,EACvB,IAAI,GAAE,aAAkB,GACvB,YAAY,CA+Fd"}