@mneme-ai/core 0.8.3

package/README.md

@@ -0,0 +1,31 @@
+# @mneme-ai/core
+
+Core indexing, retrieval, and graph engine for [Mneme](https://github.com/patsa2561-art/mneme-ai).
+
+```ts
+import { git, indexer, store, retrieve } from "@mneme-ai/core";
+
+const s = new store.MnemeStore("./.mneme/mneme.db");
+const idx = new indexer.Indexer({ cwd: process.cwd(), store: s });
+await idx.run();
+
+const results = await retrieve.search("why does parseAmount use try/catch?", {
+  store: s,
+  topK: 5,
+});
+```
+
+## What's in here
+
+- `git/` — log/blame parser, repo metadata, GitHub + GitLab adapters
+- `store/` — better-sqlite3 wrapper with FTS5 + BLOB embeddings
+- `indexer/` — chunker + embedder driver
+- `retrieve/` — hybrid search (BM25 + vector cosine fused via Reciprocal Rank Fusion) + reranker contracts
+- `correlate/` — incident correlation contracts (Phase 3)
+- `entities/` — symbol-level memory contracts (Phase 2)
+
+See the [main README](https://github.com/patsa2561-art/mneme-ai#readme) for the full picture and [ARCHITECTURE.md](https://github.com/patsa2561-art/mneme-ai/blob/main/ARCHITECTURE.md) for the data-flow diagram.
+
+## License
+
+MIT.

package/dist/correlate/index.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Phase 3 — Error correlation engine.
+ *
+ * The differentiator. Given:
+ *   - commits (from git)
+ *   - incidents (from pager / manual JSON)
+ *   - entities (phase 2)
+ *
+ * produce Correlation rows that answer:
+ *   "every time PaymentService changes, OrderQueue throws within 48h"
+ *
+ * Phase 3 will fill in:
+ *   - temporal correlation (commit window → incident spike)
+ *   - structural correlation (file overlap, call-graph proximity)
+ *   - semantic correlation (commit message vs stack trace embeddings)
+ *
+ * For now this module exports the contracts that the @mneme-ai/correlator package implements.
+ */
+import type { Commit, Correlation, Incident } from "../types.js";
+export interface CorrelationEngine {
+    readonly name: string;
+    /** Build correlations between a window of commits and a window of incidents. */
+    correlate(input: CorrelateInput): Promise<Correlation[]>;
+}
+export interface CorrelateInput {
+    commits: Commit[];
+    incidents: Incident[];
+    /** Window in milliseconds — how long after a commit an incident may be attributed to it. */
+    windowMs?: number;
+}
+export interface IncidentAdapter {
+    readonly source: "sentry" | "datadog" | "manual" | "github" | "log";
+    fetch(opts: FetchIncidentOptions): Promise<Incident[]>;
+}
+export interface FetchIncidentOptions {
+    since?: string;
+    until?: string;
+    projectId?: string;
+    apiKey?: string;
+    orgSlug?: string;
+}
+/** Default temporal window: 7 days. */
+export declare const DEFAULT_WINDOW_MS: number;
+//# sourceMappingURL=index.d.ts.map

package/dist/correlate/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/correlate/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAEjE,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,gFAAgF;IAChF,SAAS,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC,CAAC;CAC1D;AAED,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,SAAS,EAAE,QAAQ,EAAE,CAAC;IACtB,4FAA4F;IAC5F,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,MAAM,EAAE,QAAQ,GAAG,SAAS,GAAG,QAAQ,GAAG,QAAQ,GAAG,KAAK,CAAC;IACpE,KAAK,CAAC,IAAI,EAAE,oBAAoB,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC;CACxD;AAED,MAAM,WAAW,oBAAoB;IACnC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,uCAAuC;AACvC,eAAO,MAAM,iBAAiB,QAA0B,CAAC"}

package/dist/correlate/index.js

@@ -0,0 +1,21 @@
+/**
+ * Phase 3 — Error correlation engine.
+ *
+ * The differentiator. Given:
+ *   - commits (from git)
+ *   - incidents (from pager / manual JSON)
+ *   - entities (phase 2)
+ *
+ * produce Correlation rows that answer:
+ *   "every time PaymentService changes, OrderQueue throws within 48h"
+ *
+ * Phase 3 will fill in:
+ *   - temporal correlation (commit window → incident spike)
+ *   - structural correlation (file overlap, call-graph proximity)
+ *   - semantic correlation (commit message vs stack trace embeddings)
+ *
+ * For now this module exports the contracts that the @mneme-ai/correlator package implements.
+ */
+/** Default temporal window: 7 days. */
+export const DEFAULT_WINDOW_MS = 7 * 24 * 60 * 60 * 1000;
+//# sourceMappingURL=index.js.map

package/dist/correlate/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/correlate/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AA8BH,uCAAuC;AACvC,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC"}

package/dist/enrich/index.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Enrichment — synthesize missing context for commits with poor messages.
+ *
+ * The honest framing: we never *replace* git history. The original commit
+ * message stays untouched. We add a `synthesized_note` row keyed by commit
+ * hash, marked with the model that produced it, and search treats it as a
+ * separate kind of chunk so users can always tell synthesized text from
+ * original text.
+ *
+ * The system prompt is intentionally cautious — it tells the model to *infer
+ * conservatively from the diff* and to admit uncertainty rather than
+ * confabulate. We mark notes that fall back to "unknown" so they don't
+ * pollute search.
+ */
+import type { Commit } from "../types.js";
+export declare const SYNTHESIZE_SYSTEM_PROMPT = "You are reading a git commit and the diff it produced.\nYour job is to write a 2-4 sentence note explaining the most likely WHY behind the change,\ninferred CONSERVATIVELY from the diff alone \u2014 not invented.\n\nRules:\n1. Refer only to what the diff and adjacent commits actually contain. Never make up facts.\n2. If the diff is too small or generic to infer intent, say exactly: \"Cannot determine purpose from diff alone.\"\n3. Use plain prose, no bullet lists, no markdown headings.\n4. Avoid filler (\"This commit changes...\"). Open with the inferred motivation.\n5. Mention specific function/file names from the diff when they help; never invent names.\n\nOutput ONLY the note. No preamble, no signoff, no quotes.";
+export interface CommitContextForSynthesis {
+    commit: Commit;
+    diff: string;
+    /** Few neighbor commit subjects for temporal context. */
+    neighborSubjects?: string[];
+}
+export declare function buildSynthesisPrompt(input: CommitContextForSynthesis): string;
+/**
+ * Heuristic: a commit "needs healing" when its message gives no real signal.
+ * - Subject shorter than `subjectMinLen` characters, or
+ * - Subject matches one of the generic templates ("update", "fix", "wip", etc.), and
+ * - Body is empty
+ *
+ * Tunable so users can heal the worst offenders first.
+ */
+export declare function needsHealing(commit: Commit, subjectMinLen?: number): boolean;
+/** Return true if the synthesized text is a polite "don't know" — should not be persisted as memory. */
+export declare function isUncertain(note: string): boolean;
+//# sourceMappingURL=index.d.ts.map

package/dist/enrich/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/enrich/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAE1C,eAAO,MAAM,wBAAwB,ytBAWqB,CAAC;AAE3D,MAAM,WAAW,yBAAyB;IACxC,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,yDAAyD;IACzD,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;CAC7B;AAED,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,yBAAyB,GAAG,MAAM,CAqB7E;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,aAAa,SAAK,GAAG,OAAO,CAQxE;AAED,wGAAwG;AACxG,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAOjD"}

package/dist/enrich/index.js

@@ -0,0 +1,69 @@
+export const SYNTHESIZE_SYSTEM_PROMPT = `You are reading a git commit and the diff it produced.
+Your job is to write a 2-4 sentence note explaining the most likely WHY behind the change,
+inferred CONSERVATIVELY from the diff alone — not invented.
+
+Rules:
+1. Refer only to what the diff and adjacent commits actually contain. Never make up facts.
+2. If the diff is too small or generic to infer intent, say exactly: "Cannot determine purpose from diff alone."
+3. Use plain prose, no bullet lists, no markdown headings.
+4. Avoid filler ("This commit changes..."). Open with the inferred motivation.
+5. Mention specific function/file names from the diff when they help; never invent names.
+
+Output ONLY the note. No preamble, no signoff, no quotes.`;
+export function buildSynthesisPrompt(input) {
+    const { commit, diff, neighborSubjects = [] } = input;
+    const lines = [];
+    lines.push(`Commit: ${commit.shortHash || commit.hash.slice(0, 7)}`);
+    lines.push(`Author: ${commit.authorName} <${commit.authorEmail}>`);
+    lines.push(`Date:   ${commit.authorDate}`);
+    lines.push(`Subject: ${commit.subject || "(empty)"}`);
+    if (commit.body && commit.body.trim()) {
+        lines.push(`Body: ${commit.body}`);
+    }
+    if (commit.files.length) {
+        lines.push(`Files: ${commit.files.slice(0, 8).join(", ")}${commit.files.length > 8 ? " (+more)" : ""}`);
+    }
+    if (neighborSubjects.length) {
+        lines.push(`Neighboring commits:`);
+        for (const s of neighborSubjects.slice(0, 5))
+            lines.push(`  - ${s}`);
+    }
+    lines.push("");
+    lines.push("Diff (truncated to 4000 chars):");
+    lines.push(diff.length > 4000 ? diff.slice(0, 4000) + "\n…(truncated)" : diff);
+    return lines.join("\n");
+}
+/**
+ * Heuristic: a commit "needs healing" when its message gives no real signal.
+ * - Subject shorter than `subjectMinLen` characters, or
+ * - Subject matches one of the generic templates ("update", "fix", "wip", etc.), and
+ * - Body is empty
+ *
+ * Tunable so users can heal the worst offenders first.
+ */
+export function needsHealing(commit, subjectMinLen = 20) {
+    const subject = commit.subject.trim();
+    const body = commit.body.trim();
+    if (body.length > 30)
+        return false; // already has a body
+    if (subject.length < subjectMinLen)
+        return true;
+    const generic = /^(?:wip|update[sd]?|fix|fixed|fixes|tweak|small\s+change|misc|stuff|refactor|cleanup|chore|adjust|tweaks)\.?$/i;
+    if (generic.test(subject))
+        return true;
+    return false;
+}
+/** Return true if the synthesized text is a polite "don't know" — should not be persisted as memory. */
+export function isUncertain(note) {
+    if (!note)
+        return true;
+    const t = note.trim().toLowerCase();
+    if (t.length < 30)
+        return true;
+    if (t.includes("cannot determine purpose from diff alone"))
+        return true;
+    if (t.startsWith("i cannot") || t.startsWith("unable to"))
+        return true;
+    return false;
+}
+//# sourceMappingURL=index.js.map

package/dist/enrich/index.js.map

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

package/dist/entities/cosine-clones.d.ts

@@ -0,0 +1,6 @@
+import { type CloneDetector, type DetectOptions, type EntityCluster } from "./index.js";
+export declare class CosineCloneDetector implements CloneDetector {
+    readonly name = "cosine-connected-components-v1";
+    detect(opts: DetectOptions): Promise<EntityCluster[]>;
+}
+//# sourceMappingURL=cosine-clones.d.ts.map

package/dist/entities/cosine-clones.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cosine-clones.d.ts","sourceRoot":"","sources":["../../src/entities/cosine-clones.ts"],"names":[],"mappings":"AAoBA,OAAO,EAGL,KAAK,aAAa,EAClB,KAAK,aAAa,EAClB,KAAK,aAAa,EACnB,MAAM,YAAY,CAAC;AAMpB,qBAAa,mBAAoB,YAAW,aAAa;IACvD,QAAQ,CAAC,IAAI,oCAAoC;IAE3C,MAAM,CAAC,IAAI,EAAE,aAAa,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC;CAoE5D"}

package/dist/entities/cosine-clones.js

@@ -0,0 +1,142 @@
+/**
+ * Cosine-similarity clone detector.
+ *
+ *   1. For each entity pair, compute cosine of their embeddings.
+ *   2. Build a similarity graph: edge A↔B if cos(A,B) ≥ threshold.
+ *   3. Connected-component-cluster the graph (union-find).
+ *   4. Drop singletons; cap cluster size at maxClusterSize.
+ *   5. Compute cohesion = mean pairwise cosine within cluster.
+ *
+ * Why connected components and not HDBSCAN: the threshold is the user's lever.
+ * Connected components are monotone in the threshold — slide it up, get fewer
+ * tighter clusters; slide it down, get bigger looser ones. Users can reason
+ * about that. HDBSCAN's `min_cluster_size` and `min_samples` are not
+ * intuitive for "I want clones tighter than 0.85".
+ *
+ * Complexity: O(N²). Fine up to ~5,000 entities (~12 M comparisons, sub-second
+ * on a laptop). Beyond that, swap in approximate-NN — same surface, faster core.
+ */
+import { createHash } from "node:crypto";
+import { DEFAULT_CLONE_THRESHOLD, DEFAULT_MAX_CLUSTER_SIZE, } from "./index.js";
+export class CosineCloneDetector {
+    name = "cosine-connected-components-v1";
+    async detect(opts) {
+        const threshold = opts.threshold ?? DEFAULT_CLONE_THRESHOLD;
+        const maxClusterSize = opts.maxClusterSize ?? DEFAULT_MAX_CLUSTER_SIZE;
+        const withVecs = opts.entities.filter(hasEmbedding);
+        if (withVecs.length < 2)
+            return [];
+        // Pre-normalize for cosine = dot product.
+        const norms = withVecs.map((e) => normalize(e.embedding));
+        // Union-find structure.
+        const parent = new Int32Array(withVecs.length);
+        for (let i = 0; i < parent.length; i++)
+            parent[i] = i;
+        const find = (x) => {
+            while (parent[x] !== x) {
+                parent[x] = parent[parent[x]];
+                x = parent[x];
+            }
+            return x;
+        };
+        const union = (a, b) => {
+            const ra = find(a);
+            const rb = find(b);
+            if (ra !== rb)
+                parent[rb] = ra;
+        };
+        // Pair-wise cosine via dot of normalized vectors. Track sims for cohesion.
+        const simMap = new Map(); // key: "min-max"
+        for (let i = 0; i < norms.length; i++) {
+            for (let j = i + 1; j < norms.length; j++) {
+                const sim = dot(norms[i], norms[j]);
+                if (sim >= threshold) {
+                    union(i, j);
+                    simMap.set(`${i}-${j}`, sim);
+                }
+            }
+        }
+        // Group by root.
+        const groups = new Map();
+        for (let i = 0; i < withVecs.length; i++) {
+            const root = find(i);
+            const g = groups.get(root);
+            if (g)
+                g.push(i);
+            else
+                groups.set(root, [i]);
+        }
+        const clusters = [];
+        for (const [, indices] of groups) {
+            if (indices.length < 2)
+                continue;
+            const limited = indices.slice(0, maxClusterSize);
+            const cohesion = pairwiseMean(limited, simMap);
+            const members = limited.map((i) => stripVec(withVecs[i]));
+            clusters.push({
+                id: clusterId(members.map((m) => m.id)),
+                cohesion,
+                members,
+            });
+        }
+        // Stable ordering: most-cohesive first; tiebreak by largest cluster.
+        clusters.sort((a, b) => {
+            if (b.members.length !== a.members.length)
+                return b.members.length - a.members.length;
+            return b.cohesion - a.cohesion;
+        });
+        return clusters;
+    }
+}
+function hasEmbedding(e) {
+    return e.embedding instanceof Float32Array && e.embedding.length > 0;
+}
+function normalize(v) {
+    let n = 0;
+    for (let i = 0; i < v.length; i++)
+        n += v[i] * v[i];
+    const norm = Math.sqrt(n);
+    if (norm === 0)
+        return v;
+    const out = new Float32Array(v.length);
+    for (let i = 0; i < v.length; i++)
+        out[i] = v[i] / norm;
+    return out;
+}
+function dot(a, b) {
+    if (a.length !== b.length)
+        return 0;
+    let s = 0;
+    for (let i = 0; i < a.length; i++)
+        s += a[i] * b[i];
+    return s;
+}
+function pairwiseMean(indices, simMap) {
+    if (indices.length < 2)
+        return 0;
+    let total = 0;
+    let count = 0;
+    for (let i = 0; i < indices.length; i++) {
+        for (let j = i + 1; j < indices.length; j++) {
+            const a = indices[i];
+            const b = indices[j];
+            const key = a < b ? `${a}-${b}` : `${b}-${a}`;
+            const sim = simMap.get(key);
+            if (sim !== undefined) {
+                total += sim;
+                count++;
+            }
+        }
+    }
+    return count > 0 ? total / count : 0;
+}
+function stripVec(e) {
+    const { embedding, ...rest } = e;
+    void embedding;
+    return rest;
+}
+function clusterId(memberIds) {
+    const sorted = [...memberIds].sort();
+    return "c_" + createHash("sha1").update(sorted.join("|")).digest("hex").slice(0, 12);
+}
+//# sourceMappingURL=cosine-clones.js.map

package/dist/entities/cosine-clones.js.map

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

package/dist/entities/cosine-clones.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=cosine-clones.test.d.ts.map

package/dist/entities/cosine-clones.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cosine-clones.test.d.ts","sourceRoot":"","sources":["../../src/entities/cosine-clones.test.ts"],"names":[],"mappings":""}

package/dist/entities/cosine-clones.test.js

@@ -0,0 +1,109 @@
+import { describe, it, expect } from "vitest";
+import { CosineCloneDetector } from "./cosine-clones.js";
+const e = (id, vec) => ({
+    id,
+    kind: "function",
+    name: id,
+    filePath: `${id}.ts`,
+    startLine: 1,
+    endLine: 10,
+    language: "typescript",
+    embedding: Float32Array.from(vec),
+});
+describe("CosineCloneDetector", () => {
+    const det = new CosineCloneDetector();
+    it("returns no clusters when fewer than 2 entities have embeddings", async () => {
+        expect(await det.detect({ entities: [] })).toEqual([]);
+        expect(await det.detect({ entities: [e("a", [1, 0, 0])] })).toEqual([]);
+    });
+    it("clusters two near-identical entities", async () => {
+        const out = await det.detect({
+            entities: [e("a", [1, 0, 0]), e("b", [1, 0.01, 0])],
+            threshold: 0.99,
+        });
+        expect(out).toHaveLength(1);
+        expect(out[0].members.map((m) => m.id).sort()).toEqual(["a", "b"]);
+    });
+    it("does not cluster orthogonal entities at any threshold", async () => {
+        const out = await det.detect({
+            entities: [e("a", [1, 0]), e("b", [0, 1])],
+            threshold: 0.5,
+        });
+        expect(out).toEqual([]);
+    });
+    it("connects via transitive similarity (A↔B, B↔C → cluster {A,B,C})", async () => {
+        const out = await det.detect({
+            entities: [e("a", [1, 0, 0]), e("b", [0.95, 0.31, 0]), e("c", [0.85, 0.5, 0])],
+            threshold: 0.92,
+        });
+        expect(out).toHaveLength(1);
+        expect(out[0].members).toHaveLength(3);
+    });
+    it("threshold is monotone — higher threshold produces fewer clusters", async () => {
+        const ents = [
+            e("a", [1, 0, 0]),
+            e("b", [0.95, 0.31, 0]),
+            e("c", [0, 1, 0]),
+            e("d", [0, 0.95, 0.31]),
+        ];
+        const loose = await det.detect({ entities: ents, threshold: 0.5 });
+        const strict = await det.detect({ entities: ents, threshold: 0.99 });
+        const looseCount = loose.reduce((n, c) => n + c.members.length, 0);
+        const strictCount = strict.reduce((n, c) => n + c.members.length, 0);
+        expect(strictCount).toBeLessThanOrEqual(looseCount);
+    });
+    it("respects maxClusterSize cap", async () => {
+        const ents = Array.from({ length: 8 }, (_, i) => e(`x${i}`, [1, i * 0.001, 0]));
+        const out = await det.detect({ entities: ents, threshold: 0.9, maxClusterSize: 3 });
+        expect(out[0].members.length).toBe(3);
+    });
+    it("computes cohesion ∈ [threshold, 1]", async () => {
+        const out = await det.detect({
+            entities: [e("a", [1, 0, 0]), e("b", [1, 0.05, 0])],
+            threshold: 0.9,
+        });
+        const c = out[0];
+        expect(c.cohesion).toBeGreaterThanOrEqual(0.9);
+        expect(c.cohesion).toBeLessThanOrEqual(1);
+    });
+    it("produces deterministic cluster ids (sorted member ids)", async () => {
+        const a = await det.detect({
+            entities: [e("a", [1, 0, 0]), e("b", [1, 0.01, 0])],
+            threshold: 0.99,
+        });
+        const b = await det.detect({
+            entities: [e("b", [1, 0.01, 0]), e("a", [1, 0, 0])],
+            threshold: 0.99,
+        });
+        expect(a[0].id).toBe(b[0].id);
+    });
+    it("ignores entities without embeddings", async () => {
+        const noEmbed = {
+            id: "no",
+            kind: "function",
+            name: "no",
+            filePath: "no.ts",
+            startLine: 1,
+            endLine: 1,
+            language: "typescript",
+        };
+        const out = await det.detect({
+            entities: [e("a", [1, 0]), e("b", [1, 0.01]), noEmbed],
+            threshold: 0.99,
+        });
+        expect(out[0].members.find((m) => m.id === "no")).toBeUndefined();
+    });
+    it("output is sorted by cluster size desc, then cohesion desc", async () => {
+        const ents = [
+            e("a1", [1, 0, 0]),
+            e("a2", [1, 0.01, 0]),
+            e("a3", [1, 0.02, 0]),
+            e("b1", [0, 1, 0]),
+            e("b2", [0, 1, 0.01]),
+        ];
+        const out = await det.detect({ entities: ents, threshold: 0.99 });
+        expect(out).toHaveLength(2);
+        expect(out[0].members.length).toBeGreaterThanOrEqual(out[1].members.length);
+    });
+});
+//# sourceMappingURL=cosine-clones.test.js.map

package/dist/entities/cosine-clones.test.js.map

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

package/dist/entities/index.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Phase 2 — entity-level memory.
+ *
+ * Phase 1 indexes commits and PR text. Phase 2 indexes the *symbols inside the
+ * code itself* — functions, classes, modules, exported types — so we can answer
+ * questions like:
+ *
+ *   "Which functions in this repo do roughly the same thing as parseAmount?"
+ *   "Find all places that re-implement retry logic."
+ *   "Where is this concept handled outside of its declared module?"
+ *
+ * The contracts live here. The parsers and clusterers plug in by implementing
+ * these interfaces. v0.2 will ship a tree-sitter-backed EntityParser and a
+ * cosine-clustering CloneDetector. Both are forward-compatible with this surface.
+ */
+import type { Entity } from "../types.js";
+/**
+ * Walks a workspace and emits every interesting symbol it finds.
+ *
+ * Implementations should:
+ *   - Use tree-sitter or an equivalent AST library — regex is not enough
+ *   - Skip generated, vendored, and node_modules paths by default
+ *   - Be incremental-friendly: callers may only re-parse changed files
+ */
+export interface EntityParser {
+    readonly name: string;
+    readonly languages: string[];
+    parseRepo(opts: ParseOptions): AsyncIterable<Entity>;
+    parseFile(filePath: string, source: string): Iterable<Entity>;
+}
+export interface ParseOptions {
+    cwd: string;
+    /** Limit to specific paths (relative to cwd). */
+    paths?: string[];
+    /** Languages to consider; default = all that the parser supports. */
+    languages?: string[];
+    onProgress?: (filesParsed: number) => void;
+}
+/**
+ * Groups entities by semantic similarity. The output is a set of clusters, each
+ * containing entities that "do roughly the same thing". The detector itself
+ * decides how strict the threshold is.
+ *
+ *   detect({ entities, embedder, threshold: 0.85 })
+ */
+export interface CloneDetector {
+    readonly name: string;
+    detect(opts: DetectOptions): Promise<EntityCluster[]>;
+}
+export interface DetectOptions {
+    entities: Entity[];
+    /** Cosine threshold (0..1). Higher = stricter. */
+    threshold?: number;
+    /** Cap on cluster size to keep results scannable. */
+    maxClusterSize?: number;
+}
+export interface EntityCluster {
+    /** Stable id derived from member entity ids. */
+    id: string;
+    /** Cluster cohesion score (mean pairwise cosine, 0..1). */
+    cohesion: number;
+    members: Entity[];
+    /** Optional one-line summary the detector chose to attach. */
+    label?: string;
+}
+/**
+ * Default thresholds used across the codebase.
+ */
+export declare const DEFAULT_CLONE_THRESHOLD = 0.85;
+export declare const DEFAULT_MAX_CLUSTER_SIZE = 12;
+export { TypeScriptParser, entityEmbeddingText } from "./typescript-parser.js";
+export { PythonParser } from "./python-parser.js";
+export { CosineCloneDetector } from "./cosine-clones.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/entities/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/entities/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAE1C;;;;;;;GAOG;AACH,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,SAAS,EAAE,MAAM,EAAE,CAAC;IAC7B,SAAS,CAAC,IAAI,EAAE,YAAY,GAAG,aAAa,CAAC,MAAM,CAAC,CAAC;IACrD,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC;CAC/D;AAED,MAAM,WAAW,YAAY;IAC3B,GAAG,EAAE,MAAM,CAAC;IACZ,iDAAiD;IACjD,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,qEAAqE;IACrE,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,UAAU,CAAC,EAAE,CAAC,WAAW,EAAE,MAAM,KAAK,IAAI,CAAC;CAC5C;AAED;;;;;;GAMG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,MAAM,CAAC,IAAI,EAAE,aAAa,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC,CAAC;CACvD;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,kDAAkD;IAClD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,qDAAqD;IACrD,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,aAAa;IAC5B,gDAAgD;IAChD,EAAE,EAAE,MAAM,CAAC;IACX,2DAA2D;IAC3D,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,8DAA8D;IAC9D,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,eAAO,MAAM,uBAAuB,OAAO,CAAC;AAC5C,eAAO,MAAM,wBAAwB,KAAK,CAAC;AAE3C,OAAO,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAC/E,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/entities/index.js

@@ -0,0 +1,24 @@
+/**
+ * Phase 2 — entity-level memory.
+ *
+ * Phase 1 indexes commits and PR text. Phase 2 indexes the *symbols inside the
+ * code itself* — functions, classes, modules, exported types — so we can answer
+ * questions like:
+ *
+ *   "Which functions in this repo do roughly the same thing as parseAmount?"
+ *   "Find all places that re-implement retry logic."
+ *   "Where is this concept handled outside of its declared module?"
+ *
+ * The contracts live here. The parsers and clusterers plug in by implementing
+ * these interfaces. v0.2 will ship a tree-sitter-backed EntityParser and a
+ * cosine-clustering CloneDetector. Both are forward-compatible with this surface.
+ */
+/**
+ * Default thresholds used across the codebase.
+ */
+export const DEFAULT_CLONE_THRESHOLD = 0.85;
+export const DEFAULT_MAX_CLUSTER_SIZE = 12;
+export { TypeScriptParser, entityEmbeddingText } from "./typescript-parser.js";
+export { PythonParser } from "./python-parser.js";
+export { CosineCloneDetector } from "./cosine-clones.js";
+//# sourceMappingURL=index.js.map

package/dist/entities/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/entities/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AA0DH;;GAEG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,IAAI,CAAC;AAC5C,MAAM,CAAC,MAAM,wBAAwB,GAAG,EAAE,CAAC;AAE3C,OAAO,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAC/E,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/entities/python-parser.d.ts

@@ -0,0 +1,16 @@
+import type { Entity } from "../types.js";
+import type { EntityParser, ParseOptions } from "./index.js";
+export declare class PythonParser implements EntityParser {
+    readonly name = "python-ast";
+    readonly languages: string[];
+    private pythonCmd;
+    /** Detect which Python binary works on this machine. */
+    preload(): Promise<void>;
+    parseRepo(opts: ParseOptions): AsyncIterable<Entity>;
+    parseFile(_filePath: string, _source: string): Iterable<Entity>;
+    parseSourceAsync(filePath: string, source: string): Promise<Entity[]>;
+    private parseSource;
+    private runPython;
+    private probe;
+}
+//# sourceMappingURL=python-parser.d.ts.map

package/dist/entities/python-parser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"python-parser.d.ts","sourceRoot":"","sources":["../../src/entities/python-parser.ts"],"names":[],"mappings":"AA2BA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAmF7D,qBAAa,YAAa,YAAW,YAAY;IAC/C,QAAQ,CAAC,IAAI,gBAAgB;IAC7B,QAAQ,CAAC,SAAS,WAAc;IAEhC,OAAO,CAAC,SAAS,CAAuB;IAExC,wDAAwD;IAClD,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAcvB,SAAS,CAAC,IAAI,EAAE,YAAY,GAAG,aAAa,CAAC,MAAM,CAAC;IAuB3D,SAAS,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,QAAQ,CAAC,MAAM,CAAC;IAOzD,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;YAK7D,WAAW;IAoCzB,OAAO,CAAC,SAAS;IAejB,OAAO,CAAC,KAAK;CAad"}