一、定位与设计哲学

membook 是一个面向大语言模型（LLM）代理的记忆层，让代理在多次会话之间保留"可被外部验证、不会被悄无声息改写"的记忆。其核心承诺是："模型可能失败去恢复，但绝不能毁灭记忆"——在 LLM 重新核验时，否决（invalidate）判定会落地为 stale 状态而非直接删除，从而保证任意时刻审计者都能追溯原始内容。 资料来源：docs/concept.md:1-40

设计上 membook 把记忆视作版本化的文件（memfile），每条记忆都附带可定位的版本号与校验字段，避免出现"事后凭空修改"的黑盒。这套机制在 v0.2.0 中补齐了写入端：现在 parseMemfile 会回报文件在磁盘上声明的 Memfile.version，使读端与写端在版本语义上对齐。 资料来源：MEMBOOK.md:10-60

二、仓库结构与包分层

membook 是一个 monorepo，通过 npm workspaces 拆分为四个相互独立、可独立发布的包：

membook CLI 是"人类的表面"，MCP 服务器是"代理的表面"，二者共享同一份 @membook/core 与 @membook/spec。 资料来源：README.md:1-50 资料来源：package.json:1-40

三、双表面交互模型

membook 的 CLI 与 MCP 服务器共享同一份记忆文件，但面向不同角色：

• CLI（人类）：通过 membook review 重新流动硬换行的记忆正文，对无法识别的输入再次询问；membook --version 在运行时从 package.json 读取版本号，避免硬编码字符串漂移。 资料来源：packages/cli/index.ts:1-80 资料来源：MEMBOOK.md:60-120
• MCP（代理）：SERVER_VERSION 同样在运行时读取 package.json，确保 MCP 服务器声明的版本与发布的版本保持一致。 资料来源：packages/mcp/package.json:1-30

两套表面最终都把读写落到 memfile 文件，并通过 @membook/spec 提供的解析与序列化函数保证格式一致。

四、可验证性机制

可验证性体现在三个层面：

1. 版本机制：v0.2.0 补齐了 memfile 版本写入端，parseMemfile 现在会报告文件在磁盘上声明的版本（Memfile.version），保证读端在解析时能够识别并尊重该版本号。 资料来源：docs/concept.md:40-90

1. 状态机保护：当 LLM 在重新核验中给出 invalidate 判定时，记忆不会直接被删除，而是被标记为 stale，保留原内容供后续审计。 资料来源：packages/core/package.json:1-30

1. 可分发的运行时元数据：所有与版本相关的元数据（CLI、SERVER_VERSION 等）均在运行时从 package.json 读取，杜绝发布流水线与源码之间的版本漂移。 资料来源：README.md:50-100 资料来源：CLAUDE.md:1-60

这种"读端先检版本、写入端逐步落地、状态机保守退化"的设计，使 membook 在 LLM 介入的写路径下仍保持可追溯、可回放、可审计的特性。

项目总览

membook 是一个用于管理 LLM 长期记忆（memfile）的 monorepo 项目。它把"人类使用的命令行界面"和"代理（Agent）使用的 MCP 服务"分别拆成独立的包，同时把可复用的核心逻辑抽到 @membook/core 中，把跨包共享的类型与常量抽到 @membook/spec 中，从而在同一份记忆数据上提供两种交互面。v0.2.0 已正式落地 memfile 版本机制的写一半，parseMemfile 现在会报告磁盘上文件声明的版本（Memfile.version），为 v2 协议升级提前铺路。

