dsh-memory-fish 0.0.0-stage → 0.7.0

package/lib/store.mjs

@@ -0,0 +1,264 @@
+import { promises as fs } from 'node:fs';
+import fsSync from 'node:fs';
+import path from 'node:path';
+import { nowIso, stamp, dayOf, localDay, estTokens, initialStability, addDays, isDue, redactSecrets } from './util.mjs';
+
+// ---------------------------------------------------------------- 存储
+
+export class Store {
+  constructor(dir) {
+    this.dir = dir;
+    this.memDir = path.join(dir, 'memories');
+    this.archDir = path.join(dir, 'archive');
+    this.journalDir = path.join(dir, 'journal');
+    this.dreamDir = path.join(dir, 'dream');
+    this.profileFile = path.join(dir, 'profile.md');
+    this.indexFile = path.join(dir, 'index.json');
+    this.statsFile = path.join(dir, 'stats.json');
+    this.entries = [];
+    this.stats = { saved: 0, updated: 0, searches: 0, consolidations: 0, lastConsolidate: null, captured: 0, capturedSinceDream: 0, dreams: 0, lastDream: null };
+  }
+
+  async init() {
+    await fs.mkdir(this.memDir, { recursive: true });
+    await fs.mkdir(this.archDir, { recursive: true });
+    await fs.mkdir(this.journalDir, { recursive: true });
+    await fs.mkdir(this.dreamDir, { recursive: true });
+    await this.load();
+  }
+
+  /** 追加一条对话记录到当天 journal（L3 原始层，永不注入上下文）。落盘前强制脱敏。 */
+  async appendJournal(record) {
+    const day = localDay();
+    const file = path.join(this.journalDir, `${day}.jsonl`);
+    const safe = { ...record, text: redactSecrets(record?.text ?? '') };
+    await fs.appendFile(file, JSON.stringify(safe) + '\n', 'utf8').catch(() => {});
+    this.stats.capturedSinceDream = (this.stats.capturedSinceDream || 0) + 1;
+  }
+
+  /** 读取最近 n 天的 journal 条目。 */
+  async readJournal(days = 2) {
+    const out = [];
+    const now = new Date();
+    for (let i = 0; i < days; i++) {
+      const d = new Date(now.getTime() - i * 86400000);
+      const file = path.join(this.journalDir, `${localDay(d)}.jsonl`);
+      let text = '';
+      try { text = await fs.readFile(file, 'utf8'); } catch { continue; }
+      for (const line of text.split('\n')) {
+        if (!line.trim()) continue;
+        try { out.push(JSON.parse(line)); } catch { /* 跳过坏行 */ }
+      }
+    }
+    out.sort((a, b) => String(a.ts).localeCompare(String(b.ts)));
+    return out;
+  }
+
+  async saveDreamReport(day, content) {
+    const file = path.join(this.dreamDir, `${day}.md`);
+    await atomicWrite(file, content);
+    return file;
+  }
+
+  async readDreamReport(day = localDay(new Date(Date.now() - 86400000))) {
+    const file = path.join(this.dreamDir, `${day}.md`);
+    try { return { day, content: await fs.readFile(file, 'utf8'), file }; } catch { return { day, content: '', file }; }
+  }
+
+  async pruneJournal(keepDays) {
+    const cutoff = new Date(Date.now() - keepDays * 86400000);
+    let removed = 0;
+    let files = [];
+    try { files = await fs.readdir(this.journalDir); } catch { return 0; }
+    for (const f of files) {
+      if (!f.endsWith('.jsonl')) continue;
+      const dayStr = f.replace(/\.jsonl$/, '');
+      const t = new Date(`${dayStr}T00:00:00`).getTime();
+      if (Number.isFinite(t) && t < cutoff.getTime()) {
+        await fs.unlink(path.join(this.journalDir, f)).catch(() => {});
+        removed++;
+      }
+    }
+    return removed;
+  }
+
+  async load() {
+    try {
+      const raw = await fs.readFile(this.indexFile, 'utf8');
+      const data = JSON.parse(raw);
+      this.entries = Array.isArray(data.entries) ? data.entries : [];
+    } catch {
+      this.entries = await this.scan();
+    }
+    await this.migrate();
+    try {
+      this.stats = { ...this.stats, ...JSON.parse(await fs.readFile(this.statsFile, 'utf8')) };
+    } catch { /* 首次运行 */ }
+    if (!fsSync.existsSync(this.profileFile)) {
+      await fs.writeFile(this.profileFile, '# 小肥鱼记忆 · L0 画像\n\n（还没有写入画像）\n', 'utf8');
+    }
+  }
+
+  /** v0.4 迁移：给旧条目补上 salience / 复习调度 / 链接字段；v0.5 补时间有效性字段。 */
+  async migrate() {
+    let changed = false;
+    const now = nowIso();
+    for (const e of this.entries) {
+      if (typeof e.salience !== 'number') { e.salience = 5; changed = true; }
+      if (!e.stability) {
+        e.stability = initialStability(e.importance, e.salience);
+        e.lastReview = e.lastReview || e.updated || now;
+        e.nextReview = addDays(e.lastReview, Math.round(e.stability));
+        e.reviews = e.reviews || 0;
+        changed = true;
+      }
+      if (!Array.isArray(e.links)) { e.links = []; changed = true; }
+      if (!e.nextReview) { e.nextReview = addDays(e.updated || now, Math.round(e.stability)); changed = true; }
+      // 时间有效性（P3）：旧数据默认"从创建时起一直有效"
+      if (!e.validFrom) { e.validFrom = e.created || now; changed = true; }
+      if (e.validTo === undefined) { e.validTo = null; changed = true; }
+      if (!Array.isArray(e.history)) { e.history = []; changed = true; }
+    }
+    if (changed) {
+      try { await this.saveIndex(); } catch { /* 忽略 */ }
+    }
+  }
+
+  /** 索引丢失时，从 memories/*.md 的 frontmatter 重建。 */
+  async scan() {
+    const entries = [];
+    let files = [];
+    try { files = await fs.readdir(this.memDir); } catch { return entries; }
+    for (const f of files) {
+      if (!f.endsWith('.md')) continue;
+      try {
+        const text = await fs.readFile(path.join(this.memDir, f), 'utf8');
+        const e = parseFrontmatter(text, f.replace(/\.md$/, ''));
+        if (e) entries.push(e);
+      } catch { /* 跳过坏文件 */ }
+    }
+    return entries;
+  }
+
+  async saveIndex() {
+    const data = { version: 1, updated: nowIso(), entries: this.entries };
+    await atomicWrite(this.indexFile, JSON.stringify(data, null, 2) + '\n');
+  }
+
+  async saveStats() {
+    await atomicWrite(this.statsFile, JSON.stringify(this.stats, null, 2) + '\n');
+  }
+
+  /** active 的条目：置顶 → 显著性 → 重要度 → 更新时间。 */
+  visible() {
+    return this.entries
+      .filter(e => e.status === 'active')
+      .sort((a, b) => {
+        if (!!b.pinned !== !!a.pinned) return b.pinned ? 1 : -1;
+        if ((b.salience ?? 5) !== (a.salience ?? 5)) return (b.salience ?? 5) - (a.salience ?? 5);
+        if ((b.importance ?? 3) !== (a.importance ?? 3)) return (b.importance ?? 3) - (a.importance ?? 3);
+        return String(b.updated).localeCompare(String(a.updated));
+      });
+  }
+
+  /** 到期该复习的条目。 */
+  due(now = Date.now()) {
+    return this.entries.filter(e => e.status === 'active' && isDue(e, now));
+  }
+
+  byId(id) {
+    return this.entries.find(e => e.id === id);
+  }
+
+  async writeMemory(entry, content) {
+    const fm = [
+      '---',
+      `id: ${entry.id}`,
+      `created: ${entry.created}`,
+      `updated: ${entry.updated}`,
+      `valid_from: ${entry.validFrom ?? entry.created ?? ''}`,
+      `valid_to: ${entry.validTo ?? ''}`,
+      `importance: ${entry.importance}`,
+      `salience: ${entry.salience ?? 5}`,
+      `pinned: ${entry.pinned ? 'true' : 'false'}`,
+      `status: ${entry.status}`,
+      `stability: ${entry.stability ?? ''}`,
+      `last_review: ${entry.lastReview ?? ''}`,
+      `next_review: ${entry.nextReview ?? ''}`,
+      `reviews: ${entry.reviews ?? 0}`,
+      `tags: ${(entry.tags || []).join(', ')}`,
+      `supersedes: ${(entry.supersedes || []).join(', ')}`,
+      `links: ${(entry.links || []).join(', ')}`,
+      '---',
+      '',
+      `# ${entry.title}`,
+      '',
+      content.trim(),
+      '',
+    ].join('\n');
+    entry.file = path.join(this.memDir, `${entry.id}.md`);
+    entry.chars = fm.length;
+    entry.tokens = estTokens(fm);
+    await atomicWrite(entry.file, fm);
+    return fm;
+  }
+
+  async archiveContent(entry, content) {
+    const at = stamp();
+    const file = path.join(this.archDir, `${entry.id}.${at}.md`);
+    const fm = [
+      '---',
+      `id: ${entry.id}`,
+      `title: ${entry.title}`,
+      `archived_at: ${nowIso()}`,
+      '---',
+      '',
+      content,
+      '',
+    ].join('\n');
+    await atomicWrite(file, fm);
+    return file;
+  }
+}
+
+export function parseFrontmatter(text, fallbackId) {
+  const m = /^---\n([\s\S]*?)\n---\n\n?# ([^\n]*)\n\n?([\s\S]*)$/.exec(text);
+  if (!m) return null;
+  const meta = {};
+  for (const line of m[1].split('\n')) {
+    const i = line.indexOf(':');
+    if (i < 0) continue;
+    meta[line.slice(0, i).trim()] = line.slice(i + 1).trim();
+  }
+  return {
+    id: meta.id || fallbackId,
+    title: m[2].trim(),
+    content: m[3],
+    created: meta.created || nowIso(),
+    updated: meta.updated || meta.created || nowIso(),
+    validFrom: meta.valid_from || meta.created || nowIso(),
+    validTo: meta.valid_to || null,
+    history: [],
+    importance: Number(meta.importance) || 3,
+    salience: Number(meta.salience) || 5,
+    pinned: meta.pinned === 'true',
+    status: (meta.status || 'active').trim(),
+    stability: Number(meta.stability) || null,
+    lastReview: meta.last_review || null,
+    nextReview: meta.next_review || null,
+    reviews: Number(meta.reviews) || 0,
+    tags: (meta.tags || '').split(',').map(s => s.trim()).filter(Boolean),
+    supersedes: (meta.supersedes || '').split(',').map(s => s.trim()).filter(Boolean),
+    links: (meta.links || '').split(',').map(s => s.trim()).filter(Boolean),
+    hits: 0,
+    lastHit: null,
+    chars: text.length,
+    tokens: estTokens(text),
+  };
+}
+
+export async function atomicWrite(file, data) {
+  const tmp = `${file}.${process.pid}.${Date.now()}.tmp`;
+  await fs.writeFile(tmp, data, 'utf8');
+  await fs.rename(tmp, file);
+}

