cortico-world-memory 0.1.0

package/src/world.ts

@@ -0,0 +1,336 @@
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import type { World, WorldHost, ToolDef, ToolTag } from 'cortico/core/types.ts';
+import type { WorldContext } from 'cortico/world.ts';
+import type { MemoryConfig } from './config.ts';
+import { MemoryBase } from './memory.ts';
+import { EmbeddingClient } from './embedding.ts';
+import { VectorStore } from './vector-store.ts';
+import { FactStore } from './fact-store.ts';
+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 { buildEventText, buildView, promptVars } from './observe.ts';
+
+const ENV_PROMPT_FILE = fileURLToPath(new URL('./ENV_PROMPT.md', import.meta.url));
+
+export class MemoryWorld implements World {
+  readonly id = 'memory';
+  private host: WorldHost | null = null;
+  private timer: ReturnType<typeof setInterval> | null = null;
+  private seq = 0;
+  private mem: MemoryBase | null = null;
+  private vectors: VectorStore | null = null;
+  private facts: FactStore | null = null;
+  private kb: KnowledgeStore | null = null;
+  private reflect: ReflectionStore | null = null;
+  private persona: PersonaStore | null = null;
+  private profile: ProfileStore | null = null;
+  private embedder: EmbeddingClient | null = null;
+
+  constructor(private readonly ctx: WorldContext<MemoryConfig>) {}
+
+  /** 环境提示词变量:要点/摘要/话题/统计,每轮上下文构建时现取(纯内存读)。 */
+  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);
+    return promptVars(view);
+  }
+
+  private get cfg(): MemoryConfig {
+    return this.ctx.cfg;
+  }
+
+  tools(): ToolDef[] {
+    return Object.values(this.buildTools());
+  }
+
+  console() {
+    return {
+      config: [], // 旋钮由部署的 worlds/memory.json 提供,此处不重复
+      promptDocs: [
+        {
+          key: 'worlds.memory.envPrompt',
+          title: '记忆系统 · 环境提示词',
+          description: '进 system 前缀的那一段:记忆库的使用纪律与动态记忆上下文。',
+          path: ENV_PROMPT_FILE,
+          role: 'envPrompt',
+          vars: [
+            { name: 'memoryContext', description: '重要信息/摘要/话题/统计 的拼接文本' },
+            { name: 'memoryScopes', description: '现存记忆域列表' },
+            { name: 'memoryVectors', description: '向量索引覆盖数/总数' },
+          ],
+        },
+      ],
+    };
+  }
+
+  async start(host: WorldHost): Promise<void> {
+    this.host = host;
+    const ctxData = this.ctx.dataDir;
+    const dataDir = typeof ctxData === 'string' && ctxData ? ctxData : '.';
+    this.mem = new MemoryBase(dataDir, this.cfg.maxHistory);
+    this.vectors = new VectorStore(dataDir);
+    this.facts = new FactStore(dataDir);
+    this.kb = new KnowledgeStore(dataDir);
+    this.reflect = new ReflectionStore(dataDir);
+    this.persona = new PersonaStore(dataDir);
+    this.profile = new ProfileStore(dataDir);
+    this.embedder = new EmbeddingClient(this.cfg);
+
+    host.log.info('[memory] 启动', {
+      dataDir,
+      maxHistory: this.cfg.maxHistory,
+      embedding: this.cfg.embeddingProvider,
+    });
+    if (this.cfg.embeddingProvider === 'sidecar') {
+      const ok = await this.embedder.sidecarHealthy();
+      host.log.info('[memory] sidecar 探测', ok === true ? '在线' : '不在线(自动只用 BM25)');
+    }
+
+    this.timer = setInterval(() => {
+      this.push('memory.context', buildEventText(this.view()));
+    }, Math.max(10_000, this.cfg.observeIntervalMs));
+
+    this.push('memory.context', buildEventText(this.view()));
+  }
+
+  /** stop 必须 async 返回 Promise(框架 withDeadline 直接 work.then)。 */
+  async stop(): Promise<void> {
+    if (this.timer) clearInterval(this.timer);
+    this.timer = null;
+    this.mem?.flush();
+    this.vectors?.flush(); // 防抖写盘强制落盘
+    this.facts?.flush();
+    this.kb?.flush();
+    this.reflect?.flush();
+    this.persona?.flush();
+    this.profile?.flush();
+  }
+
+  private view() {
+    return buildView(this.mem!, this.vectors!, 'main', this.cfg.notesInPrompt, this.profile);
+  }
+
+  private push(type: string, text: string) {
+    if (!this.host) return;
+    this.seq += 1;
+    // 内部事件+piggyback:记忆快照进会话历史但不唤醒回合,否则每个周期会触发生成让 bot 自言自语。
+    this.host.pushEvent({
+      type,
+      ts: new Date().toISOString(),
+      source: this.id,
+      origin: 'internal',
+      text,
+    }, { trigger: 'piggyback' }).catch(() => {});
+  }
+
+  // ---- 工具表:mem_ 前缀(框架内工具名全局唯一,避开 mc_*/其它 World) ----
+  private buildTools(): Record<string, ToolDef> {
+    const str = (title: string) => ({ type: 'string', title });
+    const num = (title: string) => ({ type: 'number', title });
+    const mk = (
+      name: string,
+      description: string,
+      properties: Record<string, unknown>,
+      required: string[],
+      tags: ToolTag[],
+      run: (a: Record<string, any>) => Promise<string>,
+      extra: Partial<ToolDef> = {},
+    ): ToolDef => ({
+      name,
+      description,
+      parameters: { type: 'object', additionalProperties: false, properties, required },
+      tags,
+      handler: async (args) => {
+        try { return await run(args); } catch (e: any) { return `⚠ 调用失败: ${e?.message ?? e}`; }
+      },
+      ...extra,
+    });
+
+    const scopeOf = (a: Record<string, any>) => (typeof a.scope === 'string' && a.scope.trim() ? a.scope.trim() : 'main');
+
+    return {
+      mem_remember: mk('mem_remember', '把一件值得长期记住的事写进记忆库(同时落「事实库」做去重重排 + 建向量索引,之后 mem_recall 可按语义找回)。', { text: str('内容'), scope: str('记忆域') }, ['text'], ['write'],
+        async (a) => {
+          const scope = scopeOf(a);
+          const text = String(a.text);
+          const added = this.facts!.add(scope, [text]); // 事实库:SHA-256 去重 + 原子落盘
+          this.vectors!.add(scope, text, this.cfg.embeddingProvider === 'off' ? null : await this.embedder!.embed(text), this.cfg.maxVectorsPerScope);
+          return added ? `OK 已记住(${scope}): ${text.slice(0, 80)}` : `OK 已存在,跳过重复(${scope})`;
+        }),
+      mem_recall: mk('mem_recall', '按语义+关键词混合检索长期记忆(事实库全文 + BM25+向量+RRF 融合),找旧账/回忆约定时用。', { query: str('查询'), top_k: num('条数'), scope: str('记忆域') }, ['query'], ['read'],
+        async (a) => {
+          const scope = scopeOf(a);
+          const topK = Math.min(20, Number(a.top_k) || this.cfg.vectorTopK);
+          const query = String(a.query);
+          const vector = this.cfg.embeddingProvider === 'off' ? null : await this.embedder!.embed(query);
+          const hits = this.vectors!.hybridSearch(scope, query, vector, topK);
+          const facts = this.facts!.recall(scope, query, topK);
+          // 合并两路结果,按 text 去重,事实库命中的优先(更精确)。
+          const seen = new Set<string>();
+          const out: string[] = [];
+          for (const f of facts) if (!seen.has(f.text)) { seen.add(f.text); out.push(f.text); }
+          for (const h of hits) if (!seen.has(h.text)) { seen.add(h.text); out.push(h.text); }
+          if (!out.length) return `OK ${scope} 里没有匹配「${query}」的记忆`;
+          return `OK ${out.slice(0, topK).map((t, i) => `${i + 1}. ${t}`).join('\n')}`;
+        }),
+      mem_recent: mk('mem_recent', '回看本域最近的短期对话(最多 maxHistory 条)。', { n: num('条数'), scope: str('记忆域') }, [], ['read', 'snapshot'],
+        async (a) => {
+          const items = this.mem!.recent(scopeOf(a), Number(a.n) || 10);
+          if (!items.length) return 'OK 短期记忆是空的';
+          return `OK\n${items.map((it) => `${it.role}: ${it.content.slice(0, 120)}`).join('\n')}`;
+        }),
+      mem_overflow: mk('mem_overflow', '短期记忆快满时,取出最旧的一半条目(出窗),让它们被压缩进 mem_summary。', { scope: str('记忆域') }, [], ['act'],
+        async (a) => {
+          const items = this.mem!.overflowItems(scopeOf(a));
+          if (!items) return 'OK 短期记忆还没满,无需压缩';
+          return `OK 取出 ${items.length} 条:\n${items.map((it) => `${it.role}: ${it.content.slice(0, 120)}`).join('\n')}`;
+        }),
+      mem_summary: mk('mem_summary', '读或写本域的对话摘要。带 text 为写(建议先把 mem_overflow 取出的旧条目浓缩成一段);不带为读。', { text: str('摘要内容'), scope: str('记忆域') }, [], ['read', 'write'],
+        async (a) => {
+          const scope = scopeOf(a);
+          if (typeof a.text === 'string' && a.text.trim()) {
+            this.mem!.setSummary(scope, String(a.text));
+            return `OK 摘要已更新(${scope})`;
+          }
+          const s = this.mem!.getSummary(scope);
+          return s ? `OK 当前摘要: ${s}` : `OK ${scope} 还没有摘要`;
+        }),
+      mem_topic: mk('mem_topic', '读或写当前话题(话题切换时更新它,帮助上下文连贯)。', { text: str('话题内容'), scope: str('记忆域') }, [], ['read', 'write'],
+        async (a) => {
+          const scope = scopeOf(a);
+          if (typeof a.text === 'string' && a.text.trim()) {
+            this.mem!.setTopic(scope, String(a.text));
+            return `OK 话题已更新(${scope})`;
+          }
+          const t = this.mem!.getTopic(scope);
+          return t ? `OK 当前话题: ${t}` : `OK ${scope} 还没有设定话题`;
+        }),
+      mem_note: mk('mem_note', '记一条「重要信息」(用户明确要求记住的事/硬约束),它会常驻进环境提示词。', { text: str('内容'), scope: str('记忆域') }, ['text'], ['write'],
+        async (a) => {
+          const n = this.mem!.addNote(scopeOf(a), String(a.text));
+          return `OK 重要信息 #${n} 已记录`;
+        }),
+      mem_notes: mk('mem_notes', '列出本域的全部「重要信息」及编号(编号用于 mem_forget_note)。', { scope: str('记忆域') }, [], ['read'],
+        async (a) => {
+          const notes = this.mem!.getNotes(scopeOf(a));
+          if (!notes.length) return 'OK 还没有重要信息';
+          return `OK\n${notes.map((n, i) => `${i + 1}. ${n.text}`).join('\n')}`;
+        }),
+      mem_forget_note: mk('mem_forget_note', '按编号(1 起)删掉一条「重要信息」。先 mem_notes 确认编号再用。', { index: num('编号'), scope: str('记忆域') }, ['index'], ['write'],
+        async (a) => {
+          const ok = this.mem!.removeNote(scopeOf(a), Number(a.index) - 1);
+          return ok ? 'OK 已删除' : `FAIL 没有第 ${Number(a.index)} 条`;
+        }),
+      mem_knowledge: mk('mem_knowledge', '沉淀一条「通用知识」(联网学到的、主题化的知识条目,区别于 mem_remember 的零散事实)。同主题会合并,事实级去重,超量淘汰最旧。', { topic: str('主题'), facts: str('知识要点(多条用换行分隔)'), keywords: str('关键词(逗号分隔,可选)'), sources: str('来源(逗号分隔,可选)') }, ['topic', 'facts'], ['write'],
+        async (a) => {
+          const topic = String(a.topic ?? '').trim();
+          const facts = String(a.facts ?? '').split('\n').map((s) => s.trim()).filter(Boolean);
+          const keywords = (typeof a.keywords === 'string' ? a.keywords : '').split(/[,，]/).map((s) => s.trim()).filter(Boolean);
+          const sources = (typeof a.sources === 'string' ? a.sources : '').split(/[,，]/).map((s) => s.trim()).filter(Boolean);
+          const r = this.kb!.addEntry(topic, facts, keywords, sources);
+          if (!r.ok) return 'FAIL 主题和要点不能为空';
+          return `OK ${r.merged ? '已并入已有主题' : '新主题'}「${topic}」,新增 ${r.newFacts} 条事实,知识库共 ${r.total} 条`;
+        }),
+      mem_knowledge_fact: mk('mem_knowledge_fact', '把单条知识文本直接记进知识库(主题取前 30 字,自动提炼关键词)。', { content: str('知识内容') }, ['content'], ['write'],
+        async (a) => {
+          const r = this.kb!.addFact(String(a.content ?? ''));
+          return r.ok ? `OK 已沉淀(${r.merged ? '并入已有主题' : '新主题'}),知识库共 ${r.total} 条` : 'FAIL 内容为空';
+        }),
+      mem_knowledge_recall: mk('mem_knowledge_recall', '回答问题前先查知识库,命中就直接复用(省去重复搜索)。返回最相关主题及要点。', { query: str('查询/问题'), top_k: num('条数') }, ['query'], ['read'],
+        async (a) => {
+          const hits = this.kb!.recall(String(a.query ?? ''), Math.min(10, Number(a.top_k) || 2));
+          if (!hits.length) return 'OK 知识库里没有相关条目';
+          return `OK 命中 ${hits.length} 条:\n` + hits.map((e) => {
+            const lines = e.facts.map((f, i) => `${i + 1}. ${f}`).join('\n');
+            return `◆ ${e.topic}（学习日期 ${e.learnedAt}）\n${lines}`;
+          }).join('\n');
+        }),
+      mem_knowledge_list: mk('mem_knowledge_list', '列出知识库全部主题(及命中数),便于总览已沉淀的知识。', { limit: num('条数') }, [], ['read'],
+        async (a) => {
+          const entries = this.kb!.count();
+          if (!entries) return 'OK 知识库还是空的';
+          return `OK 知识库共 ${entries} 条主题`;
+        }),
+      mem_reflect: mk('mem_reflect', '沉淀一条「反思/交互偏好/纠错」(五维记忆之反思维):用户偏好(preference)、交互风格(style)、用户洞察(insight)、AI纠错(correction)、对话模式(pattern)。可执行的会被提炼为常驻交互规则。', { content: str('反思内容(一句话)'), type: str('类型:preference/style/insight/correction/pattern'), evidence: str('支撑证据/对话片段(可选)'), user_id: str('用户ID(默认 main)'), confidence: num('置信度0-1'), actionable: num('是否可执行(1/0)') }, ['content', 'type'], ['write'],
+        async (a) => {
+          const type = String(a.type ?? 'insight');
+          if (!['preference', 'style', 'insight', 'correction', 'pattern'].includes(type)) return 'FAIL 类型必须是 preference/style/insight/correction/pattern 之一';
+          const r = this.reflect!.reflect(
+            String(a.content ?? ''),
+            type as any,
+            String(a.user_id ?? 'main'),
+            typeof a.evidence === 'string' ? a.evidence : undefined,
+            typeof a.confidence === 'number' ? Math.max(0, Math.min(1, a.confidence)) : 0.6,
+            Number(a.actionable ?? 1) >= 1,
+          );
+          return r.added ? `OK 反思已沉淀(${type});可执行的已提炼为交互规则` : 'FAIL 内容为空或重复';
+        }),
+      mem_reflect_rules: mk('mem_reflect_rules', '列出已沉淀的交互规则(从可执行反思提炼,常驻指导后续交互)。', { user_id: str('用户ID(默认 main)') }, [], ['read'],
+        async (a) => {
+          const { rules } = this.reflect!.getFor(String(a.user_id ?? 'main'));
+          if (!rules.length) return 'OK 还没有交互规则';
+          return `OK 交互规则(${rules.length}):\n` + rules.map((r, i) => `${i + 1}. [${r.type}] ${r.rule} (置信 ${(r.confidence ?? 0).toFixed(2)})`).join('\n');
+        }),
+      mem_persona: mk('mem_persona', '记录与某用户的独特相处模式(五维记忆之人格维):特征列表 + 风格描述,per-user 隔离、特征去重、上限20。', { user_id: str('用户ID(默认 main)'), traits: str('相处特征(多条用换行或逗号分隔)'), style: str('整体风格描述(可选)') }, ['user_id', 'traits'], ['write'],
+        async (a) => {
+          const uid = String(a.user_id ?? 'main');
+          const traits = String(a.traits ?? '').split(/[\n,，]/).map((s) => s.trim()).filter(Boolean);
+          const r = this.persona!.update(uid, traits, typeof a.style === 'string' ? a.style : '');
+          return `OK 已更新 ${uid} 的人格记忆,当前特征 ${r.traits} 条`;
+        }),
+      mem_persona_get: mk('mem_persona_get', '读取某用户的人格记忆(特征+风格),不存在则提示。', { user_id: str('用户ID(默认 main)') }, [], ['read'],
+        async (a) => {
+          const p = this.persona!.get(String(a.user_id ?? 'main'));
+          if (!p) return 'OK 还没有这个人设记忆';
+          const traits = p.traits.length ? p.traits.map((t, i) => `${i + 1}. ${t}`).join('\n') : '(无特征)';
+          return `OK 人格记忆:\n特征:\n${traits}${p.style ? `\n风格: ${p.style}` : ''}`;
+        }),
+      mem_persona_global: mk('mem_persona_global', '设置/读取全局风格(跨用户统一的人格基调,可选)。', { style: str('全局风格(留空为读)') }, [], ['read', 'write'],
+        async (a) => {
+          if (typeof a.style === 'string' && a.style.trim()) {
+            this.persona!.setGlobalStyle(a.style);
+            return 'OK 全局风格已更新';
+          }
+          const g = this.persona!.getGlobalStyle();
+          return g ? `OK 全局风格: ${g}` : 'OK 还没有设置全局风格';
+        }),
+      mem_profile: mk('mem_profile', '记/更新某用户的「人物档案」(永久记住的关键信息:称呼/身份/关系等),常驻进环境提示词。合并新事实+去重+上限50。', { user_id: str('用户ID(默认 main)'), facts: str('人物事实(多条用换行或逗号分隔)') }, ['user_id', 'facts'], ['write'],
+        async (a) => {
+          const uid = String(a.user_id ?? 'main');
+          const facts = String(a.facts ?? '').split(/[\n,，]/).map((s) => s.trim()).filter(Boolean);
+          const r = this.profile!.update(uid, facts);
+          return `OK 已更新 ${uid} 人物档案,当前 ${r.total} 条`;
+        }),
+      mem_profile_replace: mk('mem_profile_replace', '整体替换某用户人物档案(用于纠错,例如用户说「别再叫我XX」)。', { user_id: str('用户ID(默认 main)'), facts: str('正确的人物事实(多条用换行或逗号分隔)') }, ['user_id', 'facts'], ['write'],
+        async (a) => {
+          const uid = String(a.user_id ?? 'main');
+          const facts = String(a.facts ?? '').split(/[\n,，]/).map((s) => s.trim()).filter(Boolean);
+          const r = this.profile!.replace(uid, facts);
+          return `OK 已替换 ${uid} 人物档案,当前 ${r.total} 条`;
+        }),
+      mem_profile_get: mk('mem_profile_get', '读取某用户人物档案。', { user_id: str('用户ID(默认 main)') }, [], ['read'],
+        async (a) => {
+          const facts = this.profile!.get(String(a.user_id ?? 'main'));
+          return facts.length ? `OK 人物档案:\n${facts.map((f, i) => `${i + 1}. ${f}`).join('\n')}` : 'OK 还没有人物档案';
+        }),
+      mem_stats: mk('mem_stats', '记忆库统计:记忆域/条数/向量索引覆盖/当前配置的向量来源。', {}, [], ['snapshot', 'read'],
+        async () => {
+          const stats = this.vectors!.stats();
+          const sidecar = await this.embedder!.sidecarHealthy();
+          return `OK ${JSON.stringify({
+            scopes: stats.scopes,
+            total: stats.total,
+            indexed: stats.indexed,
+            embedding: this.cfg.embeddingProvider,
+            ...(sidecar !== null ? { sidecarOnline: sidecar } : {}),
+            maxHistory: this.cfg.maxHistory,
+          })}`;
+        }),
+      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 已落盘'; }),
+    };
+  }
+}