Skip to content

armgit / cindy

Public Imported from GitHub
0

Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。

16.3 KB
Raw Blame
/**
 * MakerMemoryStore — per-workdir 的统一 facade, 把 storage (fs) 和 fts (sqlite) 组合在一起。
 *
 * 职责:
 *  - 对外只暴露一组方法: read / write / delete / list / search / getIndex / consolidate
 *  - 内部协调 storage 跟 fts 的同步: write/delete/consolidate 时触发 fts.upsert/delete
 *  - fts 同步失败不阻塞主路径 — 文件已落盘就算成功, fts 错误只 log warn
 *  - 启动时一次性 sanity check: storage 跟 fts 的 record count 不一致 → 全量 rebuild
 *
 * 不管:
 *  - workdir → 目录的 sanitize (manager 层算好后传 dir + dbPath)
 *  - SQLite Database 实例的生命周期 (manager 持有 + close)
 *  - Agent 联动 / mode 切换 (manager 层)
 *
 * 跨 session 一致性:
 *  本类是 per-workdir 单例 (manager 实例池保证), 同一 workdir 内多 session 共享同一个 store,
 *  storage 按目录串行变更,界面条件更新/删除与伙伴工具写入共享同一互斥。
 */

import type Database from 'better-sqlite3';

import { MemoryFts } from './fts.js';
import { MemoryStorage, sanitizeWorkdir, buildFilename, parseFilename } from './storage.js';
import {
  DEFAULT_MEMORY_CONFIG,
  MemoryError,
  type MemoryConfig,
  type MemoryRecord,
  type MemoryType,
  type SearchHit,
  type SearchOptions,
  type WriteOptions,
  type WriteResult,
} from './types.js';
import type { Logger } from '../interfaces/logger.js';

export interface MakerMemoryStoreDeps {
  /** 已就绪的目录绝对路径 (manager 算好) */
  storageDir: string;
  /** 调用方记录的 workdir 绝对路径 (写进 meta.json) */
  absWorkdir: string;
  /** SQLite 实例 (host 注入, manager 创建并持有 close) */
  db: Database.Database;
  logger: Logger;
  /** 配置覆盖, 缺省走 DEFAULT_MEMORY_CONFIG */
  config?: Partial<MemoryConfig>;
  /**
   * 每次 mutation (write/delete/consolidate/resetType/resetAll) 执行前的 owner
   * scope 守卫 (review #2388 Codex 5th P1): 裸 store 经 getStore 返回后可能被
   * 调用方在 manager 守卫之外使用, 后置复核无法撤销已发生的文件变更 —— 必须在
   * 写操作开始前复核。由 manager 注入 (锚定 store 创建时的 scope), scope 已变
   * 则抛 memory:not-ready。缺席 = 静态宿主, 不守卫。
   */
  scopeCheck?: () => void;
}

export interface ConsolidateOptions {
  /** 要合并的源文件列表 (会被 delete) */
  sources: string[];
  /** 新生成条目的 type/name/title/description/body */
  target: WriteOptions;
}

export interface ConsolidateResult {
  ok: true;
  /** 新文件名 */
  filename: string;
  /** 实际删除的源文件 (源不存在的会被跳过) */
  deletedSources: string[];
  /** 软警告: 删源后按最终磁盘状态重算 (可能与写入时点不同, 也可能出现/消失); 重算失败退回写入时点值 */
  warning?: WriteResult['warning'];
  /** 软警告数值明细, 与 warning 同生同灭 */
  warningDetail?: WriteResult['warningDetail'];
}

export class MakerMemoryStore {
  private readonly storage: MemoryStorage;
  private readonly fts: MemoryFts;
  private readonly logger: Logger;
  private initialized = false;

  constructor(private readonly deps: MakerMemoryStoreDeps) {
    const config = { ...DEFAULT_MEMORY_CONFIG, ...(deps.config ?? {}) };
    this.storage = new MemoryStorage(
      deps.storageDir,
      config,
      // 透传 scope 守卫到 storage 写路径 — write 内部 tryReadRaw await 窗口后、
      // 真正写盘前复核 (review #2388 Codex 8th P1)
      deps.scopeCheck ? () => this.assertScopeOk() : undefined,
    );
    this.fts = new MemoryFts(deps.db);
    this.logger = deps.logger;
  }

