@deepstrike/sdk 0.2.39 → 0.2.40

package/dist/memory/agent.d.ts

@@ -1,66 +1,33 @@
 /**
  * Long-term memory agent implementation (Phase 7).
  *
- * Provides two main capabilities:
- * 1. Extract memories from conversation transcripts (后台代理)
- * 2. Select relevant memories for current context (LLM选择器)
+ * Provides deterministic selection and boundary validation for long-term memories.
  *
  * Design principles:
  * - Kernel defines memory types and validation rules
  * - SDK performs I/O and selection
- * - LLM (Sonnet) acts as selector, not vector similarity
+ * - Semantic reranking remains an optional DreamStore capability
  */
-import type { SessionData, MemoryEntry, MemoryKind, MemoryMetadata, MemoryWriteRequest, MemoryQuery, MemoryRetrieval } from "./protocols.js";
-export type { MemoryKind, MemoryMetadata, MemoryWriteRequest, MemoryQuery, MemoryRetrieval, } from "./protocols.js";
-/**
- * Memory index entry (from MEMORY.md).
- */
-export interface MemoryIndexEntry {
-    name: string;
-    description: string;
-    kind?: MemoryKind;
-    file: string;
-    updated_at: number;
-}
-/**
- * Extract memories from a completed session.
- *
- * This is typically called by a background agent after a session completes.
- * It analyzes the conversation and generates new memory write requests.
- *
- * @param sessionData - The completed session data
- * @param existingMemories - Existing memories to avoid duplicates
- * @returns Array of memory write requests
- */
-export declare function extractMemories(sessionData: SessionData, existingMemories: MemoryEntry[]): Promise<MemoryWriteRequest[]>;
+import type { MemoryQuery, MemoryRecall, MemoryRecord } from "./protocols.js";
+export type { MemoryKind, MemoryQuery, MemoryRecall, MemoryRecord, } from "./protocols.js";
 /**
  * Select relevant memories for the current context.
  *
- * This uses an LLM (Sonnet) as a selector, not vector similarity.
- * The process:
- * 1. Read memory index (name + description for each memory)
- * 2. Filter out already_surfaced and recentTools
- * 3. Send the filtered list to LLM with current context
- * 4. LLM returns top-5 most relevant memory IDs
+ * The reference selector is deterministic and provider-independent: lexical overlap first,
+ * recency second. Semantic/embedding reranking belongs in a DreamStore plugin.
  *
  * @param query - Memory query from kernel
  * @param memoryIndex - Memory index entries
  * @param model - Optional model name (default: claude-sonnet-4-20250514)
  * @returns Memory retrieval result
  */
-export declare function selectMemories(query: MemoryQuery, memoryIndex: MemoryIndexEntry[], model?: string): Promise<MemoryRetrieval>;
+export declare function selectMemories(query: MemoryQuery, records: MemoryRecord[]): Promise<MemoryRecall[]>;
 /**
  * Validate memory before writing (kernel-side validation mirror).
  *
  * This SDK-side validation provides early feedback before sending to kernel.
  */
