dsh-continual-evolve 0.7.6 → 0.8.0

package/lib/recall.js

@@ -0,0 +1,142 @@
+import { buildRelevanceIndex, relevanceScore } from "./search.js";
+import { CONFLICT_HINT_KEY } from "./types.js";
+import { isArchived, isMemoryType, ARCHIVED_AT_KEY, MEMORY_TYPE_KEY, SOURCE_SEQS_KEY, SOURCE_SESSION_KEY } from "./types.js";
+/** Memory recall types (the `memoryType` taxonomy, not entry kinds). */
+export const RECALL_MEMORY_TYPES = ["user", "feedback", "project", "reference"];
+/** Entry kinds recall can filter on; memory is the default. */
+const RECALL_KINDS = ["prompt", "memory", "skill", "subagent"];
+/** Default and maximum hits returned per recall call. */
+export const DEFAULT_RECALL_LIMIT = 10;
+export const MAX_RECALL_LIMIT = 50;
+/**
+ * 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 function recallMemories(engine, context, filters = {}) {
+    const kinds = filters.kinds ?? ["memory"];
+    for (const kind of kinds) {
+        if (!RECALL_KINDS.includes(kind)) {
+            throw new Error(`evolve_recall: unknown kind "${kind}" (expected one of ${RECALL_KINDS.join(", ")})`);
+        }
+    }
+    const scopes = filters.scopes ?? ["local", "project", "global"];
+    for (const scope of scopes) {
+        if (scope !== "local" && scope !== "project" && scope !== "global") {
+            throw new Error(`evolve_recall: unknown scope "${scope}" (expected local, project, or global)`);
+        }
+    }
+    const memoryTypes = filters.memoryTypes ?? [];
+    for (const memoryType of memoryTypes) {
+        if (!RECALL_MEMORY_TYPES.includes(memoryType)) {
+            throw new Error(`evolve_recall: unknown memoryType "${memoryType}" (expected one of ${RECALL_MEMORY_TYPES.join(", ")})`);
+        }
+    }
+    const limit = typeof filters.limit === "number" && Number.isFinite(filters.limit) && filters.limit > 0
+        ? Math.min(Math.floor(filters.limit), MAX_RECALL_LIMIT)
+        : DEFAULT_RECALL_LIMIT;
+    const query = filters.query?.trim() ?? "";
+    const candidates = [];
+    const notes = [];
+    for (const scope of scopes) {
+        const storeId = scope === "local" ? context.sessionId : scope === "project" ? context.projectKey : undefined;
+        if (scope !== "global" && storeId === undefined) {
+            notes.push(`${scope} store skipped: ${scope === "local" ? "no live session id" : "no project key for this session"}`);
+            continue;
+        }
+        let state;
+        try {
+            state = engine.load(scope, storeId);
+        }
+        catch (cause) {
+            notes.push(`${scope} store unreadable: ${cause instanceof Error ? cause.message : String(cause)}`);
+            continue;
+        }
+        for (const kind of kinds) {
+            for (const entry of Object.values(state.entries[kind])) {
+                if (!filters.includeArchived && isArchived(entry))
+                    continue;
+                if (kind === "memory" && memoryTypes.length > 0) {
+                    const type = entry.metadata[MEMORY_TYPE_KEY];
+                    if (typeof type !== "string" || !memoryTypes.includes(type))
+                        continue;
+                }
+                candidates.push(entry);
+            }
+        }
+    }
+    const ranked = query.length > 0 ? rankByRelevance(candidates, query) : [...candidates].sort((a, b) => (a.updated_at < b.updated_at ? 1 : a.updated_at > b.updated_at ? -1 : 0));
+    return { hits: ranked.slice(0, limit).map(toRecallHit), notes, totalCandidates: candidates.length };
+}
+function rankByRelevance(candidates, query) {
+    const index = buildRelevanceIndex(candidates);
+    const normalized = query.trim().toLowerCase();
+    return candidates
+        .map((entry) => {
+        let score = relevanceScore(index, entry, query);
+        // Exact scope:id addressing wins over fuzzy relevance (the
+        // memory-agent manifest search precedent).
+        if (`${entry.scope}:${entry.id}`.toLowerCase() === normalized)
+            score += 1000;
+        return { entry, score };
+    })
+        .filter((hit) => hit.score > 0)
+        .sort((a, b) => b.score - a.score || (a.entry.updated_at < b.entry.updated_at ? 1 : -1))
+        .map((hit) => hit.entry);
+}
+function toRecallHit(entry) {
+    const memoryType = entry.kind === "memory" && isMemoryType(entry.metadata[MEMORY_TYPE_KEY])
+        ? String(entry.metadata[MEMORY_TYPE_KEY])
+        : undefined;
+    const staleHint = typeof entry.metadata[CONFLICT_HINT_KEY] === "string" && entry.metadata[CONFLICT_HINT_KEY].length > 0
+        ? String(entry.metadata[CONFLICT_HINT_KEY])
+        : undefined;
+    const sourceSession = typeof entry.metadata[SOURCE_SESSION_KEY] === "string" ? String(entry.metadata[SOURCE_SESSION_KEY]) : undefined;
+    const rawSeqs = entry.metadata[SOURCE_SEQS_KEY];
+    const sourceSeqs = Array.isArray(rawSeqs) && rawSeqs.every((seq) => typeof seq === "number") ? rawSeqs : undefined;
+    return {
+        scope: entry.scope,
+        kind: entry.kind,
+        id: entry.id,
+        title: entry.title,
+        content: entry.content,
+        path: entry.path,
+        version: entry.version,
+        createdAt: entry.created_at,
+        updatedAt: entry.updated_at,
+        archived: isArchived(entry),
+        ...(memoryType !== undefined ? { memoryType } : {}),
+        ...(staleHint !== undefined ? { staleHint } : {}),
+        ...(sourceSession !== undefined ? { sourceSession } : {}),
+        ...(sourceSeqs !== undefined ? { sourceSeqs } : {}),
+    };
+}
+/**
+ * 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 function formatRecallResult(result, query) {
+    const lines = [`recall: ${result.hits.length} hit(s)${query?.trim() ? ` for "${query.trim()}"` : ""} (${result.totalCandidates} candidate(s))`];
+    for (const hit of result.hits) {
+        const type = hit.memoryType !== undefined ? ` · type=${hit.memoryType}` : "";
+        const archived = hit.archived ? " · archived" : "";
+        const stale = hit.staleHint !== undefined ? ` · conflict-hint=${hit.staleHint}` : "";
+        const source = hit.sourceSession !== undefined ? ` · src=${hit.sourceSession}${hit.sourceSeqs ? `:${hit.sourceSeqs.join(",")}` : ""}` : "";
+        lines.push(`- [${hit.scope}:${hit.kind}:${hit.id}] ${hit.title} (v${hit.version}${type}${archived}${stale}${source})`);
+        lines.push(`  ${hit.content}`);
+    }
+    for (const note of result.notes) {
+        lines.push(`note: ${note}`);
+    }
+    if (result.hits.length === 0) {
+        lines.push(`(${ARCHIVED_AT_KEY} entries are hidden unless includeArchived is set)`);
+    }
+    return lines.join("\n");
+}
+//# sourceMappingURL=recall.js.map

package/lib/service.js

@@ -4,6 +4,7 @@ import { randomUUID } from "node:crypto";
 import { rollbackProposal } from "./rollback.js";
 import { loadHarnessState, saveHarnessState } from "./state.js";
 import { appendResult, loadResults, pruneJsonlFile, pruneSnapshots, resolveHistoryRetention, snapshotBefore, storePaths } from "./store.js";
+import { materializeMemoryProjection } from "./projection.js";
 import { CONFLICT_BLOCK_SCORE, CONFLICT_WARN_SCORE, buildConflictNotice, mostSimilarEntry, secretLeakReason } from "./promotion.js";
 /** A post-commit apply failure that still carries the durable applied result. */
 export class EvolutionApplyPostCommitError extends Error {
@@ -137,6 +138,19 @@ export function createEvolutionEngine(baseDir, hooks = {}, opts = {}) {
         catch {
             // ignored — the next apply retries
         }
+        // Readable Markdown projection (P1): rewritten from the post-apply
+        // state whenever a memory edit landed, so rollback and archive stay
+        // in sync through this same apply path. The model has no writer for
+        // these files — only this engine entry point materializes them.
+        if (result.appliedEdits.some((edit) => edit.applied && edit.kind === "memory")) {
+            try {
+                materializeMemoryProjection(paths.stateDir, state);
+            }
+            catch {
+                // ignored — the projection is derived (JSON stays the source
+                // of truth) and the next memory apply retries
+            }
+        }
         try {
             hooks.onApplied?.(result);
         }

package/lib/tool.js

@@ -5,6 +5,7 @@ import { formatHarnessStateForPrompt } from "./render.js";
 import { requireGlobalApproval } from "./approval.js";
 import { CONFLICT_WARN_SCORE, buildConflictNotice, mostSimilarEntry } from "./promotion.js";
 import { entrySourceOf } from "./source.js";
+import { formatRecallResult, recallMemories } from "./recall.js";
 import { getUsageCount, loadUsage } from "./usage.js";
 import { buildEvolveCompleteEvent, emitEvolveComplete } from "./evolve-event.js";
 import { DEFAULT_REVIEWS_RETAIN } from "./store.js";
@@ -115,6 +116,45 @@ export function registerEvolveTools(ctx, engine, opts) {
             return textResult(text);
         },
     }));
