cortico-bot-zcor 0.1.0 → 0.1.1

package/README.md

@@ -14,6 +14,7 @@ AI 自行调用工具保存和检索记忆：
 - `zcor_memory_important(id, important)`：标记或取消重要记忆。
 - `zcor_memory_query(keywords?, from?, to?, limit?, offset?)`：本地查询当前记忆。
 - `zcor_memory_history(keywords?, from?, to?, limit?, offset?)`：本地查询操作历史。
+- `zcor_memory_backup()` / `zcor_memory_restore(backupFile)`：备份或恢复 Memory 状态。
 - `zcor_synonyms_add(terms)`：添加同义词组。
 - `zcor_memory_search(keywords)`：关键词数组检索。
 
@@ -41,13 +42,14 @@ AI 自行调用工具保存和检索记忆：
 `nextOffset`；同一时刻按记录顺序倒序。`limit` 默认 20、最多 100，`offset` 默认 0。
 查询期间新增记录可能改变分页位置。
 
-`memory-state.json` 原子保存当前记忆、重要标记和操作历史。首次工具操作自动载入旧
+`memory-state.json` 原子保存当前记忆、重要标记和操作历史，包含状态格式版本。首次工具操作自动载入旧
 `memories.json` 的全部记录，保留原文件作迁移快照，此后以 `memory-state.json` 为准。
 没有旧文件时从空记忆开始。操作历史从迁移后开始；修改保留前后全文，删除保留删除前全文，
 重要标记保留替换回执。所有记忆工具调用记录参数及成功或错误状态，包括读取、查询和同义词修改；
 自动召回、系统前缀读取不记操作历史。历史查询本身在结果产生后留痕。
 历史随操作累积、没有自动清理；整份状态文件在写入时重写，适合单进程的小型 Memory。
 同义词文件与操作日志分别保存，日志写入失败会返回“操作可能已生效”的错误。
+`zcor_memory_backup` 生成带时间戳的状态副本；恢复前应先备份当前状态，恢复只接受当前版本的副本。
 
 `synonyms.json` 保存词组，首次创建时复制包内的中文及少量英文词组。
 可以通过工具补充，或直接编辑部署侧同义词文件。

package/package.json

