peon-mem 1.0.0

package/dist/entities.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Deterministic entity resolution for the knowledge graph.
+ *
+ * The old `inferEntities` (file-extension regex + backtick spans) produced a broken graph:
+ *  - PHANTOM nodes: the space in a path like ".../Project_x 2/peon-mcp/src/daemon.ts" let the
+ *    regex start mid-path, yielding "2/peon-mcp/src/daemon.ts".
+ *  - ALIAS FRAGMENTATION: one file appeared under up to 7 surface forms (daemon.ts,
+ *    src/daemon.ts, peon-mcp/src/daemon.ts, /Users/.../daemon.ts, worktree paths, ...),
+ *    each a distinct node — so spreading activation never connected them.
+ *
+ * This module canonicalizes a raw entity string to a stable key + classifies it into a
+ * NAMESPACE (code vs domain) so retrieval can keep file/symbol co-occurrence from drowning
+ * domain concepts. Fully deterministic — no model, no network.
+ */
+export type EntityNamespace = "code" | "domain";
+export type EntityKind = "file" | "symbol" | "concept";
+export interface CanonicalEntity {
+    /** Stable dedup key (canonical form). */
+    key: string;
+    /** Display name (canonical form, original-ish casing). */
+    name: string;
+    kind: EntityKind;
+    namespace: EntityNamespace;
+}
+/** Canonicalize one raw entity string. Returns null for junk (empty, too long, pure noise). */
+export declare function canonicalizeEntity(raw: string): CanonicalEntity | null;
+/**
+ * Extract DOMAIN entities from prose: products/acronyms with internal capitals or digits
+ * (MaskSQL, NL2SQL, BIRD, DTS-SQL, GPT-5) and short proper-noun sequences (Shantanu Sharma).
+ * Conservative — single sentence-initial Capitalized words are NOT entities (avoids noise) —
+ * so the 83% of beliefs that are prose finally get graph-linkable concepts.
+ */
+export declare function extractDomainEntities(content: string): CanonicalEntity[];
+/**
+ * Resolve the entities mentioned in a piece of content (file paths + backtick spans + domain
+ * proper nouns/products), deduped to canonical entities. Replaces the old regex-only `inferEntities`.
+ */
+export declare function resolveEntities(content: string, extra?: readonly string[]): CanonicalEntity[];
+/** Back-compat: canonical entity KEYS for the string[] `entities` field on records. */
+export declare function inferCanonicalEntities(content: string, extra?: readonly string[]): string[];
+export interface RegistryEntity {
+    key: string;
+    name: string;
+    kind: EntityKind;
+    namespace: EntityNamespace;
+    /** Surface forms that fold into this canonical entity. */
+    aliases: string[];
+    /** Mention count across the brain (graph salience / hub indicator). */
+    salience: number;
+}
+/**
+ * Build the canonical entity registry from every entity occurrence across all records.
+ * Performs cross-form ALIAS MERGE: a bare basename ("daemon.ts") folds into the unique
+ * path key that shares it ("src/daemon.ts") — finishing the de-fragmentation 1a starts.
+ * Ambiguous basenames (two distinct paths share it) are left alone. Returns the registry
+ * plus a `canonical(rawKey) -> finalKey` map for rewriting record entities and graph nodes.
+ */
+export declare function buildEntityRegistry(entityKeys: readonly string[]): {
+    entities: RegistryEntity[];
+    canonical: Map<string, string>;
+};

package/dist/entities.js