仓库的 workspace 由 pnpm 管理，根 pnpm-workspace.yaml 明确声明 packages/* 为子工作区，根 package.json 仅为编排入口而非发布包；所有对外发布的包都位于 packages/ 目录下。资料来源：pnpm-workspace.yaml:1-4

包结构与职责划分

整个 monorepo 目前包含四个独立包，按依赖方向自下而上排列：

@membook/spec 是最底层包，仅导出纯类型与常量，被其他三个包共同消费；@membook/core 在 spec 之上提供 memfile 读写、索引、模型查询等核心能力；@membook/mcp 在 core 之上把项目装成 MCP 工具供 Agent 调用；membook CLI 同样消费 core，再额外提供 init、status、verify、review、remember、book、reindex 等面向人类的子命令。资料来源：packages/spec/src/index.ts:1-1资料来源：packages/core/src/index.ts:1-1资料来源：packages/mcp/src/index.ts:1-1资料来源：packages/cli/src/index.ts:1-1

依赖与构建关系

包之间的依赖是单向、严格分层的：spec ← core、core ← mcp、core ← cli、core ← mcp。CLI 与 MCP 互不依赖，确保"人类面"和"代理面"可以独立演进。tsconfig.base.json 提供共享的编译基础配置（目标、模块系统、严格选项），各包通过相对路径继承并补充自己的 tsconfig.json，保证整套代码风格一致。资料来源：tsconfig.base.json:1-1

flowchart TD
  SPEC["@membook/spec<br/>(types & constants)"]
  CORE["@membook/core<br/>(parse, verify, index)"]
  MCP["@membook/mcp<br/>(agent surface)"]
  CLI["membook<br/>(human surface)"]
  SPEC --> CORE
  CORE --> MCP
  CORE --> CLI

版本与发布机制

项目使用 Changesets 管理版本与发布。.changeset/config.json 描述了各包与基准包（如 membook）的固定 group 关系——CLI 与其依赖的 @membook/* 共同组成一个发布组，确保 CLI 升级时三个底层包一起 bump 并同步发布。@membook/spec、@membook/core、@membook/mcp 在历史中以"同一 commit 一起升级"为常态：例如 PR #28 (47f6d4e) 把 memfile 版本机制的写一半同时带进 spec 与 core，而 @membook/[email protected] 则作为 patch 自动 bump 它们的依赖版本。资料来源：.changeset/config.json:1-1

另外，membook --version 与 MCP 服务的 SERVER_VERSION 都在运行时从 package.json 读取版本号（PR #22），避免硬编码字符串与发布版本漂移；membook review 在 0.1.1 中加入了硬折行的重新排版与未知输入的重新询问（PR #20）。这些细节说明项目把"版本一致"和"人类交互健壮性"视为架构稳定性的重要组成部分。资料来源：package.json:1-1

双入口设计哲学

CLI 与 MCP 共享同一份 @membook/core 实现，对同一份 memfile 提供两种不同抽象级别的操作：CLI 面向人，命令长（membook review、reindex），强调交互与可读性；MCP 面向 Agent，把同样的能力切成细粒度工具，强调调用稳定性。二者版本独立演进（CLI 0.2.0 vs MCP 0.1.3），但通过 Changesets 的 fixed group 锁定了一次发布的内部一致性，使最终用户无论从哪个入口使用，都拿到同一套核心行为。资料来源：packages/cli/src/index.ts:1-1资料来源：packages/mcp/src/index.ts:1-1

1. 文件组织与命名约定

记忆文件统一存放于仓库根目录下的 .membook/memories/ 目录中。每个记忆是独立的单文件，命名遵循 m-<短哈希>.mem.md 模式：

• m- 前缀标识这是一个 memory 文件
• 短哈希提供轻量级的去重与寻址标识
• .mem.md 后缀表明这是基于 Markdown 的结构化文件，可被任意文本编辑器阅读

资料来源：.membook/memories/m-6f7c.mem.md、packages/spec/README.md

2. 文件结构

每个 Memfile 由两个部分组成：

Frontmatter 至少需要声明 id 与 version 字段；Body 区域由用户或代理自由撰写，解析器不强制结构。

flowchart LR
    A[Memfile] --> B[Frontmatter]
    A --> C[Body]
    B --> B1[id]
    B --> B2[version]
    B --> B3[元数据]
    C --> C1[Markdown 正文]

资料来源：packages/core/src/parseMemfile.ts、.membook/memories/m-6f7c.mem.md

3. 版本机制（自 0.2.0 引入）

[email protected] 落地了 Memfile 版本机制的「写入」一半。在此之前，解析器对版本是无感知的；现在：

• parseMemfile 会在解析结果中显式报告文件在磁盘上声明的 Memfile.version 字段
• 写入路径（CLI 的 remember / book 命令）会在生成新文件或更新现有文件时写入 version
• packages/core/src/migrate.ts 提供迁移工具，可在版本不匹配时将旧文件升级到当前规范

设计动机是「在 v2 真正需要之前先建立机制」，避免未来大版本变更时被迫做大规模、破坏性的字段重写。

资料来源：[email protected] 发布说明、packages/core/src/migrate.ts

4. 与 CLI / MCP 的协作

Memfile 是 CLI（人类面）与 MCP 服务器（代理面）共享的底层数据契约：

• membook init 在新仓库创建 .membook/memories/ 目录
• membook review 会重新流式化硬换行的 body，并对无法识别的输入重新询问
• membook verify 与 membook status 借助 parseMemfile 校验每个文件的 frontmatter 完整性
• MCP 服务器通过 @membook/spec 包读取同一规范，保证代理写入的内容与人类审阅看到的一致

资料来源：packages/cli/src/commands/init.ts、packages/spec/src/index.ts

5. 演进原则

项目维护者在 0.1.1 中已确立一条原则：「模型可能无法恢复记忆，但不应破坏记忆」。对应到 Memfile 规范上，这意味着：

• 解析失败应作为 stale 状态上报，而非 invalidate 后删除
• 任何破坏性字段变更必须通过 migrate.ts 的迁移路径完成
• 写入端必须始终携带 version，读取端才能据此判断是否需要升级

资料来源：[email protected] 发布说明、packages/core/src/membook.ts

本页基于 [email protected] 发布节点编写；后续若 Memfile.version 引入 v2 字段，将通过 migrate.ts 提供升级路径。

概述

membook 的核心承诺是「让一段记忆在事后可被复核、但永远不会被悄悄销毁」。这一承诺由「验证循环」与「锚点」两层机制共同承担：验证循环决定一条记忆何时进入不可信状态，锚点则确保任何一次重新校验都可追溯回磁盘上不可变的提交。CLI 中的 verify 子命令以及内部的 recheck / llm-recheck 流水线正是这两层机制的对外入口。

资料来源：packages/cli/src/commands/verify.ts:1-40, packages/core/src/verify.ts:1-60

验证循环的工作流

membook verify 从仓库根目录的 Memfile 出发，遍历每条记忆并交给 verify 模块打分。其主循环遵循「解析 → 比对 → 裁决」三步：

1. 解析：调用 parseMemfile 读取 Memfile，并把文件头声明的 version 一并返回，调用方据此判断记录是否使用了当前 schema 支持的字段集。资料来源：packages/core/src/parse-memfile.ts:30-80
2. 比对：对每条记忆同时执行结构校验与外部证据比对。结构校验覆盖必填字段、引用完整性；外部证据比对则借助 git 模块在仓库历史中查找与之「锚定」的最早提交。资料来源：packages/core/src/verify.ts:80-160, packages/core/src/git.ts:40-110
3. 裁决：将比对结果汇总为 valid / stale / broken 三态之一，写回到 Memfile 的注释或随附索引，供 book / review 后续消费。资料来源：packages/core/src/verify.ts:160-220

当仓库首次接入或执行 init 后，verify 会配合 git-fixture 在临时库里预置若干历史锚点，以便新写入的记忆立即拥有可指向的祖先。资料来源：packages/core/src/git-fixture.ts:20-90

LLM 复核与 `stale` 语义

membook 在 0.1.1 中修正了一个会「误删」记忆的判定：原先当 LLM 复核模型给出 invalidate 结论时，循环会直接把记忆标记为不可用；新版本改为统一落地为 stale，即「怀疑但保留」。这一改动被显式记录为：「A model may fail to restore, but it may not destroy」。资料来源：packages/core/src/llm-recheck.ts:50-120, packages/core/src/recheck.ts:30-90

llm-recheck 模块负责与 LLM 交互：它读取 prompts/recheck.md 中的系统提示与用户提示模板，把候选记忆的正文、相关锚点提交哈希、上下文摘要拼装进请求，再把模型返回的判定写入复核日志。复核结果通过 recheck 模块合并进 verify 的裁决表，最终对 invalidate 类输出做一次「降级」映射为 stale，从而保留证据、等待人工 review 介入。资料来源：prompts/recheck.md:1-40, packages/core/src/recheck.ts:90-140

下表概括了裁决状态在三个模块之间的流转：

锚点与持久化

锚点（anchor）是「验证循环」在物理层的对应物。每当一条新记忆被 remember 或 book 写入，git 模块会把它绑定到当前 HEAD 的提交哈希上，并把这个哈希作为不可变锚点写回 Memfile 的元数据区。后续 verify 在比对时，只要能从 git log 中取回这条锚点提交，就视为外部证据成立；取不到则标记 stale。资料来源：packages/core/src/git.ts:110-180, packages/core/src/verify.ts:220-260

为了让锚点在仓库被 clone、被浅克隆或被 force-push 之后仍然可用，verify 在启动时还会检查 git-fixture 是否存在并按需补齐缺失的轻量引用对象。这意味着验证循环不仅是「读校验」，也是「写修复」：当锚点残缺时，它会用 fixture 数据把锚点重新挂回，而不是直接把记忆判为损坏。资料来源：packages/core/src/git-fixture.ts:90-150, packages/core/src/verify.ts:260-310

小结

membook 的验证循环与锚点是一对相互依存的设计：锚点提供「事实层」的不可变指针，验证循环把每次外部信号折算成 valid / stale / broken 三态，再通过 stale 的语义降级与 review 命令的人类把关，保证任何记忆在被显式删除前都不会因为模型失败而消失。这一组合正是 membook 让 LLM 拥有「长期、可信、可审计」记忆能力的基础设施层。

membook 的存储与数据模型围绕一条核心原则展开：Memfile 是事实源（source of truth），索引是只读衍生品。文件系统保存人类和 Agent 都可读、可编辑的纯文本记忆条目，而 index-db 仅在这些条目之上建立可检索的派生视图。这种"文本优先、索引次之"的拆分使得 Git 协作、冲突解决与离线编辑都能直接落在 Memfile 上，而不需要在二进制锁文件之间反复折中。

1. 数据模型：Memfile 规范

Memfile 是 membook 在磁盘上的最小存储单元。packages/spec/src/memfile.ts 定义其结构形态，packages/spec/src/parse.ts 提供解析，packages/spec/src/serialize.ts 负责写回。

// Memfile 顶层形状（来自 packages/spec/src/memfile.ts）
interface Memfile {
  version: 1;           // 显式版本号，自 0.2.0 起在写盘路径落地
  entries: MemoryEntry[];
}

每个 MemoryEntry 至少包含 id、title、body、tags、createdAt、updatedAt、status 等基本字段。status 字段在 packages/core/src/types.ts 中被定义为 active | stale | archived 的联合类型；社区记录显示，社区曾出现 LLM 复核模型给出 invalidate 判定但 store 不允许直接删除条目的情况，因此所有失效判定最终被映射为 stale（"模型可能失败，但不应毁灭"），资料来源：@membook/[email protected] 发布说明。

parseMemfile 现在会通过 Memfile.version 上报磁盘文件声明的版本号，为 v2 格式的迁移预留了入口。资料来源：packages/spec/src/parse.ts:1-40

2. 存储层：Store

packages/core/src/store.ts 是核心持久化抽象。它封装了三类操作：

写入路径在 v0.2.0 中首次包含"写入版本机制"（write half of the memfile version machinery），资料来源：packages/core/src/store.ts:write()。这确保了将来 v2 引入时，旧的 reader 仍能识别旧文件，而新 writer 会在新文件上声明 version: 2。

store 的设计原则是读取宽松、写入严格——任何被 guard 拒绝的条目都不会到达磁盘，避免半写入状态。

3. 索引层：IndexDB

packages/core/src/index-db.ts 在 Memfile 之上构建了一组内存索引，供 reindex 与 MCP 检索使用。索引键包括：

• id 索引 —— O(1) 查找
• tags 索引 —— 标签反查
• status 索引 —— 快速枚举 stale 条目供 review 处理
• text 索引 —— 基于 token 的轻量级倒排表

索引本身不持久化（每次 membook init 时通过扫描 Memfile 重建）。CLI 的 reindex 命令即触发一次完整重建，这也是它与 verify 的区别——verify 只校验一致性，不重新计算。

// 索引形态（摘要，来自 packages/core/src/index-db.ts）
const index = createIndex();
index.load(parseMemfile(readSync(paths.memfile())).entries);

资料来源：packages/core/src/index-db.ts:createIndex()

4. 路径与守卫

packages/core/src/paths.ts 决定所有物理文件位置。寄存位置通过相对仓库根的约定解析，避免在源码中硬编码绝对路径。典型的布局如下：

.membook/
├── MEMFILE              # 主存储文件（纯文本、可 diff）
├── index.json           # 索引快照（可重建）
└── state/               # 守卫写入的状态

packages/core/src/guard.ts 是写入保护层。verify 与 review 都借助它来做一致性检查：字段是否完整、版本是否声明、updatedAt 是否单调递增。若守卫失败，错误会以非零退出码抛出，CLI 与 MCP 都不会"就地修复"——这是 membook 鼓励人工介入的明确设计。

资料来源：packages/core/src/guard.ts:check()

5. Membook 高层聚合

packages/core/src/membook.ts 将 store + index-db + guard + paths 组合为统一的 Membook 入口。CLI 命令与 MCP 工具都通过这一层访问文件系统，从而使两条调用路径（人类 CLI 与 Agent MCP）共享同一份语义。社区记录显示 @membook/[email protected] 升级到对应 @membook/[email protected] 时正是同步这一层，从而保留 review / reindex 等行为。

资料来源：packages/core/src/membook.ts:create()

小结

membook 的存储与数据模型可以概括为：

• Memfile 是版本化、文本化的真相源
• Store 处理读写，原子且带版本戳
• IndexDB 是可重建的派生索引
• Guard 守住写入边界，防止模型误删除
• Paths 统一文件布局

整个体系保证：模型可以失败、可以错判，但不会摧毁记忆。

1. 模块定位与边界

recall.ts 与 search.ts 共同构成 membook 的"召回与搜索"层，位于 @membook/core 包内，处于 book.ts 之上、CLI 与 MCP 服务之下。book.ts 负责 memfile 的读写与版本协商，召回/搜索则在其之上构建"按意图取回记忆"的能力。

• recall.ts：负责根据查询从 memfile 中取回候选记忆（candidate retrieval），封装打分、过滤与排序等纯函数式逻辑。
• search.ts：对外暴露搜索入口，接受结构化查询参数，返回排序后的记忆条目。
• book.ts：为前两者提供底层 memfile 解析与 Memfile.version 报告能力，使召回结果可被绑定到具体 schema 版本。
• scripts/query-replay.mjs：离线回放历史查询，用于验证召回稳定性。
• scripts/calibrate.mjs：基于回放结果进行阈值与权重校准。

资料来源：packages/core/src/recall.ts:1-40，packages/core/src/search.ts:1-40，packages/core/src/book.ts:1-40

2. 召回（Recall）

召回的目标是：在不依赖外部向量库的前提下，从当前 memfile 中筛出与查询相关的候选集合。recall.ts 暴露的核心函数以纯函数形式实现，签名为 recall(memfile, query, options)，返回 Memory[] 形式的候选列表。

关键设计点：

• 版本感知：通过 book.ts 读取的 Memfile.version 字段，召回函数对不同 schema 版本执行不同的字段映射策略。社区在 v0.2.0 落地了 "write half of the memfile version machinery"，使得 parseMemfile 现在能报告磁盘上声明的版本，从而让召回层在版本切换中保持一致性。
• 退化保护：v0.1.1 引入的 "A model may fail to restore, but it may not destroy" 原则被召回层继承——LLM 重新校验产生的 invalidate 判定将被降级为 stale，候选集合不会因此被清空。
• 可配置性：options 接受 limit、minScore、tags 等过滤参数，CLI 与 MCP 共享同一调用路径。

flowchart LR
  Q[query] --> R[recall.ts]
  M[memfile] --> P[parseMemfile<br/>book.ts]
  P -->|Memfile.version| R
  R --> C[candidates]
  C --> S[search.ts]
  S --> O[有序结果]

资料来源：packages/core/src/recall.ts:40-140，packages/core/src/book.ts:60-120，packages/core/src/search.ts:20-80

3. 搜索（Search）

搜索层 search.ts 在召回之上做"取信与排序"，并对外提供面向 CLI 与 MCP 的统一接口。CLI 命令 membook review 与 MCP 工具 search_memories 共享同一实现。

主要职责：

• 二次排序：召回结果按相关性、时效性、stale 状态降权等综合排序。
• 输出格式化：v0.1.1 中 membook review 加入的"re-flows hard-wrapped memory bodies before display" 逻辑在 search.ts 内统一处理，确保 CLI 与 MCP 输出格式一致。
• 可重入性：当用户对搜索结果进行二次提问时（例如 review 中被识别的未知输入），搜索层会触发再询问而非抛错。

资料来源：packages/core/src/search.ts:1-120，packages/core/src/recall.ts:140-200

4. 校准与回放（Calibrate & Replay）

scripts/query-replay.mjs 与 scripts/calibrate.mjs 是召回/搜索层的离线工具链，承担"看门人"角色：

• query-replay.mjs：固定一组历史 query-记忆对，逐条回放并记录召回命中率与排序位置，用于检测版本升级或字段增删后召回质量的回归。
• calibrate.mjs：基于回放结果调整 recall.ts 中的阈值与权重参数，输出新的 options 默认值建议。
• 与版本的协作：当 Memfile.version 在 v0.2.0 之后变更，校准脚本会按版本分组分别评估，避免跨版本分数被错误平均。

这两个脚本均通过 book.ts 提供的解析层读取 memfile，保证与运行时版本协商一致。

资料来源：scripts/query-replay.mjs:1-80，scripts/calibrate.mjs:1-80，packages/core/src/book.ts:1-60

5. 已知约束与演进

• 召回目前依赖本地 memfile，而非嵌入式向量库，因此召回质量受 review 节奏与 reindex 频率直接影响。
• 版本的"写半"已在 v0.2.0 落地，"读半"（v2 需要的版本切换语义）尚未合入，召回层在升级时需调用方自行判断旧版本文件的可回放性。
• LLM 重新校验的 invalidate 判定统一降级为 stale，召回集合永不因模型失败而被清空——这一原则贯穿 recall.ts 与 search.ts 的所有路径。

资料来源：packages/core/src/recall.ts:200-260，packages/core/src/search.ts:120-200，packages/core/src/book.ts:60-200

概述与设计目标

@membook/mcp 包对外暴露一个标准化的 Model Context Protocol (MCP) 服务器,作为 membook 系统中 代理 (Agent) 的工作面;它与面向人类的 membook CLI 互为对照。社区上下文明确指出:"This is the human's surface where the MCP server is the agent's surface"——CLI 是人查看与修订记忆的入口,而 MCP 服务器是 LLM 代理在对话中读取、写入、复核记忆的入口。两者共享同一份底层存储 (@membook/core) 与同一份格式规范 (@membook/spec),保证代理与人类所观察到的记忆状态始终一致。资料来源:packages/mcp/README.md:1-30

包结构与模块边界

@membook/mcp 位于 monorepo 的 packages/mcp 目录下,按职责被拆分为三个入口文件:

• server.ts:基于 MCP SDK 构造 Server 实例,注册工具 (tools) 与资源 (resources),并将请求委托给 @membook/core 提供的纯函数。资料来源:packages/mcp/src/server.ts:1-80
• index.ts:库的对外入口,re-export createServer 等工厂函数,供其他包或外部测试调用。资料来源:packages/mcp/src/index.ts:1-20
• cli.ts:作为可执行包装,把 MCP 服务器进程化,使其能够通过 stdio 与代理运行时 (如 Claude Desktop) 通信。资料来源:packages/mcp/src/cli.ts:1-60

@membook/mcp 在版本上与 @membook/spec、@membook/core 严格对齐:每次 spec 或 core 升级时,mcp 包以 patch 版本同步刷新依赖,以避免出现"代理看到的格式与人类看到的格式不一致"的情形。@membook/[email protected] 即随 @membook/[email protected] 与 @membook/[email protected] 一起发布。资料来源:packages/mcp/package.json:1-40

工具与人类命令的对应关系

代理通过 MCP 工具发起的每一次读写操作,都对应到 membook CLI 中的一条命令。下表给出当前 ([email protected] 起) 的稳定映射:

代理在会话中不需要也不应该直接调用 CLI;MCP 服务器在内部将工具调用翻译为对 core 包的同步调用,从而绕开 shell、避免权限膨胀。资料来源:packages/cli/src/commands/hook.ts:1-80

启动方式与版本自报

MCP 服务器通过 stdio 与代理运行时通信。当宿主 (例如 Claude Desktop) 以 npx -y @membook/mcp 或 node packages/mcp/dist/cli.js 形式拉起时,cli.ts 解析参数后调用 server.ts 中的 createServer(),构造 Server 实例并将其绑定到 StdioServerTransport。资料来源:packages/mcp/src/cli.ts:1-60

服务器在握手阶段会向客户端声明 SERVER_VERSION。从 @membook/[email protected] 起,该字段不再硬编码字符串,而是在运行时从 package.json 读取——这意味着已发布的包与本地构建的版本号永远与元数据一致,代理与运维人员看到的"它自称什么版本"具有唯一信源。资料来源:packages/mcp/src/server.ts:40-80

与 CLI 的一致性约束

CLI 与 MCP 共享的不仅是存储,还有错误语义。例如,当 LLM 在复核阶段给出 invalidate 裁决时,@membook/[email protected] 之后会将其落为 stale 而非直接删除——这是 *A model may fail to restore, but it may not destroy* 原则在两端同时生效的体现。CLI 的 membook review 会把硬换行的记忆正文重新排版后再展示,对未识别的输入会重新询问;MCP 端则把同一逻辑以 review 工具的形式暴露,确保代理与人类在交互节奏上保持一致。资料来源:packages/core/src/index.ts:1-60

格式方面,@membook/[email protected] 引入了 memfile 版本的"写半边"机制: parseMemfile 现在会报告磁盘上 Memfile.version 声明的版本,使得 MCP 服务器写入的 memfile 与 CLI 读出的 memfile 在版本字段上自动对齐,为后续 v2 升级路径奠定基础。资料来源:packages/spec/src/index.ts:1-60

至此,MCP 服务器与 CLI 在 membook 中构成了"双表面、单内核"的格局:任何一端的演进都必须同步到另一端,并由 spec / core 包作为唯一仲裁者。

概述

membook CLI 是仓库中面向人类操作者的"工作面"，与面向 AI 代理的 @membook/mcp MCP 服务器形成对照。它封装了 @membook/core 与 @membook/spec 的核心能力（记忆存储、解析、校验、版本协商），通过一组以动词命名的子命令，让用户从命令行直接驱动原本由 LLM 触发的记忆生命周期。

资料来源：packages/cli/src/cli.ts:1-80

CLI 入口 cli.ts 负责解析全局选项（如 --version、仓库根目录），并按子命令名称分发到 packages/cli/src/commands/ 下的独立模块。每个命令文件自身只负责参数解析、调用核心库以及格式化输出，保持职责单一。

子命令清单

CLI 在 v0.1.0 首次引入时已提供完整的七个命令，构成一个最小但闭合的人类工作流：

资料来源：packages/cli/src/commands/init.ts:1-40、packages/cli/src/commands/status.ts:1-30、packages/cli/src/commands/verify.ts:1-30、packages/cli/src/commands/review.ts:1-30、packages/cli/src/commands/remember.ts:1-30、packages/cli/src/commands/book.ts:1-30、packages/cli/src/commands/reindex.ts:1-30

输出层统一收敛到 packages/cli/src/output.ts，避免每个命令各自实现打印逻辑，便于保持表格、颜色与错误信息的风格一致。资料来源：packages/cli/src/output.ts:1-40

`review` 命令的交互行为

review 是 CLI 中最具交互性的命令。v0.1.1 引入的两项关键改进决定了它的实际手感：

1. 正文重排（re-flow）：在显示之前，命令会对硬换行（hard-wrapped）的记忆正文重新按当前终端宽度排版，避免因早期写入时设定的行宽导致阅读错位。资料来源：packages/cli/src/commands/review.ts:40-90
2. 输入再问（re-ask）：当用户在审阅中给出无法识别的指令时，命令不会直接失败，而是再次发起提示，把未知输入留给用户重新输入。这一行为与核心层"模型可能失效但不应销毁数据"的原则一致——LLM 在 @membook/core 中的 invalidate 复核结果会被降级为 stale 而非删除。资料来源：packages/cli/src/commands/review.ts:90-140

这一设计让 review 既能展示记忆，又能承载"在不确定中保持可逆"的工作流。

版本号与 Memfile 版本协商

CLI 的对外版本号不再硬编码。自 v0.1.2 起，membook --version 在运行时读取 packages/cli/package.json 中的 version 字段并打印，确保发布产物与代码同步。资料来源：packages/cli/src/commands/misc.ts:1-40、packages/cli/package.json:1-20

在记忆文件层面，v0.2.0 落地了 memfile 版本机制的"写入半边"：parseMemfile 现在会报告磁盘上文件所声明的版本（Memfile.version），CLI 可以在写入新记忆时把当前 schema 版本号一并落盘，从而与读取端的解析保持一致。该改动合并到 @membook/[email protected] 与 @membook/[email protected]，并作为 @membook/[email protected] 的依赖更新被传递。资料来源：packages/cli/src/commands/remember.ts:30-80

典型工作流

flowchart LR
    A[init] --> B[remember / MCP 写入]
    B --> C[status 巡检]
    C --> D{需要复盘?}
    D -- 是 --> E[review 交互修订]
    D -- 否 --> F[verify 校验]
    E --> F
    F --> G[reindex 重建索引]
    G --> H[book 归档]

整个流程从 init 建立仓库开始，经由 remember（或 MCP 服务器写入）积累记忆，再以 status 与 verify 做常规体检；review 在人工介入时提供可逆的修订通道，reindex 与 book 则用于结构性维护与归档。资料来源：packages/cli/src/cli.ts:80-140

这种"以动词为主、命令间相互独立、共享同一核心层与输出层"的组织方式，使得 CLI 既可以作为人类独立使用的工具，又能在代理驱动的 MCP 流程之外承担兜底人工操作的角色。

概览

"提炼与种子化"是 membook 在 @membook/core 包中提供的两条互为补充的 LLM 驱动管线，用于在 Memfile 与 模型状态 之间搬运结构化记忆：

• 提炼（Distill）：将原始文本（对话、笔记、文档片段）压缩成可索引、可校验的"记忆条目"。
• 种子化（Seed）：从已存在的记忆库中抽取代表性样本，作为冷启动或迁移场景下的初始记忆集。

两条管线共享同一套 provider 抽象与 prompt 模板，并通过 scripts/backtest.mjs 进行回测评估。资料来源：packages/core/src/distill.ts、packages/core/src/seed.ts、packages/core/src/provider.ts

提炼（Distill）

提炼入口位于 packages/core/src/distill.ts，对应 prompt 模板为 prompts/distill.md。其职责是把非结构化输入转化为符合 Memfile 规范的条目。

• 输入：任意长度的原文（通常由 membook remember 收集）。
• 输出：带有标题、正文、标签与来源指针的记忆条目。
• 流程：

1. 调用 provider.ts 中暴露的 LLM provider 获取补全。
2. 按 prompts/distill.md 的指令，要求模型输出去重、去冗余的条目。
3. 将模型产物解析后写入 Memfile，沿用 Memfile.version 字段以兼容 v0.2.0 的版本机读。资料来源：packages/core/src/distill.ts、prompts/distill.md

设计约束：模型可以失败，但不能破坏。这与 0.1.1 发布的"invalidate 落到 stale"策略一致——提炼失败时，原有 Memfile 不会被覆盖，仅做标记。资料来源：[email protected] release notes

种子化（Seed）

种子化入口位于 packages/core/src/seed.ts，对应 prompt 模板为 prompts/seed.md。它用于从一个已有 Memfile 中抽取而非"凭空生成"记忆种子。

• 典型场景：新建仓库后 membook init、跨设备迁移、回测离线评估。
• 行为：扫描源 Memfile，按代表性（覆盖主题广度、避免冗余）筛选若干条目，导出为最小可用的种子文件。
• 与提炼的区别：提炼是"由文到条"，种子化是"由条到条"。两者共享 provider，但 prompt 目标截然不同。资料来源：packages/core/src/seed.ts、prompts/seed.md

共享基础设施与回测

provider.ts 是提炼与种子化的共同依赖：它封装了模型调用、重试与版本协商，使两条管线在切换底层模型时不需要改动业务代码。资料来源：packages/core/src/provider.ts

scripts/backtest.mjs 提供离线评估手段：在历史 Memfile 上重放提炼与种子化，对比输出与预期，从而判断 prompt 调整是否引入了退化。该脚本与 CLI 命令 verify 协同工作，是 membook 在 0.1.0 发布时引入的人类侧表面的一部分。资料来源：scripts/backtest.mjs、[email protected] release notes

下表汇总两条管线的关键差异：

设计目标与作用范围

membook 把记忆条目以 Memfile 形式落盘，并通过 reindex 进入向量索引，供后续 review / book / MCP 工具调用检索。一旦真实凭据（API key、token、私钥、password）被无意写入记忆库，就会在检索向量中被长期保留，形成"自建泄漏面"。

密钥扫描与防护 子系统在 @membook/core 内部以两道关卡拦截该风险：

• 写入侧：在 remember / book 等命令落盘前对正文做检测；
• 读取侧：在 verify / review / reindex 阶段对既有 Memfile 做回扫。

资料来源：packages/core/src/secret-scan.ts

扫描器：secret-scan

secret-scan.ts 提供纯函数式检测原语，被描述为"可复用的检测器"。它接收文本或记忆条目，输出命中列表（规则 ID、偏移量、建议处理方式）。规则集合覆盖常见凭据形态：高熵随机串、典型厂商前缀、JWT 结构、PEM 块等。

设计上保持 core-only 依赖：扫描器不直接读写磁盘，不耦合 CLI 或 MCP 工具，便于在 guard、测试以及未来的第三方集成中复用。

flowchart LR
  A[remember / book] --> B[guard 包装]
  M[MCP tool handler] --> B
  B --> C[secret-scan]
  C -->|命中| D{策略判定}
  D -->|strict| E[拒绝写入]
  D -->|warn| F[标记 + 继续]
  C -->|未命中| G[写入 Memfile]
  G --> H[verify 回扫]
  H -->|历史命中| I[review 裁定]
  I --> J[reindex 重建索引]

资料来源：packages/core/src/secret-scan.ts、packages/core/src/guard.ts

守门策略：guard

guard.ts 是策略层，把扫描器与命令生命周期粘合起来。它同时被人类侧 CLI（packages/cli）和 agent 侧 MCP server（@membook/mcp）调用，保证 agent 不会绕过 CLI 单独写入命中体。

默认策略是 fail-closed：未通过扫描的条目不会写入；存在宽松模式以便开发态调试。guard 的判定结果会回传给调用方，使 membook status 能在摘要里报告扫描活动。

资料来源：packages/core/src/guard.ts

测试样本：fake-secrets

fake-secrets.ts 提供带有固定前缀和可控校验位的伪密钥样本，仅用于测试。它驱动的回归点至少包括：

• 扫描器对各家族命中的召回率；
• guard 在 strict / warn 模式下的分支；
• 脱敏后字符串仍能被 parseMemfile 解析回读。

社区在 [email protected] 修复的 review 回流与未识别输入重问行为，也是用这些稳定样本做回归，避免与真实凭据形态脱钩。

资料来源：packages/core/src/fake-secrets.ts

公开策略与上报

SECURITY.md 声明威胁模型、支持版本、披露窗口与上报渠道。它推荐的标准处置流程是：membook verify 定位命中 → membook review 逐条裁定 → membook reindex 重建索引，避免旧向量残留。该流程与 parseMemfile 在 [email protected] 升级后的版本读取能力相配合，确保历史回扫结果可被正确解析。

资料来源：SECURITY.md

与其它子系统的耦合

下表列出主要耦合点，便于排查相关改动：

资料来源：packages/core/src/index.ts、packages/spec/src/index.ts

概览

在 membook 中，"索引、迁移与 MEMBOOK 生成" 是 @membook/core 与 @membook/cli 中三个紧密关联的功能模块，分别对应工作区数据结构的刷新、跨版本演进以及面向人类与代理的可读文档输出。CLI 子命令 reindex、migrate 与 book 是它们的人类入口，而 MCP 服务器则暴露对应的代理入口。

资料来源：MEMBOOK.md:1-40

索引重建（reindex）

packages/core/src/reindex.ts 负责在已存在的 Memfile 工作区内，根据当前磁盘上的 memory 条目重新构建派生索引。该步骤典型场景包括：手动编辑 memfile 后、引入新的标签规则后，或迁移之后希望让索引与原文保持严格一致。

CLI 中由 packages/cli/src/commands/misc.ts 中的 reindex 子命令包装。当 membook reindex 被调用时，它读取本地 Memfile 解析出的数据流，把每条 memory 重新打散为可检索单元，并写回 .membook/ 下的派生文件。原 memory 条目的正本（canonical body）在此过程中不会被破坏，因此 reindex 是一种"安全可重试"的操作。

资料来源：packages/core/src/reindex.ts:1-60

迁移与版本管理（migrate）

packages/core/src/migrate.ts 实现跨 Memfile 格式版本的迁移逻辑。@membook/[email protected] 引入了"读取侧"的版本号声明：解析器现在会报告磁盘文件声明的 schema 版本，并由核心在启动或写入时进行一致性检查。

迁移原则遵循"A model may fail to restore, but it may not destroy"（在 @membook/[email protected] 释出时被明确提出）：当 LLM 的复审或迁移可能造成数据丢失时，宁可将其结果标记为 stale 而非 invalidate。该原则同样适用于迁移路径——目标版本无法 100% 还原的字段不应被静默删除，而应进入待人工裁定的状态。

docs/design/v0.2-workspaces.md 描述了工作区升级时的回滚语义：在升级前会先冻结当前 Memfile 的哈希，以便需要时回退。

资料来源：packages/core/src/migrate.ts:1-80 资料来源：docs/design/v0.2-workspaces.md:1-60

MEMBOOK 生成（book）

packages/core/src/book.ts 把工作区中的精选 memory 聚合为单文件 MEMBOOK.md，作为面向人类阅读者的"知识手册"。其生成过程如下：

CLI 命令 membook book 触发该流程；该功能在 [email protected] 首发。生成的 MEMBOOK.md 同时会被纳入版本控制，使得仓库审阅者能在不安装 membook 工具链的情况下查阅项目的长期记忆。

资料来源：packages/core/src/book.ts:1-120 资料来源：packages/cli/src/commands/misc.ts:1-40

三者协作关系

reindex、migrate 与 book 构成一条流水线：当用户编辑或迁移 memfile 后，建议先执行 membook reindex 以同步派生索引；若 schema 跨越版本边界，则先运行 membook migrate，再 reindex；最后通过 membook book 重新生成人类可读的 MEMBOOK.md。@membook/mcp 中的代理工具同样遵循这一顺序，从而保证代理与人类在同一种"记忆视图"下协作。

资料来源：MEMBOOK.md:30-80 资料来源：packages/cli/src/commands/misc.ts:40-100

工具链与开发环境

membook 的运行时版本被严格锁定在单一来源，避免在多个包中重复硬编码字符串。仓库使用 .nvmrc 文件记录项目要求的 Node.js 主版本，开发者可通过 nvm use 切换；同时提供 mise.toml 以兼容使用 mise（前身 rtx）管理多语言工具链的贡献者 资料来源：.nvmrc:1-1 资料来源：mise.toml:1-1。

这一双轨制（nvm + mise）使得无论团队成员偏好哪类版本管理器，CI 与本地环境都能对齐到同一 Node.js 版本，从而避免"在我机器上能跑"的常见问题。

变更与发布流程

membook 采用 monorepo 布局，由 membook（CLI 门面）、@membook/core、@membook/spec、@membook/mcp 四个包组成，并通过 Changesets 驱动版本号与发布说明 资料来源：docs/releasing.md:1-1。

发布流程的关键约定如下：

版本号不再在源码中硬编码，而是从 package.json 在运行时读取；这意味着 PR #22 修复后，membook --version（CLI）以及 SERVER_VERSION（MCP 服务器）始终反映已发布包的真实版本号 资料来源：[email protected] 资料来源：@membook/[email protected]。

变更说明遵循 Changesets 规范——次要变更以 ### Minor Changes 标记，补丁以 ### Patch Changes 标记，并在同一标题下列出关联提交哈希与贡献者致谢。例如 [email protected] 与 @membook/[email protected] 同步在 PR #28 中引入"memfile 版本写半边"机制，parseMemfile 现可报告磁盘上文件声明的 Memfile.version 资料来源：[email protected]。

自家使用（Dogfooding）

docs/dogfood.md 记录了 membook 团队如何将自家产品用于自身记忆管理。这一"吃自己的狗粮"实践既是产品的真实场景验证，也是新功能的首批用户 资料来源：docs/dogfood.md:1-1。

从社区上下文可推断，该实践与 CLI 的 membook review 紧密相关——PR #20 改进了 membook review 的文本回流（reflow）行为，使得维护者在浏览硬换行的记忆正文时获得更佳阅读体验，并在遇到未识别的输入时主动重新询问 资料来源：[email protected]。这表明 dogfooding 反馈直接驱动了 UX 改进。

发布后脚本与平台适配

scripts/post-public-setup.sh 提供仓库对外公开后的一次性初始化脚本，常见用途包括：调整可见性配置、刷新依赖锁文件、或在 fork 场景下重置自动化令牌 资料来源：scripts/post-public-setup.sh:1-1。

平台适配方面，membook 的 MCP 服务器通过 @modelcontextprotocol/sdk 与支持 MCP 协议的客户端（如 Claude Desktop）通信；CLI 则通过 node 直接执行，跨 macOS、Linux 与 Windows 平台。这种"一份配置，多端运行"的部署模型，配合上述工具链与发布流程，使项目的运维成本被压缩到最小。

flowchart LR
    A[PR 提交 changeset] --> B[合并到 main]
    B --> C[Changesets 自动版本 PR]
    C --> D[合并版本 PR]
    D --> E[CI 发布到 npm]
    E --> F[运行时读取 package.json 版本]
    F --> G[CLI / MCP 服务器报告真实版本]

总结

membook 的运维体系围绕三个核心轴构建：确定性（.nvmrc + mise.toml 锁定运行时）、可追溯性（Changesets 把每次发布与具体 PR/提交关联）、真实使用（dogfooding 让团队成为首批使用者）。这三者共同保证 CLI 与 MCP 服务器在不同平台上报告的版本号始终与 package.json 一致，避免出现"发布版本与运行版本漂移"的运维事故。

Pitfall Log / 踩坑日志

项目：getmembook/membook

摘要：发现 17 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：配置坑 - 可能修改宿主 AI 配置。

1. 配置坑 · 可能修改宿主 AI 配置

• 严重度：medium
• 证据强度：source_linked
• 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
• 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
• 证据：capability.host_targets | https://github.com/getmembook/membook | host_targets=mcp_host, claude, claude_code

2. 配置坑 · 失败模式：configuration: [email protected]

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: [email protected]
• 对用户的影响：Upgrade or migration may change expected behavior: [email protected]
• 证据：failure_mode_cluster:github_release | https://github.com/getmembook/membook/releases/tag/membook%400.1.0 | [email protected]

3. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 证据：capability.assumptions | https://github.com/getmembook/membook | README/documentation is current enough for a first validation pass.

4. 运行坑 · 失败模式：runtime: @membook/[email protected]

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this runtime risk before relying on the project: @membook/[email protected]
• 对用户的影响：Upgrade or migration may change expected behavior: @membook/[email protected]
• 证据：failure_mode_cluster:github_release | https://github.com/getmembook/membook/releases/tag/%40membook/mcp%400.1.2 | @membook/[email protected]

5. 运行坑 · 失败模式：runtime: [email protected]

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this runtime risk before relying on the project: [email protected]
• 对用户的影响：Upgrade or migration may change expected behavior: [email protected]
• 证据：failure_mode_cluster:github_release | https://github.com/getmembook/membook/releases/tag/membook%400.1.2 | [email protected]

6. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 证据：evidence.maintainer_signals | https://github.com/getmembook/membook | last_activity_observed missing

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | https://github.com/getmembook/membook | no_demo; severity=medium

8. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 证据：risks.scoring_risks | https://github.com/getmembook/membook | no_demo; severity=medium

9. 运行坑 · 失败模式：performance: @membook/[email protected]

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this performance risk before relying on the project: @membook/[email protected]
• 对用户的影响：Upgrade or migration may change expected behavior: @membook/[email protected]
• 证据：failure_mode_cluster:github_release | https://github.com/getmembook/membook/releases/tag/%40membook/core%400.1.1 | @membook/[email protected]

10. 运行坑 · 失败模式：performance: @membook/[email protected]

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this performance risk before relying on the project: @membook/[email protected]
• 对用户的影响：Upgrade or migration may change expected behavior: @membook/[email protected]
• 证据：failure_mode_cluster:github_release | https://github.com/getmembook/membook/releases/tag/%40membook/core%400.2.0 | @membook/[email protected]

11. 运行坑 · 失败模式：performance: @membook/[email protected]

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this performance risk before relying on the project: @membook/[email protected]
• 对用户的影响：Upgrade or migration may change expected behavior: @membook/[email protected]
• 证据：failure_mode_cluster:github_release | https://github.com/getmembook/membook/releases/tag/%40membook/spec%400.2.0 | @membook/[email protected]

12. 运行坑 · 失败模式：performance: [email protected]

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this performance risk before relying on the project: [email protected]
• 对用户的影响：Upgrade or migration may change expected behavior: [email protected]
• 证据：failure_mode_cluster:github_release | https://github.com/getmembook/membook/releases/tag/membook%400.1.1 | [email protected]

13. 运行坑 · 失败模式：performance: [email protected]

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this performance risk before relying on the project: [email protected]
• 对用户的影响：Upgrade or migration may change expected behavior: [email protected]
• 证据：failure_mode_cluster:github_release | https://github.com/getmembook/membook/releases/tag/membook%400.2.0 | [email protected]

14. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 证据：evidence.maintainer_signals | https://github.com/getmembook/membook | issue_or_pr_quality=unknown

15. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 证据：evidence.maintainer_signals | https://github.com/getmembook/membook | release_recency=unknown

16. 维护坑 · 失败模式：maintenance: @membook/[email protected]

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this maintenance risk before relying on the project: @membook/[email protected]
• 对用户的影响：Upgrade or migration may change expected behavior: @membook/[email protected]
• 证据：failure_mode_cluster:github_release | https://github.com/getmembook/membook/releases/tag/%40membook/mcp%400.1.1 | @membook/[email protected]

17. 维护坑 · 失败模式：maintenance: @membook/[email protected]

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this maintenance risk before relying on the project: @membook/[email protected]
• 对用户的影响：Upgrade or migration may change expected behavior: @membook/[email protected]
• 证据：failure_mode_cluster:github_release | https://github.com/getmembook/membook/releases/tag/%40membook/mcp%400.1.3 | @membook/[email protected]