package/lib/tools.mjs

@@ -0,0 +1,398 @@
+import { promises as fs } from 'node:fs';
+import { defineTool } from '@deepseek-ai/dsh-tools';
+import { out, nowIso, dayOf, similar, reinforce, SECRET_RE, estTokens } from './util.mjs';
+import { buildInjection } from './inject.mjs';
+import { saveMemoryCore } from './core.mjs';
+import { buildDream } from './dream.mjs';
+import { atomicWrite } from './store.mjs';
+import { withLock } from './lock.mjs';
+import { log } from './log.mjs';
+
+/** 需要串行化的写操作：跨进程锁 + 写前重读索引。 */
+const MUTATING = new Set(['memory_save', 'memory_pin', 'memory_forget', 'memory_profile_save', 'memory_consolidate', 'memory_dream']);
+
+export function registerTools(ctx, store, cfg, toolImpl) {
+  const register = (def) => {
+    const original = def.execute;
+    if (MUTATING.has(def.name) && typeof original === 'function') {
+      def.execute = async (args, exec) => withLock(store.dir, async () => {
+        await store.load();
+        return original.call(def, args, exec);
+      });
+    }
+    toolImpl[def.name] = def;
+    try {
+      ctx.tools.register(defineTool(def));
+    } catch (error) {
+      log.warn('tool register failed', def.name, error);
+    }
+  };
+
+  // ---- memory_save ----
+  register({
+    name: 'memory_save',
+    description: '保存一条跨会话记忆。只存"一个月后仍然成立"的结论：偏好、纠正、决策及其理由、排障闭环、关键数字/ID。不要存过程状态、临时错误、仓库里能直接读到的东西、密钥。同主题会原地更新（自动去重），不会重复堆积。内容写成给未来 agent 的祈使句，2-5 句，自包含。',
+    parameters: {
+      title: { type: 'string', required: true, description: '短标题（≤40 字），会成为热索引的一行。' },
+      content: { type: 'string', required: true, description: '记忆正文，2-5 句自包含的祈使句。' },
+      tags: { type: 'array', items: { type: 'string' }, description: '至多 3 个标签。' },
+      importance: { type: 'number', description: '重要度 1-5（默认 3；用户明确要求记住=5）。' },
+      pin: { type: 'boolean', description: '是否置顶（置顶记忆永远在热索引最前，不参与衰减）。' },
+    },
+    output: { schema: { type: 'object', additionalProperties: true }, render: (_a, v) => [{ type: 'text', text: JSON.stringify(v, null, 1) }] },
+    async execute(args) {
+      return await saveMemoryCore(store, cfg, args);
+    },
+  });
+
+  // ---- memory_search ----
+  register({
+    name: 'memory_search',
+    description: '在本地记忆里做关键词检索（标题/标签/正文，大小写不敏感），返回相关条目摘要。当过去的偏好、决策或上下文可能相关时先用它查证，不要直接重问用户。默认只搜"当前有效"的记忆；asOf="2026-09-01" 可按时间点查历史版本（回答"上个月我们用什么方案"）；includeArchived=true 会连冷档案一起搜。',
+    parameters: {
+      query: { type: 'string', required: true, description: '关键词或短语。' },
+      limit: { type: 'number', description: '最多返回条数（默认 8，最大 20）。' },
+      asOf: { type: 'string', description: '时间点（ISO 日期），查那一刻有效的记忆版本；省略则只看当前有效版本。' },
+      includeArchived: { type: 'boolean', description: '是否包含已归档的冷记忆（默认 false）。' },
+    },
+    output: { schema: { type: 'object', additionalProperties: true }, render: (_a, v) => [{ type: 'text', text: JSON.stringify(v, null, 1) }] },
+    async execute(args) {
+      const q = String(args.query ?? '').trim();
+      if (!q) return out({ ok: false, code: 'invalid_input', message: 'query 不能为空' });
+      const limit = Math.min(20, Math.max(1, Math.trunc(Number(args.limit) || 8)));
+      if (!store.entries.length) await store.load();
+      const lower = q.toLowerCase();
+      const asOfMs = args.asOf ? new Date(String(args.asOf)).getTime() : NaN;
+      const hasAsOf = Number.isFinite(asOfMs);
+      const pool = args.includeArchived === true ? store.entries : store.entries.filter(e => e.status === 'active');
+      const nowMs = Date.now();
+
+      // 每条记忆可能有多"代"内容（history），统一展开成带有效期的版本
+      const versions = [];
+      for (const e of pool) {
+        const current = {
+          entry: e, title: e.title, content: e.content ?? '',
+          validFrom: e.validFrom || e.created || '',
+          validTo: e.validTo || null,
+          historical: false,
+        };
+        const hist = (e.history || []).map(h => ({
+          entry: e, title: h.title || e.title, content: h.content ?? '',
+          validFrom: h.validFrom || '', validTo: h.validTo || null, historical: true,
+        }));
+        versions.push(...hist, current);
+      }
+
+      const inRange = (v) => {
+        if (!hasAsOf) return v.historical === false; // 默认只看当前有效版本
+        const from = new Date(v.validFrom).getTime();
+        const to = v.validTo ? new Date(v.validTo).getTime() : nowMs;
+        return Number.isFinite(from) && from <= asOfMs && asOfMs <= to;
+      };
+
+      const hits = [];
+      for (const v of versions) {
+        if (!inRange(v)) continue;
+        const e = v.entry;
+        let score = 0;
+        if (String(v.title).toLowerCase().includes(lower)) score += 3;
+        if ((e.tags || []).some(t => String(t).toLowerCase().includes(lower))) score += 2;
+        let body = v.content;
+        if (!body) {
+          try { body = (await fs.readFile(e.file, 'utf8')).replace(/^---[\s\S]*?---\n\n?/, ''); } catch { body = ''; }
+        }
+        if (body.toLowerCase().includes(lower)) score += 1;
+        if (score > 0) {
+          const idx = body.toLowerCase().indexOf(lower);
+          const start = Math.max(0, idx - 40);
+          const excerpt = (start > 0 ? '…' : '') + body.slice(start, idx + lower.length + 60).replace(/\s+/g, ' ').trim();
+          hits.push(out({
+            id: e.id, title: v.title, tags: e.tags || [], scope: 'user', status: e.status,
+            importance: e.importance ?? 3, updated: dayOf(v.validFrom), score, excerpt,
+            validFrom: dayOf(v.validFrom), validTo: v.validTo ? dayOf(v.validTo) : null,
+            historical: v.historical,
+          }));
+        }
+      }
+      hits.sort((a, b) => b.score - a.score || String(b.validFrom).localeCompare(String(a.validFrom)));
+      const top = hits.slice(0, limit);
+      for (const h of top) {
+        if (h.historical) continue; // 历史版本不参与复习加固
+        const e = store.byId(h.id);
+        if (e && cfg.reviewEnabled) reinforce(e, 1.3); // 提取练习：命中即加固
+        else if (e) { e.hits = (e.hits || 0) + 1; e.lastHit = nowIso(); }
+      }
+      if (top.some(h => !h.historical)) { await store.saveIndex(); store.stats.searches += 1; await store.saveStats(); }
+      return out({
+        query: q, asOf: hasAsOf ? dayOf(new Date(asOfMs).toISOString()) : null,
+        total: hits.length, returned: top.length, matches: top,
+      });
+    },
+  });
+
+  // ---- memory_read ----
+  register({
+    name: 'memory_read',
+    description: '按 id 读取一条记忆的全文（超过 4000 字符会截断并给出本地路径）。id 来自 memory_search 或 memory_list。读取本身也是一次复习，会轻微加固记忆。',
+    parameters: { id: { type: 'string', required: true, description: '记忆 id。' } },
+    output: { schema: { type: 'object', additionalProperties: true }, render: (_a, v) => [{ type: 'text', text: JSON.stringify(v, null, 1) }] },
+    async execute(args) {
+      const safe = String(args.id ?? '').trim();
+      const e = store.byId(safe);
+      if (!e) return out({ ok: false, code: 'not_found', message: `没有 id 为 ${safe} 的记忆，先用 memory_search 找。` });
+      let content = '';
+      try { content = await fs.readFile(e.file, 'utf8'); } catch {
+        content = `# ${e.title}\n\n${e.content ?? ''}`;
+      }
+      const body = content;
+      const truncated = body.length > 4000;
+      if (cfg.reviewEnabled) {
+        reinforce(e, 1.1);
+        await store.saveIndex();
+      }
+      return out({
+        ok: true, id: e.id, title: e.title, status: e.status, tags: e.tags || [],
+        importance: e.importance ?? 3, salience: e.salience ?? 5,
+        stability: e.stability, nextReview: e.nextReview,
+        validFrom: e.validFrom || e.created, validTo: e.validTo || null,
+        historyCount: (e.history || []).length,
+        created: e.created, updated: e.updated,
+        content: truncated ? body.slice(0, 4000) : body,
+        truncated, local_file: e.file, size_bytes: Buffer.byteLength(body, 'utf8'),
+      });
+    },
+  });
+
+  // ---- memory_list ----
+  register({
+    name: 'memory_list',
+    description: '列出最近的活跃记忆（置顶优先，其次按更新时间倒序）。用于快速了解记住过什么。',
+    parameters: { limit: { type: 'number', description: '最多条数（默认 8，最大 50）。' } },
+    output: { schema: { type: 'object', additionalProperties: true }, render: (_a, v) => [{ type: 'text', text: JSON.stringify(v, null, 1) }] },
+    async execute(args) {
+      if (!store.entries.length) await store.load();
+      const limit = Math.min(50, Math.max(1, Math.trunc(Number(args.limit) || 8)));
+      const visible = store.visible();
+      const entries = visible.slice(0, limit).map(e => out({
+        id: e.id, title: e.title, pinned: !!e.pinned, tags: e.tags || [],
+        importance: e.importance ?? 3, updated: dayOf(e.updated), hits: e.hits || 0,
+      }));
+      const archived = store.entries.filter(e => e.status !== 'active').length;
+      return out({ ok: true, total: visible.length, archived, returned: entries.length, entries });
+    },
+  });
+
+  // ---- memory_pin ----
+  register({
+    name: 'memory_pin',
+    description: '置顶或取消置顶一条记忆。置顶记忆永远出现在热索引最前，不参与衰减归档。',
+    parameters: {
+      id: { type: 'string', required: true, description: '记忆 id。' },
+      pinned: { type: 'boolean', description: 'true 置顶，false 取消（默认 true）。' },
+    },
+    output: { schema: { type: 'object', additionalProperties: true }, render: (_a, v) => [{ type: 'text', text: JSON.stringify(v, null, 1) }] },
+    async execute(args) {
+      const e = store.byId(String(args.id ?? '').trim());
+      if (!e) return out({ ok: false, code: 'not_found', message: '没有找到该记忆' });
+      e.pinned = args.pinned === false ? false : true;
+      e.updated = nowIso();
+      await store.saveIndex();
+      return out({ ok: true, id: e.id, pinned: e.pinned, title: e.title });
+    },
+  });
+
+  // ---- memory_forget ----
+  register({
+    name: 'memory_forget',
+    description: '遗忘一条记忆（软删除：状态标记 deleted 并移出索引，文件保留在冷档案，不会被压缩复活）。用户明确要求"忘掉"时使用。',
+    parameters: { id: { type: 'string', required: true, description: '记忆 id。' } },
+    output: { schema: { type: 'object', additionalProperties: true }, render: (_a, v) => [{ type: 'text', text: JSON.stringify(v, null, 1) }] },
+    async execute(args) {
+      const e = store.byId(String(args.id ?? '').trim());
+      if (!e) return out({ ok: false, code: 'not_found', message: '没有找到该记忆' });
+      try {
+        const text = await fs.readFile(e.file, 'utf8');
+        await store.archiveContent(e, text);
+      } catch { /* 文件可能已不在 */ }
+      e.status = 'deleted';
+      e.validTo = e.validTo || nowIso();
+      e.pinned = false;
+      e.updated = nowIso();
+      try { await fs.unlink(e.file); } catch { /* 已删除 */ }
+      await store.saveIndex();
+      return out({ ok: true, id: e.id, forgotten: true, title: e.title });
+    },
+  });
+
+  // ---- memory_profile_save ----
+  register({
+    name: 'memory_profile_save',
+    description: '写入 L0 画像（每次会话都常驻注入的一小段文字，预算约 200 tokens）。只放"关于铁凝的事实与硬约束"：称呼、身份、偏好、雷点。不是记忆条目，别放项目细节。',
+    parameters: {
+      content: { type: 'string', required: true, description: '画像正文（Markdown，纯文本也行），会按预算截断。' },
+    },
+    output: { schema: { type: 'object', additionalProperties: true }, render: (_a, v) => [{ type: 'text', text: JSON.stringify(v, null, 1) }] },
+    async execute(args) {
+      const raw = String(args.content ?? '').trim();
+      if (!raw) return out({ ok: false, code: 'invalid_input', message: 'content 不能为空' });
+      if (SECRET_RE.test(raw)) return out({ ok: false, code: 'secret_refused', message: '疑似密钥/凭据，拒绝写入画像。' });
+      const body = `# 小肥鱼记忆 · L0 画像\n\n${raw}\n`;
+      await atomicWrite(store.profileFile, body);
+      return out({ ok: true, saved: true, tokens: estTokens(raw), budget: cfg.profileTokens });
+    },
+  });
+
+  // ---- memory_dream ----
+  register({
+    name: 'memory_dream',
+    description: '睡梦机制（三阶段）：SWS 重放+压缩近似记忆、SHY 显著性加权衰减、REM 建立联想链接；同时输出到期复习清单。默认只报告不自动保存（autoSave=true 时只自动保存用户明确说"记住…"的句子）。做完梦后逐条判断候选、memory_save 值得留下的，再 memory_consolidate。',
+    parameters: {
+      days: { type: 'number', description: '回顾最近几天（默认 2）。' },
+      autoSave: { type: 'boolean', description: '是否自动保存"明确要求记住"的候选（默认 false）。' },
+    },
+    output: { schema: { type: 'object', additionalProperties: true }, render: (_a, v) => [{ type: 'text', text: JSON.stringify(v, null, 1) }] },
+    async execute(args) {
+      const days = Math.min(30, Math.max(1, Math.trunc(Number(args.days) || cfg.dreamDays)));
+      const dream = await buildDream(store, cfg, days);
+      const autoSaved = [];
+      if (args.autoSave === true) {
+        for (const c of dream.cues) {
+          if (!c.explicit) continue;
+          const raw = c.text.replace(/^.*?(记住|记一下|记下)[:：]?\s*/, '').trim();
+          if (!raw) continue;
+          const title = raw.slice(0, 30);
+          const r = await saveMemoryCore(store, cfg, { title, content: raw, tags: ['睡眠提炼'], importance: 4 });
+          autoSaved.push({ title, id: r.id, updated: r.updated === true, noop: r.noop === true, ok: r.ok });
+        }
+      }
+      return out({
+        ok: true, day: dream.day, days, sessions: dream.sessions, messages: dream.messages,
+        phases: {
+          sws: dream.phases.sws.mergedCount,
+          shy: dream.phases.shy.demotedCount,
+          rem: dream.phases.rem.linkCount,
+        },
+        dueReview: dream.due,
+        cues: dream.cues.length,
+        candidates: dream.cues.map(c => ({ at: c.at, session: c.session, text: c.text, explicit: c.explicit })),
+        autoSaved, reportFile: dream.file, report: dream.report,
+      });
+    },
+  });
+
+  // ---- memory_stats ----
+  register({
+    name: 'memory_stats',
+    description: '查看记忆占用统计：活跃/归档条数、L0+L1 注入 token、磁盘字符量、检索次数。用于确认上下文成本是否恒定。',
+    parameters: {},
+    output: { schema: { type: 'object', additionalProperties: true }, render: (_a, v) => [{ type: 'text', text: JSON.stringify(v, null, 1) }] },
+    async execute() {
+      if (!store.entries.length) await store.load();
+      const hot = buildInjection(store, cfg);
+      const active = store.entries.filter(e => e.status === 'active');
+      const archived = store.entries.filter(e => e.status !== 'active');
+      const totalChars = store.entries.reduce((n, e) => n + (e.chars || 0), 0);
+      const due = store.due();
+      const salienceAvg = active.length
+        ? Number((active.reduce((n, e) => n + (e.salience ?? 5), 0) / active.length).toFixed(1))
+        : 0;
+      return out({
+        ok: true,
+        active: active.length, archived: archived.length, pinned: active.filter(e => e.pinned).length,
+        dueReview: due.length,
+        salienceAvg,
+        reviews: active.reduce((n, e) => n + (e.reviews || 0), 0),
+        l1Lines: hot.l1Lines, coldRemaining: hot.cold,
+        injectedL0Tokens: hot.profileTokens, injectedL1Tokens: hot.l1Tokens,
+        budgetTokens: cfg.budgetTokens,
+        diskChars: totalChars,
+        hits: store.stats.searches, saved: store.stats.saved, updated: store.stats.updated,
+        captured: store.stats.captured || 0,
+        dreams: store.stats.dreams || 0,
+        lastDream: store.stats.lastDream || null,
+        lastConsolidate: store.stats.lastConsolidate,
+      });
+    },
+  });
+
+  // ---- memory_consolidate ----
+  register({
+    name: 'memory_consolidate',
+    description: '手动整理记忆：合并同主题近似条目（相似度≥0.75，旧的归档、新的保留并记录 supersede）、衰减归档长期未用的低重要度记忆。纯本地规则，不调用 LLM。返回整理报告。',
+    parameters: { dryRun: { type: 'boolean', description: '只报告不修改（默认 false）。' } },
+    output: { schema: { type: 'object', additionalProperties: true }, render: (_a, v) => [{ type: 'text', text: JSON.stringify(v, null, 1) }] },
+    async execute(args) {
+      if (!store.entries.length) await store.load();
+      const dry = args.dryRun === true;
+      const merged = [];
+      const archived = [];
+      const now = Date.now();
+
+      // 1) 合并近似条目
+      const active = store.entries.filter(e => e.status === 'active').sort((a, b) => String(b.updated).localeCompare(String(a.updated)));
+      const removed = new Set();
+      for (let i = 0; i < active.length; i++) {
+        const a = active[i];
+        if (removed.has(a.id)) continue;
+        for (let j = i + 1; j < active.length; j++) {
+          const b = active[j];
+          if (removed.has(b.id)) continue;
+          const sim = similar(`${a.title}\n${a.content ?? ''}`, `${b.title}\n${b.content ?? ''}`);
+          if (sim < cfg.dedupeThreshold) continue;
+          const keep = String(a.updated).localeCompare(String(b.updated)) >= 0 ? a : b;
+          const drop = keep === a ? b : a;
+          merged.push({ kept: keep.id, dropped: drop.id, similarity: Number(sim.toFixed(2)) });
+          if (!dry) {
+            keep.supersedes = [...new Set([...(keep.supersedes || []), drop.id])];
+            try {
+              const text = await fs.readFile(drop.file, 'utf8');
+              await store.archiveContent(drop, text);
+            } catch { /* 忽略 */ }
+            drop.status = 'archived';
+            drop.validTo = drop.validTo || nowIso();
+            drop.pinned = false;
+            drop.updated = nowIso();
+            removed.add(drop.id);
+          } else {
+            removed.add(drop.id);
+          }
+        }
+      }
+
+      // 2) 衰减归档：>archiveAfterDays 天未更新、低重要度、未置顶、从未被检索
+      for (const e of store.entries) {
+        if (e.status !== 'active' || e.pinned) continue;
+        if ((e.importance ?? 3) >= 4 || (e.hits || 0) > 0) continue;
+        const ageDays = (now - new Date(e.updated || e.created).getTime()) / 86400000;
+        if (ageDays > cfg.archiveAfterDays) {
+          if (!dry) {
+            try {
+              const text = await fs.readFile(e.file, 'utf8');
+              await store.archiveContent(e, text);
+            } catch { /* 忽略 */ }
+            e.status = 'archived';
+            e.validTo = e.validTo || nowIso();
+            e.updated = nowIso();
+          }
+          archived.push({ id: e.id, ageDays: Math.round(ageDays) });
+        }
+      }
+
+      if (!dry) {
+        await store.saveIndex();
+        store.stats.consolidations += 1;
+        store.stats.lastConsolidate = nowIso();
+        await store.saveStats();
+      }
+      const hot = buildInjection(store, cfg);
+      return out({
+        ok: true, dryRun: dry,
+        mergedCount: merged.length, archivedCount: archived.length,
+        merged, archived,
+        activeAfter: store.entries.filter(e => e.status === 'active').length,
+        injectedL1Tokens: hot.l1Tokens, budgetTokens: cfg.budgetTokens,
+      });
+    },
+  });
+
+}