cortico-world-memory 0.1.8 → 0.1.10

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cortico-world-memory",
-  "version": "0.1.8",
+  "version": "0.1.10",
   "type": "module",
   "description": "Cortico World 扩展：五层记忆（事实库/知识库/反思/人格/档案）+ 三级记忆底座 + Hybrid Recall 向量混合检索（移植自 E:/qq_bot 的记忆系统与 memory_server 向量 sidecar，qq_bot 源码零改动）。",
   "license": "MIT",

package/src/backend.ts

@@ -10,7 +10,7 @@
  *  SQLite 驱动优先级:先试 `better-sqlite3`(原生,若已安装),缺失则回退 Node 内置
  *  `node:sqlite`(v24+ 自带,零安装)。两者 API 兼容(.prepare().get()/.run()、.exec())。
  */
-import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, renameSync, statSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 
 export type BackendKind = 'json' | 'sqlite';
@@ -164,3 +164,69 @@ export async function createBackend(kind: BackendKind, dataDir: string, log?: Lo
   log?.('[memory] 存储后端=json');
   return new JsonBackend(dataDir);
 }
+
+/**
+ * 只读打开 memory.db,导出 KV 行为 Map<stem, obj>。供「切回 JSON」时回填用。
+ * 优先 better-sqlite3,缺失则回退 Node 内置 node:sqlite(本环境走这条)。
+ */
+export async function readSqliteData(dataDir: string, stems: readonly string[]): Promise<Map<string, unknown>> {
+  const dbFile = join(dataDir, 'memory.db');
+  if (!existsSync(dbFile)) return new Map();
+  let db: any;
+  try {
+    const mod: any = await import('better-sqlite3');
+    const Database = mod.default ?? mod;
+    db = new Database(dbFile, { readonly: true });
+  } catch {
+    const { DatabaseSync } = await import('node:sqlite');
+    db = new DatabaseSync(dbFile, { readOnly: true });
+  }
+  const out = new Map<string, unknown>();
+  try {
+    let rows: any[];
+    if (stems.length) {
+      const ph = stems.map(() => '?').join(',');
+      rows = db.prepare(`SELECT name, data FROM kv WHERE name IN (${ph})`).all(...stems);
+    } else {
+      rows = db.prepare('SELECT name, data FROM kv').all();
+    }
+    for (const r of rows) {
+      try { out.set(r.name, JSON.parse(r.data)); } catch { /* 跳过损坏行 */ }
+    }
+  } finally {
+    try { db.close(); } catch { /* ignore */ }
+  }
+  return out;
+}
+
+/**
+ * 切回 JSON 时,若 memory.db 存在且其中数据比对应 JSON 文件更新,回填到 JSON 文件,
+ * 消除 json↔sqlite 切换的数据不对称(此前 sqlite→json 会丢 SQLite 期间的写入)。
+ * 返回回填的 store 数量。仅当 JSON 缺文件或比 DB 更旧时才覆盖,避免冲掉用户在 JSON 上的后续手动编辑。
+ */
+export async function backfillSqliteToJson(dataDir: string, log?: LogFn): Promise<number> {
+  const dbFile = join(dataDir, 'memory.db');
+  if (!existsSync(dbFile)) return 0;
+  let fromSqlite: Map<string, unknown>;
+  try {
+    fromSqlite = await readSqliteData(dataDir, ALL_STEMS);
+  } catch (e: any) {
+    log?.(`[memory] 读 SQLite 失败,跳过回填: ${e?.message ?? e}`);
+    return 0;
+  }
+  if (!fromSqlite.size) return 0;
+  const json = new JsonBackend(dataDir);
+  let filled = 0;
+  const dbMtime = statSync(dbFile).mtimeMs;
+  for (const stem of ALL_STEMS) {
+    if (!fromSqlite.has(stem)) continue;
+    const jsonFile = join(dataDir, stem + '.json');
+    const jsonMtime = existsSync(jsonFile) ? statSync(jsonFile).mtimeMs : 0;
+    if (jsonMtime === 0 || dbMtime > jsonMtime) {
+      json.writeJson(stem, fromSqlite.get(stem));
+      filled++;
+    }
+  }
+  if (filled) log?.(`[memory] 已从 SQLite 回填 ${filled} 个 store 到 JSON(不丢切换期间写入)`);
+  return filled;
+}

package/src/config.ts