-export declare function validateMemory(request: MemoryWriteRequest): {
+export declare function validateMemory(record: MemoryRecord): {
     valid: boolean;
     error?: string;
 };
-/**
- * Infer memory kind from metadata (mirrors kernel logic).
- */
-export declare function inferMemoryKind(metadata: MemoryMetadata): MemoryKind;
-/** Build a memory index from DreamStore entries for {@link selectMemories}. */
-export declare function memoriesToIndex(entries: MemoryEntry[]): MemoryIndexEntry[];

package/dist/memory/agent.js

@@ -1,151 +1,68 @@
 /**
  * Long-term memory agent implementation (Phase 7).
  *
- * Provides two main capabilities:
- * 1. Extract memories from conversation transcripts (后台代理)
- * 2. Select relevant memories for current context (LLM选择器)
+ * Provides deterministic selection and boundary validation for long-term memories.
  *
  * Design principles:
  * - Kernel defines memory types and validation rules
  * - SDK performs I/O and selection
- * - LLM (Sonnet) acts as selector, not vector similarity
+ * - Semantic reranking remains an optional DreamStore capability
  */
-/**
- * Extract memories from a completed session.
- *
- * This is typically called by a background agent after a session completes.
- * It analyzes the conversation and generates new memory write requests.
- *
- * @param sessionData - The completed session data
- * @param existingMemories - Existing memories to avoid duplicates
- * @returns Array of memory write requests
- */
-export async function extractMemories(sessionData, existingMemories) {
-    // In a real implementation, this would:
-    // 1. Use an LLM to analyze the session transcript
-    // 2. Identify new insights, preferences, and context
-    // 3. Generate memory write requests with proper classification
-    // 4. Check for duplicates against existing memories
-    // For now, return a stub implementation
-    return [];
-}
+import { rankMemories } from "./ranking.js";
 /**
  * Select relevant memories for the current context.
  *
- * This uses an LLM (Sonnet) as a selector, not vector similarity.
- * The process:
- * 1. Read memory index (name + description for each memory)
- * 2. Filter out already_surfaced and recentTools
- * 3. Send the filtered list to LLM with current context
- * 4. LLM returns top-5 most relevant memory IDs
+ * The reference selector is deterministic and provider-independent: lexical overlap first,
+ * recency second. Semantic/embedding reranking belongs in a DreamStore plugin.
  *
  * @param query - Memory query from kernel
  * @param memoryIndex - Memory index entries
  * @param model - Optional model name (default: claude-sonnet-4-20250514)
  * @returns Memory retrieval result
  */
-export async function selectMemories(query, memoryIndex, model = "claude-sonnet-4-20250514") {
-    // 1. Filter out already surfaced and tool-related memories
-    const filterOut = new Set([
-        ...query.already_surfaced,
-        ...query.active_tools,
-    ]);
-    const candidates = memoryIndex.filter((entry) => !filterOut.has(entry.name) && !isToolMemory(entry));
-    // 2. If no candidates, return empty
-    if (candidates.length === 0) {
-        return {
-            selected_memory_ids: [],
-            selection_rationale: "No candidates after filtering",
-        };
-    }
-    // 3. In a real implementation, this would:
-    // - Construct a prompt with current context and memory descriptions
-    // - Call the LLM API
-    // - Parse the response to extract selected memory IDs
-    // For now, return a stub implementation
-    return {
-        selected_memory_ids: candidates.slice(0, query.top_k).map((c) => c.name),
-        selection_rationale: "Stub implementation",
-    };
-}
-/**
- * Check if a memory is tool-related (should be filtered from recentTools).
- */
-function isToolMemory(entry) {
-    const toolKeywords = ["usage", "how to use", "example", "syntax", "api"];
-    const lowerDesc = entry.description.toLowerCase();
-    const lowerName = entry.name.toLowerCase();
-    // Filter out usage docs, but keep warnings/caveats
-    const isUsage = toolKeywords.some((kw) => lowerDesc.includes(kw) || lowerName.includes(kw));
-    const isWarning = lowerDesc.includes("warning") || lowerDesc.includes("caveat") || lowerDesc.includes("bug");
-    return isUsage && !isWarning;
+export async function selectMemories(query, records) {
+    const candidates = records.filter(record => record.scope.tenant_id === query.scope.tenant_id
+        && record.scope.namespace === query.scope.namespace
+        && (query.kinds.length === 0 || query.kinds.includes(record.kind)));
+    const ranked = rankMemories(query.query, candidates.map((record, insertionIndex) => ({
+        value: record,
+        searchableText: `${record.name} ${record.description} ${record.content}`,
+        updatedAt: Number.isFinite(record.updated_at) ? record.updated_at : 0,
+        recallCount: record.recall_count,
+        ttlDays: record.ttl_days,
+        insertionIndex,
+    })), query.top_k);
+    // score is relevance (from ranking), deliberately distinct from the record's stored confidence.
+    return ranked
+        .filter(hit => query.min_score === undefined || hit.score >= query.min_score)
+        .map(hit => ({ record: hit.value, score: hit.score, why: hit.why }));
 }
 /**
  * Validate memory before writing (kernel-side validation mirror).
  *
  * This SDK-side validation provides early feedback before sending to kernel.
  */
-export function validateMemory(request) {
+export function validateMemory(record) {
     // Check required fields
-    if (!request.metadata.name || request.metadata.name.trim().length === 0) {
+    if (!record.record_id || record.record_id.trim().length === 0) {
+        return { valid: false, error: "Missing required field: record_id" };
+    }
+    if (!record.scope.tenant_id || !record.scope.namespace) {
+        return { valid: false, error: "Missing required field: scope" };
+    }
+    if (!record.name || record.name.trim().length === 0) {
         return { valid: false, error: "Missing required field: name" };
     }
-    if (!request.metadata.description || request.metadata.description.trim().length === 0) {
+    if (!record.description || record.description.trim().length === 0) {
         return { valid: false, error: "Missing required field: description" };
     }
     // Check name length
-    if (request.metadata.name.length > 100) {
-        return { valid: false, error: `Name too long: ${request.metadata.name.length} chars (limit: 100)` };
+    if (record.name.length > 100) {
+        return { valid: false, error: `Name too long: ${record.name.length} chars (limit: 100)` };
     }
     // Check content size
-    if (request.content.length > 10_000) {
-        return { valid: false, error: `Content too large: ${request.content.length} bytes (limit: 10000)` };
-    }
-    // Check forbidden patterns
-    const forbiddenPatterns = [
-        { pattern: "代码模式:", reason: "应从代码推，不应存储" },
-        { pattern: "文件路径:", reason: "应从git推，不应存储" },
-        { pattern: "架构:", reason: "应从实际代码推" },
-        { pattern: "git历史:", reason: "git log是权威" },
-        { pattern: "CLAUDE.md:", reason: "已在文档中" },
-        { pattern: "TODO:", reason: "临时任务不应进记忆" },
-    ];
-    for (const { pattern, reason } of forbiddenPatterns) {
-        if (request.content.includes(pattern)) {
-            return { valid: false, error: `Forbidden pattern '${pattern}': ${reason}` };
-        }
+    if (record.content.length > 10_000) {
+        return { valid: false, error: `Content too large: ${record.content.length} bytes (limit: 10000)` };
     }
     return { valid: true };
 }
-/**
- * Infer memory kind from metadata (mirrors kernel logic).
- */
-export function inferMemoryKind(metadata) {
-    if (metadata.user_role || metadata.expertise_level) {
-        return "user";
-    }
-    if (metadata.preference_rule || metadata.approved_pattern) {
-        return "feedback";
-    }
-    if (metadata.project_phase || metadata.relative_date) {
-        return "project";
-    }
-    if (metadata.external_url || metadata.ticket_ref) {
-        return "reference";
-    }
-    // Default: feedback (most common)
-    return "feedback";
-}
-/** Build a memory index from DreamStore entries for {@link selectMemories}. */
-export function memoriesToIndex(entries) {
-    return entries.map(entry => {
-        const meta = (entry.metadata ?? {});
-        return {
-            name: String(meta.name ?? entry.text.slice(0, 40)),
-            description: String(meta.description ?? entry.text.slice(0, 120)),
-            kind: meta.kind,
-            file: String(meta.file ?? ""),
-            updated_at: Number(meta.updated_at ?? 0),
-        };
-    });
-}

package/dist/memory/extraction.d.ts

@@ -0,0 +1,4 @@
+import type { LLMProvider } from "../types.js";
+import type { MemoryRecord, MemoryScope, SessionData } from "./protocols.js";
+export declare function extractSessionMemories(provider: LLMProvider, session: SessionData, scope: MemoryScope, systemPrompt?: string): Promise<MemoryRecord[]>;
+export declare function parseExtractedMemories(output: string, session: SessionData, scope: MemoryScope): MemoryRecord[];

package/dist/memory/extraction.js

@@ -0,0 +1,79 @@
+const KINDS = new Set(["user", "feedback", "project", "reference"]);
+export async function extractSessionMemories(provider, session, scope, systemPrompt) {
+    const transcript = session.messages
+        .map(message => `[${message.role.toUpperCase()}] ${message.content}`)
+        .join("\n")
+        .slice(0, 8_000);
+    const context = {
+        systemText: [
+            systemPrompt,
+            "Extract durable, reusable facts from this completed session. Return only JSON; do not include transient progress or guesses.",
+        ].filter(Boolean).join("\n\n"),
+        turns: [{
+                role: "user",
+                content: `${transcript}\n\nReturn {"memories":[{"name":"stable-kebab-key","kind":"user|feedback|project|reference","content":"fact","description":"why durable","confidence":0.0,"links":[],"pinned":false,"ttl_days":null,"evidence_refs":[]}]} with at most 10 items. Return {"memories":[]} when nothing is durable.`,
+                toolCalls: [],
+            }],
+    };
+    let output = "";
+    const state = provider.createRunState?.();
+    for await (const event of provider.stream(context, [], undefined, state)) {
+        if (event.type === "text_delta" && "delta" in event)
+            output += event.delta;
+    }
+    return parseExtractedMemories(output, session, scope);
+}
+export function parseExtractedMemories(output, session, scope) {
+    let value;
+    try {
+        value = JSON.parse(output.trim().replace(/^```(?:json)?\s*/i, "").replace(/\s*```$/, ""));
+    }
+    catch {
+        return [];
+    }
+    if (!value || typeof value !== "object" || !Array.isArray(value.memories))
+        return [];
+    const now = session.updatedAtMs;
+    const records = [];
+    for (const raw of value.memories.slice(0, 10)) {
+        if (!raw || typeof raw !== "object")
+            continue;
+        const draft = raw;
+        const name = typeof draft.name === "string" ? draft.name.trim() : "";
+        const kind = typeof draft.kind === "string" && KINDS.has(draft.kind)
+            ? draft.kind
+            : undefined;
+        const content = typeof draft.content === "string" ? draft.content.trim() : "";
+        if (!name || !kind || !content)
+            continue;
+        const confidence = typeof draft.confidence === "number" && Number.isFinite(draft.confidence)
+            ? Math.max(0, Math.min(1, draft.confidence))
+            : 0.5;
+        records.push({
+            record_id: `${scope.tenant_id}:${scope.namespace}:${kind}:${name}`,
+            scope,
+            name,
+            kind,
+            content,
+            description: typeof draft.description === "string" ? draft.description.trim() : "",
+            provenance: {
+                session_id: session.sessionId,
+                author: "extraction",
+                trust: "untrusted",
+                evidence_refs: Array.isArray(draft.evidence_refs)
+                    ? draft.evidence_refs.filter((ref) => typeof ref === "string")
+                    : [],
+            },
+            created_at: now,
+            updated_at: now,
+            recall_count: 0,
+            confidence,
+            links: Array.isArray(draft.links) ? draft.links.filter((link) => typeof link === "string") : [],
+            pinned: draft.pinned === true,
+            ...(typeof draft.ttl_days === "number" && Number.isInteger(draft.ttl_days) && draft.ttl_days > 0
+                ? { ttl_days: draft.ttl_days }
+                : {}),
+        });
+    }
+    return records;
+}

package/dist/memory/in-memory-store.d.ts

@@ -6,32 +6,45 @@
  *
  * Use cases:
  *   - Benchmark A/B variants where memory is on/off (preload via constructor).
- *   - Unit tests that exercise `Agent.dream()` or the `memory_query` path without disk I/O.
+ *   - Unit tests that exercise session extraction or the `memory_query` path without disk I/O.
  *   - Local development / CI where a persistent memory store isn't needed.
  *
- * The `search()` impl is intentionally trivial — it returns the first `topK` memories for the
- * agent regardless of `query`. The kernel ranks by score before deciding what to surface, so the
- * order memories were inserted is what callers see. For semantic search, plug in a real store.
+ * Search returns a genuine relevance score (distinct lexical overlap, lifted by recall history and
+ * lowered by TTL/staleness) — never the record's stored confidence. The store is the authority for
+ * the full record set, so it (M3) bounds itself by value-ordered retention eviction and (M3/M4)
+ * mirrors recall lifecycle and pin state. For semantic search, plug in a real store.
  */
-import type { CurationResult, DreamStore, MemoryEntry, SessionData } from "./protocols.js";
+import type { DreamStore, MemoryQuery, MemoryRecall, MemoryRecallLifecycle, MemoryRecord, SessionData } from "./protocols.js";
+export interface InMemoryDreamStoreOptions {
+    /** Cap the per-agent record set; a write past it evicts the lowest-value unpinned records (M3). */
+    maxRecords?: number;
+    /** Age (days) past which a record's recall relevance is discounted. Default 2. */
+    staleWarningDays?: number;
+    /** Wall-clock source for staleness scoring + recall stamps. Injectable for deterministic tests. */
+    now?: () => number;
+}
 export declare class InMemoryDreamStore implements DreamStore {
     private readonly initialMemories;
-    private sessions;
     private memories;
     /** Sessions persisted via `saveSession`; exposed for test assertions. */
     readonly savedSessions: SessionData[];
+    private readonly maxRecords?;
+    private readonly staleWarningDays;
+    private readonly now;
     /**
      * @param initialMemories Optional seed memories applied to every agent that asks for memories
      *                        for the first time. Useful for benchmark scenarios that preload a fact.
      */
-    constructor(initialMemories?: MemoryEntry[]);
-    /** Pre-populate sessions for a specific agent (test/benchmark setup). */
-    addSession(agentId: string, session: SessionData): void;
-    /** Pre-populate memories for a specific agent (test/benchmark setup). */
-    addMemories(agentId: string, entries: MemoryEntry[]): void;
-    loadSessions(agentId: string): Promise<SessionData[]>;
-    loadMemories(agentId: string): Promise<MemoryEntry[]>;
-    commit(agentId: string, result: CurationResult, existing: MemoryEntry[]): Promise<void>;
-    search(agentId: string, _query: string, topK?: number): Promise<MemoryEntry[]>;
+    constructor(initialMemories?: MemoryRecord[], options?: InMemoryDreamStoreOptions);
+    private recordsFor;
+    upsert(agentId: string, incoming: MemoryRecord): Promise<void>;
+    /** M3: value-ordered retention eviction. Sheds the lowest-value unpinned records — the shared
+     *  deterministic formula, never a blind tail-cut — until the set fits `maxRecords`. */
+    private evictToCapacity;
+    search(agentId: string, query: MemoryQuery): Promise<MemoryRecall[]>;
     saveSession(data: SessionData): Promise<void>;
+    /** M3: mirror the kernel's journaled recall lifecycle into the durable records. */
+    recordRecall(agentId: string, recalls: MemoryRecallLifecycle[]): Promise<void>;
+    /** M4: set a record's pin so retention eviction cannot shed it. */
+    setPinned(agentId: string, recordId: string, pinned: boolean): Promise<void>;
 }

package/dist/memory/in-memory-store.js

@@ -1,30 +1,24 @@
+import { rankMemories } from "./ranking.js";
+import { memoryRetentionScore } from "./retention.js";
 export class InMemoryDreamStore {
     initialMemories;
-    sessions = new Map();
     memories = new Map();
     /** Sessions persisted via `saveSession`; exposed for test assertions. */
     savedSessions = [];
+    maxRecords;
+    staleWarningDays;
+    now;
     /**
      * @param initialMemories Optional seed memories applied to every agent that asks for memories
      *                        for the first time. Useful for benchmark scenarios that preload a fact.
      */
-    constructor(initialMemories = []) {
+    constructor(initialMemories = [], options = {}) {
         this.initialMemories = initialMemories;
+        this.maxRecords = options.maxRecords;
+        this.staleWarningDays = options.staleWarningDays ?? 2;
+        this.now = options.now ?? Date.now;
     }
-    /** Pre-populate sessions for a specific agent (test/benchmark setup). */
-    addSession(agentId, session) {
-        const list = this.sessions.get(agentId) ?? [];
-        list.push(session);
-        this.sessions.set(agentId, list);
-    }
-    /** Pre-populate memories for a specific agent (test/benchmark setup). */
-    addMemories(agentId, entries) {
-        this.memories.set(agentId, [...(this.memories.get(agentId) ?? []), ...entries]);
-    }
-    async loadSessions(agentId) {
-        return this.sessions.get(agentId) ?? [];
-    }
-    async loadMemories(agentId) {
+    recordsFor(agentId) {
         if (this.memories.has(agentId))
             return this.memories.get(agentId);
         if (this.initialMemories.length > 0) {
@@ -33,18 +27,73 @@ export class InMemoryDreamStore {
         }
         return [];
     }
-    async commit(agentId, result, existing) {
-        const kept = existing.filter((_, i) => !result.toRemoveIndices.includes(i));
-        this.memories.set(agentId, [...kept, ...result.toAdd]);
+    async upsert(agentId, incoming) {
+        const kept = [...this.recordsFor(agentId)];
+        const index = kept.findIndex(record => record.scope.tenant_id === incoming.scope.tenant_id
+            && record.scope.namespace === incoming.scope.namespace
+            && record.kind === incoming.kind
+            && record.name === incoming.name);
+        if (index >= 0)
+            kept[index] = incoming;
+        else
+            kept.push(incoming);
+        this.memories.set(agentId, this.evictToCapacity(kept));
+    }
+    /** M3: value-ordered retention eviction. Sheds the lowest-value unpinned records — the shared
+     *  deterministic formula, never a blind tail-cut — until the set fits `maxRecords`. */
+    evictToCapacity(records) {
+        if (this.maxRecords === undefined || records.length <= this.maxRecords)
+            return records;
+        const nowMs = this.now();
+        const scored = records.map((record, insertionIndex) => ({
+            record,
+            insertionIndex,
+            score: record.pinned ? Number.POSITIVE_INFINITY : memoryRetentionScore(record, nowMs, this.staleWarningDays),
+        }));
+        // Keep the highest-value maxRecords; ties break on insertion order (older first survives).
+        scored.sort((a, b) => b.score - a.score || a.insertionIndex - b.insertionIndex);
+        return scored.slice(0, this.maxRecords).map(entry => entry.record);
     }
-    async search(agentId, _query, topK = 5) {
-        const all = await this.loadMemories(agentId);
-        return all.slice(0, topK);
+    async search(agentId, query) {
+        const all = this.recordsFor(agentId);
+        const candidates = all.filter(record => record.scope.tenant_id === query.scope.tenant_id
+            && record.scope.namespace === query.scope.namespace
+            && (query.kinds.length === 0 || query.kinds.includes(record.kind)));
+        const ranked = rankMemories(query.query, candidates.map((record, insertionIndex) => {
+            return {
+                value: record,
+                searchableText: `${record.name} ${record.description} ${record.content}`,
+                updatedAt: Number.isFinite(record.updated_at) ? record.updated_at : 0,
+                recallCount: record.recall_count,
+                ttlDays: record.ttl_days,
+                insertionIndex,
+            };
+        }), query.top_k, { nowMs: this.now(), staleWarningDays: this.staleWarningDays });
+        return ranked
+            .filter(hit => query.min_score === undefined || hit.score >= query.min_score)
+            .map(hit => ({ record: hit.value, score: hit.score, why: hit.why }));
     }
     async saveSession(data) {
         this.savedSessions.push(data);
-        const list = this.sessions.get(data.agentId) ?? [];
-        list.push(data);
-        this.sessions.set(data.agentId, list);
+    }
+    /** M3: mirror the kernel's journaled recall lifecycle into the durable records. */
+    async recordRecall(agentId, recalls) {
+        const records = this.recordsFor(agentId);
+        for (const recall of recalls) {
+            const record = records.find(candidate => candidate.record_id === recall.record_id);
+            if (record) {
+                record.recall_count = recall.recall_count;
+                record.last_recalled_at = recall.last_recalled_at;
+            }
+        }
+        this.memories.set(agentId, records);
+    }
+    /** M4: set a record's pin so retention eviction cannot shed it. */
+    async setPinned(agentId, recordId, pinned) {
+        const records = this.recordsFor(agentId);
+        const record = records.find(candidate => candidate.record_id === recordId);
+        if (record)
+            record.pinned = pinned;
+        this.memories.set(agentId, records);
     }
 }