  /**
   * scope 前置守卫: owner scope 已变则抛 memory:not-ready (manager 注入,
   * 锚定 store 创建时 scope)。所有公开操作 (读 + 写) 开始前调用:
   *  - 写操作: 文件系统变更发生前拦截, 后置复核无法撤销已发生的变更
   *    (review #2388 Codex 5th P1);
   *  - 只读操作: session 启动时 Claude/Codex 直接 getStore().getIndex() 拼
   *    system prompt (在 withStore 后置检查之外), 边界窗口不得把旧 owner 的
   *    MEMORY.md 注入新 session (review #2388 Codex 6th P1)。
   */
  private assertScopeOk(): void {
    this.deps.scopeCheck?.();
  }

  /** mkdir + meta.json + FTS 表创建 + sanity check (count 不一致 → rebuild). 幂等. */
  async init(): Promise<void> {
    if (this.initialized) return;
    await this.storage.init(this.deps.absWorkdir);
    // 派生索引 (MEMORY.md) 无条件重建 (review #2388 Codex 24th P1): dirty 标记
    // 是实例内存态 — 写/删被边界中止后 store 会被 close/重建, 标记丢失;
    // 安全打开时直接重建, 不依赖实例状态, 同 owner 后续 session 不再读 stale 索引。
    await this.storage.rebuildIndex();
    // storage.init await 后、FTS 副作用前复核 (review #2388 Codex 18th P1):
    // 首次打开的 getStore 无 withStore 后置检查, 边界不得在此创建旧 owner 的 fts.db。
    this.assertScopeOk();
    this.fts.init();
    await this.sanityCheck();
    // FTS 无条件重建 (review #2388 Codex 24th P2): update/append 被边界中止时
    // 文件数不变, sanityCheck 的 count 检查永不触发 — open 时全量重建保证
    // memory_search 不返回 stale 结果。
    const all = await this.storage.list();
    // list await 后、rebuild 前复核 (review #2388 Codex 25th P1): 边界/resetAll
    // 在 list 在途时开始 — 不得重写旧 owner 的 fts.db 或碰被删的 db。
    this.assertScopeOk();
    this.fts.rebuild(all);
    // sanityCheck/list 内部多次 await 后复核。
    this.assertScopeOk();
    this.initialized = true;
  }

  // ── 直通 storage 的方法 (read 类) ────────────────────────────────────────

  async list(): Promise<MemoryRecord[]> {
    this.assertScopeOk();
    await this.init();
    const records = await this.storage.list();
    // await 后复核 (review #2388 Codex 11th P1): 读取在途时边界可能发生,
    // 不得把旧 owner 数据返回给新会话。
    this.assertScopeOk();
    return records;
  }

  async read(filename: string): Promise<MemoryRecord> {
    this.assertScopeOk();
    await this.init();
    const rec = await this.storage.read(filename);
    this.assertScopeOk();
    return rec;
  }

  async getIndex(): Promise<string> {
    this.assertScopeOk();
    await this.init();
    const index = await this.storage.getIndex();
    // session 启动路径 getStore().getIndex() 无 withStore 后置检查 — 返回前
    // 复核, 边界窗口不得把旧 owner 的 MEMORY.md 赋给 makerMemoryIndex。
    this.assertScopeOk();
    return index;
  }

  async getIndexSize(): Promise<number> {
    this.assertScopeOk();
    await this.init();
    const size = await this.storage.getIndexSize();
    this.assertScopeOk();
    return size;
  }

  // ── 写入类 (storage + fts 两侧同步) ─────────────────────────────────────

  async write(opts: WriteOptions): Promise<WriteResult> {
    this.assertScopeOk();
    await this.init();
    return this.syncWrite(await this.storage.write(opts));
  }

  /** Conditional in-place edit; retains legacy filenames and uses the shared storage queue. */
  async update(
    filename: string,
    expectedUpdatedAt: string,
    changes: Pick<WriteOptions, 'title' | 'description' | 'body'>,
  ): Promise<MemoryRecord> {
    this.assertScopeOk();
    await this.init();
    const saved = await this.storage.update(filename, expectedUpdatedAt, changes);
    await this.syncWrite({ ok: true, filename });
    return saved;
  }

