evolcore 0.0.28 → 0.0.29

package/dist/core/memory/memory-writer.js

@@ -0,0 +1,432 @@
+/**
+ * memory-writer.ts — pending note 与正式记忆的增改归档（v3）
+ *
+ * 只有整理会话（sessionType=memory）能调用这三个操作，由 ipc.ts 做会话类型与
+ * 模式↔作用域的双重校验后委托到这里。本模块只负责文件层面的动作：
+ *
+ *   - createMemory  新建正式记忆：写 consolidated/、签名、归档 --replaces 的旧文件
+ *   - updateMemory  改标签或续期（--touch），改完重新签名
+ *   - archiveMemory 归档（唯一的下线方式，没有删除）
+ *
+ * 签名基础设施已就绪（signMemoryFile），但验签门控尚未开启——
+ * 门控设计已存档，待后续按需启用。
+ */
+import fs from 'fs';
+import path from 'path';
+import { resolveRoot } from '../../paths.js';
+import { signMemoryFile } from './memory-signature.js';
+import { refreshMemoryMeta } from './index-manager.js';
+import { getMemoryArray, getMemoryString, parseMemoryDocument, serializeMemoryDocument, setMemoryField, } from './memory-document.js';
+const SLUG_RE = /^[a-zA-Z0-9][a-zA-Z0-9-]{0,63}$/;
+/** 与 memory-signature.ts 的 MAX_MEMORY_BYTES 保持一致（10KB）。 */
+const MAX_CONTENT_BYTES = 10 * 1024;
+/** 解析某个作用域的记忆目录。 */
+export function resolveScopeDirs(scope, taskCtx, ownerAid, peerKeyOverride) {
+    const selfAid = taskCtx.selfAid;
+    if (!selfAid)
+        throw new Error('无法确定当前 agent AID（selfAid 为空）');
+    const root = resolveRoot();
+    if (scope === 'agent') {
+        const memoryDir = path.join(root, 'agents', selfAid, 'personal', 'memory');
+        return { memoryDir, consolidatedDir: path.join(memoryDir, 'consolidated') };
+    }
+    if (scope === 'relation') {
+        const peerKey = peerKeyOverride ?? taskCtx.peerKey;
+        if (!peerKey)
+            throw new Error('relation 作用域需要 peerKey（当前会话无对端信息）');
+        // 防止路径穿越：peerKey 不能含路径分隔符或 ..
+        if (peerKey.includes('..') || peerKey.includes('/') || peerKey.includes('\\')) {
+            throw new Error(`INVALID_PEER_KEY: peerKey 格式非法: "${peerKey}"`);
+        }
+        const memoryDir = path.join(root, 'agents', selfAid, 'relations', peerKey, 'memory');
+        return { memoryDir, consolidatedDir: path.join(memoryDir, 'consolidated') };
+    }
+    if (!ownerAid)
+        throw new Error('owner 作用域需要 ownerAid（当前 agent 未配置 owner）');
+    const memoryDir = path.join(root, 'memory', 'owner', ownerAid);
+    return { memoryDir, consolidatedDir: path.join(memoryDir, 'consolidated') };
+}
+/**
+ * 把用户给的路径解析成 consolidated/ 下的绝对路径。
+ * 允许 slug / <slug>.md / 相对或绝对路径（须落在本作用域的 consolidated/ 内）。
+ */
+export function resolveConsolidatedPath(dirs, input) {
+    const base = path.resolve(dirs.consolidatedDir);
+    const looksLikePath = input.includes('/') || input.includes('\\');
+    if (!looksLikePath) {
+        const slug = input.replace(/\.md$/, '');
+        assertSlug(slug);
+        return path.join(base, `${slug}.md`);
+    }
+    // 允许 "consolidated/xxx.md" 这种相对 MEMORY.md 的写法
+    const candidates = [path.resolve(input), path.resolve(dirs.memoryDir, input)];
+    for (const abs of candidates) {
+        const rel = path.relative(base, abs);
+        if (!rel.startsWith('..') && !path.isAbsolute(rel))
+            return abs;
+    }
+    throw new Error(`ROLE_ACCESS_DENIED: 只能操作本作用域 consolidated/ 下的记忆（${base}），当前路径越界: ${input}`);
+}
+function assertSlug(slug) {
+    if (!SLUG_RE.test(slug)) {
+        throw new Error(`slug 格式非法：只允许字母、数字、连字符，长度 1-64，当前值: "${slug}"`);
+    }
+}
+// ── shared memory document helpers ─────────────────────────────────────────
+function readMemory(content) {
+    return parseMemoryDocument(content);
+}
+function writeSignedMemory(document, selfAid) {
+    return signMemoryFile(serializeMemoryDocument(document), selfAid).then(result => result.signed);
+}
+export async function createMemory(req) {
+    assertSlug(req.slug);
+    if (!req.description || req.description.trim() === '')
+        throw new Error('description 不能为空');
+    if (!req.content || req.content.trim() === '')
+        throw new Error('content 不能为空');
+    const bytes = Buffer.byteLength(req.content, 'utf-8');
+    if (bytes > MAX_CONTENT_BYTES) {
+        throw new Error(`MEMORY_TOO_LARGE: content ${bytes} 字节，超过上限 ${MAX_CONTENT_BYTES} 字节（10KB）。` +
+            `一条记忆应当是一句话能说清的结论。内容确实这么多时，请拆成多条分别 create。`);
+    }
+    const dirs = resolveScopeDirs(req.scope, req.taskCtx, req.ownerAid, req.targetPeerKey);
+    fs.mkdirSync(dirs.consolidatedDir, { recursive: true });
+    const targetPath = path.join(dirs.consolidatedDir, `${req.slug}.md`);
+    const replacePaths = (req.replaces ?? []).map(p => resolveConsolidatedPath(dirs, p));
+    // 撞名闸门：目标已存在且没被 --replaces 覆盖 → 拒绝
+    if (fs.existsSync(targetPath) && !replacePaths.includes(targetPath)) {
+        throw new Error(`SLUG_EXISTS: 目标已存在: ${targetPath}\n` +
+            `如果要替换它，请在 --replaces 里列出该路径；如果是新记忆，请换一个 slug。`);
+    }
+    // profile 唯一性：一个关系只能有一条 profile 记忆
+    if (req.tags.includes('profile')) {
+        const others = findProfileMemories(dirs, targetPath);
+        for (const other of others) {
+            if (!replacePaths.includes(other)) {
+                throw new Error(`PROFILE_EXISTS: 该作用域已有画像记忆: ${other}\n` +
+                    `一个关系只能有一条 profile 记忆，重新生成请用 --replaces 指定它。`);
+            }
+        }
+    }
+    const now = new Date().toISOString();
+    const createdAt = readExistingCreatedAt(targetPath) ?? now;
+    const document = parseMemoryDocument('');
+    document.hasFrontmatter = true;
+    setMemoryField(document, 'name', req.slug);
+    setMemoryField(document, 'description', req.description.trim());
+    setMemoryField(document, 'scope', req.scope);
+    if (req.scope === 'relation' && req.taskCtx.peerKey)
+        setMemoryField(document, 'peerKey', req.taskCtx.peerKey);
+    if (req.scope === 'owner' && req.ownerAid)
+        setMemoryField(document, 'ownerAid', req.ownerAid);
+    setMemoryField(document, 'createdAt', createdAt);
+    setMemoryField(document, 'updatedAt', now);
+    setMemoryField(document, 'createdBy', 'memory-trigger');
+    if (req.scope === 'agent' && req.generalizedFrom)
+        setMemoryField(document, 'generalizedFrom', req.generalizedFrom);
+    if (req.scope === 'owner' && req.promotedFrom)
+        setMemoryField(document, 'promotedFrom', req.promotedFrom);
+    if (req.tags.length > 0)
+        setMemoryField(document, 'tags', req.tags);
+    if (req.keywords?.length)
+        setMemoryField(document, 'keywords', req.keywords);
+    if (replacePaths.length > 0)
+        setMemoryField(document, 'replaces', replacePaths.map(p => path.relative(dirs.memoryDir, p)));
+    document.body = req.content.trimEnd();
+    const signed = await writeSignedMemory(document, req.taskCtx.selfAid);
+    const tmp = targetPath + '.tmp';
+    fs.writeFileSync(tmp, signed, 'utf-8');
+    fs.renameSync(tmp, targetPath);
+    // 归档被替换的旧文件（在写入成功之后做，失败不影响新文件）
+    const archived = [];
+    for (const p of replacePaths) {
+        if (!fs.existsSync(p))
+            continue;
+        if (path.resolve(p) === path.resolve(targetPath))
+            continue;
+        const dest = archivePath(dirs.memoryDir, p);
+        fs.mkdirSync(path.dirname(dest), { recursive: true });
+        try {
+            fs.renameSync(p, dest);
+            archived.push(dest);
+        }
+        catch { /* 归档失败不影响主流程，由下次整理清理 */ }
+    }
+    // 刷新本作用域的 _meta.json（扫描优化用；失败不影响主流程）
+    refreshMemoryMeta(dirs.memoryDir);
+    return { ok: true, filePath: targetPath, archived, scopeDirs: dirs };
+}
+/** 列出本作用域内除 exceptPath 之外、带 profile 标签的记忆文件。 */
+function findProfileMemories(dirs, exceptPath) {
+    if (!fs.existsSync(dirs.consolidatedDir))
+        return [];
+    const out = [];
+    for (const f of fs.readdirSync(dirs.consolidatedDir)) {
+        if (!f.endsWith('.md'))
+            continue;
+        const fp = path.join(dirs.consolidatedDir, f);
+        if (path.resolve(fp) === path.resolve(exceptPath))
+            continue;
+        try {
+            const document = readMemory(fs.readFileSync(fp, 'utf-8'));
+            if (getMemoryArray(document, 'tags').includes('profile'))
+                out.push(fp);
+        }
+        catch { /* ignore */ }
+    }
+    return out;
+}
+function readExistingCreatedAt(filePath) {
+    if (!fs.existsSync(filePath))
+        return undefined;
+    try {
+        return getMemoryString(readMemory(fs.readFileSync(filePath, 'utf-8')), 'createdAt');
+    }
+    catch { /* ignore */ }
+    return undefined;
+}
+/** 归档路径：<memory>/archive/consolidated/<原文件名> */
+function archivePath(memoryDir, filePath) {
+    return path.join(memoryDir, 'archive', 'consolidated', path.basename(filePath));
+}
+/**
+ * 把 agent 级或 owner 级记忆降级回上一层（agent→relation 或 owner→agent）。
+ * 依据记忆文件 frontmatter 里的 generalizedFrom / promotedFrom 字段找到来源层。
+ * 只降一层，可以连续调用进一步降级。
+ *
+ * 遇到目标路径已有同名文件时，把当前文件归档到 archive/consolidated/，不覆盖也不报错。
+ */
+export async function demoteMemory(req) {
+    const selfAid = req.taskCtx.selfAid;
+    if (!selfAid)
+        throw new Error('无法确定当前 agent AID（selfAid 为空）');
+    const root = resolveRoot();
+    const srcDirs = resolveScopeDirs(req.scope, req.taskCtx, req.ownerAid);
+    const srcPath = path.join(srcDirs.consolidatedDir, `${req.slug}.md`);
+    if (!fs.existsSync(srcPath))
+        throw new Error(`找不到记忆文件: ${srcPath}`);
+    const content = fs.readFileSync(srcPath, 'utf-8');
+    const fromRelPath = getMemoryString(readMemory(content), req.scope === 'agent' ? 'generalizedFrom' : 'promotedFrom');
+    if (!fromRelPath) {
+        throw new Error(`DEMOTE_NO_SOURCE: 记忆文件缺少来源字段（${req.scope === 'agent' ? 'generalizedFrom' : 'promotedFrom'}），` +
+            `无法确定降级目标。只有由 generalize/promote 整理会话产出的记忆才能降级。`);
+    }
+    // 来源路径相对于 agents/<selfAid>/，解析成绝对路径
+    const agentRoot = path.join(root, 'agents', selfAid);
+    const destPath = path.resolve(agentRoot, fromRelPath);
+    // 路径安全检查：目标必须落在当前 agent 目录下
+    if (!destPath.startsWith(agentRoot + path.sep)) {
+        throw new Error(`DEMOTE_PATH_ERROR: 来源路径越界: ${fromRelPath}`);
+    }
+    const destMemoryDir = destPath.includes(`${path.sep}consolidated${path.sep}`)
+        ? destPath.slice(0, destPath.lastIndexOf(`${path.sep}consolidated${path.sep}`))
+        : path.dirname(path.dirname(destPath));
+    let conflictArchived = false;
+    let finalDestPath = destPath;
+    if (fs.existsSync(destPath)) {
+        // 同名冲突：把当前文件归档，不覆盖，不失败
+        const archiveDest = archivePath(srcDirs.memoryDir, srcPath);
+        fs.mkdirSync(path.dirname(archiveDest), { recursive: true });
+        fs.renameSync(srcPath, archiveDest);
+        finalDestPath = archiveDest;
+        conflictArchived = true;
+    }
+    else {
+        fs.mkdirSync(path.dirname(destPath), { recursive: true });
+        fs.renameSync(srcPath, destPath);
+    }
+    // 跨作用域搬运，源与目标两个目录都要刷新元数据
+    refreshMemoryMeta(srcDirs.memoryDir);
+    refreshMemoryMeta(destMemoryDir);
+    return {
+        ok: true,
+        destPath: finalDestPath,
+        conflictArchived,
+        srcScopeDirs: srcDirs,
+        destMemoryDir,
+    };
+}
+export async function updateMemory(req) {
+    const dirs = resolveScopeDirs(req.scope, req.taskCtx, req.ownerAid);
+    const filePath = resolveConsolidatedPath(dirs, req.target);
+    if (!fs.existsSync(filePath))
+        throw new Error(`找不到记忆文件: ${filePath}`);
+    const raw = fs.readFileSync(filePath, 'utf-8');
+    const document = readMemory(raw);
+    const prevTags = getMemoryArray(document, 'tags');
+    if (req.tags !== undefined)
+        setMemoryField(document, 'tags', req.tags.length > 0 ? req.tags : undefined);
+    // 刷新 updatedAt（--touch 的续期语义就是刷新这里 + 文件 mtime）
+    const now = new Date().toISOString();
+    setMemoryField(document, 'updatedAt', now);
+    const signed = await writeSignedMemory(document, req.taskCtx.selfAid);
+    const tmp = filePath + '.tmp';
+    fs.writeFileSync(tmp, signed, 'utf-8');
+    fs.renameSync(tmp, filePath);
+    refreshMemoryMeta(dirs.memoryDir);
+    return { ok: true, filePath, prevTags, scopeDirs: dirs };
+}
+// ── archive ────────────────────────────────────────────────────────────────
+export async function archiveMemory(req) {
+    const dirs = resolveScopeDirs(req.scope, req.taskCtx, req.ownerAid);
+    const archived = [];
+    for (const t of req.targets) {
+        const p = resolveConsolidatedPath(dirs, t);
+        if (!fs.existsSync(p))
+            throw new Error(`找不到记忆文件: ${p}`);
+        const dest = archivePath(dirs.memoryDir, p);
+        fs.mkdirSync(path.dirname(dest), { recursive: true });
+        fs.renameSync(p, dest);
+        archived.push(dest);
+    }
+    refreshMemoryMeta(dirs.memoryDir);
+    return { ok: true, archived, scopeDirs: dirs };
+}
+const NOTE_MAX_CONTENT_BYTES = 4 * 1024;
+function assertMemoryEnabled(memoryConfig) {
+    if (memoryConfig?.enableRelation === false) {
+        throw new Error('SCOPE_DISABLED: 记忆系统已停用（memory.enableRelation=false）');
+    }
+}
+export function relationMemoryDir(taskCtx) {
+    const selfAid = taskCtx.selfAid;
+    if (!selfAid)
+        throw new Error('无法确定当前 agent AID（selfAid 为空）');
+    const peerKey = taskCtx.peerKey;
+    if (!peerKey)
+        throw new Error('relation 作用域需要 peerKey（当前会话无对端信息）');
+    if (peerKey.includes('..') || peerKey.includes('/') || peerKey.includes('\\')) {
+        throw new Error(`INVALID_PEER_KEY: peerKey 格式非法: "${peerKey}"`);
+    }
+    return path.join(resolveRoot(), 'agents', selfAid, 'relations', peerKey, 'memory');
+}
+function pendingDir(taskCtx) {
+    return path.join(relationMemoryDir(taskCtx), 'pending');
+}
+function assertNoteContent(content) {
+    if (!content || content.trim() === '')
+        throw new Error('content 不能为空');
+    const bytes = Buffer.byteLength(content, 'utf8');
+    if (bytes > NOTE_MAX_CONTENT_BYTES)
+        throw new Error(`content 超过 ${NOTE_MAX_CONTENT_BYTES} 字节限制（当前 ${bytes} 字节）`);
+}
+function resolvePendingPath(taskCtx, input) {
+    const base = path.resolve(pendingDir(taskCtx));
+    if (!input.includes('/') && !input.includes('\\')) {
+        const slug = input.replace(/\.md$/, '');
+        assertSlug(slug);
+        return path.join(base, `${slug}.md`);
+    }
+    const abs = path.resolve(input);
+    const rel = path.relative(base, abs);
+    if (rel.startsWith('..') || path.isAbsolute(rel))
+        throw new Error(`ROLE_ACCESS_DENIED: 只能操作当前关系 pending/ 下的记忆（${base}），当前路径越界: ${input}`);
+    return abs;
+}
+function writeAtomic(filePath, content, exclusive = false) {
+    const tmpPath = `${filePath}.tmp`;
+    try {
+        fs.writeFileSync(tmpPath, content, exclusive ? { encoding: 'utf-8', flag: 'wx' } : 'utf-8');
+        fs.renameSync(tmpPath, filePath);
+    }
+    catch (error) {
+        try {
+            fs.unlinkSync(tmpPath);
+        }
+        catch { /* ignore */ }
+        if (error?.code === 'EEXIST' && exclusive)
+            throw new Error('已有同名的 note 正在写入，请稍后重试或改用 note update');
+        throw error;
+    }
+}
+export async function writeMemoryNote(req) {
+    assertMemoryEnabled(req.memoryConfig);
+    assertNoteContent(req.content);
+    assertSlug(req.slug);
+    const dir = pendingDir(req.taskCtx);
+    const dirCreated = !fs.existsSync(dir);
+    fs.mkdirSync(dir, { recursive: true });
+    const now = new Date().toISOString();
+    const document = parseMemoryDocument('');
+    document.hasFrontmatter = true;
+    setMemoryField(document, 'name', req.slug);
+    setMemoryField(document, 'scope', 'relation');
+    setMemoryField(document, 'peerKey', req.taskCtx.peerKey ?? '');
+    if (req.taskCtx.chatType)
+        setMemoryField(document, 'chatType', req.taskCtx.chatType);
+    if (req.speakers?.length)
+        setMemoryField(document, 'speakers', req.speakers);
+    if (req.taskCtx.sessionId)
+        setMemoryField(document, 'evolcoreSessionId', req.taskCtx.sessionId);
+    if (req.taskCtx.taskId)
+        setMemoryField(document, 'taskId', req.taskCtx.taskId);
+    setMemoryField(document, 'createdAt', now);
+    setMemoryField(document, 'updatedAt', now);
+    setMemoryField(document, 'createdBy', req.taskCtx.baseagent ?? 'agent');
+    if (req.tags?.length)
+        setMemoryField(document, 'tags', req.tags);
+    document.body = req.content.trimEnd();
+    const filePath = path.join(dir, `${req.slug}.md`);
+    if (fs.existsSync(filePath))
+        throw new Error(`SLUG_EXISTS: 该 slug 已存在同名 note: ${filePath}`);
+    const content = serializeMemoryDocument(document);
+    writeAtomic(filePath, content, true);
+    return { ok: true, filePath, dirCreated, fileSize: Buffer.byteLength(content, 'utf-8') };
+}
+export async function updateMemoryNote(req) {
+    assertMemoryEnabled(req.memoryConfig);
+    const filePath = resolvePendingPath(req.taskCtx, req.target);
+    if (!fs.existsSync(filePath))
+        throw new Error(`找不到 note: ${filePath}`);
+    const document = parseMemoryDocument(fs.readFileSync(filePath, 'utf-8'));
+    if (req.newSlug !== undefined) {
+        assertSlug(req.newSlug);
+        setMemoryField(document, 'name', req.newSlug);
+    }
+    if (req.tags !== undefined)
+        setMemoryField(document, 'tags', req.tags.length ? req.tags : undefined);
+    if (req.content !== undefined) {
+        assertNoteContent(req.content);
+        document.body = req.content;
+    }
+    setMemoryField(document, 'updatedAt', new Date().toISOString());
+    const destPath = req.newSlug === undefined ? filePath : path.join(path.dirname(filePath), `${req.newSlug}.md`);
+    if (destPath !== filePath && fs.existsSync(destPath))
+        throw new Error(`SLUG_EXISTS: 目标 slug 已存在同名 note: ${destPath}`);
+    writeAtomic(destPath, serializeMemoryDocument(document));
+    if (destPath !== filePath)
+        fs.rmSync(filePath, { force: true });
+    return { ok: true, filePath: destPath };
+}
+export async function dropMemoryNote(req) {
+    assertMemoryEnabled(req.memoryConfig);
+    const filePath = resolvePendingPath(req.taskCtx, req.target);
+    if (!fs.existsSync(filePath))
+        throw new Error(`找不到 note: ${filePath}`);
+    const archiveDir = path.join(path.dirname(filePath), 'archive');
+    fs.mkdirSync(archiveDir, { recursive: true });
+    const ts = new Date().toISOString().replace(/[-:]/g, '').replace('T', '-').slice(0, 15);
+    const dest = path.join(archiveDir, `${ts}-${path.basename(filePath)}`);
+    fs.renameSync(filePath, dest);
+    return { ok: true, filePath: dest };
+}
+export async function listMemoryNotes(req) {
+    assertMemoryEnabled(req.memoryConfig);
+    const dir = pendingDir(req.taskCtx);
+    if (!fs.existsSync(dir))
+        return { ok: true, notes: [] };
+    const notes = [];
+    for (const name of fs.readdirSync(dir)) {
+        if (!name.endsWith('.md'))
+            continue;
+        try {
+            const document = parseMemoryDocument(fs.readFileSync(path.join(dir, name), 'utf-8'));
+            const firstLine = document.body.split('\n').map(line => line.trim()).find(Boolean) ?? '';
+            notes.push({ slug: getMemoryString(document, 'name') ?? name.replace(/\.md$/, ''), tags: getMemoryArray(document, 'tags'), firstLine: firstLine.length > 80 ? `${firstLine.slice(0, 80)}…` : firstLine, updatedAt: getMemoryString(document, 'updatedAt') });
+        }
+        catch { /* ignore unreadable notes */ }
+    }
+    notes.sort((a, b) => (a.updatedAt ?? '').localeCompare(b.updatedAt ?? ''));
+    return { ok: true, notes };
+}