@@ -1,13 +1,28 @@
 {
   "name": "cortico-bot-zcor",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "type": "module",
   "main": "./index.ts",
   "description": "Cortico bot with synonym title retrieval and LLM memory selection",
   "license": "MIT",
-  "keywords": ["cortico-bot", "cortico"],
-  "engines": { "node": ">=22" },
-  "cortico": { "kind": "bot", "api": 6, "displayName": "zcor" },
-  "files": ["index.ts", "persona", "README.md"],
-  "devDependencies": { "cortico": "^0.1.16" }
+  "keywords": [
+    "cortico-bot",
+    "cortico"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "cortico": {
+    "kind": "bot",
+    "api": 6,
+    "displayName": "zcor"
+  },
+  "files": [
+    "index.ts",
+    "persona",
+    "README.md"
+  ],
+  "devDependencies": {
+    "cortico": "^0.1.16"
+  }
 }

package/persona/memory.ts

@@ -7,6 +7,7 @@ export const MAX_CANDIDATES = 20;
 export const MAX_RESULTS = 5;
 export const MAX_AUTO_RECALL = 10;
 export const MAX_IMPORTANT = 5;
+export const MEMORY_STATE_VERSION = 1;
 
 export interface MemoryOperation {
   id: string;
@@ -15,6 +16,7 @@ export interface MemoryOperation {
   details: unknown;
 }
 interface MemoryState {
+  version: number;
   records: MemoryRecord[];
   importantIds: string[];
   history: MemoryOperation[];
@@ -102,6 +104,10 @@ export class MemoryStore {
     renameSync(temporary, file);
   }
 
+  private freshState(records: MemoryRecord[] = []): MemoryState {
+    return { version: MEMORY_STATE_VERSION, records, importantIds: [], history: [] };
+  }
+
   private legacyRecords(): MemoryRecord[] {
     const data: unknown = JSON.parse(readFileSync(this.file, 'utf8'));
     if (!Array.isArray(data) || !data.every((v) => v && typeof v === 'object'
@@ -112,9 +118,9 @@ export class MemoryStore {
   }
 
   private state(): MemoryState {
-    if (!existsSync(this.stateFile)) return { records: this.legacyRecords(), importantIds: [], history: [] };
+    if (!existsSync(this.stateFile)) return this.freshState(this.legacyRecords());
     const state = JSON.parse(readFileSync(this.stateFile, 'utf8')) as MemoryState;
-    if (!state || !Array.isArray(state.records) || !state.records.every((record) => record
+    if (!state || state.version !== MEMORY_STATE_VERSION || !Array.isArray(state.records) || !state.records.every((record) => record
       && ['id', 'title', 'content', 'createdAt', 'updatedAt'].every((key) =>
         typeof (record as unknown as Record<string, unknown>)[key] === 'string'))
       || !Array.isArray(state.importantIds) || state.importantIds.length > MAX_IMPORTANT
@@ -122,7 +128,7 @@ export class MemoryStore {
       || !state.importantIds.every((id) => typeof id === 'string' && state.records.some((r) => r.id === id))
       || !Array.isArray(state.history) || !state.history.every((entry) => entry
         && typeof entry.id === 'string' && typeof entry.recordedAt === 'string' && typeof entry.kind === 'string')) {
-      throw new Error('memory-state.json 格式错误');
+      throw new Error(`memory-state.json 格式错误或版本不支持（需要 ${MEMORY_STATE_VERSION}）`);
     }
     return state;
   }
@@ -130,6 +136,7 @@ export class MemoryStore {
   private records(): MemoryRecord[] { return this.state().records; }
 
   private commit(state: MemoryState, kind: string, details: unknown): void {
+    state.version = MEMORY_STATE_VERSION;
     state.history.push({ id: randomUUID(), recordedAt: this.now(), kind, details });
     this.save(this.stateFile, state);
   }
@@ -138,6 +145,22 @@ export class MemoryStore {
     this.commit(this.state(), kind, details);
   }
 
+  backup(): string {
+    const backupFile = `${this.stateFile}.bak-${this.now().replace(/[:.]/g, '-')}`;
+    writeFileSync(backupFile, readFileSync(this.stateFile, 'utf8'), 'utf8');
+    return backupFile;
+  }
+
+  restore(backupFile: unknown): void {
+    const file = requiredText(backupFile, 'backupFile');
+    const restored = JSON.parse(readFileSync(file, 'utf8')) as MemoryState;
+    if (restored.version !== MEMORY_STATE_VERSION || !Array.isArray(restored.records)
+      || !Array.isArray(restored.importantIds) || !Array.isArray(restored.history)) {
+      throw new Error(`备份格式错误或版本不支持（需要 ${MEMORY_STATE_VERSION}）`);
+    }
+    this.save(this.stateFile, restored);
+  }
+
   important(): MemoryRecord[] {
     const state = this.state();
     return state.importantIds.map((id) => state.records.find((record) => record.id === id)!);

package/persona/persona.ts

@@ -128,6 +128,13 @@ export class ZcorPersona implements Persona {
         query, [], ['read'], (args) => this.memory.query(args)),
       tool('zcor_memory_history', '本地查询操作记录：按操作时间范围（含端点）及记录全文关键词全部命中筛选。包含修改前后内容、删除快照、重要标记和工具调用结果状态；按时间倒序分页，不调用 LLM。',
         query, [], ['read'], (args) => this.memory.history(args)),
+      tool('zcor_memory_backup', '将当前 Memory 状态复制为带时间戳的备份文件。', {}, [], ['write'],
+        () => ({ file: this.memory.backup() })),
+      tool('zcor_memory_restore', '从指定备份文件恢复 Memory 状态；恢复前应先备份当前状态。',
+        { backupFile: string }, ['backupFile'], ['write'], (args) => {
+          this.memory.restore(args.backupFile);
+          return { restored: true };
+        }),
       tool('zcor_memory_delete', '按 id 删除当前记忆；操作历史保留删除前内容。', { id: string }, ['id'], ['write'],
         (args) => ({ deleted: this.memory.delete(args.id) })),
       tool('zcor_synonyms_add', '保存一组同义词，查询时双向扩展，重叠词组连通。',