  private async syncWrite(result: WriteResult): Promise<WriteResult> {
    // storage await 后、FTS 同步前复核 (review #2388 Codex 15th P1): 边界不得
    // 让 manager.write 直接路径 (Pi compaction) 改旧 owner 的 fts.db。
    this.assertScopeOk();
    // FTS 同步 — 失败只 warn, 文件已落盘
    try {
      const rec = await this.storage.read(result.filename);
      // reread await 后、upsert 前复核 (review #2388 Codex 16th P1): 边界
      // 不得让 FTS 写入旧 owner 的 fts.db; not-ready 透传 (fail-closed)。
      this.assertScopeOk();
      this.fts.upsert(rec);
    } catch (e) {
      if (e instanceof MemoryError && e.code === 'not-ready') throw e;
      this.logger.warn('memory fts upsert failed (file written ok, will rebuild on next sanity)', {
        filename: result.filename,
        error: String(e),
      });
    }
    return result;
  }

  async delete(filename: string, expectedUpdatedAt?: string): Promise<void> {
    this.assertScopeOk();
    await this.init();
    await this.storage.delete(filename, expectedUpdatedAt);
    // storage await 后、FTS 同步前复核 (review #2388 Codex 15th P1)
    this.assertScopeOk();
    try {
      this.fts.delete(filename);
    } catch (e) {
      this.logger.warn('memory fts delete failed (file already removed, will rebuild on next sanity)', {
        filename,
        error: String(e),
      });
    }
  }

  /** 仅清空一种 memory;给 agent 私有的系统记忆(如 Pi digest)使用。 */
  async resetType(type: MemoryType): Promise<{ removedCount: number }> {
    this.assertScopeOk();
    await this.init();
    const matching = (await this.storage.list()).filter((record) => record.frontmatter.type === type);
    for (const record of matching) {
      await this.delete(record.filename);
    }
    return { removedCount: matching.length };
  }

  // ── 检索 ─────────────────────────────────────────────────────────────────

  async search(query: string, opts?: SearchOptions): Promise<SearchHit[]> {
    // 读守卫 (review #2388 Codex 10th P2): 与 list/read/getIndex 一致,
    // 边界不得把旧 owner 的 FTS 检索结果返回给新会话。
    this.assertScopeOk();
    await this.init();
    const hits = await this.fts.search(query, opts);
    this.assertScopeOk();
    return hits;
  }

  // ── 合并 (LLM 在 size warning 后调) ─────────────────────────────────────

  /**
   * 原子化合并: 写入新条目 → 删源 → 重建索引一次。
   * 任意源不存在时跳过 (不抛), 真删过的列表回 deletedSources。
   * 失败时尽力恢复: 若新条目写失败直接抛; 若删除中途失败已删的不回滚 (文件系统不支持)。
   */
  async consolidate(opts: ConsolidateOptions): Promise<ConsolidateResult> {
    this.assertScopeOk();
    await this.init();
    // 防呆: 不允许把 target 写到正要被删的 source 里 (否则会自删)
    const targetFilename = buildFilename(opts.target.type, opts.target.name);
    const sourcesToDelete = opts.sources.filter((s) => s !== targetFilename);

    // 写新的 (撞名时走 update)
    const writeOpts: WriteOptions = { ...opts.target };
    const targetExists = await this.tryReadRaw(targetFilename);
    if (targetExists) {
      writeOpts.mode = 'update';
    } else {
      writeOpts.mode = 'create';
    }
    // tryReadRaw 与 entry check 之间有 await 窗口 — 写 target 前再复核一次
    // (review #2388 Codex 7th P1), 边界不得写入旧 owner 文件。
    this.assertScopeOk();
    const writeRes = await this.storage.write(writeOpts);

    // 删源 — 每次删除前复核 scope (review #2388 Codex 7th P1): target write 与
    // 删源之间有 await, 边界若在窗口内发生, 裸 storage.delete 仍会变更旧 owner
    // 文件; 后置复核无法撤销, 必须在每个删除动作前拦截。
    const deleted: string[] = [];
    for (const src of sourcesToDelete) {
      try {
        this.assertScopeOk();
        await this.storage.delete(src);
        // 删除后复核 — storage.delete 跨越 fs.unlink, 边界不得在其后继续 (review #2388)
        this.assertScopeOk();
        deleted.push(src);
      } catch (e) {
        if (e instanceof MemoryError && e.code === 'not-ready') throw e;
        if (e instanceof MemoryError && e.code === 'not-found') continue;
        this.logger.warn('consolidate: failed to delete source (continuing)', {
          source: src,
          error: String(e),
        });
      }
    }

    // FTS 同步 (整体重建一次, 比逐个 upsert/delete 简单且更不容易出错)
    // rebuild 前复核 (review #2388 Codex 15th P1): 删源循环的 await 窗口后,
    // 边界不得让 FTS 重建落在旧 owner 的 sqlite 上。
    this.assertScopeOk();
    try {
      const all = await this.storage.list();
      // list await 后、rebuild 前复核 (review #2388 Codex 17th P1): list 在途时
      // 边界可能发生; not-ready 透传, FTS 不得写入旧 owner fts.db。
      this.assertScopeOk();
      this.fts.rebuild(all);
    } catch (e) {
      if (e instanceof MemoryError && e.code === 'not-ready') throw e;
      this.logger.warn('consolidate fts rebuild failed', { error: String(e) });
    }

    // 删源后索引已变小, 写入时点的软警告可能失真 — 以最终磁盘状态重算;
    // 重算失败时退回写入时点的值 (宁可保守报警, 不静默丢警告)
    let finalDetail = writeRes.warningDetail;
    try {
      finalDetail = await this.storage.assessWarning(writeRes.filename);
    } catch (e) {
      this.logger.warn('consolidate: reassess warning failed, using write-time detail', {
        error: String(e),
      });
    }

    return {
      ok: true,
      filename: writeRes.filename,
      deletedSources: deleted,
      ...(finalDetail ? { warning: finalDetail.kind, warningDetail: finalDetail } : {}),
    };
  }

