cortico-world-memory 0.1.5 → 0.1.7

package/package.json

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

package/src/backend.ts

@@ -0,0 +1,166 @@
+/**
+ * 存储后端抽象 —— 让 7 个记忆 store 的落盘方式可在「JSON 文件」与「SQLite」间切换,
+ * store 内部逻辑零改动(仍是内存对象,只把 load/save 委托给 backend.readJson/writeJson)。
+ *
+ *  - JsonBackend(默认):保持原行为,每 stem 一个 `*.json` 文件,原子提交(tmp+rename)。
+ *  - SqliteBackend:单库 `memory.db` 的 KV 表 `kv(name TEXT PRIMARY KEY, data TEXT)`,
+ *    每个 stem 的完整文件对象作为一行 JSON 存储。首次启动若检测到旧 JSON 文件,
+ *    自动迁移进 SQLite(一次性,不丢历史)。
+ *
+ *  SQLite 驱动优先级:先试 `better-sqlite3`(原生,若已安装),缺失则回退 Node 内置
+ *  `node:sqlite`(v24+ 自带,零安装)。两者 API 兼容(.prepare().get()/.run()、.exec())。
+ */
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+
+export type BackendKind = 'json' | 'sqlite';
+
+/** 全部记忆存储的 stem(文件名去掉 .json)。迁移与校验用。 */
+export const ALL_STEMS = [
+  'memory-data',
+  'fact-store',
+  'knowledge-base',
+  'reflection-data',
+  'persona-data',
+  'user-profiles',
+  'vector-memory',
+] as const;
+
+export interface StoreBackend {
+  readonly kind: BackendKind;
+  /** 读取某 stem 的完整文件对象;不存在或损坏返回 null。 */
+  readJson(stem: string): unknown | null;
+  /** 写入某 stem 的完整文件对象(原子/即时)。 */
+  writeJson(stem: string, obj: unknown): void;
+  /** 删除某 stem(切回 JSON 等场景用)。 */
+  removeJson(stem: string): void;
+  /** 强制落盘/关闭(仅由 world.stop 调一次)。 */
+  flush(): void;
+  /** 一次性把旧 JSON 文件导入本后端(若本 stem 尚未存在)。 */
+  migrateFromJson(stems: readonly string[]): void;
+}
+
+// ---------------- JSON 后端(默认,保持原行为) ----------------
+export class JsonBackend implements StoreBackend {
+  readonly kind = 'json' as const;
+  constructor(private readonly dataDir: string) {}
+  readJson(stem: string): unknown | null {
+    const f = join(this.dataDir, stem + '.json');
+    if (!existsSync(f)) return null;
+    try {
+      return JSON.parse(readFileSync(f, 'utf8'));
+    } catch {
+      return null;
+    }
+  }
+  writeJson(stem: string, obj: unknown): void {
+    const f = join(this.dataDir, stem + '.json');
+    try {
+      mkdirSync(dirname(f), { recursive: true });
+      const tmp = f + '.tmp';
+      writeFileSync(tmp, JSON.stringify(obj, null, 2), 'utf8');
+      renameSync(tmp, f);
+    } catch {
+      /* 落盘失败不影响内存态,下次 flush 重试 */
+    }
+  }
+  removeJson(stem: string): void {
+    const f = join(this.dataDir, stem + '.json');
+    try {
+      if (existsSync(f)) renameSync(f, f + '.bak');
+    } catch {
+      /* ignore */
+    }
+  }
+  flush(): void {}
+  migrateFromJson(): void {
+    /* JSON 后端本就以文件为准,无需迁移 */
+  }
+}
+
+// ---------------- SQLite 后端(KV 封装) ----------------
+class SqliteBackend implements StoreBackend {
+  readonly kind = 'sqlite' as const;
+  readonly driver: string;
+  private constructor(
+    private readonly dataDir: string,
+    private readonly db: any,
+    driver: string,
+  ) {
+    db.exec('CREATE TABLE IF NOT EXISTS kv (name TEXT PRIMARY KEY, data TEXT)');
+    this.driver = driver;
+  }
+
+  static async create(dataDir: string): Promise<SqliteBackend> {
+    mkdirSync(dataDir, { recursive: true });
+    let db: any;
+    let driver: string;
+    try {
+      const mod: any = await import('better-sqlite3');
+      const Database = mod.default ?? mod;
+      db = new Database(join(dataDir, 'memory.db'));
+      driver = 'better-sqlite3';
+    } catch {
+      const { DatabaseSync } = await import('node:sqlite');
+      db = new DatabaseSync(join(dataDir, 'memory.db'));
+      driver = 'node:sqlite';
+    }
+    return new SqliteBackend(dataDir, db, driver);
+  }
+
+  readJson(stem: string): unknown | null {
+    const row = this.db.prepare('SELECT data FROM kv WHERE name = ?').get(stem);
+    if (!row) return null;
+    try {
+      return JSON.parse(row.data);
+    } catch {
+      return null;
+    }
+  }
+
+  writeJson(stem: string, obj: unknown): void {
+    this.db.prepare('INSERT OR REPLACE INTO kv (name, data) VALUES (?, ?)').run(stem, JSON.stringify(obj));
+  }
+
+  removeJson(stem: string): void {
+    this.db.prepare('DELETE FROM kv WHERE name = ?').run(stem);
+  }
+
+  flush(): void {
+    try {
+      this.db.close();
+    } catch {
+      /* ignore */
+    }
+  }
+
+  migrateFromJson(stems: readonly string[]): void {
+    for (const stem of stems) {
+      if (this.readJson(stem) !== null) continue; // 已迁移过则跳过
+      const f = join(this.dataDir, stem + '.json');
+      if (!existsSync(f)) continue;
+      try {
+        this.writeJson(stem, JSON.parse(readFileSync(f, 'utf8')));
+      } catch {
+        /* 损坏文件忽略 */
+      }
+    }
+  }
+}
+
+export type LogFn = (msg: string) => void;
+
+/** 按配置创建后端。sqlite 初始化失败时回退 JSON 并打日志。 */
+export async function createBackend(kind: BackendKind, dataDir: string, log?: LogFn): Promise<StoreBackend> {
+  if (kind === 'sqlite') {
+    try {
+      const b = await SqliteBackend.create(dataDir);
+      log?.(`[memory] 存储后端=sqlite (driver=${b.driver})`);
+      return b;
+    } catch (e: any) {
+      log?.(`[memory] sqlite 初始化失败,回退 JSON: ${e?.message ?? e}`);
+    }
+  }
+  log?.('[memory] 存储后端=json');
+  return new JsonBackend(dataDir);
+}