package/dist/core/memory/staleness.js

@@ -0,0 +1,117 @@
+/**
+ * staleness.ts — 遗忘的超期判据（v3）
+ *
+ * 两个时间戳分工，是整个遗忘机制的地基：
+ *
+ *   **mtime**      —— 「候选集入场券」。超过 forgetAfterDays 就进候选。
+ *                     进一次候选就刷一次，于是 forgetAfterDays 内不会第二次进候选。
+ *   **updatedAt**  —— 「真正的审查节拍」。决定这条记忆是否真的交给模型审查。
+ *
+ * 两种记忆的规则不同：
+ *
+ *   普通记忆
+ *     mtime 超 forgetAfterDays → 进候选 → updatedAt 也超 forgetAfterDays → 交模型审查
+ *     模型续期 → `ec memory update --touch` → mtime 与 updatedAt 同时刷新
+ *
+ *   长期记忆（带 long-term 标签）
+ *     mtime 超 forgetAfterDays → 进候选，但【不交给模型】
+ *     程序只刷 mtime（updatedAt 不动）→ forgetAfterDays 内不再进候选
+ *     ……如此反复，直到 updatedAt 超过 30 天才真正交给模型审查
+ *
+ * 「交模型审查」的门槛固定为 30 天（LONG_TERM_REVIEW_DAYS），不做成配置项。
+ *
+ * 判据集中在这里，**trigger 与 context 必须共用**——它们如果各写一套，
+ * 就会出现「触发了但候选为空」或「评估了不该动的记忆」这类不一致。
+ */
+import fs from 'fs';
+import path from 'path';
+import { getMemoryArray, getMemoryString, parseMemoryDocument } from './memory-document.js';
+/** 普通记忆的遗忘超期天数兜底值，与 MemoryConfig.forgetAfterDays 的默认值一致。 */
+export const DEFAULT_FORGET_AFTER_DAYS = 3;
+/** 长期记忆的固定审查周期（天）。 */
+export const LONG_TERM_REVIEW_DAYS = 30;
+/** 这条记忆是否打了长期标记。 */
+export function isLongTerm(tags) {
+    return tags.includes('long-term');
+}
+/**
+ * 这条记忆应当在多少天内不被重复审查。
+ * 长期记忆用固定 30 天，普通记忆用配置值。
+ */
+export function reviewWindowDays(tags, thresholds) {
+    return isLongTerm(tags) ? LONG_TERM_REVIEW_DAYS : thresholds.forgetAfterDays;
+}
+const DAY_MS = 24 * 60 * 60 * 1000;
+/** 从 frontmatter 读一个数组字段。 */
+export function readFmArray(content, key) {
+    return getMemoryArray(parseMemoryDocument(content), key);
+}
+/** 从 frontmatter 读一个标量字段。 */
+export function readFmValue(content, key) {
+    return getMemoryString(parseMemoryDocument(content), key);
+}
+/** 从 frontmatter 读 updatedAt 的毫秒时间戳；读不到返回 undefined。 */
+export function readUpdatedAtMs(content) {
+    const raw = readFmValue(content, 'updatedAt');
+    if (!raw)
+        return undefined;
+    const ms = Date.parse(raw);
+    return Number.isFinite(ms) ? ms : undefined;
+}
+/** 扫目录，返回所有 mtime 已过「候选门票」的记忆。不做超期判定，只收窄集合。 */
+export function collectCandidates(consolidatedDir, thresholds, now = Date.now()) {
+    if (!fs.existsSync(consolidatedDir))
+        return [];
+    let names;
+    try {
+        names = fs.readdirSync(consolidatedDir).filter(f => f.endsWith('.md'));
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const name of names) {
+        const filePath = path.join(consolidatedDir, name);
+        let content;
+        let mtimeMs;
+        try {
+            content = fs.readFileSync(filePath, 'utf-8');
+            mtimeMs = fs.statSync(filePath).mtimeMs;
+        }
+        catch {
+            continue;
+        }
+        // 候选门票：mtime 超 forgetAfterDays。长期记忆不豁免这一关。
+        const ticketMs = now - thresholds.forgetAfterDays * DAY_MS;
+        if (mtimeMs >= ticketMs)
+            continue;
+        const tags = readFmArray(content, 'tags');
+        const updatedAtMs = readUpdatedAtMs(content) ?? mtimeMs;
+        out.push({ name, filePath, tags, mtimeMs, updatedAtMs, content });
+    }
+    out.sort((a, b) => a.name.localeCompare(b.name));
+    return out;
+}
+/**
+ * 这条候选是否**真的该交给模型审查**。
+ *
+ * 判定落在 updatedAt 上：
+ *   - 普通记忆：updatedAt 超过 forgetAfterDays
+ *   - 长期记忆：updatedAt 超过固定的 30 天
+ */
+export function isDueForReview(info, thresholds, now = Date.now()) {
+    const windowMs = reviewWindowDays(info.tags, thresholds) * DAY_MS;
+    return info.updatedAtMs < now - windowMs;
+}
+/**
+ * 只刷 mtime、不动 updatedAt —— 长期记忆的「减速」动作。
+ *
+ * 效果：这条记忆在 forgetAfterDays 内不会再次进候选，但它**没有**被标记为
+ * 「审查过」，所以 updatedAt 继续走，直到超过 30 天才真正交给模型。
+ *
+ * 这是**程序自己**做的，不暴露成 CLI 参数——否则模型可能拿它假装续期。
+ */
+export function deferCandidate(filePath, now = Date.now()) {
+    const t = now / 1000;
+    fs.utimesSync(filePath, t, t);
+}