# https://github.com/getmembook/membook 项目说明书

生成时间：2026-07-26 21:37:02 UTC

## 目录

- [项目概述：可验证的记忆](#page-1)
- [整体架构与包结构](#page-2)
- [Memfile 格式规范](#page-3)
- [验证循环与锚点](#page-4)
- [存储与数据模型](#page-5)
- [召回与搜索](#page-6)
- [MCP 服务器与代理集成](#page-7)
- [CLI 命令与人类工作流](#page-8)
- [提炼与种子化](#page-9)
- [密钥扫描与防护](#page-10)
- [索引、迁移与 MEMBOOK 生成](#page-11)
- [运维、测试与平台支持](#page-12)

<a id='page-1'></a>

## 项目概述：可验证的记忆

### 相关页面

相关主题：[整体架构与包结构](#page-2), [验证循环与锚点](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/getmembook/membook/blob/main/README.md)
- [MEMBOOK.md](https://github.com/getmembook/membook/blob/main/MEMBOOK.md)
- [docs/concept.md](https://github.com/getmembook/membook/blob/main/docs/concept.md)
- [CLAUDE.md](https://github.com/getmembook/membook/blob/main/CLAUDE.md)
- [package.json](https://github.com/getmembook/membook/blob/main/package.json)
- [packages/spec/package.json](https://github.com/getmembook/membook/blob/main/packages/spec/package.json)
- [packages/core/package.json](https://github.com/getmembook/membook/blob/main/packages/core/package.json)
- [packages/mcp/package.json](https://github.com/getmembook/membook/blob/main/packages/mcp/package.json)
- [packages/cli/index.ts](https://github.com/getmembook/membook/blob/main/packages/cli/index.ts)
</details>

# 项目概述：可验证的记忆

## 一、定位与设计哲学

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 | 面向人类：提供 `init`、`status`、`verify`、`review`、`remember`、`book`、`reindex` 等命令 |
| `@membook/mcp` | MCP Server | 面向代理：暴露模型上下文协议工具，作为代理的读写入口 |
| `@membook/core` | 核心库 | 记忆的索引、检索、校验、状态机等核心算法 |
| `@membook/spec` | 规范库 | memfile 的语法、版本号、字段约束等契约定义 |

`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]()

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

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

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

---

<a id='page-2'></a>

## 整体架构与包结构

### 相关页面

相关主题：[Memfile 格式规范](#page-3), [MCP 服务器与代理集成](#page-7), [CLI 命令与人类工作流](#page-8)

>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [pnpm-workspace.yaml](https://github.com/getmembook/membook/blob/main/pnpm-workspace.yaml)
- [package.json](https://github.com/getmembook/membook/blob/main/package.json)
- [tsconfig.base.json](https://github.com/getmembook/membook/blob/main/tsconfig.base.json)
- [packages/spec/src/index.ts](https://github.com/getmembook/membook/blob/main/packages/spec/src/index.ts)
- [packages/core/src/index.ts](https://github.com/getmembook/membook/blob/main/packages/core/src/index.ts)
- [packages/mcp/src/index.ts](https://github.com/getmembook/membook/blob/main/packages/mcp/src/index.ts)
- [packages/cli/src/index.ts](https://github.com/getmembook/membook/blob/main/packages/cli/src/index.ts)
- [.changeset/config.json](https://github.com/getmembook/membook/blob/main/.changeset/config.json)
</details>

# 整体架构与包结构

## 项目总览

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/spec@0.2.0 |
| `@membook/core` | 解析、校验、编/解码、索引、模型打分 | @membook/core@0.2.0 |
| `@membook/mcp` | 面向 Agent 的 MCP 服务端 | @membook/mcp@0.1.3 |
| `membook` | 面向人类的 CLI 入口 | membook@0.2.0 |

`@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]()`

```mermaid
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/mcp@0.1.3` 则作为 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]()`

---

<a id='page-3'></a>

## Memfile 格式规范

### 相关页面

相关主题：[验证循环与锚点](#page-4), [存储与数据模型](#page-5), [索引、迁移与 MEMBOOK 生成](#page-11)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [packages/spec/README.md](https://github.com/getmembook/membook/blob/main/packages/spec/README.md)
- [packages/core/src/membook.ts](https://github.com/getmembook/membook/blob/main/packages/core/src/membook.ts)
- [packages/core/src/migrate.ts](https://github.com/getmembook/membook/blob/main/packages/core/src/migrate.ts)
- [packages/core/src/parseMemfile.ts](https://github.com/getmembook/membook/blob/main/packages/core/src/parseMemfile.ts)
- [.membook/memories/m-6f7c.mem.md](https://github.com/getmembook/membook/blob/main/.membook/memories/m-6f7c.mem.md)
- [packages/spec/src/index.ts](https://github.com/getmembook/membook/blob/main/packages/spec/src/index.ts)
- [packages/cli/src/commands/init.ts](https://github.com/getmembook/membook/blob/main/packages/cli/src/commands/init.ts)
</details>

# Memfile 格式规范

`Memfile` 是 membook 系统用于在磁盘上持久化记忆（memory）的标准文件格式。它是一种轻量的、人类可读的 Markdown 变体，扩展了 YAML 风格的 frontmatter，用于携带结构化元数据并保留可读的正文内容。本页说明其文件组织、字段语义以及自 0.2.0 起引入的版本声明机制。

## 1. 文件组织与命名约定

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

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

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

## 2. 文件结构

每个 Memfile 由两个部分组成：

| 区域 | 内容 | 作用 |
|------|------|------|
| Frontmatter | YAML 风格的键值块，包裹在 `---` 分隔符之间 | 携带结构化元数据（id、创建时间、标签、版本等） |
| Body | Markdown 正文 | 记忆的实际内容（可被 `membook review` 等命令重新流式排版） |

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

```mermaid
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 引入）

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

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

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

资料来源：[membook@0.2.0 发布说明](https://github.com/getmembook/membook/releases/tag/membook%400.2.0)、[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`，读取端才能据此判断是否需要升级

资料来源：[membook@0.1.1 发布说明](https://github.com/getmembook/membook/releases/tag/membook%400.1.1)、[packages/core/src/membook.ts]()

> 本页基于 membook@0.2.0 发布节点编写；后续若 `Memfile.version` 引入 v2 字段，将通过 `migrate.ts` 提供升级路径。

---

<a id='page-4'></a>

## 验证循环与锚点

### 相关页面

相关主题：[Memfile 格式规范](#page-3), [提炼与种子化](#page-9), [密钥扫描与防护](#page-10)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [packages/core/src/verify.ts](https://github.com/getmembook/membook/blob/main/packages/core/src/verify.ts)
- [packages/core/src/recheck.ts](https://github.com/getmembook/membook/blob/main/packages/core/src/recheck.ts)
- [packages/core/src/llm-recheck.ts](https://github.com/getmembook/membook/blob/main/packages/core/src/llm-recheck.ts)
- [packages/core/src/git.ts](https://github.com/getmembook/membook/blob/main/packages/core/src/git.ts)
- [packages/core/src/git-fixture.ts](https://github.com/getmembook/membook/blob/main/packages/core/src/git-fixture.ts)
- [packages/core/src/parse-memfile.ts](https://github.com/getmembook/membook/blob/main/packages/core/src/parse-memfile.ts)
- [prompts/recheck.md](https://github.com/getmembook/membook/blob/main/prompts/recheck.md)
- [packages/cli/src/commands/verify.ts](https://github.com/getmembook/membook/blob/main/packages/cli/src/commands/verify.ts)
</details>

# 验证循环与锚点

## 概述

`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]()

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

| 来源 | 原始判定 | 落盘状态 | 后续动作 |
| --- | --- | --- | --- |
| 结构校验 | 缺字段 / 引用断裂 | `broken` | 由 `review` 命令要求人工修正 |
| 外部证据 | 锚点提交丢失或被改写 | `stale` | 进入 `recheck` 队列等待 LLM 再判 |
| LLM 复核 | `invalidate` | `stale`（降级） | 进入 `review` 队列等待人类决定 |
| 全部通过 | — | `valid` | 维持原状，不做任何写入 |

## 锚点与持久化

锚点（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 拥有「长期、可信、可审计」记忆能力的基础设施层。

---

<a id='page-5'></a>

## 存储与数据模型

### 相关页面

相关主题：[Memfile 格式规范](#page-3), [召回与搜索](#page-6), [索引、迁移与 MEMBOOK 生成](#page-11)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- 资料来源： [packages/core/src/store.ts](https://github.com/getmembook/membook/blob/main/packages/core/src/store.ts)
- 资料来源： [packages/core/src/index-db.ts](https://github.com/getmembook/membook/blob/main/packages/core/src/index-db.ts)
- 资料来源： [packages/core/src/membook.ts](https://github.com/getmembook/membook/blob/main/packages/core/src/membook.ts)
- 资料来源： [packages/core/src/guard.ts](https://github.com/getmembook/membook/blob/main/packages/core/src/guard.ts)
- 资料来源： [packages/core/src/paths.ts](https://github.com/getmembook/membook/blob/main/packages/core/src/paths.ts)
</details>

相关源码文件</summary>

以下源码文件用于生成本页说明：

- [packages/core/src/types.ts](https://github.com/getmembook/membook/blob/main/packages/core/src/types.ts)
- [packages/core/src/paths.ts](https://github.com/getmembook/membook/blob/main/packages/core/src/paths.ts)
- [packages/core/src/store.ts](https://github.com/getmembook/membook/blob/main/packages/core/src/store.ts)
- [packages/core/src/index-db.ts](https://github.com/getmembook/membook/blob/main/packages/core/src/index-db.ts)
- [packages/core/src/membook.ts](https://github.com/getmembook/membook/blob/main/packages/core/src/membook.ts)
- [packages/core/src/guard.ts](https://github.com/getmembook/membook/blob/main/packages/core/src/guard.ts)
- [packages/spec/src/memfile.ts](https://github.com/getmembook/membook/blob/main/packages/spec/src/memfile.ts)
- [packages/spec/src/parse.ts](https://github.com/getmembook/membook/blob/main/packages/spec/src/parse.ts)
- [packages/spec/src/serialize.ts](https://github.com/getmembook/membook/blob/main/packages/spec/src/serialize.ts)
</details>

# 存储与数据模型

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` 负责写回。

```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/core@0.1.1` 发布说明。

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

## 2. 存储层：Store

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

| 操作 | 含义 | 关键调用 |
| ---- | ---- | -------- |
| `read` | 读取并解析 Memfile，返回 `Memfile` 对象 | 由 `verify` / `review` / `reindex` 触发 |
| `write` | 序列化并原子写回 | 由 `remember` / `book` 触发，落地 `version` 字段 |
| `append` / `update` | 就地变更条目 | 维护 `updatedAt` 并可能将 `status` 切到 `stale` |

写入路径在 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` 只校验一致性，不重新计算。

```ts
// 索引形态（摘要，来自 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/mcp@0.1.3` 升级到对应 `@membook/core@0.2.0` 时正是同步这一层，从而保留 review / reindex 等行为。

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

## 小结

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

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

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

---

<a id='page-6'></a>

## 召回与搜索

### 相关页面

相关主题：[存储与数据模型](#page-5), [MCP 服务器与代理集成](#page-7)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- 资料来源： [packages/core/src/recall.ts](https://github.com/getmembook/membook/blob/main/packages/core/src/recall.ts)
- 资料来源： [packages/core/src/search.ts](https://github.com/getmembook/membook/blob/main/packages/core/src/search.ts)
- 资料来源： [packages/core/src/book.ts](https://github.com/getmembook/membook/blob/main/packages/core/src/book.ts)
- 资料来源： [scripts/query-replay.mjs](https://github.com/getmembook/membook/blob/main/scripts/query-replay.mjs)
- 资料来源： [scripts/calibrate.mjs](https://github.com/getmembook/membook/blob/main/scripts/calibrate.mjs)
</details>

以下源码文件用于生成本页说明：

- [packages/core/src/recall.ts](https://github.com/getmembook/membook/blob/main/packages/core/src/recall.ts)
- [packages/core/src/search.ts](https://github.com/getmembook/membook/blob/main/packages/core/src/search.ts)
- [packages/core/src/book.ts](https://github.com/getmembook/membook/blob/main/packages/core/src/book.ts)
- [scripts/query-replay.mjs](https://github.com/getmembook/membook/blob/main/scripts/query-replay.mjs)
- [scripts/calibrate.mjs](https://github.com/getmembook/membook/blob/main/scripts/calibrate.mjs)
</details>

# 召回与搜索

## 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 共享同一调用路径。

```mermaid
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` 中被识别的未知输入），搜索层会触发再询问而非抛错。

| 入口 | 调用方 | 用途 |
| --- | --- | --- |
| `membook review` | CLI（人类） | 浏览与确认记忆 |
| `search_memories` | MCP（Agent） | 按需调用 |
| `reindex` | CLI | 触发召回底层重建 |

资料来源：[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]()

---

<a id='page-7'></a>

## MCP 服务器与代理集成

### 相关页面

相关主题：[整体架构与包结构](#page-2), [CLI 命令与人类工作流](#page-8), [密钥扫描与防护](#page-10)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [packages/mcp/src/server.ts](https://github.com/getmembook/membook/blob/main/packages/mcp/src/server.ts)
- [packages/mcp/src/index.ts](https://github.com/getmembook/membook/blob/main/packages/mcp/src/index.ts)
- [packages/mcp/src/cli.ts](https://github.com/getmembook/membook/blob/main/packages/mcp/src/cli.ts)
- [packages/mcp/README.md](https://github.com/getmembook/membook/blob/main/packages/mcp/README.md)
- [packages/mcp/package.json](https://github.com/getmembook/membook/blob/main/packages/mcp/package.json)
- [packages/cli/src/commands/hook.ts](https://github.com/getmembook/membook/blob/main/packages/cli/src/commands/hook.ts)
- [packages/core/src/index.ts](https://github.com/getmembook/membook/blob/main/packages/core/src/index.ts)
- [packages/spec/src/index.ts](https://github.com/getmembook/membook/blob/main/packages/spec/src/index.ts)
</details>

# MCP 服务器与代理集成

## 概述与设计目标

`@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/mcp@0.1.3` 即随 `@membook/spec@0.2.0` 与 `@membook/core@0.2.0` 一起发布。资料来源:[packages/mcp/package.json:1-40]()

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

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

| CLI 命令 | MCP 工具意图 | 作用 |
| --- | --- | --- |
| `membook init` | `init` | 在仓库根初始化 `.membook/` 目录 |
| `membook status` | `status` | 报告当前 memfile 的健康度与版本 |
| `membook verify` | `verify` | 校验记忆条目是否被外部篡改 |
| `membook review` | `review` | 列出待人工裁决的 `stale` 条目 |
| `membook remember` | `remember` | 写入或更新一条记忆 |
| `membook book` | `book` | 把候选条目正式落盘归档 |
| `membook reindex` | `reindex` | 重建搜索/检索索引 |

代理在会话中不需要也不应该直接调用 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/mcp@0.1.2` 起,该字段不再硬编码字符串,而是在运行时从 `package.json` 读取——这意味着已发布的包与本地构建的版本号永远与元数据一致,代理与运维人员看到的"它自称什么版本"具有唯一信源。资料来源:[packages/mcp/src/server.ts:40-80]()

## 与 CLI 的一致性约束

CLI 与 MCP 共享的不仅是存储,还有错误语义。例如,当 LLM 在复核阶段给出 `invalidate` 裁决时,`@membook/core@0.1.1` 之后会将其落为 `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/spec@0.2.0` 引入了 memfile 版本的"写半边"机制: `parseMemfile` 现在会报告磁盘上 `Memfile.version` 声明的版本,使得 MCP 服务器写入的 memfile 与 CLI 读出的 memfile 在版本字段上自动对齐,为后续 v2 升级路径奠定基础。资料来源:[packages/spec/src/index.ts:1-60]()

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

---

<a id='page-8'></a>

## CLI 命令与人类工作流

### 相关页面

相关主题：[MCP 服务器与代理集成](#page-7), [提炼与种子化](#page-9), [索引、迁移与 MEMBOOK 生成](#page-11)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [packages/cli/src/cli.ts](https://github.com/getmembook/membook/blob/main/packages/cli/src/cli.ts)
- [packages/cli/src/commands/init.ts](https://github.com/getmembook/membook/blob/main/packages/cli/src/commands/init.ts)
- [packages/cli/src/commands/status.ts](https://github.com/getmembook/membook/blob/main/packages/cli/src/commands/status.ts)
- [packages/cli/src/commands/verify.ts](https://github.com/getmembook/membook/blob/main/packages/cli/src/commands/verify.ts)
- [packages/cli/src/commands/review.ts](https://github.com/getmembook/membook/blob/main/packages/cli/src/commands/review.ts)
- [packages/cli/src/commands/remember.ts](https://github.com/getmembook/membook/blob/main/packages/cli/src/commands/remember.ts)
- [packages/cli/src/commands/book.ts](https://github.com/getmembook/membook/blob/main/packages/cli/src/commands/book.ts)
- [packages/cli/src/commands/reindex.ts](https://github.com/getmembook/membook/blob/main/packages/cli/src/commands/reindex.ts)
- [packages/cli/src/commands/misc.ts](https://github.com/getmembook/membook/blob/main/packages/cli/src/commands/misc.ts)
- [packages/cli/src/output.ts](https://github.com/getmembook/membook/blob/main/packages/cli/src/output.ts)
- [packages/cli/package.json](https://github.com/getmembook/membook/blob/main/packages/cli/package.json)
</details>

# CLI 命令与人类工作流

## 概述

`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 首次引入时已提供完整的七个命令，构成一个最小但闭合的人类工作流：

| 命令 | 用途 | 典型使用场景 |
| --- | --- | --- |
| `init` | 在当前目录初始化一个 membook 仓库 | 新建项目时一次性引导 |
| `status` | 查看记忆库整体状态、计数、索引健康度 | 日常巡检 |
| `verify` | 对记忆文件做结构与一致性校验 | 提交前、CI 中 |
| `review` | 交互式审阅记忆正文，并就地修订 | 周期性人工复盘 |
| `remember` | 主动写入一条新记忆，跳过 LLM 路径 | 手动补充关键事实 |
| `book` | 归档或翻阅历史记忆条目 | 回溯与导出 |
| `reindex` | 重建内部索引（如时间线、标签） | 大批量编辑之后 |

资料来源：[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/spec@0.2.0` 与 `@membook/core@0.2.0`，并作为 `@membook/mcp@0.1.3` 的依赖更新被传递。资料来源：[packages/cli/src/commands/remember.ts:30-80]()

## 典型工作流

```mermaid
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 流程之外承担兜底人工操作的角色。

---

<a id='page-9'></a>

## 提炼与种子化

### 相关页面

相关主题：[验证循环与锚点](#page-4), [CLI 命令与人类工作流](#page-8)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [packages/core/src/distill.ts](https://github.com/getmembook/membook/blob/main/packages/core/src/distill.ts)
- [packages/core/src/seed.ts](https://github.com/getmembook/membook/blob/main/packages/core/src/seed.ts)
- [packages/core/src/provider.ts](https://github.com/getmembook/membook/blob/main/packages/core/src/provider.ts)
- [prompts/distill.md](https://github.com/getmembook/membook/blob/main/prompts/distill.md)
- [prompts/seed.md](https://github.com/getmembook/membook/blob/main/prompts/seed.md)
- [scripts/backtest.mjs](https://github.com/getmembook/membook/blob/main/scripts/backtest.mjs)
</details>

# 提炼与种子化

## 概览

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

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

两条管线共享同一套 provider 抽象与 prompt 模板，并通过 `scripts/backtest.mjs` 进行回测评估。资料来源：[packages/core/src/distill.ts](https://github.com/getmembook/membook/blob/main/packages/core/src/distill.ts)、[packages/core/src/seed.ts](https://github.com/getmembook/membook/blob/main/packages/core/src/seed.ts)、[packages/core/src/provider.ts](https://github.com/getmembook/membook/blob/main/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](https://github.com/getmembook/membook/blob/main/packages/core/src/distill.ts)、[prompts/distill.md](https://github.com/getmembook/membook/blob/main/prompts/distill.md)

> 设计约束：**模型可以失败，但不能破坏**。这与 0.1.1 发布的"invalidate 落到 stale"策略一致——提炼失败时，原有 Memfile 不会被覆盖，仅做标记。资料来源：[membook@0.1.1 release notes](https://github.com/getmembook/membook/releases/tag/membook%400.1.1)

## 种子化（Seed）

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

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

## 共享基础设施与回测

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

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

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

| 维度 | 提炼（Distill） | 种子化（Seed） |
|------|----------------|----------------|
| 输入 | 原始文本 | 已存在的 Memfile |
| 输出 | 记忆条目 | 代表性子集 |
| Prompt | `prompts/distill.md` | `prompts/seed.md` |
| 触发命令 | `remember`、`book` | `init`、`reindex` |
| 失败语义 | `stale`（保留原文） | `stale`（保留源 Memfile） |

---

<a id='page-10'></a>

## 密钥扫描与防护

### 相关页面

相关主题：[存储与数据模型](#page-5), [MCP 服务器与代理集成](#page-7)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- 资料来源： [packages/core/src/secret-scan.ts](https://github.com/getmembook/membook/blob/main/packages/core/src/secret-scan.ts)
- 资料来源： [packages/core/src/guard.ts](https://github.com/getmembook/membook/blob/main/packages/core/src/guard.ts)
- 资料来源： [packages/core/src/fake-secrets.ts](https://github.com/getmembook/membook/blob/main/packages/core/src/fake-secrets.ts)
- 资料来源： [SECURITY.md](https://github.com/getmembook/membook/blob/main/SECURITY.md)
</details>

summary>

以下源码文件用于生成本页说明：

- [packages/core/src/secret-scan.ts](https://github.com/getmembook/membook/blob/main/packages/core/src/secret-scan.ts)
- [packages/core/src/guard.ts](https://github.com/getmembook/membook/blob/main/packages/core/src/guard.ts)
- [packages/core/src/fake-secrets.ts](https://github.com/getmembook/membook/blob/main/packages/core/src/fake-secrets.ts)
- [SECURITY.md](https://github.com/getmembook/membook/blob/main/SECURITY.md)
- [packages/core/src/index.ts](https://github.com/getmembook/membook/blob/main/packages/core/src/index.ts)
- [packages/spec/src/index.ts](https://github.com/getmembook/membook/blob/main/packages/spec/src/index.ts)
</details>

# 密钥扫描与防护

## 设计目标与作用范围

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

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

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

资料来源：[packages/core/src/secret-scan.ts](https://github.com/getmembook/membook/blob/main/packages/core/src/secret-scan.ts)

## 扫描器：secret-scan

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

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

```mermaid
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](https://github.com/getmembook/membook/blob/main/packages/core/src/secret-scan.ts)、[packages/core/src/guard.ts](https://github.com/getmembook/membook/blob/main/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](https://github.com/getmembook/membook/blob/main/packages/core/src/guard.ts)

## 测试样本：fake-secrets

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

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

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

资料来源：[packages/core/src/fake-secrets.ts](https://github.com/getmembook/membook/blob/main/packages/core/src/fake-secrets.ts)

## 公开策略与上报

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

资料来源：[SECURITY.md](https://github.com/getmembook/membook/blob/main/SECURITY.md)

## 与其它子系统的耦合

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

| 关联子系统 | 与密钥防护的关系 |
|---|---|
| `@membook/spec` 解析器 | 扫描命中序列化后必须仍可被 `parseMemfile` 读回 |
| `@membook/core` 导出 | `secret-scan` / `guard` 由 `packages/core/src/index.ts` 统一暴露 |
| CLI / MCP 入口 | 同一份运行时版本号（membook@0.1.2、@membook/mcp@0.1.2）便于在告警中定位 |
| `reindex` 流水线 | 必须在脱敏定稿后执行，否则索引可能保留旧命中片段 |

资料来源：[packages/core/src/index.ts](https://github.com/getmembook/membook/blob/main/packages/core/src/index.ts)、[packages/spec/src/index.ts](https://github.com/getmembook/membook/blob/main/packages/spec/src/index.ts)

---

<a id='page-11'></a>

## 索引、迁移与 MEMBOOK 生成

### 相关页面

相关主题：[Memfile 格式规范](#page-3), [存储与数据模型](#page-5), [CLI 命令与人类工作流](#page-8)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [packages/core/src/reindex.ts](https://github.com/getmembook/membook/blob/main/packages/core/src/reindex.ts)
- [packages/core/src/migrate.ts](https://github.com/getmembook/membook/blob/main/packages/core/src/migrate.ts)
- [packages/core/src/book.ts](https://github.com/getmembook/membook/blob/main/packages/core/src/book.ts)
- [MEMBOOK.md](https://github.com/getmembook/membook/blob/main/MEMBOOK.md)
- [docs/design/v0.2-workspaces.md](https://github.com/getmembook/membook/blob/main/docs/design/v0.2-workspaces.md)
- [packages/cli/src/commands/misc.ts](https://github.com/getmembook/membook/blob/main/packages/cli/src/commands/misc.ts)
</details>

# 索引、迁移与 MEMBOOK 生成

## 概览

在 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/spec@0.2.0` 引入了"读取侧"的版本号声明：解析器现在会报告磁盘文件声明的 schema 版本，并由核心在启动或写入时进行一致性检查。

迁移原则遵循"A model may fail to restore, but it may not destroy"（在 `@membook/core@0.1.1` 释出时被明确提出）：当 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`，作为面向人类阅读者的"知识手册"。其生成过程如下：

| 步骤 | 输入 | 输出 |
| --- | --- | --- |
| 1. 收集 | 索引与原始 memory 条目 | 带标签的候选列表 |
| 2. 排序 | 候选列表 | 按优先级与时间排序的序列 |
| 3. 渲染 | 排序后序列 | `MEMBOOK.md` 文本 |
| 4. 写出 | `MEMBOOK.md` 文本 | 项目根目录下的可读文件 |

CLI 命令 `membook book` 触发该流程；该功能在 `membook@0.1.0` 首发。生成的 `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]()

---

<a id='page-12'></a>

## 运维、测试与平台支持

### 相关页面

相关主题：[项目概述：可验证的记忆](#page-1), [整体架构与包结构](#page-2)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [CONTRIBUTING.md](https://github.com/getmembook/membook/blob/main/CONTRIBUTING.md)
- [docs/dogfood.md](https://github.com/getmembook/membook/blob/main/docs/dogfood.md)
- [docs/releasing.md](https://github.com/getmembook/membook/blob/main/docs/releasing.md)
- [scripts/post-public-setup.sh](https://github.com/getmembook/membook/blob/main/scripts/post-public-setup.sh)
- [.nvmrc](https://github.com/getmembook/membook/blob/main/.nvmrc)
- [mise.toml](https://github.com/getmembook/membook/blob/main/mise.toml)
</details>

# 运维、测试与平台支持

本页描述 membook 项目的运维、测试与平台支持机制，覆盖开发环境配置、变更与发布流程、自家使用（dogfooding）以及发布后脚本工具。这些资料主要来自仓库根目录与 `docs/`、`scripts/` 子目录下的源文件，并结合 `membook` 与 `@membook/*` 包的发布说明交叉印证。

## 工具链与开发环境

membook 的运行时版本被严格锁定在单一来源，避免在多个包中重复硬编码字符串。仓库使用 `.nvmrc` 文件记录项目要求的 Node.js 主版本，开发者可通过 `nvm use` 切换；同时提供 `mise.toml` 以兼容使用 [mise](https://mise.jdx.dev/)（前身 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]()。

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

| 阶段 | 操作 | 产出 |
| --- | --- | --- |
| 变更登记 | 开发者通过 PR 提交 changeset | `.changeset/*.md` 文件 |
| 合并 | 合并至 `main` 后自动生成版本 PR | 版本号与 CHANGELOG 草稿 |
| 发布 | 合并版本 PR 触发 CI | 多个包发布到 npm |
| 版本号回填 | 各包的 `package.json` `version` 字段被自动更新 | 运行时 `SERVER_VERSION` 同步 |

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

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

## 自家使用（Dogfooding）

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

从社区上下文可推断，该实践与 CLI 的 `membook review` 紧密相关——PR [#20](https://github.com/getmembook/membook/pull/20) 改进了 `membook review` 的文本回流（reflow）行为，使得维护者在浏览硬换行的记忆正文时获得更佳阅读体验，并在遇到未识别的输入时主动重新询问 资料来源：[membook@0.1.1]()。这表明 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 平台。这种"一份配置，多端运行"的部署模型，配合上述工具链与发布流程，使项目的运维成本被压缩到最小。

```mermaid
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` 一致，避免出现"发布版本与运行版本漂移"的运维事故。

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Doramagic 踩坑日志

项目：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: membook@0.1.0

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

## 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/mcp@0.1.2

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

## 5. 运行坑 · 失败模式：runtime: membook@0.1.2

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

## 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/core@0.1.1

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

## 10. 运行坑 · 失败模式：performance: @membook/core@0.2.0

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

## 11. 运行坑 · 失败模式：performance: @membook/spec@0.2.0

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

## 12. 运行坑 · 失败模式：performance: membook@0.1.1

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

## 13. 运行坑 · 失败模式：performance: membook@0.2.0

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

## 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/mcp@0.1.1

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

## 17. 维护坑 · 失败模式：maintenance: @membook/mcp@0.1.3

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

<!-- canonical_name: getmembook/membook; human_manual_source: deepwiki_human_wiki -->