package/src/config.ts

@@ -44,6 +44,13 @@ export interface MemoryConfig {
   embeddingSidecarUrl: string;
   /** `sidecar` 模式单次调用的超时(毫秒)。qq_bot 侧模型首载可达数分钟,别调太小。 */
   embeddingTimeoutMs: number;
+  /**
+   * 持久化后端:
+   *  - `json`    原生 JSON 文件(每 store 一个 `*.json`,默认);
+   *  - `sqlite`  单库 `memory.db` 的 KV 封装(自动尝试 better-sqlite3,缺失回退 Node 内置 node:sqlite)。
+   * 首次切到 sqlite 会自动把已有 JSON 迁移进库;切回 json 以 JSON 文件为准(可能落后 sqlite 的后续写入)。
+   */
+  storageBackend: 'json' | 'sqlite';
 }
 
 export const MEMORY_DEFAULTS: MemoryConfig = {
@@ -61,6 +68,7 @@ export const MEMORY_DEFAULTS: MemoryConfig = {
   embeddingModel: '',
   embeddingSidecarUrl: 'http://127.0.0.1:8766',
   embeddingTimeoutMs: 180_000,
+  storageBackend: 'json',
 };
 
 /** 控制台可调旋钮。一个属性一条 JSON Schema,没有手写表单。 */
@@ -88,6 +96,10 @@ export const MEMORY_CONFIG_GROUP: ConfigGroup = {
       'worlds.memory.embeddingModel': { type: 'string', title: 'Embeddings 模型', description: 'http 模式用,如 nomic-embed-text。' },
       'worlds.memory.embeddingSidecarUrl': { type: 'string', title: 'Sidecar 地址', description: 'sidecar 模式用,qq_bot memory_server(默认 http://127.0.0.1:8766)。' },
       'worlds.memory.embeddingTimeoutMs': { type: 'number', title: 'Sidecar 超时(ms)', description: 'qq_bot 向量模型首载慢,默认 3 分钟。' },
+      'worlds.memory.storageBackend': {
+        type: 'string', title: '存储后端', enum: ['json', 'sqlite'],
+        description: 'json=原生 JSON 文件(默认);sqlite=单库 KV(自动 better-sqlite3→node:sqlite 回退)。切 sqlite 首次自动迁移旧 JSON。',
+      },
     },
   },
 };

