cortico-world-memory 0.1.0

package/src/knowledge-store.ts

@@ -0,0 +1,169 @@
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+
+export interface KnowledgeEntry {
+  id: string;
+  topic: string;
+  keywords: string[];
+  facts: string[];
+  sources: string[];
+  learnedAt: string;
+  updated: string;
+  hits: number;
+}
+
+interface KbFile {
+  entries: KnowledgeEntry[];
+}
+
+const MAX_ENTRIES = 200;
+const MAX_FACTS_PER_ENTRY = 20;
+const MAX_KEYWORDS = 12;
+const MAX_SOURCES = 8;
+
+const norm = (s: string): string => (s ?? '').replace(/\s+/g, '').toLowerCase();
+// 召回匹配域:主题 + 关键词 + 事实全文(否则中文事实只在 fact 文本里、关键词里没有,会检索不到)。
+const entryBlob = (e: KnowledgeEntry): string => [e.topic, ...e.keywords, ...e.facts].join(' ').toLowerCase();
+const queryTokens = (q: string): string[] =>
+  (q.toLowerCase().match(/[a-z0-9][a-z0-9.\-_/#]*/g) ?? []).filter((t) => t.length >= 2);
+
+/**
+ * 通用知识库(对齐 qq_bot knowledge_store):
+ * - 联网学到的通用知识沉淀于此(与 fact_store 事实库区分:这里是「主题化知识条目」)
+ * - add:同主题合并、事实级全库去重、超量淘汰最旧
+ * - recall:主题/关键词命中 + 全 token 命中,复用知识省去重复搜索
+ * - 原子落盘(临时文件 + rename)
+ */
+export class KnowledgeStore {
+  private readonly file: string;
+  private data: KbFile = { entries: [] };
+  private dirty = false;
+  private readonly flushTimer: ReturnType<typeof setInterval>;
+
+  constructor(dataDir: string, flushMs = 2000) {
+    this.file = join(dataDir, 'knowledge-base.json');
+    this.load();
+    this.flushTimer = setInterval(() => this.flush(), flushMs);
+  }
+
+  private load(): void {
+    try {
+      if (existsSync(this.file)) {
+        const raw = JSON.parse(readFileSync(this.file, 'utf8'));
+        if (raw && Array.isArray(raw.entries)) this.data.entries = raw.entries;
+      }
+    } catch {
+      this.data = { entries: [] };
+    }
+  }
+
+  private saveNow(): void {
+    if (!this.dirty) return;
+    try {
+      mkdirSync(dirname(this.file), { recursive: true });
+      const tmp = this.file + '.tmp';
+      writeFileSync(tmp, JSON.stringify(this.data, null, 2), 'utf8');
+      renameSync(tmp, this.file);
+      this.dirty = false;
+    } catch {
+      /* 落盘失败不影响内存态 */
+    }
+  }
+
+  flush(): void {
+    clearInterval(this.flushTimer);
+    this.saveNow();
+  }
+
+  /** 添加/合并一条知识(对应 add_entry):主题合并 + 事实级去重 + 超量淘汰最旧。 */
+  addEntry(topic: string, facts: string[], keywords: string[] = [], sources: string[] = []): { ok: boolean; newFacts: number; merged: boolean; total: number } {
+    const t = (topic ?? '').trim();
+    const fs = [...new Set((facts ?? []).map((f) => (f ?? '').trim()).filter(Boolean))];
+    const kws = [...new Set((keywords ?? []).map((k) => (k ?? '').trim()).filter(Boolean))];
+    const srcs = [...new Set((sources ?? []).map((s) => (s ?? '').trim()).filter(Boolean))];
+    if (!t || !fs.length) return { ok: false, newFacts: 0, merged: false, total: this.data.entries.length };
+
+    const now = new Date().toISOString().slice(0, 19).replace('T', ' ');
+    const date = now.slice(0, 10);
+    const knownFacts = new Set(this.data.entries.flatMap((e) => e.facts.map(norm)));
+    const newFacts = fs.filter((f) => !knownFacts.has(norm(f)));
+
+    const target = this.data.entries.find((e) => norm(e.topic) === norm(t)) ?? null;
+    const merged = target !== null;
+    if (!target) {
+      const entry: KnowledgeEntry = {
+        id: Math.random().toString(36).slice(2, 10),
+        topic: t,
+        keywords: [],
+        facts: [],
+        sources: [],
+        learnedAt: date,
+        updated: now,
+        hits: 0,
+      };
+      this.data.entries.push(entry);
+      var tgt = entry;
+    } else {
+      var tgt = target;
+    }
+
+    if (newFacts.length) {
+      tgt.facts = [...tgt.facts, ...newFacts].slice(-MAX_FACTS_PER_ENTRY);
+      tgt.updated = now;
+    }
+    const existKw = new Set(tgt.keywords.map((k) => k.toLowerCase()));
+    for (const k of kws) if (!existKw.has(k.toLowerCase())) { tgt.keywords.push(k); existKw.add(k.toLowerCase()); }
+    tgt.keywords = tgt.keywords.slice(0, MAX_KEYWORDS);
+    const existSrc = new Set(tgt.sources);
+    for (const s of srcs) if (!existSrc.has(s)) { tgt.sources.push(s); existSrc.add(s); }
+    tgt.sources = tgt.sources.slice(0, MAX_SOURCES);
+
+    if (this.data.entries.length > MAX_ENTRIES) {
+      this.data.entries.sort((a, b) => a.updated.localeCompare(b.updated));
+      this.data.entries = this.data.entries.slice(-MAX_ENTRIES);
+    }
+    this.dirty = true;
+    return { ok: true, newFacts: newFacts.length, merged, total: this.data.entries.length };
+  }
+
+  /** 单条文本入知识库(对应 add_fact):主题取前 30 字,关键词取英文/数字词。 */
+  addFact(content: string): { ok: boolean; newFacts: number; merged: boolean; total: number } {
+    const c = (content ?? '').trim();
+    if (!c) return { ok: false, newFacts: 0, merged: false, total: this.data.entries.length };
+    const tokens = [...new Set(c.toLowerCase().match(/[a-z0-9][a-z0-9.\-_/#]*/g) ?? [])].slice(0, 6);
+    return this.addEntry(c.slice(0, 30).trim(), [c], tokens, []);
+  }
+
+  /** 检索知识(对应 build_recall_context 的检索部分)。 */
+  recall(query: string, limit = 2): KnowledgeEntry[] {
+    const q = (query ?? '').trim().toLowerCase();
+    if (!q) return [];
+    const qTokens = queryTokens(query);
+    const scored: { e: KnowledgeEntry; score: number }[] = [];
+    for (const e of this.data.entries) {
+      let score = 0;
+      for (const kw of [e.topic, ...e.keywords]) {
+        const k = kw.trim().toLowerCase();
+        if (k.length >= 3 && q.includes(k)) score = Math.max(score, k === e.topic.toLowerCase() ? 3 : 2);
+      }
+      // 事实文本命中(中文/长句常只在 fact 里):给基础分 1。
+      if (score === 0) {
+        for (const f of e.facts) {
+          const fk = f.trim().toLowerCase();
+          if (fk && q.includes(fk)) { score = 1; break; }
+        }
+      }
+      if (score === 0 && qTokens.length && qTokens.every((t) => entryBlob(e).includes(t))) score = 1;
+      if (score > 0) scored.push({ e, score });
+    }
+    scored.sort((a, b) => b.score - a.score || b.e.hits - a.e.hits);
+    const hits = scored.slice(0, Math.max(1, limit)).map((x) => x.e);
+    for (const h of hits) h.hits += 1; // 命中累加(对齐 mark_used)
+    this.dirty = true;
+    return hits;
+  }
+
+  count(): number {
+    return this.data.entries.length;
+  }
+}

package/src/memory.ts

@@ -0,0 +1,181 @@
+/**
+ * 三级记忆底座 —— 移植自 E:/qq_bot/memory.py 的 `Memory` 类,qq_bot 源码零改动。
+ *
+ * 对齐项:
+ *  - 短期:每 scope 保留最近 maxHistory 条原始对话(cap 环形语义);
+ *  - 摘要:超窗口旧历史压缩后的长期保留(这里提供存取,压缩本身由人格用工具完成);
+ *  - 话题:当前话题串,供话题切换检测;
+ *  - 持久化:JSON 落盘 + 2 秒防抖合并写 + close() 强制刷盘(对齐 atexit 语义);
+ *  - overflow_items:取前一半旧条目出窗(与 python 版同一半数保留策略)。
+ * 差异:qq_bot 按 `user:{id}` 统一键;Cortico 侧没有 IM 用户概念,scope 由调用方给
+ * (默认 'main',可按渠道/世界分域,如 'mc'、'qq:21907')。
+ */
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+
+export interface ShortTermEntry {
+  role: 'user' | 'assistant' | 'system';
+  content: string;
+  ts: number;
+}
+
+const SAVE_DEBOUNCE_MS = 2000;
+
+export class MemoryBase {
+  private readonly store = new Map<string, ShortTermEntry[]>();
+  private readonly summary = new Map<string, string>();
+  private readonly topic = new Map<string, string>();
+  private readonly notes = new Map<string, Array<{ text: string; ts: number }>>();
+  private readonly file: string;
+  private dirty = false;
+  private lastSave = 0;
+  private flushTimer: ReturnType<typeof setTimeout> | null = null;
+
+  constructor(
+    dataDir: string,
+    private readonly maxHistory: number,
+  ) {
+    mkdirSync(dataDir, { recursive: true });
+    this.file = join(dataDir, 'memory-data.json');
+    this.load();
+  }
+
+  // ---------------- 持久化(防抖,对齐 _SAVE_DEBOUNCE) ----------------
+  private load(): void {
+    if (!existsSync(this.file)) return;
+    try {
+      const raw = JSON.parse(readFileSync(this.file, 'utf8')) as {
+        store?: Record<string, ShortTermEntry[]>;
+        summary?: Record<string, string>;
+        topic?: Record<string, string>;
+        notes?: Record<string, Array<{ text: string; ts: number }>>;
+      };
+      for (const [k, v] of Object.entries(raw.store ?? {})) if (Array.isArray(v)) this.store.set(k, v.slice(-this.maxHistory));
+      for (const [k, v] of Object.entries(raw.summary ?? {})) if (typeof v === 'string') this.summary.set(k, v);
+      for (const [k, v] of Object.entries(raw.topic ?? {})) if (typeof v === 'string') this.topic.set(k, v);
+      for (const [k, v] of Object.entries(raw.notes ?? {})) if (Array.isArray(v)) this.notes.set(k, v);
+    } catch { /* 损坏按空起步 */ }
+  }
+
+  private scheduleSave(): void {
+    const now = Date.now();
+    if (now - this.lastSave < SAVE_DEBOUNCE_MS) {
+      this.dirty = true;
+      if (!this.flushTimer) {
+        this.flushTimer = setTimeout(() => { this.flushTimer = null; this.flush(); }, SAVE_DEBOUNCE_MS);
+        this.flushTimer.unref?.();
+      }
+      return;
+    }
+    this.flush();
+  }
+
+  /** 全量落盘(防抖到期 / stop 时 / mem_flush 工具都会调)。 */
+  flush(): void {
+    try {
+      const dump = (m: Map<string, unknown>) => Object.fromEntries([...m.entries()].filter(([, v]) => Array.isArray(v) ? (v as unknown[]).length : !!v));
+      const data = {
+        store: dump(this.store) as Record<string, ShortTermEntry[]>,
+        summary: dump(this.summary) as Record<string, string>,
+        topic: dump(this.topic) as Record<string, string>,
+        notes: dump(this.notes) as Record<string, Array<{ text: string; ts: number }>>,
+      };
+      mkdirSync(dirname(this.file), { recursive: true });
+      // 原子提交(archive-first 单文件等价):先写临时文件再 rename 到目标,
+      // 同卷 rename 原子,避免写到一半崩溃损坏整个 memory-data.json(对齐 qq_bot fact_store)。
+      const tmp = this.file + '.tmp';
+      writeFileSync(tmp, JSON.stringify(data, null, 2), 'utf8');
+      renameSync(tmp, this.file);
+      this.dirty = false;
+      this.lastSave = Date.now();
+    } catch { /* 磁盘失败不炸主流程 */ }
+  }
+
+  // ---------------- 短期 ----------------
+  add(scope: string, role: ShortTermEntry['role'], content: string): void {
+    const s = scope || 'main';
+    const list = (this.store.get(s) ?? []).slice();
+    list.push({ role, content, ts: Date.now() });
+    this.store.set(s, list.slice(-this.maxHistory));
+    this.scheduleSave();
+  }
+
+  recent(scope: string, n?: number): ShortTermEntry[] {
+    const list = this.store.get(scope || 'main') ?? [];
+    return n && n > 0 ? list.slice(-n) : [...list];
+  }
+
+  /** 短期是否已满(对齐 is_full)。 */
+  isFull(scope: string): boolean {
+    return (this.store.get(scope || 'main')?.length ?? 0) >= this.maxHistory;
+  }
+
+  /**
+   * 取出需要压缩进摘要的旧条目(前一半),短期保留后一半。对齐 overflow_items。
+   * 返回 null = 还没满到该压缩。
+   */
+  overflowItems(scope: string): ShortTermEntry[] | null {
+    const s = scope || 'main';
+    const items = this.store.get(s) ?? [];
+    if (items.length <= this.maxHistory / 2) return null;
+    const overflow = items.slice(0, items.length - Math.floor(this.maxHistory / 2));
+    this.store.set(s, items.slice(items.length - Math.floor(this.maxHistory / 2)));
+    this.scheduleSave();
+    return overflow;
+  }
+
+  clearShortTerm(scope: string): void {
+    this.store.delete(scope || 'main');
+    this.scheduleSave();
+  }
+
+  // ---------------- 摘要 / 话题 ----------------
+  setSummary(scope: string, text: string): void {
+    if (text.trim()) this.summary.set(scope || 'main', text.trim());
+    else this.summary.delete(scope || 'main');
+    this.scheduleSave();
+  }
+
+  getSummary(scope: string): string {
+    return this.summary.get(scope || 'main') ?? '';
+  }
+
+  setTopic(scope: string, text: string): void {
+    if (text.trim()) this.topic.set(scope || 'main', text.trim());
+    else this.topic.delete(scope || 'main');
+    this.scheduleSave();
+  }
+
+  getTopic(scope: string): string {
+    return this.topic.get(scope || 'main') ?? '';
+  }
+
+  // ---------------- 重要信息(对齐 important_notes 的存取语义) ----------------
+  addNote(scope: string, text: string): number {
+    const s = scope || 'main';
+    const list = this.notes.get(s) ?? [];
+    list.push({ text: text.trim(), ts: Date.now() });
+    this.notes.set(s, list.slice(-100));
+    this.scheduleSave();
+    return list.length - 1; // 返回新笔记的 0-based 索引（与 mem_forget_note 对齐）
+  }
+
+  getNotes(scope: string): Array<{ text: string; ts: number }> {
+    return this.notes.get(scope || 'main') ?? [];
+  }
+
+  removeNote(scope: string, index: number): boolean {
+    const list = this.notes.get(scope || 'main') ?? [];
+    if (index < 0 || index >= list.length) return false;
+    list.splice(index, 1);
+    this.notes.set(scope || 'main', list);
+    this.scheduleSave();
+    return true;
+  }
+
+  // ---------------- 全局 ----------------
+  scopes(): string[] {
+    const set = new Set<string>([...this.store.keys(), ...this.summary.keys(), ...this.topic.keys(), ...this.notes.keys()]);
+    return [...set].sort();
+  }
+}

package/src/observe.ts

@@ -0,0 +1,60 @@
+// 把记忆状态拼成「她此刻能想起的东西」——对应 qq_bot memory_context.build_memory_messages
+// 的注入语义,但走 Cortico 的 envPrompt 插值 + 事件推送两条通道。
+import type { MemoryBase } from './memory.ts';
+import type { VectorStore } from './vector-store.ts';
+import type { ProfileStore } from './profile-store.ts';
+
+export interface MemoryView {
+  topic: string;
+  summary: string;
+  notes: Array<{ text: string; ts: number }>;
+  scopes: string[];
+  vectorStats: { scopes: number; total: number; indexed: number; model: string };
+  profileHint: string;
+}
+
+export function buildView(mem: MemoryBase, vectors: VectorStore, scope: string, notesInPrompt: number, profile: ProfileStore | null): MemoryView {
+  return {
+    topic: mem.getTopic(scope),
+    summary: mem.getSummary(scope),
+    notes: mem.getNotes(scope).slice(-notesInPrompt),
+    scopes: mem.scopes(),
+    vectorStats: vectors.stats(),
+    profileHint: profile ? profile.hint(scope) : '',
+  };
+}
+
+/** 环境提示词的动态变量值(envPromptVars 用;快,纯内存读)。 */
+export function promptVars(view: MemoryView): Record<string, string> {
+  const lines: string[] = [];
+  if (view.profileHint) {
+    lines.push('【人物档案】');
+    lines.push(view.profileHint);
+  }
+  if (view.notes.length) {
+    lines.push('【重要信息】(用户/你明确要求记住的)');
+    view.notes.forEach((n, i) => lines.push(`${i + 1}. ${n.text}`));
+  }
+  if (view.summary) lines.push(`【之前的对话摘要】${view.summary}`);
+  if (view.topic) lines.push(`【当前话题】${view.topic}`);
+  const { total, indexed } = view.vectorStats;
+  lines.push(`【记忆库】长期记忆 ${total} 条(其中 ${indexed} 条已建向量索引)。`);
+  return {
+    memoryContext: lines.join('\n'),
+    memoryScopes: view.scopes.join(', ') || '(无)',
+    memoryVectors: `${indexed}/${total}`,
+  };
+}
+
+/** 周期推送用的事件正文(比提示词变量更啰嗦,给人格当「记忆快照」)。 */
+export function buildEventText(view: MemoryView): string {
+  const lines: string[] = ['# 记忆快照 (memory)'];
+  const { total, indexed, scopes } = view.vectorStats;
+  lines.push(`- 记忆域: ${view.scopes.join(', ') || '(空)'} / 向量索引: ${indexed}/${total} 条 / 库: ${scopes || '无'}`);
+  if (view.topic) lines.push(`- 当前话题: ${view.topic}`);
+  if (view.profileHint) lines.push(`- 人物档案: ${view.profileHint}`);
+  if (view.summary) lines.push(`- 对话摘要: ${view.summary}`);
+  if (view.notes.length) lines.push(`- 重要信息: ${view.notes.map((n) => n.text).join(' / ')}`);
+  lines.push(`\n要记的事用 mem_remember / mem_note 存;找旧账用 mem_recall 混合检索;没别的就用 mem_recall 或继续手头的事。`);
+  return lines.join('\n');
+}

package/src/persona-store.ts

@@ -0,0 +1,100 @@
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+
+interface Persona {
+  traits: string[];
+  style: string;
+  updated: number;
+}
+
+interface PersonaFile {
+  personas: Record<string, Persona>;
+  globalStyle: string;
+}
+
+const MAX_TRAITS_PER_USER = 20;
+
+/**
+ * 人格记忆(对齐 qq_bot persona_memory,五维记忆第五维):
+ * - 与每个用户的独特相处模式(特征 traits + 风格 style),per-user 隔离
+ * - 特征合并去重 + 上限淘汰;全局风格可选
+ * - 原子落盘(临时文件 + rename)
+ */
+export class PersonaStore {
+  private readonly file: string;
+  private data: PersonaFile = { personas: {}, globalStyle: '' };
+  private dirty = false;
+  private readonly flushTimer: ReturnType<typeof setInterval>;
+
+  constructor(dataDir: string, flushMs = 2000) {
+    this.file = join(dataDir, 'persona-data.json');
+    this.load();
+    this.flushTimer = setInterval(() => this.flush(), flushMs);
+  }
+
+  private load(): void {
+    try {
+      if (existsSync(this.file)) {
+        const raw = JSON.parse(readFileSync(this.file, 'utf8'));
+        if (raw && typeof raw === 'object') {
+          this.data.personas = raw.personas ?? {};
+          this.data.globalStyle = raw.globalStyle ?? '';
+        }
+      }
+    } catch {
+      /* 损坏则重置 */
+    }
+  }
+
+  private saveNow(): void {
+    if (!this.dirty) return;
+    try {
+      mkdirSync(dirname(this.file), { recursive: true });
+      const tmp = this.file + '.tmp';
+      writeFileSync(tmp, JSON.stringify(this.data, null, 2), 'utf8');
+      renameSync(tmp, this.file);
+      this.dirty = false;
+    } catch {
+      /* 落盘失败不影响内存态 */
+    }
+  }
+
+  flush(): void {
+    clearInterval(this.flushTimer);
+    this.saveNow();
+  }
+
+  /** 更新某用户的人格记忆(特征合并去重 + 上限)。 */
+  update(userId: string, traits: string[], style = ''): { traits: number } {
+    const uid = String(userId);
+    const persona = this.data.personas[uid] ?? (this.data.personas[uid] = { traits: [], style: '', updated: 0 });
+    const existing = new Set(persona.traits);
+    for (const t of traits.map((x) => (x ?? '').trim()).filter(Boolean)) {
+      if (!existing.has(t)) existing.add(t);
+    }
+    let list = [...existing];
+    if (list.length > MAX_TRAITS_PER_USER) list = list.slice(-MAX_TRAITS_PER_USER);
+    persona.traits = list;
+    if (style && style.trim()) persona.style = style.trim();
+    persona.updated = Date.now() / 1000;
+    this.dirty = true;
+    return { traits: list.length };
+  }
+
+  setGlobalStyle(style: string): void {
+    this.data.globalStyle = (style ?? '').trim();
+    this.dirty = true;
+  }
+
+  get(userId: string): Persona | null {
+    return this.data.personas[String(userId)] ?? null;
+  }
+
+  getGlobalStyle(): string {
+    return this.data.globalStyle;
+  }
+
+  count(): number {
+    return Object.keys(this.data.personas).length;
+  }
+}

package/src/profile-store.ts

@@ -0,0 +1,102 @@
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+
+interface Profile {
+  facts: string[];
+  updated: number;
+}
+
+interface ProfileFile {
+  profiles: Record<string, Profile>;
+}
+
+const MAX_FACTS_PER_USER = 50;
+
+/**
+ * 人物档案(对齐 qq_bot long_term_memory 的 profile 部分):
+ * - 永久记住用户关键信息(称呼/身份/关系等),常驻进环境提示词
+ * - update:合并新事实+去重+上限50(对齐 update_profile)
+ * - replace:整体替换(用于纠错,对齐 replace_profile)
+ * - 原子落盘(临时文件 + rename)
+ */
+export class ProfileStore {
+  private readonly file: string;
+  private data: ProfileFile = { profiles: {} };
+  private dirty = false;
+  private readonly flushTimer: ReturnType<typeof setInterval>;
+
+  constructor(dataDir: string, flushMs = 2000) {
+    this.file = join(dataDir, 'user-profiles.json');
+    this.load();
+    this.flushTimer = setInterval(() => this.flush(), flushMs);
+  }
+
+  private load(): void {
+    try {
+      if (existsSync(this.file)) {
+        const raw = JSON.parse(readFileSync(this.file, 'utf8'));
+        if (raw && typeof raw === 'object' && raw.profiles) this.data.profiles = raw.profiles;
+      }
+    } catch {
+      this.data = { profiles: {} };
+    }
+  }
+
+  private saveNow(): void {
+    if (!this.dirty) return;
+    try {
+      mkdirSync(dirname(this.file), { recursive: true });
+      const tmp = this.file + '.tmp';
+      writeFileSync(tmp, JSON.stringify(this.data, null, 2), 'utf8');
+      renameSync(tmp, this.file);
+      this.dirty = false;
+    } catch {
+      /* 落盘失败不影响内存态 */
+    }
+  }
+
+  flush(): void {
+    clearInterval(this.flushTimer);
+    this.saveNow();
+  }
+
+  /** 合并新事实(去重 + 上限50)。 */
+  update(userId: string, facts: string[]): { total: number } {
+    const uid = String(userId);
+    const p = this.data.profiles[uid] ?? (this.data.profiles[uid] = { facts: [], updated: 0 });
+    const existing = new Set(p.facts);
+    for (const f of facts.map((x) => (x ?? '').trim()).filter(Boolean)) {
+      if (!existing.has(f)) existing.add(f);
+    }
+    let list = [...existing];
+    if (list.length > MAX_FACTS_PER_USER) list = list.slice(-MAX_FACTS_PER_USER);
+    p.facts = list;
+    p.updated = Date.now() / 1000;
+    this.dirty = true;
+    return { total: list.length };
+  }
+
+  /** 整体替换(纠错,对齐 replace_profile)。 */
+  replace(userId: string, facts: string[]): { total: number } {
+    const uid = String(userId);
+    const list = [...new Set(facts.map((x) => (x ?? '').trim()).filter(Boolean))].slice(-MAX_FACTS_PER_USER);
+    this.data.profiles[uid] = { facts: list, updated: Date.now() / 1000 };
+    this.dirty = true;
+    return { total: list.length };
+  }
+
+  get(userId: string): string[] {
+    return this.data.profiles[String(userId)]?.facts ?? [];
+  }
+
+  /** 生成注入提示词用的文本(对齐 build_profile_hint)。 */
+  hint(userId: string): string {
+    const facts = this.get(userId);
+    if (!facts.length) return '';
+    return `人物档案(${userId}):\n` + facts.map((f, i) => `${i + 1}. ${f}`).join('\n');
+  }
+
+  count(): number {
+    return Object.keys(this.data.profiles).length;
+  }
+}