  /** 清空当前 workdir 全部 memory (manager.resetWorkdir 调). 慎用 */
  async resetAll(): Promise<{ removedCount: number }> {
    this.assertScopeOk();
    await this.init();
    const all = await this.storage.list();
    // list 是 await 窗口 — 逐项删除前必须逐次复核 (review #2388 Greptile 8th P1):
    // 边界在 list 期间发生则删除不得继续作用于旧 owner 文件。
    for (const r of all) {
      try {
        this.assertScopeOk();
        await this.storage.delete(r.filename);
        // 删除后复核 (review #2388 Greptile 9th P1): storage.delete 跨越
        // fs.unlink 与 rebuildIndex, 最后一次删除等待期间切换则删除+索引重建
        // 不得跨边界完成 — 立即中止, 不返回成功 removedCount。
        this.assertScopeOk();
      } catch (e) {
        if (e instanceof MemoryError && e.code === 'not-ready') throw e;
        /* swallow */
      }
    }
    // 最终 FTS 重建前复核 (review #2388 Codex 19th P1): 删除循环后仍可能跨
    // 边界, 不得在旧 owner 的 fts.db 上 rebuild; not-ready 透传 fail-closed。
    this.assertScopeOk();
    try { this.fts.rebuild([]); } catch { /* swallow */ }
    return { removedCount: all.length };
  }

  // ── 内部 ─────────────────────────────────────────────────────────────────

  /** storage 跟 fts count 不一致 → 全量 rebuild fts */
  private async sanityCheck(): Promise<void> {
    const fileCount = (await this.storage.list()).length;
    // list await 后、访问 SQLite 前复核 (review #2388 Greptile 18th P1):
    // 首次打开的 init 期间并发 resetAll 可能已关闭 db — 不得用已关句柄调
    // fts.count() 抛裸 SQLite/IO 错误, 应 fail-closed 抛 not-ready。
    this.assertScopeOk();
    const ftsCount = this.fts.count();
    if (ftsCount === -1 || ftsCount !== fileCount) {
      this.logger.info('memory fts inconsistent, rebuilding', { fileCount, ftsCount });
      const all = await this.storage.list();
      // list await 后、rebuild 前复核 (review #2388 Codex 19th P1): 边界不得
      // 在旧 owner 的 fts.db 上重建。
      this.assertScopeOk();
      this.fts.rebuild(all);
    }
  }

  private async tryReadRaw(filename: string): Promise<boolean> {
    if (!parseFilename(filename)) return false;
    try {
      await this.storage.read(filename);
      return true;
    } catch {
      return false;
    }
  }
}

// 跟 storage helper 同步导出, 让 manager 不用各处 import
export { sanitizeWorkdir, buildFilename, parseFilename };
export { memoryScopeDirName } from './storage.js';