package/src/fact-store.ts

@@ -1,6 +1,5 @@
 import { createHash } from 'node:crypto';
-import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
-import { dirname, join } from 'node:path';
+import { StoreBackend, JsonBackend } from './backend.ts';
 
 export interface Fact {
   hash: string;
@@ -20,22 +19,23 @@ export interface Fact {
  * 纯 JS 实现,不引入 better-sqlite3 原生依赖(world 扩展装原生模块有风险)。
  */
 export class FactStore {
-  private readonly file: string;
+  private readonly stem = 'fact-store';
+  private readonly backend: StoreBackend;
   private data: Record<string, Fact[]> = {};
   private dirty = false;
   private readonly flushTimer: ReturnType<typeof setInterval>;
 
-  constructor(dataDir: string, flushMs = 2000) {
-    this.file = join(dataDir, 'fact-store.json');
+  constructor(dataDir: string, backend?: StoreBackend, flushMs = 2000) {
+    this.backend = backend ?? new JsonBackend(dataDir);
     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.scopes) this.data = raw.scopes;
+      const raw = this.backend.readJson(this.stem);
+      if (raw && typeof raw === 'object' && (raw as { scopes?: unknown }).scopes) {
+        this.data = (raw as { scopes: Record<string, Fact[]> }).scopes;
       }
     } catch {
       this.data = {};
@@ -44,15 +44,8 @@ export class FactStore {
 
   private saveNow(): void {
     if (!this.dirty) return;
-    try {
-      mkdirSync(dirname(this.file), { recursive: true });
-      const tmp = this.file + '.tmp';
-      writeFileSync(tmp, JSON.stringify({ scopes: this.data }, null, 2), 'utf8');
-      renameSync(tmp, this.file);
-      this.dirty = false;
-    } catch {
-      /* 落盘失败不影响内存态,下次 flush 重试 */
-    }
+    this.backend.writeJson(this.stem, { scopes: this.data });
+    this.dirty = false;
   }
 
   /** 强制落盘(供 stop 调用)。 */

package/src/knowledge-store.ts

@@ -1,5 +1,4 @@
-import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
-import { dirname, join } from 'node:path';
+import { StoreBackend, JsonBackend } from './backend.ts';
 
 export interface KnowledgeEntry {
   id: string;
@@ -35,23 +34,22 @@ const queryTokens = (q: string): string[] =>
  * - 原子落盘(临时文件 + rename)
  */
 export class KnowledgeStore {
-  private readonly file: string;
+  private readonly stem = 'knowledge-base';
+  private readonly backend: StoreBackend;
   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');
+  constructor(dataDir: string, backend?: StoreBackend, flushMs = 2000) {
+    this.backend = backend ?? new JsonBackend(dataDir);
     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;
-      }
+      const raw = this.backend.readJson(this.stem);
+      if (raw && Array.isArray((raw as KbFile).entries)) this.data.entries = (raw as KbFile).entries;
     } catch {
       this.data = { entries: [] };
     }
@@ -59,15 +57,8 @@ export class KnowledgeStore {
 
   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 {
-      /* 落盘失败不影响内存态 */
-    }
+    this.backend.writeJson(this.stem, this.data);
+    this.dirty = false;
   }
 
   flush(): void {

package/src/memory.ts

@@ -10,8 +10,7 @@
  * 差异: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';
+import { StoreBackend, JsonBackend } from './backend.ts';
 
 export interface ShortTermEntry {
   role: 'user' | 'assistant' | 'system';
@@ -26,7 +25,8 @@ export class MemoryBase {
   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 readonly stem = 'memory-data';
+  private readonly backend: StoreBackend;
   private dirty = false;
   private lastSave = 0;
   private flushTimer: ReturnType<typeof setTimeout> | null = null;
@@ -34,17 +34,18 @@ export class MemoryBase {
   constructor(
     dataDir: string,
     private readonly maxHistory: number,
+    backend?: StoreBackend,
   ) {
-    mkdirSync(dataDir, { recursive: true });
-    this.file = join(dataDir, 'memory-data.json');
+    this.backend = backend ?? new JsonBackend(dataDir);
     this.load();
   }
 
   // ---------------- 持久化(防抖,对齐 _SAVE_DEBOUNCE) ----------------
   private load(): void {
-    if (!existsSync(this.file)) return;
+    const raw = this.backend.readJson(this.stem);
+    if (!raw) return;
     try {
-      const raw = JSON.parse(readFileSync(this.file, 'utf8')) as {
+      const r = raw as {
         store?: Record<string, ShortTermEntry[]>;
         summary?: Record<string, string>;
         topic?: Record<string, string>;
@@ -53,7 +54,7 @@ export class MemoryBase {
       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);
+      for (const [k, v] of Object.entries(r.notes ?? {})) if (Array.isArray(v)) this.notes.set(k, v);
     } catch { /* 损坏按空起步 */ }
   }
 
@@ -80,12 +81,7 @@ export class MemoryBase {
         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.backend.writeJson(this.stem, data);
       this.dirty = false;
       this.lastSave = Date.now();
     } catch { /* 磁盘失败不炸主流程 */ }

package/src/persona-store.ts

@@ -1,5 +1,4 @@
-import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
-import { dirname, join } from 'node:path';
+import { StoreBackend, JsonBackend } from './backend.ts';
 
 interface Persona {
   traits: string[];
@@ -21,25 +20,25 @@ const MAX_TRAITS_PER_USER = 20;
  * - 原子落盘(临时文件 + rename)
  */
 export class PersonaStore {
-  private readonly file: string;
+  private readonly stem = 'persona-data';
+  private readonly backend: StoreBackend;
   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');
+  constructor(dataDir: string, backend?: StoreBackend, flushMs = 2000) {
+    this.backend = backend ?? new JsonBackend(dataDir);
     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 ?? '';
-        }
+      const raw = this.backend.readJson(this.stem);
+      if (raw && typeof raw === 'object') {
+        const r = raw as Partial<PersonaFile>;
+        this.data.personas = r.personas ?? {};
+        this.data.globalStyle = r.globalStyle ?? '';
       }
     } catch {
       /* 损坏则重置 */
@@ -48,15 +47,8 @@ export class PersonaStore {
 
   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 {
-      /* 落盘失败不影响内存态 */
-    }
+    this.backend.writeJson(this.stem, this.data);
+    this.dirty = false;
   }
 
   flush(): void {

package/src/profile-store.ts

@@ -1,5 +1,4 @@
-import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
-import { dirname, join } from 'node:path';
+import { StoreBackend, JsonBackend } from './backend.ts';
 
 interface Profile {
   facts: string[];
@@ -20,22 +19,23 @@ const MAX_FACTS_PER_USER = 50;
  * - 原子落盘(临时文件 + rename)
  */
 export class ProfileStore {
-  private readonly file: string;
+  private readonly stem = 'user-profiles';
+  private readonly backend: StoreBackend;
   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');
+  constructor(dataDir: string, backend?: StoreBackend, flushMs = 2000) {
+    this.backend = backend ?? new JsonBackend(dataDir);
     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;
+      const raw = this.backend.readJson(this.stem);
+      if (raw && typeof raw === 'object' && (raw as ProfileFile).profiles) {
+        this.data.profiles = (raw as ProfileFile).profiles;
       }
     } catch {
       this.data = { profiles: {} };
@@ -44,15 +44,8 @@ export class ProfileStore {
 
   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 {
-      /* 落盘失败不影响内存态 */
-    }
+    this.backend.writeJson(this.stem, this.data);
+    this.dirty = false;
   }
 
   flush(): void {

package/src/reflection-store.ts

@@ -1,5 +1,4 @@
-import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
-import { dirname, join } from 'node:path';
+import { StoreBackend, JsonBackend } from './backend.ts';
 
 export type ReflectionType = 'preference' | 'style' | 'insight' | 'correction' | 'pattern';
 
@@ -38,26 +37,26 @@ const MAX_RULES = 50;
  * - 原子落盘(临时文件 + rename)
  */
 export class ReflectionStore {
-  private readonly file: string;
+  private readonly stem = 'reflection-data';
+  private readonly backend: StoreBackend;
   private data: ReflectFile = { reflections: [], interactionRules: [], stats: { totalConversations: 0, totalReflections: 0, lastReflectionTs: 0 } };
   private dirty = false;
   private readonly flushTimer: ReturnType<typeof setInterval>;
 
-  constructor(dataDir: string, flushMs = 2000) {
-    this.file = join(dataDir, 'reflection-data.json');
+  constructor(dataDir: string, backend?: StoreBackend, flushMs = 2000) {
+    this.backend = backend ?? new JsonBackend(dataDir);
     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.reflections = Array.isArray(raw.reflections) ? raw.reflections : [];
-          this.data.interactionRules = Array.isArray(raw.interactionRules) ? raw.interactionRules : [];
-          if (raw.stats) this.data.stats = raw.stats;
-        }
+      const raw = this.backend.readJson(this.stem);
+      if (raw && typeof raw === 'object') {
+        const r = raw as Partial<ReflectFile>;
+        this.data.reflections = Array.isArray(r.reflections) ? r.reflections : [];
+        this.data.interactionRules = Array.isArray(r.interactionRules) ? r.interactionRules : [];
+        if (r.stats) this.data.stats = r.stats;
       }
     } catch {
       /* 损坏则重置 */
@@ -66,15 +65,8 @@ export class ReflectionStore {
 
   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 {
-      /* 落盘失败不影响内存态 */
-    }
+    this.backend.writeJson(this.stem, this.data);
+    this.dirty = false;
   }
 
   flush(): void {

package/src/vector-store.ts

@@ -10,9 +10,8 @@
  *  - 降级:无向量记录 / 维度不齐 / embedding 服务不在,都自动退化为纯 BM25——
  *    与 qq_bot memory_client「sidecar 掉线降级进程内、功能永不中断」同一思路。
  */
-import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
-import { dirname, join } from 'node:path';
 import { decodeVectorFp16, encodeVectorFp16 } from './float16.ts';
+import { StoreBackend, JsonBackend } from './backend.ts';
 
 const BM25_K1 = 1.5;
 const BM25_B = 0.75;
@@ -121,7 +120,8 @@ function rrfFusion(rankedLists: Array<Array<{ idx: number }>>): Map<number, numb
 /** 一个 scope 的向量库(磁盘持久化 + 内存缓存 + 矩阵缓存 + 防抖写盘)。 */
 export class VectorStore {
   private data: VectorData = { vectors: {} };
-  private file: string;
+  private readonly stem = 'vector-memory';
+  private readonly backend: StoreBackend;
   private matrices = new Map<string, { version: number; m: MatrixCache | null }>();
   private versions = new Map<string, number>;
   private dirty = false;
@@ -130,31 +130,23 @@ export class VectorStore {
 
   static readonly SAVE_DEBOUNCE_MS = 2000;
 
-  constructor(dataDir: string) {
-    mkdirSync(dataDir, { recursive: true });
-    this.file = join(dataDir, 'vector-memory.json');
+  constructor(dataDir: string, backend?: StoreBackend) {
+    this.backend = backend ?? new JsonBackend(dataDir);
     this.load();
   }
 
   private load(): void {
-    if (!existsSync(this.file)) return;
+    const raw = this.backend.readJson(this.stem) as VectorData | null;
+    if (!raw || typeof raw !== 'object' || !raw.vectors || typeof raw.vectors !== 'object') return;
     try {
-      const raw = JSON.parse(readFileSync(this.file, 'utf8')) as VectorData;
-      if (raw && typeof raw === 'object' && raw.vectors && typeof raw.vectors === 'object') {
-        this.data = { vectors: raw.vectors, ...(raw.model_name ? { model_name: raw.model_name } : {}) };
-      }
+      this.data = { vectors: raw.vectors, ...(raw.model_name ? { model_name: raw.model_name } : {}) };
     } catch { /* 损坏文件按空库起步,与 python 版同策略 */ }
   }
 
   /** 同步全量写(JSON 体量 = 条数×维度/2 字节,500 条×384 维约 1.5MB,可接受)。 */
   private saveNow(): void {
     try {
-      mkdirSync(dirname(this.file), { recursive: true });
-      // 原子提交(archive-first 单文件等价):先写临时文件再 rename,同卷 rename 原子,
-      // 避免写到一半崩溃损坏整个 vector-memory.json(对齐 qq_bot fact_store crash-safe)。
-      const tmp = this.file + '.tmp';
-      writeFileSync(tmp, JSON.stringify(this.data), 'utf8');
-      renameSync(tmp, this.file);
+      this.backend.writeJson(this.stem, this.data);
       this.dirty = false;
       this.lastSave = Date.now();
     } catch { /* 磁盘失败不打断主流程;下次写入再试 */ }

package/src/world.ts

@@ -11,6 +11,7 @@ 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 { buildEventText, buildView, promptVars } from './observe.ts';
 
 const ENV_PROMPT_FILE = fileURLToPath(new URL('./ENV_PROMPT.md', import.meta.url));
@@ -79,6 +80,7 @@ export class MemoryWorld implements World {
   private persona: PersonaStore | null = null;
   private profile: ProfileStore | null = null;
   private embedder: EmbeddingClient | null = null;
+  private backend: StoreBackend | null = null; // 存储后端(json/sqlite),stop 时统一 flush 关闭
   private lastCursor = 0; // 自动捕获已扫到的事件游标(启动=当前尾,不回灌历史)
   private captureTimer: ReturnType<typeof setInterval> | null = null;
 
@@ -123,13 +125,15 @@ export class MemoryWorld implements World {
     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.backend = await createBackend(this.cfg.storageBackend ?? 'json', dataDir, (m) => host.log.info(m));
+    this.backend.migrateFromJson(ALL_STEMS); // 首次切 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);
+    this.kb = new KnowledgeStore(dataDir, this.backend);
+    this.reflect = new ReflectionStore(dataDir, this.backend);
+    this.persona = new PersonaStore(dataDir, this.backend);
+    this.profile = new ProfileStore(dataDir, this.backend);
     this.embedder = new EmbeddingClient(this.cfg);
 
     host.log.info('[memory] 启动', {
@@ -165,6 +169,7 @@ export class MemoryWorld implements World {
     this.reflect?.flush();
     this.persona?.flush();
     this.profile?.flush();
+    this.backend?.flush(); // 最后统一关闭 SQLite(每个 store 的 flush 只写行,不关库)
   }
 
   /** 启动自动捕获轮询(尊重暂停开关)。 */