dsh-continual-evolve 0.7.6 → 0.8.0

package/lib/memory-benchmark.d.ts

@@ -0,0 +1,76 @@
+import type { HarnessEntry } from "./types.js";
+/** One labeled fact the extractor should (or, when outdated, should not) produce. */
+export interface MemoryBenchmarkFact {
+    id: string;
+    memoryType: string;
+    /** Key phrases; an edit matches when its title+content carry every phrase. */
+    mustContain: string[];
+    /** Outdated facts must be avoided (create/update) or removed (archive/delete). */
+    outdated?: boolean;
+}
+export interface MemoryBenchmarkReference {
+    facts: MemoryBenchmarkFact[];
+}
+/** One proposed edit in the shape the memory loop emits. */
+export interface MemoryBenchmarkEdit {
+    action: "create" | "update" | "delete" | "archive";
+    title?: string;
+    content?: string;
+    /** Target entry id for update/delete/archive. */
+    id?: string;
+}
+export interface ScoredMemoryBenchmarkEdit {
+    action: MemoryBenchmarkEdit["action"];
+    matchedFactIds: string[];
+    duplicateOf?: string;
+    staleReason?: string;
+    noisyReason?: string;
+}
+export interface MemoryBenchmarkScore {
+    totalEdits: number;
+    matchedFacts: number;
+    precision: number;
+    recall: number;
+    duplicate: number;
+    stale: number;
+    noise: number;
+    uncoveredFactIds: string[];
+    edits: ScoredMemoryBenchmarkEdit[];
+}
+export interface MemoryGradeThresholds {
+    minPrecision: number;
+    minRecall: number;
+    maxDuplicate: number;
+    maxStale: number;
+    maxNoise: number;
+}
+/** Strict-by-default gate: duplicates and stale operations never pass unnoticed. */
+export declare const DEFAULT_MEMORY_GRADE_THRESHOLDS: MemoryGradeThresholds;
+/**
+ * v1 exclusion heuristics for noise ("不该记什么" in mechanical form):
+ * git history, repo paths re-readable from disk, stack traces, and
+ * explicitly temporary session state. Keep this list short and documented —
+ * every pattern here is a precision/recall tradeoff, not ground truth.
+ */
+export declare const MEMORY_NOISE_PATTERNS: readonly RegExp[];
+/** Content shorter than this is too thin to be a durable fact. */
+export declare const MEMORY_MIN_FACT_CHARS = 30;
+/**
+ * Score one proposal against the reference and the pre-extraction manifest.
+ *
+ * @param reference Labeled facts (live + outdated).
+ * @param edits The proposal's memory edits.
+ * @param manifest Memory entries visible before extraction (duplicate source).
+ * @returns Per-dimension counts plus a per-edit breakdown.
+ */
+export declare function scoreMemoryExtraction(reference: MemoryBenchmarkReference, edits: readonly MemoryBenchmarkEdit[], manifest: readonly HarnessEntry[]): MemoryBenchmarkScore;
+/**
+ * Grade a score against explicit thresholds.
+ *
+ * @returns pass plus one failure line per violated dimension (empty when passing).
+ */
+export declare function gradeMemoryScore(score: MemoryBenchmarkScore, thresholds?: MemoryGradeThresholds): {
+    pass: boolean;
+    failures: string[];
+};
+//# sourceMappingURL=memory-benchmark.d.ts.map

package/lib/memory-benchmark.js