@@ -0,0 +1,191 @@
+/**
+ * Deterministic entity resolution for the knowledge graph.
+ *
+ * The old `inferEntities` (file-extension regex + backtick spans) produced a broken graph:
+ *  - PHANTOM nodes: the space in a path like ".../Project_x 2/peon-mcp/src/daemon.ts" let the
+ *    regex start mid-path, yielding "2/peon-mcp/src/daemon.ts".
+ *  - ALIAS FRAGMENTATION: one file appeared under up to 7 surface forms (daemon.ts,
+ *    src/daemon.ts, peon-mcp/src/daemon.ts, /Users/.../daemon.ts, worktree paths, ...),
+ *    each a distinct node — so spreading activation never connected them.
+ *
+ * This module canonicalizes a raw entity string to a stable key + classifies it into a
+ * NAMESPACE (code vs domain) so retrieval can keep file/symbol co-occurrence from drowning
+ * domain concepts. Fully deterministic — no model, no network.
+ */
+// Source-root tokens: a path is canonicalized to the suffix starting at the first of these,
+// so "/Users/.../peon-mcp/src/daemon.ts", "peon-mcp/src/daemon.ts" and "src/daemon.ts" all
+// collapse to "src/daemon.ts".
+const SRC_ROOTS = new Set(["src", "lib", "scripts", "test", "tests", "app", "apps", "packages", "dist", "bin"]);
+const FILE_EXT_RE = /\.(ts|tsx|js|jsx|mjs|cjs|json|md|mdx|html|css|scss|py|ipynb|pdf|txt|yml|yaml|toml|sh|sql|rs|go|java|rb|c|cpp|h)$/i;
+const IDENTIFIER_RE = /^[A-Za-z_$][\w$]*(?:[.#][A-Za-z_$][\w$]*)*$/;
+/** Canonicalize one raw entity string. Returns null for junk (empty, too long, pure noise). */
+export function canonicalizeEntity(raw) {
+    const s = (raw ?? "").trim().replace(/^[`'"]+|[`'"]+$/g, "").trim();
+    if (s.length < 2 || s.length > 200)
+        return null;
+    const pathLike = s.includes("/") || s.includes("\\") || FILE_EXT_RE.test(s);
+    if (pathLike) {
+        // Normalize separators, drop a leading "./" and a leading truncation marker ("..."/"…src/…").
+        // NOTE: we deliberately do NOT blind-strip a leading numeric segment — the SRC_ROOT slice and
+        // parent/basename fallback below already collapse the "2/" phantom from "Project_x 2" WITHOUT
+        // eating real numeric directories like "2024/notes.md".
+        const p = s.replace(/\\/g, "/").replace(/^\.\//, "").replace(/^(?:\.{3}|…)\/?/, "");
+        const segs = p.split("/").filter((seg) => seg && seg !== "." && seg !== "..");
+        if (segs.length === 0)
+            return null;
+        const rootIdx = segs.findIndex((seg) => SRC_ROOTS.has(seg));
+        // With a known source root, key from there (so all prefixes of src/daemon.ts collapse).
+        // Without one, keep parent/basename — NOT bare basename — so two different DESIGN.md /
+        // SKILL.md in different dirs stay DISTINCT entities (avoid merging unrelated files).
+        const key = rootIdx >= 0
+            ? segs.slice(rootIdx).join("/")
+            : segs.length >= 2 ? segs.slice(-2).join("/") : segs[segs.length - 1];
+        if (!key)
+            return null;
+        return { key, name: key, kind: "file", namespace: "code" };
+    }
+    if (IDENTIFIER_RE.test(s)) {
+        // A product/acronym (starts-uppercase or all-caps, with internal caps or a digit — MaskSQL,
+        // BIRD, NL2SQL) is a DOMAIN concept, keyed lowercase so the backtick `MaskSQL` and the prose
+        // "MaskSQL" (via extractDomainEntities) collapse to ONE node. A lowercase-initial camelCase
+        // identifier (rankMemoryRecords) is a code symbol.
+        const internalCaps = /[A-Z]{2,}/.test(s) || /[a-z][A-Z]/.test(s) || /\d/.test(s);
+        const productLike = internalCaps && (/^[A-Z]/.test(s) || s === s.toUpperCase());
+        if (productLike)
+            return { key: s.toLowerCase(), name: s, kind: "concept", namespace: "domain" };
+        if (/[A-Z_]/.test(s.slice(1)))
+            return { key: s, name: s, kind: "symbol", namespace: "code" };
+        // lowercase single token (e.g. "vllm", "ollama") — treat as a domain concept
+        return { key: s.toLowerCase(), name: s, kind: "concept", namespace: "domain" };
+    }
+    // Multi-word phrase / proper noun → domain concept.
+    return { key: s.toLowerCase(), name: s, kind: "concept", namespace: "domain" };
+}
+// Common capitalized words that START sentences / clauses — not domain entities.
+const PROPER_NOUN_STOP = new Set([
+    "the", "this", "that", "these", "those", "a", "an", "it", "we", "i", "you", "he", "she", "they",
+    "if", "when", "then", "for", "and", "but", "or", "so", "to", "in", "on", "of", "at", "by", "as",
+    "use", "used", "using", "add", "added", "fix", "fixed", "make", "made", "set", "run", "build",
+    "now", "also", "after", "before", "while", "since", "because", "however", "note", "todo",
+    "monday", "tuesday", "wednesday", "thursday", "friday", "saturday", "sunday"
+]);
+// Acronyms/keywords that are too generic to be useful domain entities.
+const ACRONYM_STOP = new Set(["OK", "ID", "TODO", "FIXME", "JSON", "HTTP", "HTTPS", "URL", "API", "CLI", "UI", "MD", "PDF", "CSV", "YAML", "AM", "PM", "EST", "IST", "UTC"]);
+/**
+ * Extract DOMAIN entities from prose: products/acronyms with internal capitals or digits
+ * (MaskSQL, NL2SQL, BIRD, DTS-SQL, GPT-5) and short proper-noun sequences (Shantanu Sharma).
+ * Conservative — single sentence-initial Capitalized words are NOT entities (avoids noise) —
+ * so the 83% of beliefs that are prose finally get graph-linkable concepts.
+ */
+export function extractDomainEntities(content) {
+    const out = [];
+    const add = (name) => {
+        const key = name.toLowerCase();
+        out.push({ key, name, kind: "concept", namespace: "domain" });
+    };
+    // products/acronyms: a token with an internal run of ≥2 capitals or a digit (MaskSQL, BIRD, NL2SQL, GPT-5, DTS-SQL)
+    for (const m of content.matchAll(/\b[A-Za-z][A-Za-z0-9]*(?:-[A-Za-z0-9]+)*\b/g)) {
+        const tok = m[0];
+        if (tok.length < 3 || tok.length > 40)
+            continue;
+        if (ACRONYM_STOP.has(tok.toUpperCase()))
+            continue;
+        const hasInternalCaps = /[A-Z]{2,}/.test(tok) || /[a-z][A-Z]/.test(tok) || /[A-Za-z]\d|\d[A-Za-z]/.test(tok);
+        if (hasInternalCaps)
+            add(tok);
+    }
+    // proper-noun sequences: 2-3 Capitalized words (Shantanu Sharma, Master Project)
+    for (const m of content.matchAll(/\b([A-Z][a-z]+(?:\s+[A-Z][a-z]+){1,2})\b/g)) {
+        const phrase = m[1];
+        if (PROPER_NOUN_STOP.has(phrase.split(/\s+/)[0].toLowerCase()))
+            continue; // drop "The Death ...", "When Foo ..."
+        add(phrase);
+    }
+    return out;
+}
+/**
+ * Resolve the entities mentioned in a piece of content (file paths + backtick spans + domain
+ * proper nouns/products), deduped to canonical entities. Replaces the old regex-only `inferEntities`.
+ */
+export function resolveEntities(content, extra = []) {
+    const raw = [...extra];
+    // file-like spans (anchored on a real extension so we don't grab prose)
+    for (const m of content.matchAll(/[\w./\\-]*\.(?:ts|tsx|js|jsx|mjs|cjs|json|md|mdx|html|css|scss|py|ipynb|pdf|txt|yml|yaml|toml|sh|sql)\b/gi)) {
+        raw.push(m[0]);
+    }
+    // backtick-quoted spans
+    for (const m of content.matchAll(/`([^`]+)`/g))
+        raw.push(m[1]);
+    const byKey = new Map();
+    for (const r of raw) {
+        const c = canonicalizeEntity(r);
+        if (c && !byKey.has(c.key))
+            byKey.set(c.key, c);
+    }
+    // domain entities from prose (the bulk of beliefs that have no files/backticks) — already
+    // classified domain, added after so file/symbol classification of any overlap wins.
+    for (const c of extractDomainEntities(content)) {
+        if (!byKey.has(c.key))
+            byKey.set(c.key, c);
+    }
+    // Separate quotas so a long file list can't crowd domain concepts out of the cap entirely
+    // (domain entities are the associative-recall signal; they were appended last and got sliced).
+    const all = [...byKey.values()];
+    const code = all.filter((c) => c.namespace === "code").slice(0, 10);
+    const domain = all.filter((c) => c.namespace === "domain").slice(0, 8);
+    return [...code, ...domain];
+}
+/** Back-compat: canonical entity KEYS for the string[] `entities` field on records. */
+export function inferCanonicalEntities(content, extra = []) {
+    return resolveEntities(content, extra).map((e) => e.key);
+}
+/**
+ * Build the canonical entity registry from every entity occurrence across all records.
+ * Performs cross-form ALIAS MERGE: a bare basename ("daemon.ts") folds into the unique
+ * path key that shares it ("src/daemon.ts") — finishing the de-fragmentation 1a starts.
+ * Ambiguous basenames (two distinct paths share it) are left alone. Returns the registry
+ * plus a `canonical(rawKey) -> finalKey` map for rewriting record entities and graph nodes.
+ */
+export function buildEntityRegistry(entityKeys) {
+    const canonOf = new Map(); // rawKey -> its CanonicalEntity
+    for (const raw of entityKeys) {
+        if (canonOf.has(raw))
+            continue;
+        const c = canonicalizeEntity(raw);
+        if (c)
+            canonOf.set(raw, c);
+    }
+    // basename -> set of distinct path keys that end in it
+    const basenameToPaths = new Map();
+    for (const c of canonOf.values()) {
+        if (!c.key.includes("/"))
+            continue;
+        const base = c.key.split("/").pop();
+        (basenameToPaths.get(base) ?? basenameToPaths.set(base, new Set()).get(base)).add(c.key);
+    }
+    const aliasTarget = (c) => {
+        if (c.kind === "file" && !c.key.includes("/")) {
+            const matches = basenameToPaths.get(c.key);
+            if (matches && matches.size === 1)
+                return [...matches][0]; // unique → fold in
+        }
+        return c.key;
+    };
+    const canonical = new Map();
+    for (const [raw, c] of canonOf)
+        canonical.set(raw, aliasTarget(c));
+    const merged = new Map();
+    for (const raw of entityKeys) {
+        const c = canonOf.get(raw);
+        if (!c)
+            continue;
+        const finalKey = canonical.get(raw);
+        const entry = merged.get(finalKey) ?? { key: finalKey, name: finalKey, kind: c.kind, namespace: c.namespace, aliases: [], salience: 0 };
+        entry.salience += 1; // one mention occurrence
+        for (const form of [raw, c.key])
+            if (form !== finalKey && !entry.aliases.includes(form))
+                entry.aliases.push(form);
+        merged.set(finalKey, entry);
+    }
+    return { entities: [...merged.values()].sort((a, b) => b.salience - a.salience), canonical };
+}

package/dist/entity-extraction.d.ts

@@ -0,0 +1,33 @@
+import type { PeonConfig } from "./config.js";
+import type { FetchLike } from "./reranker.js";
+/**
+ * Model-grade DOMAIN entity extraction. The deterministic resolver (entities.ts) reliably catches
+ * files/symbols and obvious products/proper-nouns, but it misses the domain knowledge that matters
+ * most for associative recall — people, papers, methods, datasets, organizations stated in prose
+ * ("the professor's MaskSQL idea", "AskData on BIRD"). The consolidation panel's one firm
+ * conclusion was that entity extraction is THE place model quality earns its keep (unlike
+ * consolidation fidelity, where it's marginal). So this runs ONE batched LLM pass over the belief
+ * snippets and returns the named entities per snippet, to be MERGED with the deterministic set.
+ *
+ * Strictly optional + fail-safe: no API key, AI disabled, empty input, or any LLM/parse failure
+ * returns an empty map and the caller keeps the deterministic entities. Injectable fetch for tests.
+ */
+export interface ExtractItem {
+    /** Stable key the caller maps results back by (e.g. normalized content). */
+    key: string;
+    content: string;
+}
+export interface ExtractOptions {
+    config: PeonConfig;
+    model?: string;
+    fetchImpl?: FetchLike;
+    /** Max snippets per call + per-snippet char cap (keeps the prompt and cost bounded). */
+    maxItems?: number;
+    snippetChars?: number;
+}
+export declare function extractDomainEntitiesViaModel(items: ExtractItem[], options: ExtractOptions): Promise<Map<string, string[]>>;
+/** Tolerant parse of `[{n, entities:[...]}, ...]` from a model response. */
+export declare function parseEntityArray(content: string): Array<{
+    n: number;
+    entities: string[];
+}>;

package/dist/entity-extraction.js

@@ -0,0 +1,75 @@
+const DEFAULT_MAX_ITEMS = 40;
+const DEFAULT_SNIPPET_CHARS = 240;
+export async function extractDomainEntitiesViaModel(items, options) {
+    const out = new Map();
+    const { config } = options;
+    if (items.length === 0 || config.aiMode === "off" || !config.openRouterApiKey)
+        return out;
+    const doFetch = options.fetchImpl ?? globalThis.fetch;
+    if (!doFetch)
+        return out;
+    const maxItems = Math.max(1, Math.trunc(options.maxItems ?? DEFAULT_MAX_ITEMS));
+    const snippetChars = Math.max(40, Math.trunc(options.snippetChars ?? DEFAULT_SNIPPET_CHARS));
+    const batch = items.slice(0, maxItems);
+    const numbered = batch.map((it, i) => `${i + 1}. ${truncate(it.content, snippetChars)}`).join("\n");
+    const system = "You extract NAMED DOMAIN entities from memory snippets for a knowledge graph. For each numbered " +
+        "snippet, list the specific named entities it mentions: people, papers/methods/models, datasets, " +
+        "projects, organizations, and distinctive technical concepts. Use each entity's canonical surface " +
+        "form. EXCLUDE generic words, file paths, and code identifiers. Return ONLY a JSON array of objects " +
+        '{"n": <snippet number>, "entities": ["..."]}, empty array when a snippet names none. No prose, no fences.';
+    const user = `Snippets:\n${numbered}\n\nJSON array:`;
+    try {
+        const response = await doFetch("https://openrouter.ai/api/v1/chat/completions", {
+            method: "POST",
+            headers: { Authorization: `Bearer ${config.openRouterApiKey}`, "Content-Type": "application/json" },
+            body: JSON.stringify({
+                model: options.model ?? config.processingModel,
+                messages: [
+                    { role: "system", content: system },
+                    { role: "user", content: user }
+                ],
+                temperature: 0
+            })
+        });
+        if (!response.ok)
+            return out;
+        const json = (await response.json());
+        const parsed = parseEntityArray(json.choices?.[0]?.message?.content ?? "");
+        for (const row of parsed) {
+            const idx = row.n - 1;
+            if (idx >= 0 && idx < batch.length && row.entities.length > 0) {
+                out.set(batch[idx].key, row.entities);
+            }
+        }
+        return out;
+    }
+    catch {
+        return out; // any failure → deterministic-only
+    }
+}
+/** Tolerant parse of `[{n, entities:[...]}, ...]` from a model response. */
+export function parseEntityArray(content) {
+    const match = content.match(/\[[\s\S]*\]/);
+    if (!match)
+        return [];
+    try {
+        const parsed = JSON.parse(match[0]);
+        if (!Array.isArray(parsed))
+            return [];
+        return parsed
+            .map((row) => ({
+            n: typeof row?.n === "number" ? Math.trunc(row.n) : Number.parseInt(String(row?.n), 10),
+            entities: Array.isArray(row?.entities)
+                ? row.entities.filter((e) => typeof e === "string" && e.trim().length > 1).map((e) => e.trim()).slice(0, 12)
+                : []
+        }))
+            .filter((row) => Number.isInteger(row.n));
+    }
+    catch {
+        return [];
+    }
+}
+function truncate(text, max) {
+    const flat = text.replace(/\s+/g, " ").trim();
+    return flat.length <= max ? flat : `${flat.slice(0, max - 1)}…`;
+}

package/dist/eval-metrics.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Standard ranked-retrieval metrics for the query-driven eval harness. Pure + deterministic so
+ * they're unit-testable; the harness (scripts/eval-retrieval-labeled.mjs) feeds them a ranked list
+ * of belief ids and a relevance-judged set, and reports graph-off vs graph-on.
+ *
+ * All take `retrieved` (ranked ids, best first) and `relevant` (the judged-relevant id set).
+ */
+/** Fraction of the relevant items found in the top-k. 1 when there are no relevant items (nothing to miss). */
+export declare function recallAtK(retrieved: readonly string[], relevant: ReadonlySet<string>, k: number): number;
+/** Reciprocal rank of the FIRST relevant hit (1/rank), 0 if none retrieved. Mean over queries = MRR. */
+export declare function reciprocalRank(retrieved: readonly string[], relevant: ReadonlySet<string>): number;
+/** Normalized DCG at k with binary relevance: DCG/IDCG. 1 when there are no relevant items. */
+export declare function ndcgAtK(retrieved: readonly string[], relevant: ReadonlySet<string>, k: number): number;
+export interface QueryScore {
+    recall: number;
+    rr: number;
+    ndcg: number;
+}
+export declare function scoreQuery(retrieved: readonly string[], relevant: ReadonlySet<string>, k: number): QueryScore;
+export interface AggregateScore {
+    queries: number;
+    recallAtK: number;
+    mrr: number;
+    ndcgAtK: number;
+}
+/** Mean of per-query scores → Recall@K, MRR, nDCG@K over the whole labeled set. */
+export declare function aggregate(scores: readonly QueryScore[]): AggregateScore;

package/dist/eval-metrics.js

@@ -0,0 +1,50 @@
+/**
+ * Standard ranked-retrieval metrics for the query-driven eval harness. Pure + deterministic so
+ * they're unit-testable; the harness (scripts/eval-retrieval-labeled.mjs) feeds them a ranked list
+ * of belief ids and a relevance-judged set, and reports graph-off vs graph-on.
+ *
+ * All take `retrieved` (ranked ids, best first) and `relevant` (the judged-relevant id set).
+ */
+/** Fraction of the relevant items found in the top-k. 1 when there are no relevant items (nothing to miss). */
+export function recallAtK(retrieved, relevant, k) {
+    if (relevant.size === 0)
+        return 1;
+    let hits = 0;
+    for (const id of retrieved.slice(0, Math.max(0, k)))
+        if (relevant.has(id))
+            hits += 1;
+    return hits / relevant.size;
+}
+/** Reciprocal rank of the FIRST relevant hit (1/rank), 0 if none retrieved. Mean over queries = MRR. */
+export function reciprocalRank(retrieved, relevant) {
+    for (let i = 0; i < retrieved.length; i += 1)
+        if (relevant.has(retrieved[i]))
+            return 1 / (i + 1);
+    return 0;
+}
+/** Normalized DCG at k with binary relevance: DCG/IDCG. 1 when there are no relevant items. */
+export function ndcgAtK(retrieved, relevant, k) {
+    if (relevant.size === 0)
+        return 1;
+    const top = retrieved.slice(0, Math.max(0, k));
+    let dcg = 0;
+    for (let i = 0; i < top.length; i += 1)
+        if (relevant.has(top[i]))
+            dcg += 1 / Math.log2(i + 2);
+    const ideal = Math.min(k, relevant.size);
+    let idcg = 0;
+    for (let i = 0; i < ideal; i += 1)
+        idcg += 1 / Math.log2(i + 2);
+    return idcg > 0 ? dcg / idcg : 0;
+}
+export function scoreQuery(retrieved, relevant, k) {
+    return { recall: recallAtK(retrieved, relevant, k), rr: reciprocalRank(retrieved, relevant), ndcg: ndcgAtK(retrieved, relevant, k) };
+}
+/** Mean of per-query scores → Recall@K, MRR, nDCG@K over the whole labeled set. */
+export function aggregate(scores) {
+    const n = scores.length;
+    if (n === 0)
+        return { queries: 0, recallAtK: 0, mrr: 0, ndcgAtK: 0 };
+    const sum = scores.reduce((a, s) => ({ recall: a.recall + s.recall, rr: a.rr + s.rr, ndcg: a.ndcg + s.ndcg }), { recall: 0, rr: 0, ndcg: 0 });
+    return { queries: n, recallAtK: sum.recall / n, mrr: sum.rr / n, ndcgAtK: sum.ndcg / n };
+}

package/dist/evaluation.d.ts

@@ -0,0 +1,58 @@
+export type EvaluationTextInput = string | string[];
+export interface ExpectedMemoryInput {
+    id?: string;
+    content: string;
+}
+export interface ProcessingJobInput {
+    status?: "processed" | "skipped" | "failed" | string;
+    model?: string;
+    reason?: string;
+    estimatedTokens?: number;
+}
+export interface EvaluationInput {
+    expectedMemories: Array<string | ExpectedMemoryInput>;
+    retrievedText?: EvaluationTextInput;
+    injectedText?: EvaluationTextInput;
+    processingJobs?: ProcessingJobInput[];
+}
+export interface EvaluationReport {
+    expectedCount: number;
+    observedItemCount: number;
+    matchedExpectedCount: number;
+    matchedObservedItemCount: number;
+    recall: number;
+    coverage: number;
+    missingExpectedItems: Array<{
+        id: string;
+        content: string;
+    }>;
+    unexpectedNoisyItems: Array<{
+        source: "retrieved" | "injected";
+        content: string;
+    }>;
+    matches: Array<{
+        expectedId: string;
+        expectedContent: string;
+        observedSource: "retrieved" | "injected";
+        observedContent: string;
+        score: number;
+    }>;
+    costSummary: {
+        jobCount: number;
+        processedJobs: number;
+        skippedJobs: number;
+        failedJobs: number;
+        totalEstimatedTokens: number;
+        byModel: Record<string, {
+            jobCount: number;
+            estimatedTokens: number;
+        }>;
+    };
+}
+export interface EvaluatePeonProjectInput {
+    projectPath: string;
+    memoryDirName?: string;
+    expectedMemories?: Array<string | ExpectedMemoryInput>;
+}
+export declare function computeEvaluationReport(input: EvaluationInput): EvaluationReport;
+export declare function evaluatePeonProject(input: EvaluatePeonProjectInput): Promise<EvaluationReport>;