@@ -98,7 +98,7 @@ export const MEMORY_CONFIG_GROUP: ConfigGroup = {
       'worlds.memory.embeddingTimeoutMs': { type: 'number', title: 'Sidecar 超时(ms)', description: 'qq_bot 向量模型首载慢,默认 3 分钟。' },
       'worlds.memory.storageBackend': {
         type: 'string', title: '存储后端', enum: ['json', 'sqlite'], 'x-hot': false,
-        description: 'json=原生 JSON 文件(默认);sqlite=单库 KV(自动 better-sqlite3→node:sqlite 回退)。切 sqlite 首次自动迁移旧 JSON。改后须点「重启」生效。',
+        description: 'json=原生 JSON 文件(默认);sqlite=单库 KV(自动 better-sqlite3→node:sqlite 回退)。切 sqlite 首次自动迁移旧 JSON;切回 json 若 memory.db 数据更新会自动回填,不丢切换期间写入。改后须点「重启」生效。',
       },
     },
   },

package/src/world.ts

@@ -1,4 +1,4 @@
-import { readFileSync } from 'node:fs';
+import { readFileSync, statSync, writeFileSync, mkdirSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import type { World, WorldHost, ToolDef, ToolTag, EventEnvelope } from 'cortico/core/types.ts';
 import type { WorldContext } from 'cortico/world.ts';
@@ -12,11 +12,124 @@ import { KnowledgeStore } from './knowledge-store.ts';
 import { ReflectionStore } from './reflection-store.ts';
 import { PersonaStore } from './persona-store.ts';
 import { ProfileStore } from './profile-store.ts';
-import { createBackend, StoreBackend, ALL_STEMS } from './backend.ts';
+import { createBackend, StoreBackend, ALL_STEMS, backfillSqliteToJson } from './backend.ts';
 import { buildEventText, buildView, promptVars } from './observe.ts';
 
 const ENV_PROMPT_FILE = fileURLToPath(new URL('./ENV_PROMPT.md', import.meta.url));
 
+type _Dict = Record<string, any>;
+
+/** 仅保留对象中指定 key 的条目(用于按 scope 过滤)。 */
+function pickScope(obj: _Dict, key: string): _Dict {
+  if (obj && typeof obj === 'object' && key in obj) return { [key]: obj[key] };
+  return {};
+}
+
+/** 把导出 bundle 渲染为易读 Markdown。 */
+function renderMemoryMarkdown(b: _Dict): string {
+  const L: string[] = [];
+  const profiles = (b.profiles ?? {}) as _Dict;
+  const profKeys = Object.keys(profiles);
+  const store = (b.memory?.store ?? {}) as _Dict;
+  const storeKeys = Object.keys(store);
+  const summary = (b.memory?.summary ?? {}) as _Dict;
+  const topic = (b.memory?.topic ?? {}) as _Dict;
+  const notes = (b.memory?.notes ?? {}) as _Dict;
+  const noteKeys = Object.keys(notes);
+  const factScopes = (b.facts?.scopes ?? {}) as _Dict;
+  const factKeys = Object.keys(factScopes);
+  const knowledge = (b.knowledge?.entries ?? []) as any[];
+  const reflections = (b.reflection?.reflections ?? []) as any[];
+  const rules = (b.reflection?.rules ?? []) as any[];
+  const personas = (b.persona?.personas ?? {}) as _Dict;
+  const personaKeys = Object.keys(personas);
+  const vectors = (b.vectors?.vectors ?? []) as any[];
+
+  L.push('# 记忆导出');
+  L.push('');
+  L.push(`- 导出时间：${b.exportedAt ?? ''}`);
+  L.push(`- 作用域：${b.scope ?? 'ALL'}`);
+  L.push(`- 存储后端：${b.backend ?? 'unknown'}`);
+  L.push('');
+
+  if (profKeys.length) {
+    L.push(`## 人物档案 (${profKeys.length})`);
+    for (const u of profKeys) {
+      L.push(`### ${u}`);
+      for (const f of profiles[u]?.facts ?? []) L.push(`- ${f}`);
+    }
+    L.push('');
+  }
+  if (storeKeys.length) {
+    L.push(`## 短期记忆 (${storeKeys.length} scope)`);
+    for (const s of storeKeys) {
+      L.push(`### scope: ${s}`);
+      for (const it of store[s] ?? []) L.push(`- [${it.role ?? ''}] ${it.content ?? ''}`);
+    }
+    L.push('');
+  }
+  const sumKeys = Object.keys(summary);
+  if (sumKeys.length || Object.keys(topic).length) {
+    L.push('## 总结与主题');
+    for (const s of sumKeys) { L.push(`### ${s} 总结`); L.push(summary[s] ?? ''); }
+    for (const s of Object.keys(topic)) { L.push(`### ${s} 主题`); L.push(topic[s] ?? ''); }
+    L.push('');
+  }
+  if (noteKeys.length) {
+    L.push(`## 笔记 (${noteKeys.length})`);
+    for (const s of noteKeys) {
+      L.push(`### ${s}`);
+      for (const n of notes[s] ?? []) L.push(`- ${n.text ?? ''}`);
+    }
+    L.push('');
+  }
+  if (factKeys.length) {
+    L.push(`## 事实库 (${factKeys.length} scope)`);
+    for (const s of factKeys) {
+      L.push(`### ${s}`);
+      for (const f of factScopes[s] ?? []) L.push(`- ${f.text ?? ''}`);
+    }
+    L.push('');
+  }
+  if (knowledge.length) {
+    L.push(`## 知识库 (${knowledge.length})`);
+    for (const e of knowledge) {
+      L.push(`### ${e.topic ?? ''}`);
+      if (e.keywords?.length) L.push(`关键词：${e.keywords.join(', ')}`);
+      for (const f of e.facts ?? []) L.push(`- ${f}`);
+    }
+    L.push('');
+  }
+  if (reflections.length || rules.length) {
+    L.push(`## 反思与交互规则 (${reflections.length}/${rules.length})`);
+    for (const r of reflections) L.push(`- [${r.type}] (${r.userId}) ${r.content ?? ''}`);
+    if (rules.length) {
+      L.push('### 交互规则');
+      for (const r of rules) L.push(`- (${r.userId}) ${r.rule ?? ''}`);
+    }
+    L.push('');
+  }
+  if (personaKeys.length || b.persona?.globalStyle) {
+    L.push(`## 人格记忆 (${personaKeys.length})`);
+    if (b.persona?.globalStyle) L.push(`全局风格：${b.persona.globalStyle}`);
+    for (const u of personaKeys) {
+      L.push(`### ${u}`);
+      L.push(`风格：${personas[u]?.style ?? ''}`);
+      for (const t of personas[u]?.traits ?? []) L.push(`- ${t}`);
+    }
+    L.push('');
+  }
+  if (vectors.length) {
+    L.push(`## 向量记忆 (${vectors.length}, 模型：${b.vectors?.model ?? '未知'})`);
+    for (const v of vectors) {
+      const txt = typeof v.text === 'string' ? v.text : JSON.stringify(v.text);
+      L.push(`- [${v.scope}] ${txt.slice(0, 200)}`);
+    }
+    L.push('');
+  }
+  return L.join('\n');
+}
+
 /** 清理自动捕获的入站文本:去掉 QQ 的「【QQ群 ...】」前缀(对其它 world 无前缀,无副作用),压缩空白。 */
 function cleanCaptureText(t: string): string {
   return (t ?? '')
@@ -91,6 +204,9 @@ export class MemoryWorld implements World {
   envPromptVars(): Record<string, string> | null {
     if (!this.mem || !this.vectors) return null; // 未启动 = 本 World 这段不进前缀
     const view = buildView(this.mem, this.vectors, 'main', this.cfg.notesInPrompt, this.profile);
+    // 合并 QQ 笔记本('qq' scope)的要点，让智能体也能常驻记住——qq_note_* 走记忆插件时落在此域。
+    const qqNotes = this.mem.getNotes('qq').slice(-this.cfg.notesInPrompt);
+    if (qqNotes.length) view.notes = [...view.notes, ...qqNotes].slice(-this.cfg.notesInPrompt);
     return promptVars(view);
   }
 
@@ -126,8 +242,13 @@ export class MemoryWorld implements World {
     this.host = host;
     const ctxData = this.ctx.dataDir;
     const dataDir = typeof ctxData === 'string' && ctxData ? ctxData : '.';
-    this.backend = await createBackend(this.cfg.storageBackend ?? 'json', dataDir, (m) => host.log.info(m));
-    this.backend.migrateFromJson(ALL_STEMS); // 首次切 sqlite 自动迁移旧 JSON
+    const kind = this.cfg.storageBackend ?? 'json';
+    this.backend = await createBackend(kind, dataDir, (m) => host.log.info(m));
+    if (kind === 'sqlite') {
+      this.backend.migrateFromJson(ALL_STEMS); // json→sqlite:首次自动迁移旧 JSON
+    } else {
+      await backfillSqliteToJson(dataDir, (m) => host.log.info(m)); // sqlite→json:回填较新数据,消除切换丢写
+    }
     this.mem = new MemoryBase(dataDir, this.cfg.maxHistory, this.backend);
     this.vectors = new VectorStore(dataDir, this.backend);
     this.facts = new FactStore(dataDir, this.backend);
@@ -156,10 +277,19 @@ export class MemoryWorld implements World {
     // 自动捕获:从当前事件尾开始(不回灌历史),周期扫描外部入站消息沉淀进记忆。
     try { this.lastCursor = (host.store?.latestCursor?.() ?? 0) || 0; } catch { this.lastCursor = 0; }
     if (this.cfg.autoCapture) this.startCapture();
+    // QQ 插件笔记本桥：启用时让 qq_note_* 直接写入本插件笔记库('qq' scope)，复用常驻环境提示词与混合检索。
+    (globalThis as Record<string, unknown>)['cortico:memory:notebook'] = {
+      kind: 'memory' as const,
+      save: (text: string) => this.mem!.addNote('qq', text),
+      list: () => this.mem!.getNotes('qq'),
+      get: (index: number) => this.mem!.getNotes('qq')[index] ?? null,
+      forget: (index: number) => this.mem!.removeNote('qq', index),
+    };
   }
 
   /** stop 必须 async 返回 Promise(框架 withDeadline 直接 work.then)。 */
   async stop(): Promise<void> {
+    delete (globalThis as Record<string, unknown>)['cortico:memory:notebook'];
     if (this.timer) clearInterval(this.timer);
     this.timer = null;
     if (this.captureTimer) { clearInterval(this.captureTimer); this.captureTimer = null; }
@@ -173,6 +303,103 @@ export class MemoryWorld implements World {
     this.backend?.flush(); // 最后统一关闭 SQLite(每个 store 的 flush 只写行,不关库)
   }
 
+  /**
+   * 导出全部记忆为 JSON / Markdown 文件(便于备份、迁移、阅读)。
+   * - format: 'json' | 'markdown' | 'both'
+   * - scope: 可选,按作用域/用户过滤(短期/事实/向量按 scope;反思/人格/档案按 userId;知识库为全局始终包含)
+   * - outDir: 导出目录,默认 <dataDir>/exports
+   */
+  private async exportMemory(format: string, scope: string, outDir: string): Promise<{ text: string }> {
+    const wantJson = !format || format === 'both' || format === 'json';
+    const wantMd = !format || format === 'both' || format === 'markdown';
+    const dir = (outDir && outDir.trim()) || path.join(this.dataDir, 'exports');
+    mkdirSync(dir, { recursive: true });
+
+    const read = async (stem: string): Promise<_Dict> => {
+      try { return (await this.backend!.readJson(stem)) as _Dict; } catch { return {}; }
+    };
+
+    const memRaw = (await read('memory-data')) ?? {};
+    const factRaw = (await read('fact-store')) ?? {};
+    const vectorRaw = (await read('vector-memory')) ?? {};
+    const kbRaw = (await read('knowledge-base')) ?? {};
+    const reflRaw = (await read('reflection-data')) ?? {};
+    const personaRaw = (await read('persona-data')) ?? {};
+    const profileRaw = (await read('user-profiles')) ?? {};
+
+    let store = (memRaw.store ?? {}) as _Dict;
+    let notes = (memRaw.notes ?? {}) as _Dict;
+    let summary = (memRaw.summary ?? {}) as _Dict;
+    let topic = (memRaw.topic ?? {}) as _Dict;
+    let factScopes = (factRaw.scopes ?? {}) as _Dict;
+    let vectors = (vectorRaw.vectors ?? []) as any[];
+    let reflections = (reflRaw.reflections ?? []) as any[];
+    let rules = (reflRaw.interactionRules ?? []) as any[];
+    let personas = (personaRaw.personas ?? {}) as _Dict;
+    let profiles = (profileRaw.profiles ?? {}) as _Dict;
+    const globalStyle = (personaRaw.globalStyle ?? '') as string;
+    const knowledge = (kbRaw.entries ?? []) as any[];
+
+    const filterScope = (scope || '').trim();
+    if (filterScope) {
+      store = pickScope(store, filterScope);
+      notes = pickScope(notes, filterScope);
+      summary = pickScope(summary, filterScope);
+      topic = pickScope(topic, filterScope);
+      factScopes = pickScope(factScopes, filterScope);
+      vectors = vectors.filter((v: _Dict) => v.scope === filterScope);
+      reflections = reflections.filter((r: _Dict) => String(r.userId) === filterScope);
+      rules = rules.filter((r: _Dict) => String(r.userId) === filterScope);
+      personas = pickScope(personas, filterScope);
+      profiles = pickScope(profiles, filterScope);
+    }
+
+    const bundle: _Dict = {
+      exportedAt: new Date().toISOString(),
+      plugin: 'cortico-world-memory',
+      scope: filterScope || 'ALL',
+      backend: (this.backend as unknown as { constructor?: { name?: string } })?.constructor?.name ?? 'unknown',
+      memory: { store, summary, topic, notes },
+      facts: { scopes: factScopes },
+      vectors: { model: vectorRaw.model_name ?? null, vectors },
+      knowledge: { entries: knowledge },
+      reflection: { reflections, rules, stats: reflRaw.stats ?? {} },
+      persona: { personas, globalStyle },
+      profiles,
+    };
+
+    const stamp = new Date().toISOString().replace(/[:.]/g, '-').replace('T', '_').slice(0, 19);
+    const base = `memory-export-${stamp}`;
+    const written: string[] = [];
+
+    if (wantJson) {
+      const p = path.join(dir, `${base}.json`);
+      writeFileSync(p, JSON.stringify(bundle, null, 2), 'utf8');
+      written.push(p);
+    }
+    if (wantMd) {
+      const p = path.join(dir, `${base}.md`);
+      writeFileSync(p, renderMemoryMarkdown(bundle), 'utf8');
+      written.push(p);
+    }
+
+    const factCount = Object.values(factScopes).reduce((s: number, l: any) => s + (Array.isArray(l) ? l.length : 0), 0);
+    const counts = [
+      `短期记忆 ${Object.keys(store).length} scope`,
+      `笔记 ${Object.keys(notes).length}`,
+      `事实 ${factCount} 条`,
+      `向量 ${vectors.length}`,
+      `知识 ${knowledge.length} 条`,
+      `反思 ${reflections.length} / 规则 ${rules.length}`,
+      `人格 ${Object.keys(personas).length} 用户`,
+      `档案 ${Object.keys(profiles).length} 用户`,
+    ].join(' | ');
+
+    return {
+      text: `记忆导出完成（${filterScope ? 'scope=' + filterScope : '全部'}）\n${counts}\n文件：\n` + written.map((w) => '- ' + w).join('\n'),
+    };
+  }
+
   /** 启动自动捕获轮询(尊重暂停开关)。 */
   private startCapture(): void {
     const ms = Math.max(5000, Number(this.cfg.captureIntervalMs) || 20000);
@@ -443,6 +670,24 @@ export class MemoryWorld implements World {
         }),
       mem_flush: mk('mem_flush', '把记忆立即落盘(平时自动防抖落盘,一般不用调)。', {}, [], ['act'],
         async () => { this.mem?.flush(); this.vectors?.flush(); this.facts?.flush(); this.kb?.flush(); this.reflect?.flush(); this.persona?.flush(); this.profile?.flush(); return 'OK 已落盘'; }),
+      mem_export: mk(
+        'mem_export',
+        '把全部记忆导出为文件(JSON/Markdown),便于备份、迁移、阅读。知识库为全局始终包含;其他可按作用域/用户过滤。',
+        {
+          format: { type: 'string', optional: true, title: '格式', description: "json | markdown | both(默认 both)。" },
+          scope: { type: 'string', optional: true, title: '作用域过滤', description: '可选,按作用域/用户过滤(短期/事实/向量按 scope;反思/人格/档案按 userId)。留空导出全部。' },
+          outDir: { type: 'string', optional: true, title: '导出目录', description: '可选,文件保存目录,默认 <数据目录>/exports。' },
+        },
+        [],
+        ['act'],
+        async (args: _Dict) => {
+          const format = typeof args.format === 'string' ? args.format.trim().toLowerCase() : 'both';
+          const scope = typeof args.scope === 'string' ? args.scope.trim() : '';
+          const outDir = typeof args.outDir === 'string' ? args.outDir.trim() : '';
+          if (!['json', 'markdown', 'both'].includes(format)) return { text: '错误：format 只能是 json / markdown / both。' };
+          return await this.exportMemory(format, scope, outDir);
+        },
+      ),
     };
   }
 }