@@ -0,0 +1,170 @@
+/**
+ * Memory-specific extraction benchmark (P1): deterministic scoring of one
+ * memory proposal against a labeled reference.
+ *
+ * Unlike the harness benchmark (which runs subagents against rubrics), this
+ * module scores a proposal's SHAPE without any model call: precision and
+ * recall over reference facts, duplicate creates (update-first violations),
+ * stale operations (re-proposing outdated facts, or removing live ones), and
+ * noise (unmatched or exclusion-list material). Suite authors hand-build
+ * small references plus transcripts; the extraction loop under test produces
+ * the proposal, this module grades it.
+ *
+ * Matching is phrase-substring based (case-insensitive): a reference fact
+ * lists must-contain phrases, and a proposed edit matches when its title
+ * plus content carry every phrase. Deliberately mechanical — the benchmark
+ * measures extraction coverage, not paraphrase quality.
+ */
+import { CONFLICT_BLOCK_SCORE, mostSimilarEntry } from "./promotion.js";
+import { isArchived } from "./types.js";
+/** Strict-by-default gate: duplicates and stale operations never pass unnoticed. */
+export const DEFAULT_MEMORY_GRADE_THRESHOLDS = {
+    minPrecision: 0.7,
+    minRecall: 0.7,
+    maxDuplicate: 0,
+    maxStale: 0,
+    maxNoise: 0,
+};
+/**
+ * v1 exclusion heuristics for noise ("不该记什么" in mechanical form):
+ * git history, repo paths re-readable from disk, stack traces, and
+ * explicitly temporary session state. Keep this list short and documented —
+ * every pattern here is a precision/recall tradeoff, not ground truth.
+ */
+export const MEMORY_NOISE_PATTERNS = [
+    /\bgit\s+(log|show|commit|diff)\b/i,
+    /\bcommit\s+[0-9a-f]{5,40}\b/i,
+    /\b[0-9a-f]{40}\b/,
+    /(?:^|[\s("'])((?:src|lib|test|tests|docs|scripts)\/[A-Za-z0-9_./-]+\.[a-z]+)/,
+    /\bat\s+[\w$.]+\s*\(.*:\d+:\d+\)/,
+    /\b(temporary|one-off debugging|current task progress|in this session only)\b/i,
+];
+/** Content shorter than this is too thin to be a durable fact. */
+export const MEMORY_MIN_FACT_CHARS = 30;
+/**
+ * Score one proposal against the reference and the pre-extraction manifest.
+ *
+ * @param reference Labeled facts (live + outdated).
+ * @param edits The proposal's memory edits.
+ * @param manifest Memory entries visible before extraction (duplicate source).
+ * @returns Per-dimension counts plus a per-edit breakdown.
+ */
+export function scoreMemoryExtraction(reference, edits, manifest) {
+    const live = reference.facts.filter((fact) => !fact.outdated);
+    const outdated = reference.facts.filter((fact) => fact.outdated);
+    const liveMatched = new Set();
+    const outdatedHandled = new Set();
+    const scored = [];
+    let duplicate = 0;
+    let stale = 0;
+    let noise = 0;
+    for (const edit of edits) {
+        const text = `${edit.title ?? ""}\n${edit.content ?? ""}`;
+        const liveHits = live.filter((fact) => matchesFact(text, fact));
+        const outdatedHits = outdated.filter((fact) => matchesFact(text, fact));
+        const entry = { action: edit.action, matchedFactIds: [] };
+        if (edit.action === "create" || edit.action === "update") {
+            if (outdatedHits.length > 0) {
+                stale += 1;
+                entry.staleReason = `re-proposes outdated fact(s): ${outdatedHits.map((fact) => fact.id).join(",")}`;
+            }
+            else if (edit.action === "create") {
+                const hit = mostSimilarEntry(manifest.filter((candidate) => candidate.kind === "memory"), edit.title ?? "", edit.content ?? "", CONFLICT_BLOCK_SCORE);
+                if (hit) {
+                    duplicate += 1;
+                    entry.duplicateOf = hit.id;
+                }
+                else if (liveHits.length > 0) {
+                    for (const fact of liveHits) {
+                        liveMatched.add(fact.id);
+                        entry.matchedFactIds.push(fact.id);
+                    }
+                }
+                else {
+                    noise += 1;
+                    entry.noisyReason = noiseReason(text);
+                }
+            }
+            else if (liveHits.length > 0) {
+                for (const fact of liveHits) {
+                    liveMatched.add(fact.id);
+                    entry.matchedFactIds.push(fact.id);
+                }
+            }
+            else {
+                noise += 1;
+                entry.noisyReason = noiseReason(text);
+            }
+        }
+        else {
+            // delete/archive: correct only against outdated facts.
+            const targetHits = [...liveHits, ...outdatedHits];
+            const targetOutdated = outdatedHits.length > 0;
+            const targetEntry = edit.id !== undefined ? manifest.find((candidate) => candidate.id === edit.id) : undefined;
+            if (targetOutdated) {
+                for (const fact of outdatedHits) {
+                    outdatedHandled.add(fact.id);
+                    entry.matchedFactIds.push(fact.id);
+                }
+            }
+            else if (targetEntry !== undefined && isArchived(targetEntry)) {
+                // Re-archiving an already archived entry is harmless housekeeping.
+                entry.matchedFactIds.push(`archived:${targetEntry.id}`);
+            }
+            else if (targetHits.length > 0 || (targetEntry !== undefined && !isArchived(targetEntry))) {
+                stale += 1;
+                entry.staleReason = `removes live fact(s): ${targetHits.map((fact) => fact.id).join(",") || targetEntry?.id || "(unknown target)"}`;
+            }
+            else {
+                noise += 1;
+                entry.noisyReason = "removal matches no reference fact";
+            }
+        }
+        scored.push(entry);
+    }
+    const total = edits.length;
+    const preciseEdits = scored.filter((entry) => entry.matchedFactIds.length > 0).length;
+    const precision = total === 0 ? 1 : preciseEdits / total;
+    const recall = live.length === 0 ? 1 : liveMatched.size / live.length;
+    return {
+        totalEdits: total,
+        matchedFacts: liveMatched.size + outdatedHandled.size,
+        precision,
+        recall,
+        duplicate,
+        stale,
+        noise,
+        uncoveredFactIds: live.filter((fact) => !liveMatched.has(fact.id)).map((fact) => fact.id),
+        edits: scored,
+    };
+}
+/**
+ * Grade a score against explicit thresholds.
+ *
+ * @returns pass plus one failure line per violated dimension (empty when passing).
+ */
+export function gradeMemoryScore(score, thresholds = DEFAULT_MEMORY_GRADE_THRESHOLDS) {
+    const failures = [];
+    if (score.precision < thresholds.minPrecision)
+        failures.push(`precision ${score.precision.toFixed(2)} < ${thresholds.minPrecision}`);
+    if (score.recall < thresholds.minRecall)
+        failures.push(`recall ${score.recall.toFixed(2)} < ${thresholds.minRecall}`);
+    if (score.duplicate > thresholds.maxDuplicate)
+        failures.push(`duplicate ${score.duplicate} > ${thresholds.maxDuplicate}`);
+    if (score.stale > thresholds.maxStale)
+        failures.push(`stale ${score.stale} > ${thresholds.maxStale}`);
+    if (score.noise > thresholds.maxNoise)
+        failures.push(`noise ${score.noise} > ${thresholds.maxNoise}`);
+    return { pass: failures.length === 0, failures };
+}
+function matchesFact(text, fact) {
+    const lowered = text.toLowerCase();
+    return fact.mustContain.every((phrase) => lowered.includes(phrase.toLowerCase()));
+}
+function noiseReason(text) {
+    if (text.trim().length < MEMORY_MIN_FACT_CHARS)
+        return `thin content (<${MEMORY_MIN_FACT_CHARS} chars)`;
+    const hit = MEMORY_NOISE_PATTERNS.findIndex((pattern) => pattern.test(text));
+    return hit >= 0 ? `matches exclusion pattern #${hit + 1}` : "matches no reference fact";
+}
+//# sourceMappingURL=memory-benchmark.js.map

package/lib/notify.d.ts

@@ -29,4 +29,31 @@ export declare function buildGateNotice(result: RefinementResult, turnsSinceLast
  * the decision in reviews.jsonl.
  */
 export declare function notifyAutoReview(ctx: Context, agent: Agent, result: RefinementResult, turnsSinceLastReview: number): void;
+/** Unified extraction receipt: one shape for applied / declined / no-op. */
+export interface MemoryReceipt {
+    outcome: "applied" | "declined" | "noop";
+    /** Applied refinement batches (one per scope) for applied outcomes. */
+    results?: RefinementResult[];
+    /** Scopes the human explicitly declined. */
+    declinedScopes?: string[];
+    /** Extractor loop turns / manifest searches / wall time. */
+    turns: number;
+    searches: number;
+    durationMs: number;
+}
+/**
+ * Compose the user-visible memory receipt from applied refinement batches
+ * (never model text): every landed memory edit with its rollback command.
+ * No-op and declined-only outcomes render one quiet line each — a foreground
+ * notice for zero landed edits would be nagging, so callers only queue
+ * follow-ups for applied outcomes.
+ */
+export declare function buildMemoryReceipt(receipt: MemoryReceipt): string;
+/**
+ * Queue the memory receipt follow-up. Same containment as the gate notice:
+ * notification failure only logs. Callers gate on applied outcomes — no-op
+ * and declined-only runs stay audit-only (reviews.jsonl) and never wake
+ * the agent.
+ */
+export declare function notifyMemoryExtraction(ctx: Context, agent: Agent, receipt: MemoryReceipt): void;
 //# sourceMappingURL=notify.d.ts.map

package/lib/notify.js

@@ -40,4 +40,57 @@ export function notifyAutoReview(ctx, agent, result, turnsSinceLastReview) {
             .warn(`auto-review notice failed for ${agent.id}: ${cause instanceof Error ? cause.message : String(cause)}`);
     }
 }
+/**
+ * Compose the user-visible memory receipt from applied refinement batches
+ * (never model text): every landed memory edit with its rollback command.
+ * No-op and declined-only outcomes render one quiet line each — a foreground
+ * notice for zero landed edits would be nagging, so callers only queue
+ * follow-ups for applied outcomes.
+ */
+export function buildMemoryReceipt(receipt) {
+    const seconds = (receipt.durationMs / 1000).toFixed(1);
+    const stats = `${receipt.turns} 轮推理 / ${receipt.searches} 次检索 / ${seconds}s`;
+    if (receipt.outcome === "noop") {
+        return `🧠 记忆提取：本轮无可沉淀的持久事实（no-op，${stats}），未写入任何条目。`;
+    }
+    if (receipt.outcome === "declined" || (receipt.results ?? []).length === 0) {
+        const scopes = (receipt.declinedScopes ?? []).join("、") || "持久化作用域";
+        return `🧠 记忆提取：${scopes}的写入未获批准，已跳过（${stats}），未写入任何条目。`;
+    }
+    const results = receipt.results ?? [];
+    const applied = results.flatMap((result) => result.appliedEdits.filter((edit) => edit.applied));
+    const lines = applied.slice(0, 12).map((edit) => `- 记忆「${edit.title ?? edit.id}」（${edit.id}）`);
+    if (applied.length > 12)
+        lines.push(`- …另有 ${applied.length - 12} 条（见 /evolve history）`);
+    const declined = (receipt.declinedScopes ?? []).length > 0 ? `\n另有作用域${(receipt.declinedScopes ?? []).join("、")}未经批准（已跳过）。` : "";
+    const rollbacks = [...new Set(results.map((result) => result.id))].map((id) => `/evolve rollback ${id}`).join("；");
+    return [
+        `🧠 记忆提取：本轮沉淀 ${applied.length} 条记忆（${results.length} 个作用域批次，${stats}）：`,
+        lines.length > 0 ? lines.join("\n") : "（无条目成功应用）",
+        declined,
+        `回看：/evolve recall <关键词>；回滚：${rollbacks}`,
+        "请用一句话简短确认即可，不要调用任何工具。",
+    ]
+        .filter((part) => part !== "")
+        .join("\n");
+}
+/**
+ * Queue the memory receipt follow-up. Same containment as the gate notice:
+ * notification failure only logs. Callers gate on applied outcomes — no-op
+ * and declined-only runs stay audit-only (reviews.jsonl) and never wake
+ * the agent.
+ */
+export function notifyMemoryExtraction(ctx, agent, receipt) {
+    try {
+        agent.followup(createUserMessage({
+            content: [{ type: "text", text: buildMemoryReceipt(receipt) }],
+            source: EVOLVE_MESSAGE_SOURCE,
+        }));
+    }
+    catch (cause) {
+        ctx
+            .logger("continual-evolve")
+            .warn(`memory receipt notice failed for ${agent.id}: ${cause instanceof Error ? cause.message : String(cause)}`);
+    }
+}
 //# sourceMappingURL=notify.js.map

package/lib/projection.d.ts

@@ -0,0 +1,22 @@
+import type { HarnessState } from "./types.js";
+/** Index file name at the store root. */
+export declare const MEMORY_INDEX_FILE = "MEMORY.md";
+/** Per-fact file directory inside the store. */
+export declare const MEMORY_FACTS_DIR = "memory";
+/** Map a memory id to a flat filename (`:` is legal on disk but hostile to tools). */
+export declare function memoryFactFilename(id: string): string;
+/**
+ * Rewrite the whole projection from the post-apply state: index, one file
+ * per memory entry (including archived ones, flagged), and deletion of
+ * files whose ids no longer exist. Deterministic — the same state always
+ * produces the same files.
+ *
+ * @param stateDir The store directory holding harness_state.json.
+ * @param state The freshly persisted state (post-apply, post-rollback).
+ */
+export declare function materializeMemoryProjection(stateDir: string, state: HarnessState): void;
+/** Read back one projected fact file (round-trip helper for tests and tools). */
+export declare function readMemoryFact(factsDir: string, filename: string): string;
+/** True when the store directory carries a projection from a previous apply. */
+export declare function hasMemoryProjection(stateDir: string): boolean;
+//# sourceMappingURL=projection.d.ts.map

package/lib/projection.js

@@ -0,0 +1,112 @@
+/**
+ * Readable Markdown projection (P1): a ZCode-style `MEMORY.md` index plus
+ * one file per memory fact, materialized from the JSON store.
+ *
+ * The JSON harness state stays the single source of truth (versions,
+ * rollback, audit). The projection is a derived, human-trustable view:
+ * it is rewritten from the post-apply state inside the engine, so the
+ * model can never write it directly and rollback/archive stay in sync.
+ *
+ * Layout per store directory:
+ *
+ *   <stateDir>/MEMORY.md          one line per memory entry
+ *   <stateDir>/memory/<file>.md   one fact per file with frontmatter
+ */
+import { existsSync, mkdirSync, readdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { isArchived, isMemoryType, MEMORY_TYPE_KEY } from "./types.js";
+/** Index file name at the store root. */
+export const MEMORY_INDEX_FILE = "MEMORY.md";
+/** Per-fact file directory inside the store. */
+export const MEMORY_FACTS_DIR = "memory";
+/** Map a memory id to a flat filename (`:` is legal on disk but hostile to tools). */
+export function memoryFactFilename(id) {
+    return `${id.replace(/:/g, "_")}.md`;
+}
+/**
+ * Rewrite the whole projection from the post-apply state: index, one file
+ * per memory entry (including archived ones, flagged), and deletion of
+ * files whose ids no longer exist. Deterministic — the same state always
+ * produces the same files.
+ *
+ * @param stateDir The store directory holding harness_state.json.
+ * @param state The freshly persisted state (post-apply, post-rollback).
+ */
+export function materializeMemoryProjection(stateDir, state) {
+    const entries = Object.values(state.entries.memory).sort((a, b) => a.id < b.id ? -1 : a.id > b.id ? 1 : 0);
+    const factsDir = join(stateDir, MEMORY_FACTS_DIR);
+    mkdirSync(factsDir, { recursive: true });
+    const expected = new Map();
+    for (const entry of entries) {
+        let filename = memoryFactFilename(entry.id);
+        let suffix = 1;
+        while (expected.has(filename)) {
+            suffix += 1;
+            filename = `${memoryFactFilename(entry.id).replace(/\.md$/, "")}~${suffix}.md`;
+        }
+        expected.set(filename, entry);
+    }
+    for (const [filename, entry] of expected) {
+        writeFileSync(join(factsDir, filename), renderMemoryFact(entry), { encoding: "utf8", mode: 0o600 });
+    }
+    // Sweep facts whose entries vanished (delete); archived entries keep
+    // their file with archived:true frontmatter.
+    let existing;
+    try {
+        existing = readdirSync(factsDir).filter((file) => file.endsWith(".md"));
+    }
+    catch {
+        existing = [];
+    }
+    for (const file of existing) {
+        if (!expected.has(file)) {
+            try {
+                unlinkSync(join(factsDir, file));
+            }
+            catch {
+                // A stale fact file must not break the apply path; the next
+                // materialization retries the sweep.
+            }
+        }
+    }
+    writeFileSync(join(stateDir, MEMORY_INDEX_FILE), renderMemoryIndex([...expected]), { encoding: "utf8", mode: 0o600 });
+}
+/** Read back one projected fact file (round-trip helper for tests and tools). */
+export function readMemoryFact(factsDir, filename) {
+    return readFileSync(join(factsDir, filename), "utf8");
+}
+/** True when the store directory carries a projection from a previous apply. */
+export function hasMemoryProjection(stateDir) {
+    return existsSync(join(stateDir, MEMORY_INDEX_FILE)) && existsSync(join(stateDir, MEMORY_FACTS_DIR));
+}
+function renderMemoryFact(entry) {
+    const type = isMemoryType(entry.metadata[MEMORY_TYPE_KEY]) ? String(entry.metadata[MEMORY_TYPE_KEY]) : "untyped";
+    const frontmatter = [
+        "---",
+        `id: ${entry.id}`,
+        `scope: ${entry.scope}`,
+        `kind: memory`,
+        `memoryType: ${type}`,
+        `version: ${entry.version}`,
+        `path: ${entry.path}`,
+        `archived: ${isArchived(entry)}`,
+        `created_at: ${entry.created_at}`,
+        `updated_at: ${entry.updated_at}`,
+        "---",
+    ].join("\n");
+    return `${frontmatter}\n\n# ${entry.title}\n\n${entry.content}\n`;
+}
+function renderMemoryIndex(files) {
+    const lines = ["# Memory Index", "", "Derived from the JSON harness state — do not edit by hand; it is rewritten on every memory apply.", ""];
+    if (files.length === 0) {
+        lines.push("(no memory entries yet)");
+        return `${lines.join("\n")}\n`;
+    }
+    for (const [file, entry] of files) {
+        const type = isMemoryType(entry.metadata[MEMORY_TYPE_KEY]) ? String(entry.metadata[MEMORY_TYPE_KEY]) : "untyped";
+        const archived = isArchived(entry) ? ", archived" : "";
+        lines.push(`- [${entry.scope}:${entry.id}] ${entry.title} (type=${type}, v${entry.version}${archived}) → ${MEMORY_FACTS_DIR}/${file}`);
+    }
+    return `${lines.join("\n")}\n`;
+}
+//# sourceMappingURL=projection.js.map

package/lib/recall.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Targeted memory recall (P1): the precise-reading counterpart of the cheap
+ * directory index.
+ *
+ * The injected directory view (`inject.ts`) shows one line per entry and the
+ * full `evolve_list` dumps whole stores; neither answers "give me everything
+ * about X". Recall fills that gap: filter by query/kind/scope/memory-type,
+ * rank with the same CJK BM25 machinery as injection, and return full
+ * content plus source, version, and staleness signals. Read-only — it never
+ * mutates a store.
+ */
+import type { EvolutionEngine } from "./service.js";
+import type { HarnessScope, RefinementKind } from "./types.js";
+/** Memory recall types (the `memoryType` taxonomy, not entry kinds). */
+export declare const RECALL_MEMORY_TYPES: readonly ["user", "feedback", "project", "reference"];
+export type RecallMemoryType = (typeof RECALL_MEMORY_TYPES)[number];
+/** Default and maximum hits returned per recall call. */
+export declare const DEFAULT_RECALL_LIMIT = 10;
+export declare const MAX_RECALL_LIMIT = 50;
+export interface RecallFilters {
+    /** Free-text relevance query; empty means "most recently updated first". */
+    query?: string;
+    /** Entry kinds to search; default is memory only. */
+    kinds?: RefinementKind[];
+    /** Stores to search; default is local + project + global. */
+    scopes?: HarnessScope[];
+    /** Memory-type filter (applies to memory entries only). */
+    memoryTypes?: RecallMemoryType[];
+    /** Maximum hits; clamped to 1..50, defaults to 10. */
+    limit?: number;
+    /** Include archived entries; default false. */
+    includeArchived?: boolean;
+}
+/** One recalled entry with full content and provenance. */
+export interface RecallHit {
+    scope: HarnessScope;
+    kind: RefinementKind;
+    id: string;
+    title: string;
+    content: string;
+    path: string;
+    version: number;
+    createdAt: string;
+    updatedAt: string;
+    archived: boolean;
+    /** Memory-type hook for memory entries; undefined for other kinds. */
+    memoryType?: string;
+    /** Conflict-hint stamp left by the promotion guard, when present. */
+    staleHint?: string;
+    /** Session the entry was distilled from, when recorded. */
+    sourceSession?: string;
+    /** Source user-message seqs, when recorded. */
+    sourceSeqs?: number[];
+}
+export interface RecallResult {
+    hits: RecallHit[];
+    /** Skipped scopes with reasons (read-path honesty: never silently drop a store). */
+    notes: string[];
+    /** Candidates seen before ranking/truncation. */
+    totalCandidates: number;
+}
+export interface RecallContext {
+    /** Live session id for the local store; absent → local is skipped with a note. */
+    sessionId?: string | undefined;
+    /** Resolved project key; absent → project is skipped with a note. */
+    projectKey?: string | undefined;
+}
+/**
+ * Search the harness stores with mechanical filters and BM25 ranking.
+ *
+ * @param engine The evolution engine (read-only use).
+ * @param context Store identities for the session-scoped stores.
+ * @param filters Query/kind/scope/type/limit/archive filters.
+ * @returns Ranked hits plus a note for every scope that could not be read.
+ * @throws On an unknown kind, scope, or memory type — fail loud instead of
+ *         silently narrowing the search.
+ */
+export declare function recallMemories(engine: EvolutionEngine, context: RecallContext, filters?: RecallFilters): RecallResult;
+/**
+ * Render recall hits for a model or human reader: full content, version,
+ * source, and staleness on every hit; skipped scopes are always shown so
+ * "no results" can never hide an unread store.
+ */
+export declare function formatRecallResult(result: RecallResult, query?: string): string;
+//# sourceMappingURL=recall.d.ts.map