+    ctx.tools.register(defineTool({
+        name: "evolve_recall",
+        description: "Targeted recall over the harness stores: filter memories (or other kinds) by query, kind, scope, and memory type, and read back full content with version, source, and staleness signals. Read-only — it never mutates a store. Prefer this over evolve_list when looking for something specific.",
+        parameters: {
+            query: { type: "string", description: "Free-text relevance query. Empty means most-recently-updated first." },
+            kinds: {
+                type: "array",
+                items: { type: "string" },
+                description: "Entry kinds to search (default memory only).",
+            },
+            scopes: {
+                type: "array",
+                items: { type: "string" },
+                description: "Stores to search (default local, project, and global).",
+            },
+            memoryTypes: {
+                type: "array",
+                items: { type: "string" },
+                description: "Memory-type filter: user, feedback, project, reference (memory entries only).",
+            },
+            limit: { type: "number", description: "Maximum hits (default 10, at most 50)." },
+            includeArchived: { type: "boolean", description: "Include archived entries (default false)." },
+        },
+        output: {
+            schema: { type: "object", additionalProperties: false, properties: { text: { type: "string", required: true } } },
+            render: (_args, value) => [{ type: "text", text: value.text ?? "" }],
+        },
+        execute: async (args, exec) => {
+            const result = recallMemories(engine, { sessionId: sessionIdOf(exec), projectKey: projectKeyOf(exec.agent) ?? undefined }, {
+                ...(typeof args.query === "string" ? { query: args.query } : {}),
+                ...(Array.isArray(args.kinds) ? { kinds: args.kinds } : {}),
+                ...(Array.isArray(args.scopes) ? { scopes: args.scopes } : {}),
+                ...(Array.isArray(args.memoryTypes) ? { memoryTypes: args.memoryTypes } : {}),
+                ...(typeof args.limit === "number" ? { limit: args.limit } : {}),
+                ...(typeof args.includeArchived === "boolean" ? { includeArchived: args.includeArchived } : {}),
+            });
+            return textResult(formatRecallResult(result, typeof args.query === "string" ? args.query : undefined));
+        },
+    }));
     ctx.tools.register(defineTool({
         name: "evolve_add",
         description: "Create one harness entry (prompt/memory/skill/subagent). Executable skills require reference {type:python, import, callable} and an arguments contract; guidance skills (skill_kind=guidance) are SKILL.md documents — recurring multi-step workflows — and must NOT carry a reference. Snapshot, version, and history are handled automatically.",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-continual-evolve",
-  "version": "0.7.6",
+  "version": "0.8.0",
   "description": "Continual self-evolution plugin for DeepSeek Harness: versioned, auditable, rollback-safe harness state (prompt notes, memories, skills, subagent specs) refined from session trajectories.",
   "license": "MIT",
   "repository": {