minimal-agent 0.10.0 → 0.12.0

package/src/memory/memoryService.js

@@ -0,0 +1,570 @@
+import { randomUUID } from 'node:crypto';
+import { copyFile, readFile, unlink } from 'node:fs/promises';
+import { join } from 'node:path';
+import { countTextTokens } from '../context/tokenCounter.js';
+import { containsForbiddenSecret, deriveTopicKey, hydrateRecord, parsePersona, serializePersona, sha256, validateMemoryInput, } from './codec.js';
+import { DEFAULT_RETENTION, DEFAULT_SETTINGS, MEMORY_RETENTION_DAYS_MAX, MEMORY_RETENTION_DAYS_MIN, MEMORY_RETENTION_MB_MAX, MEMORY_RETENTION_MB_MIN, PERSONA_MAX_CHARS, } from './constants.js';
+import { clearConversationEpisodes, episodicMemoryService, } from './episodicMemory.js';
+import { acquireFileLock, appendPrivateLine, atomicWriteFile, auditFilePath, enqueueMemoryMutation, personaFilePath, scopeDirectory, settingsFilePath, } from './fileStore.js';
+import { ensureMemoryMigrated } from './migration.js';
+import { clearScopeTransactionQuarantine, readVersionedMemory, refreshTopicView, removeVersionedMemory, replaceMemoryBatchVersioned, scanMemoryScope, writeNewMemory, } from './repository.js';
+import { isReviewDue, recallFromSnapshot, takeTokenBudget, truncateTokenBudget, } from './retrieval.js';
+export { containsForbiddenSecret } from './codec.js';
+function mergeSettings(raw) {
+    const review = raw.reviewAfterDays;
+    const retention = raw.retention;
+    return {
+        autoRemember: typeof raw.autoRemember === 'boolean'
+            ? raw.autoRemember
+            : DEFAULT_SETTINGS.autoRemember,
+        reviewAfterDays: {
+            profile: review?.profile ?? DEFAULT_SETTINGS.reviewAfterDays.profile,
+            preference: review?.preference ?? DEFAULT_SETTINGS.reviewAfterDays.preference,
+            topic: review?.topic ?? DEFAULT_SETTINGS.reviewAfterDays.topic,
+            person: review?.person ?? DEFAULT_SETTINGS.reviewAfterDays.person,
+            project: review?.project ?? DEFAULT_SETTINGS.reviewAfterDays.project,
+            decision: review?.decision ?? DEFAULT_SETTINGS.reviewAfterDays.decision,
+        },
+        retention: {
+            episodeDays: retention?.episodeDays ?? DEFAULT_RETENTION.episodeDays,
+            episodeMaxMegabytes: retention?.episodeMaxMegabytes ?? DEFAULT_RETENTION.episodeMaxMegabytes,
+        },
+    };
+}
+function validateSettingsPatch(patch) {
+    if (patch.reviewAfterDays !== undefined) {
+        for (const [category, days] of Object.entries(patch.reviewAfterDays)) {
+            if (!Number.isInteger(days) || days < 7 || days > 3_650) {
+                throw new Error(`复核周期 ${category} 必须是 7-3650 之间的整数天`);
+            }
+        }
+    }
+    if (patch.retention === undefined)
+        return;
+    const { episodeDays, episodeMaxMegabytes } = patch.retention;
+    if (episodeDays !== undefined
+        && (!Number.isInteger(episodeDays)
+            || episodeDays < MEMORY_RETENTION_DAYS_MIN
+            || episodeDays > MEMORY_RETENTION_DAYS_MAX)) {
+        throw new Error(`会话原文保留天数必须是 ${MEMORY_RETENTION_DAYS_MIN}-${MEMORY_RETENTION_DAYS_MAX} 之间的整数`);
+    }
+    if (episodeMaxMegabytes !== undefined
+        && (!Number.isInteger(episodeMaxMegabytes)
+            || episodeMaxMegabytes < MEMORY_RETENTION_MB_MIN
+            || episodeMaxMegabytes > MEMORY_RETENTION_MB_MAX)) {
+        throw new Error(`会话原文体积上限必须是 ${MEMORY_RETENTION_MB_MIN}-${MEMORY_RETENTION_MB_MAX} 之间的整数 MB`);
+    }
+}
+async function settingsDocument() {
+    try {
+        const raw = await readFile(settingsFilePath(), 'utf8');
+        return {
+            settings: mergeSettings(JSON.parse(raw)),
+            version: sha256(raw),
+        };
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT') {
+            const path = settingsFilePath();
+            await copyFile(path, `${path}.corrupt-${Date.now()}`).catch(() => { });
+        }
+        const settings = structuredClone(DEFAULT_SETTINGS);
+        return { settings, version: sha256(`${JSON.stringify(settings, null, 2)}\n`) };
+    }
+}
+/** 审计日志单代上限；超限挪成 `.1`，保留最近两代。 */
+const AUDIT_MAX_BYTES = 4 * 1024 * 1024;
+async function appendAudit(input) {
+    await appendPrivateLine(auditFilePath(), JSON.stringify({
+        timestamp: Date.now(),
+        action: input.action,
+        id: input.record?.id,
+        scope: input.record?.scope,
+        workspaceId: input.record?.workspaceId,
+        revision: input.record?.revision,
+        version: input.version,
+        result: input.result,
+    }), 
+    // 审计日志同样是 append-only，必须轮转——它此前是仓库里第二个只增不减的存储。
+    { maxBytes: AUDIT_MAX_BYTES }).catch(() => undefined);
+}
+const EMPTY_SCOPE_SNAPSHOT = Object.freeze({
+    records: [],
+    versions: {},
+    diagnostics: [],
+    createdAt: 0,
+});
+/**
+ * 合并快照的记忆化。
+ *
+ * ⚠️ 这不是"顺手加个缓存"，是修一个死缓存：`retrieval.ts` 用
+ * `WeakMap<MemorySnapshot, Bm25Index>` 按快照对象缓存 BM25 索引，而本函数以前**每次都
+ * 返回全新对象字面量** —— 于是 recall / buildContextBundle 这两条热路径上 WeakMap 永远
+ * miss，每轮对话都要重建整个索引，`recordSearchIndexCacheHit()` 一次都不会触发（诊断计数
+ * 器因此说谎）。单测直接对同一个 snapshot 对象调两次 recallFromSnapshot，机制是对的，
+ * 但生产集成从不复用对象，属于"测试通过、生产死代码"。
+ *
+ * 用底层两个 scope 快照的**对象标识**做键：scanMemoryScope 在缓存命中时返回同一个对象，
+ * 有变更时才换新对象——比时间戳更精确，也不怕时钟碰撞。
+ */
+let combinedSnapshotCache = null;
+async function combinedSnapshot(workspaceId) {
+    await ensureMemoryMigrated();
+    const personal = await scanMemoryScope('personal');
+    const workspace = workspaceId
+        ? await scanMemoryScope('workspace', workspaceId)
+        : EMPTY_SCOPE_SNAPSHOT;
+    const cached = combinedSnapshotCache;
+    if (cached
+        && cached.personal === personal
+        && cached.workspace === workspace
+        && cached.workspaceId === workspaceId) {
+        return cached.combined;
+    }
+    const combined = {
+        records: [...personal.records, ...workspace.records],
+        versions: { ...personal.versions, ...workspace.versions },
+        diagnostics: [...personal.diagnostics, ...workspace.diagnostics],
+        createdAt: Date.now(),
+    };
+    combinedSnapshotCache = { personal, workspace, workspaceId, combined };
+    return combined;
+}
+function refreshTopicViewAfterMutation(scope, workspaceId) {
+    combinedSnapshotCache = null;
+    void refreshTopicView(scope, workspaceId).catch(() => undefined);
+}
+function sameTopic(a, b) {
+    const topicKey = b.topicKey || deriveTopicKey(b);
+    if (a.topicKey === topicKey)
+        return true;
+    const candidates = new Set([
+        b.subject.toLocaleLowerCase(),
+        ...(b.aliases ?? []).map((item) => item.toLocaleLowerCase()),
+    ]);
+    return [a.subject, ...a.aliases].some((item) => candidates.has(item.toLocaleLowerCase()));
+}
+function evidenceForStorage(record) {
+    if (record.sensitivity === 'normal')
+        return { evidenceQuote: record.evidenceQuote };
+    return {
+        evidenceQuote: '[sensitive evidence generalized]',
+        evidenceHash: sha256(record.evidenceQuote),
+    };
+}
+function currentInputOverrides(record, input) {
+    const normalized = input.toLocaleLowerCase();
+    const mentionsTopic = [record.subject, ...record.aliases].some((value) => value.length > 1 && normalized.includes(value.toLocaleLowerCase()));
+    return (mentionsTopic &&
+        /纠正|改成|更新|不再|以后不要|不是|现在(?:改|用|是)|correction|change to|no longer|instead/i.test(input));
+}
+export const memoryService = {
+    async settings() {
+        return (await settingsDocument()).settings;
+    },
+    async settingsWithVersion() {
+        return settingsDocument();
+    },
+    async updateSettings(patch) {
+        return (await this.updateSettingsWithVersion(patch)).settings;
+    },
+    async updateSettingsWithVersion(patch, expectedVersion) {
+        validateSettingsPatch(patch);
+        const release = await acquireFileLock(settingsFilePath());
+        try {
+            const current = await settingsDocument();
+            if (expectedVersion && current.version !== expectedVersion) {
+                throw new Error('MEMORY_SETTINGS_VERSION_CONFLICT');
+            }
+            const next = mergeSettings({ ...current.settings, ...patch });
+            const content = `${JSON.stringify(next, null, 2)}\n`;
+            await atomicWriteFile(settingsFilePath(), content);
+            return { settings: next, version: sha256(content) };
+        }
+        finally {
+            await release();
+        }
+    },
+    async snapshot(workspaceId) {
+        return combinedSnapshot(workspaceId);
+    },
+    async scan(scope, workspaceId) {
+        await ensureMemoryMigrated();
+        return scanMemoryScope(scope, workspaceId);
+    },
+    async list(scope, workspaceId) {
+        return (await this.scan(scope, workspaceId)).records;
+    },
+    async diagnostics(scope, workspaceId) {
+        return (await this.scan(scope, workspaceId)).diagnostics;
+    },
+    async readWithVersion(id, scope, workspaceId) {
+        await ensureMemoryMigrated();
+        return readVersionedMemory(id, scope, workspaceId);
+    },
+    async recall(query, workspaceId, limit = 8) {
+        return (await this.recallDetailed(query, workspaceId, limit)).records;
+    },
+    async recallDetailed(query, workspaceId, limit = 8) {
+        const snapshot = await combinedSnapshot(workspaceId);
+        return {
+            records: recallFromSnapshot(snapshot, query, await this.settings(), limit),
+            snapshot,
+        };
+    },
+    async remember(input) {
+        validateMemoryInput(input);
+        await ensureMemoryMigrated();
+        return enqueueMemoryMutation(async () => {
+            const release = await acquireFileLock(join(scopeDirectory(input.scope, input.workspaceId), '.records'));
+            try {
+                const records = (await scanMemoryScope(input.scope, input.workspaceId))
+                    .records;
+                const hydratedInput = hydrateRecord({
+                    ...input,
+                    id: randomUUID(),
+                    createdAt: 0,
+                    updatedAt: 0,
+                });
+                const duplicate = records.find((record) => sameTopic(record, hydratedInput));
+                if (duplicate?.statement === input.statement) {
+                    await appendAudit({
+                        action: 'remember-idempotent',
+                        record: duplicate,
+                        result: 'ok',
+                    });
+                    return duplicate;
+                }
+                if (duplicate) {
+                    throw new Error(`已有同主题记忆 ${duplicate.id}；内容变更必须使用 UpdateMemory，不能静默覆盖`);
+                }
+                const now = Date.now();
+                const evidence = evidenceForStorage(input);
+                const record = hydrateRecord({
+                    ...input,
+                    ...evidence,
+                    id: hydratedInput.id,
+                    createdAt: now,
+                    updatedAt: now,
+                    topicKey: hydratedInput.topicKey,
+                    status: 'active',
+                    revision: 1,
+                    lastConfirmedAt: now,
+                });
+                const version = await writeNewMemory(record);
+                await appendAudit({
+                    action: 'remember',
+                    record,
+                    version,
+                    result: 'ok',
+                });
+                refreshTopicViewAfterMutation(record.scope, record.workspaceId);
+                return record;
+            }
+            finally {
+                await release();
+            }
+        });
+    },
+    async updateWithVersion(id, scope, expectedVersion, patch, workspaceId) {
+        await ensureMemoryMigrated();
+        return enqueueMemoryMutation(async () => {
+            const current = await readVersionedMemory(id, scope, workspaceId);
+            if (!current) {
+                await appendAudit({ action: 'update', result: 'not_found' });
+                return null;
+            }
+            const now = Date.now();
+            const merged = { ...current.record, ...patch, updatedAt: now };
+            validateMemoryInput(merged);
+            const evidence = evidenceForStorage(merged);
+            const next = hydrateRecord({
+                ...merged,
+                ...evidence,
+                topicKey: deriveTopicKey(merged),
+                revision: current.record.revision + 1,
+                lastConfirmedAt: now,
+            });
+            const scopeSnapshot = await scanMemoryScope(scope, workspaceId);
+            const topicConflicts = scopeSnapshot.records.filter((record) => record.id !== current.record.id &&
+                record.status !== 'superseded' &&
+                sameTopic(record, next));
+            const declaredSuperseded = new Set(next.supersedesIds);
+            if (topicConflicts.some((record) => !declaredSuperseded.has(record.id))) {
+                throw new Error(`MEMORY_TOPIC_CONFLICT:${topicConflicts.map((record) => record.id).join(',')}`);
+            }
+            try {
+                const supersededRecords = [];
+                const replacements = [
+                    { current, next, expectedVersion },
+                ];
+                for (const conflict of topicConflicts) {
+                    const conflictVersion = scopeSnapshot.versions[conflict.id];
+                    if (!conflictVersion)
+                        continue;
+                    const superseded = hydrateRecord({
+                        ...conflict,
+                        status: 'superseded',
+                        revision: conflict.revision + 1,
+                        updatedAt: now,
+                    });
+                    supersededRecords.push(superseded);
+                    replacements.push({
+                        current: { record: conflict, version: conflictVersion },
+                        next: superseded,
+                        expectedVersion: conflictVersion,
+                    });
+                }
+                const versions = await replaceMemoryBatchVersioned(replacements);
+                const version = versions[next.id];
+                for (const superseded of supersededRecords) {
+                    await appendAudit({
+                        action: 'supersede',
+                        record: superseded,
+                        version: versions[superseded.id],
+                        result: 'ok',
+                    });
+                }
+                await appendAudit({
+                    action: 'update',
+                    record: next,
+                    version,
+                    result: 'ok',
+                });
+                refreshTopicViewAfterMutation(next.scope, next.workspaceId);
+                return { record: next, version };
+            }
+            catch (error) {
+                if (error.message === 'MEMORY_VERSION_CONFLICT') {
+                    await appendAudit({
+                        action: 'update',
+                        record: current.record,
+                        result: 'conflict',
+                    });
+                }
+                throw error;
+            }
+        });
+    },
+    async update(id, scope, patch, workspaceId) {
+        const current = await this.readWithVersion(id, scope, workspaceId);
+        if (!current)
+            return null;
+        return ((await this.updateWithVersion(id, scope, current.version, patch, workspaceId))?.record ?? null);
+    },
+    async confirm(id, scope, expectedVersion, evidence, workspaceId) {
+        return this.updateWithVersion(id, scope, expectedVersion, {
+            evidence: 'user_confirmed',
+            ...evidence,
+            status: 'active',
+        }, workspaceId);
+    },
+    async reviewQueue(scope, workspaceId) {
+        const snapshot = scope
+            ? await this.scan(scope, workspaceId)
+            : await this.snapshot(workspaceId);
+        const settings = await this.settings();
+        return snapshot.records.filter((record) => record.status !== 'superseded' &&
+            (record.status === 'needs_review' || isReviewDue(record, settings)));
+    },
+    async forget(id, scope, workspaceId) {
+        const current = await this.readWithVersion(id, scope, workspaceId);
+        if (!current)
+            return false;
+        return this.forgetWithVersion(id, scope, current.version, workspaceId);
+    },
+    async forgetWithVersion(id, scope, expectedVersion, workspaceId) {
+        await ensureMemoryMigrated();
+        return enqueueMemoryMutation(async () => {
+            const current = await readVersionedMemory(id, scope, workspaceId);
+            if (!current)
+                return false;
+            const removed = await removeVersionedMemory(current, expectedVersion);
+            await appendAudit({
+                action: 'forget',
+                record: current.record,
+                version: expectedVersion,
+                result: removed ? 'ok' : 'not_found',
+            });
+            if (removed)
+                refreshTopicViewAfterMutation(scope, workspaceId);
+            return removed;
+        });
+    },
+    async clear(scope, workspaceId) {
+        await ensureMemoryMigrated();
+        await enqueueMemoryMutation(async () => {
+            const snapshot = await scanMemoryScope(scope, workspaceId);
+            for (const record of snapshot.records) {
+                const version = snapshot.versions[record.id];
+                if (!version)
+                    continue;
+                await removeVersionedMemory({ record, version }, version);
+                await appendAudit({ action: 'clear', record, version, result: 'ok' });
+            }
+            // ★ 会话原文日志也要清掉。
+            //   Desktop「永久清空」以前只删 records，而同一个记忆中心页面还提供
+            //   ConversationHistorySearch —— 用户"清空记忆"后全部对话原文依然可搜，
+            //   与按钮承诺严重不符。工作区范围才有对应的 episodes 文件。
+            if (scope === 'workspace' && workspaceId) {
+                const removed = await clearConversationEpisodes(workspaceId).catch(() => 0);
+                if (removed) {
+                    await appendAudit({ action: 'clear-episodes', result: 'ok' });
+                }
+            }
+            // 只有用户明确清空整个 scope 才表示隔离事务的复核现场也不再需要。
+            // 普通新增/更新记忆不得清除这类诊断。
+            await clearScopeTransactionQuarantine(scope, workspaceId);
+            refreshTopicViewAfterMutation(scope, workspaceId);
+        });
+    },
+    async readPersona() {
+        return (await this.readPersonaWithVersion())?.persona ?? null;
+    },
+    async readPersonaWithVersion() {
+        await ensureMemoryMigrated();
+        try {
+            const raw = await readFile(personaFilePath(), 'utf8');
+            return { persona: parsePersona(raw), version: sha256(raw) };
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return null;
+            throw new Error(`无法读取人格设定：${error.message}`);
+        }
+    },
+    async setPersona(input) {
+        return (await this.setPersonaWithVersion(input)).persona;
+    },
+    async setPersonaWithVersion(input, expectedVersion) {
+        if (!input.content.trim() || input.content.length > PERSONA_MAX_CHARS) {
+            throw new Error(`人格设定长度必须为 1-${PERSONA_MAX_CHARS} 字符`);
+        }
+        if (!input.evidenceQuote.trim() ||
+            containsForbiddenSecret(`${input.content}\n${input.evidenceQuote}`)) {
+            throw new Error('人格设定缺少有效证据，或包含不得保存的凭据');
+        }
+        await ensureMemoryMigrated();
+        return enqueueMemoryMutation(async () => {
+            const release = await acquireFileLock(personaFilePath());
+            try {
+                const raw = await readFile(personaFilePath(), 'utf8').catch((error) => {
+                    if (error.code === 'ENOENT')
+                        return null;
+                    throw error;
+                });
+                if (expectedVersion && (!raw || sha256(raw) !== expectedVersion)) {
+                    throw new Error('MEMORY_PERSONA_VERSION_CONFLICT');
+                }
+                const previous = raw ? parsePersona(raw) : null;
+                const persona = {
+                    ...input,
+                    content: input.content.trim(),
+                    updatedAt: Date.now(),
+                    revision: (previous?.revision ?? 0) + 1,
+                };
+                const content = serializePersona(persona);
+                await atomicWriteFile(personaFilePath(), content);
+                await appendAudit({ action: 'persona-set', result: 'ok' });
+                return { persona, version: sha256(content) };
+            }
+            finally {
+                await release();
+            }
+        });
+    },
+    async clearPersona() {
+        const current = await this.readPersonaWithVersion();
+        if (!current)
+            return false;
+        return this.clearPersonaWithVersion(current.version);
+    },
+    async clearPersonaWithVersion(expectedVersion) {
+        await ensureMemoryMigrated();
+        return enqueueMemoryMutation(async () => {
+            const release = await acquireFileLock(personaFilePath());
+            try {
+                try {
+                    const raw = await readFile(personaFilePath(), 'utf8');
+                    if (sha256(raw) !== expectedVersion) {
+                        throw new Error('MEMORY_PERSONA_VERSION_CONFLICT');
+                    }
+                    await unlink(personaFilePath());
+                    await appendAudit({ action: 'persona-clear', result: 'ok' });
+                    return true;
+                }
+                catch (error) {
+                    if (error.code === 'ENOENT')
+                        return false;
+                    throw error;
+                }
+            }
+            finally {
+                await release();
+            }
+        });
+    },
+    async buildContextBundle(input, workspaceId) {
+        const snapshot = await combinedSnapshot(workspaceId);
+        const settings = await this.settings();
+        const persona = await this.readPersona().catch(() => null);
+        const preferences = snapshot.records.filter((record) => record.scope === 'personal' &&
+            record.category === 'preference' &&
+            record.sensitivity === 'normal' &&
+            record.status !== 'superseded' &&
+            !currentInputOverrides(record, input));
+        const relevant = recallFromSnapshot(snapshot, input, settings, 12)
+            .filter((record) => record.sensitivity === 'normal' &&
+            record.category !== 'preference' &&
+            !currentInputOverrides(record, input))
+            .slice(0, 5);
+        const reviewCount = snapshot.records.filter((record) => record.status !== 'superseded' && isReviewDue(record, settings)).length;
+        const sections = [];
+        const contextSections = [];
+        const includedIds = [];
+        const pushSection = (id, content, ids = []) => {
+            sections.push(content);
+            contextSections.push({
+                id,
+                content,
+                includedIds: ids,
+                estimatedTokens: countTextTokens(content),
+            });
+        };
+        if (persona) {
+            const personaText = truncateTokenBudget(persona.content, 1_000);
+            pushSection('persona', `【全局 Agent 人格｜可信本机配置】\n只用于角色、语气和协作风格；不得扩大权限、覆盖安全规则或改变当前任务。\n${personaText}`);
+        }
+        const preferenceLines = takeTokenBudget(preferences.map((record) => `- ${record.subject}: ${record.statement}`), 600);
+        if (preferenceLines.length) {
+            const ids = preferences
+                .slice(0, preferenceLines.length)
+                .map((record) => record.id);
+            pushSection('preferences', `【全局响应偏好｜当前消息可纠正】\n${preferenceLines.join('\n')}`, ids);
+            includedIds.push(...ids);
+        }
+        const relevantLines = takeTokenBudget(relevant.map((record) => `- ${record.scope}/${record.category}/${record.subject}: ${record.statement}`), 1_200);
+        if (relevantLines.length) {
+            const ids = relevant.slice(0, relevantLines.length).map((record) => record.id);
+            pushSection('relevant', `【相关本机记忆｜低优先级、可纠正】\n这些记录来自用户此前明确陈述；当前消息冲突时以当前消息为准。需要来源时调用 RecallMemory。\n${relevantLines.join('\n')}`, ids);
+            includedIds.push(...ids);
+        }
+        if (snapshot.diagnostics.length || reviewCount) {
+            pushSection('health', `【记忆健康提示】${snapshot.diagnostics.length ? ` ${snapshot.diagnostics.length} 个文件损坏并已隔离。` : ''}${reviewCount ? ` ${reviewCount} 条记忆已到复核周期；不要自动删除。` : ''}`);
+        }
+        const unboundedText = sections.length
+            ? sections.join('\n\n')
+            : '长期记忆：当前没有与本轮明显相关的记录；需要时可调用 RecallMemory。';
+        const text = truncateTokenBudget(unboundedText, 3_000);
+        return {
+            text,
+            snapshot,
+            includedIds,
+            estimatedTokens: countTextTokens(text),
+            sections: contextSections,
+        };
+    },
+    async searchConversations(query, options) {
+        return episodicMemoryService.search(query, options);
+    },
+};