Memory Fabric

Memory Fabric

面向兼容 MCP 的 AI 编码助手，以文件优先、本地优先的方式提供记忆层。

Memory Fabric 为 Claude Code、Cursor 和 GitHub Copilot 等 AI 工具提供一致、了解项目上下文的上下文层，不会将你绑定到某个模型、编辑器、云服务提供商或操作系统。

记忆以带有 YAML frontmatter 的 Markdown 格式存储，可供人阅读。无需向量数据库，无需云账户，也不需要嵌入。

---

功能

• MCP 原生：通过标准 Model Context Protocol 提供记忆工具
• 文件优先：Markdown 文件是唯一可信来源，可供检查并可直接提交
• 本地优先：核心读写功能可离线运行
• 存储优先：事实存放在 memory-store/ 中，每个文件一条；根目录映射文件（architecture.md、decisions.md 等）是由 Dreaming 生成的视图，会重新构建，绝不手动编写
• 自动捕获：每次 git 提交都会自动记录为情节记忆——无需 Agent 配合——通过可选的 post-commit 钩子实现
• Git 原生合并：可选的自定义合并驱动程序可像合并代码一样干净地合并两个分支的记忆，而不是因共享时间戳行发生冲突
• 可自我验证：记忆可以引用所依赖的文件、行或提交；ai-memory verify 会标记已失效的引用
• 从失败中学习：write_failure_memory_tool 会将同一错误的重复出现合并为一条不断扩充的记录，而不是散落成多条相似记录
• 安全处理机密信息：写入前会对 API 密钥和凭据进行脱敏
• 关注令牌预算：在限制范围内组装上下文；绝不会从文档中间截断文件
• 质量评估：在本地评估记忆的实用性，以及 Dreaming 前后的效果
• 支持 Unicode：适用于任何人类语言
• 优雅降级：即使未配置 rg、git 钩子或 Dreaming，也能正常运行

---

状态

v1.4.4 — 沿用 1.4.3 的产品修复，并清理公开产物、重新创建 git 历史记录。已发布到 PyPI。 核心 CLI 和 MCP 工具可端到端运行。有关已发布的内容、正在进行的工作和后续计划，请参阅 ROADMAP.md。

---

演示

CLI 和自动捕获流程：初始化项目，将记忆作为普通的 Markdown 文件写入仓库，然后观察 git commit 在无需 Agent 配合的情况下 自动将自身记录为情节记忆。跨工具的使用场景——一个 Agent 在某个工具中写入记忆， 另一个工具将其读回——已在 DEMO.md 中编排为分镜， 完整视频也可在其中查看。

---

隐私——无遥测

Memory Fabric 绝不会向任何地方发送数据。无需账户、没有云服务， 没有分析，也不会回传信息。核心读写流程完全不会发出网络请求； 唯一可选的网络请求是 PyPI 版本差异检查和 LLM 提供商预检，这两项都可以通过 --offline 关闭。你的记忆是自己 git 历史记录中的纯 Markdown——除非你推送， 否则它不会离开你的设备。

运行 ai-memory diary approve 后，可选的默认关闭现场日志会在你的设备上 记录运行计数。这不是会话日志，也不是遥测：不会传输任何内容。MEMORY_FABRIC_DIARY=0 是紧急关闭开关。这是刻意作出的保证，并非我们可能更改的默认设置。

---

安装

从 PyPI 安装（推荐）

需要 Python ≥ 3.11。

pipx install memory-fabric          # CLI only
pipx install "memory-fabric[mcp]"   # CLI + MCP server

也可以使用普通的 pip（在虚拟环境中）：

pip install memory-fabric          # CLI only
pip install "memory-fabric[mcp]"   # CLI + MCP server

零安装，一次性运行（需要 uv）：

uvx --from "memory-fabric[mcp]" memory-fabric-mcp   # starts the MCP server on stdio

从 GitHub 安装（最新预发布版本）

# CLI only
pipx install "git+https://github.com/elViRafa/agentic-memory.git"

# CLI + MCP server
pipx install "memory-fabric[mcp] @ git+https://github.com/elViRafa/agentic-memory.git"

也可以使用普通的 pip（在虚拟环境中）：

pip install "git+https://github.com/elViRafa/agentic-memory.git"          # CLI only
pip install "memory-fabric[mcp] @ git+https://github.com/elViRafa/agentic-memory.git"  # + MCP

升级

由于 Memory Fabric 仍在积极开发中，我们建议定期升级：

1. 升级软件包：

   # If installed via pipx:
   pipx upgrade memory-fabric
   
   # If installed in a virtual environment via pip:
   pip install --upgrade "memory-fabric[mcp]"
   
   # If installed from GitHub (pre-release):
   pipx install --force "memory-fabric[mcp] @ git+https://github.com/elViRafa/agentic-memory.git"
   

2. 刷新 MCP 客户端配置（uvx 安装）： 如果客户端配置通过 uvx 启动服务（旧版 ai-memory install 运行时默认写入此配置），uv 会提供首次缓存的构建版本，并且不会重新解析未固定版本的规范——仅重启客户端并不足够，可能导致服务落后好几个版本且毫无提示。升级后，请执行以下任一操作：

   # Re-write the client config (now pins the exact installed version, or points
   # at the local memory-fabric-mcp binary when one sits next to the CLI):
   ai-memory install --client <your-client> --project
   
   # ...or drop the stale cached build so uvx re-resolves:
   uv cache clean memory-fabric
   

   如果本地版本与 PyPI 上的最新版本不一致，或者 PATH 上有其他 ai-memory 安装覆盖了当前安装，ai-memory doctor 会发出警告。

3. 重启 MCP 客户端： 升级后，请重启 IDE（Cursor、VS Code）或助手进程（Claude Code），确保客户端重新加载更新后的 memory-fabric-mcp 服务。

4. 刷新本地项目（可选）： 如果你使用旧版 Memory Fabric 初始化了项目，请进入项目目录并运行：

   ai-memory init --install-hooks
   

   这会安全地将起始模板和本地 git 钩子集成更新到最新格式，而不会覆盖你现有的记忆 Markdown 文件。

Windows 终端：CLI 输出 UTF-8（记忆内容中可能包含破折号和项目符号）。Windows Terminal 和 PowerShell 7 开箱即用即可正确显示；在旧版控制台（使用 OEM 代码页的 PowerShell 5.1）中，如果看到替换字符，请设置 chcp 65001 或 PYTHONUTF8=1。

或者，克隆项目并以可编辑模式安装，用于本地开发：

git clone https://github.com/elViRafa/agentic-memory.git
cd agentic-memory
pip install -e .          # CLI only
pip install -e ".[mcp]"   # CLI + MCP server

---

快速开始

1. 初始化项目

ai-memory init

在当前目录中创建 .ai-memory/，其中包含起始章节和 .gitignore。

2. 检查运行状况

ai-memory doctor

3. 评估记忆质量

ai-memory eval
ai-memory eval --json

eval 会评估记忆对编码助手是否有用。它会检查章节覆盖率、起始模板内容、摘要质量、元数据、检索就绪情况以及可能存在的密钥。

如果 .ai-memory/ 已存在，报告会保存在被忽略的本地文件中：

.ai-memory/evals/latest.json
.ai-memory/evals/latest.md
.ai-memory/evals/<timestamp>-memory.json
.ai-memory/evals/<timestamp>-memory.md

如果 .ai-memory/ 尚不存在，eval 只会打印初始化前报告，不会创建任何文件。

4. 查询记忆

ai-memory query "authentication"

5. 运行维护（Dreaming）

ai-memory dream --mode light
ai-memory dream --mode deep

Dreaming 会在维护前创建快照。你可以评估 Dreaming 运行是否提升了记忆质量：

ai-memory eval --dream latest
ai-memory dream --mode light --eval

Dream eval 会将 Dreaming 前的快照与当前记忆进行比较，并报告分数变化、变更文件、改进项和退化项。

---

MCP 服务 — 安装

每个客户端只需一条命令。可安全地重复运行：会与你现有的配置合并，绝不会覆盖配置；如果无法解析原始文件，则会先备份。

一键安装

这些操作在底层会调用 uvx --from "memory-fabric[mcp]" memory-fabric-mcp——与 ai-memory install 使用相同的标准调用方式，只是不需要 CLI 步骤。需要安装 uv。

客户端	命令
Claude Code	ai-memory install --client claude-code
Claude Desktop	ai-memory install --client claude-desktop
VS Code	ai-memory install --client vscode
Cursor	ai-memory install --client cursor
Windsurf	ai-memory install --client windsurf
Codex	ai-memory install --client codex
Antigravity	ai-memory install --client antigravity
Gemini CLI	ai-memory install --client gemini-cli
Cline	ai-memory install --client cline
所有已检测到的客户端	ai-memory install --client all

添加 --project 可写入项目级配置，而非全局／用户配置（客户端支持时）。添加 --dry-run 可通过统一差异预览更改，而不写入任何内容。添加 --uninstall 只会移除 memory-fabric 条目，并保留文件中的其他所有内容。

可用的 MCP 工具

工具	描述
initialize_memory_fabric_tool	在项目中创建 .ai-memory/ 脚手架
read_combined_context_tool	在令牌预算范围内加载 Tier 0 指令和优先级记忆
read_section_tool	按名称读取单个记忆分区
keyword_search_tool	使用 ripgrep 或 Python 回退方案搜索记忆
write_local_memory_tool	仅更新引导分区（framework-rules、ubiquitous-language）。写入事实或根映射会被拒绝（先存储）——根映射由 memory-store/ 生成；请使用 write_memory_store_tool
propose_memory_patch_tool	预览拟议的记忆更改，但不应用
dream_tool	运行记忆维护／整合（--mode light
prepare_dream_payload_tool	准备候选快照，并返回用于由客户端驱动梦境整合的提示词
apply_dream_results_tool	将 LLM 整合后的 JSON 输出应用到候选快照并保存更改
evaluate_memory_fabric_tool	评估本地记忆质量
evaluate_dream_quality_tool	根据快照评估一次 Dreaming 运行
write_memory_store_tool	将记忆文件写入语义存储路径（例如 architecture/decisions/auth）；可选接受 evidence 引用列表
read_memory_store_tool	按语义路径读取单个记忆存储文件
list_memory_store_tool	列出记忆存储中的文件，可按前缀／标签筛选
delete_memory_store_tool	按语义路径移除记忆存储文件
write_session_journal_tool	追加带时间戳的会话日志条目（情景记忆）
write_failure_memory_tool	记录错误 → 修复配对；同一错误再次发生时，会累加到同一条目中

---

Agentic Architecture（让 Agent 自动使用 Memory Fabric）

注册 MCP 服务是必要的，但还不够——除非明确指示 AI Agent，否则它们不会使用其中的工具。

Memory Fabric 提供自动化的 Agentic Architecture，帮你处理这些工作。

在项目中运行 ai-memory init 时，CLI 会自动部署一整套 Agent 指令文件，为每种主流 AI 工具量身定制：

目标	创建的文件
Gemini CLI / Codex / Antigravity	AGENTS.md
Grok（TUI / Build / Agent harness）	AGENTS.md（主要项目规则）；完整文档和 MCP 注册信息位于 ~/.grok/config.toml 或 .mcp.json；如果已为客户端安装，请参阅 .grok/docs/user-guide/13-memory-fabric.md
Cursor IDE	.cursor/rules/memory-fabric.mdc
Windsurf IDE	.windsurf/rules/memory-fabric.md
Cline / 通用 IDE Agent	.agents/rules/memory-store.md、.agents/rules/dreaming.md
Claude Code	CLAUDE.md（新建或追加）
GitHub Copilot	.github/copilot-instructions.md（新建或追加）

单一事实来源（同步）

所有这些文件都由 Memory Fabric Python 软件包中的 两个规范内容块生成。运行 ai-memory sync-agents 会根据这些模板重新生成所有平台文件，确保内容完全一致。如果你使用了 ai-memory init --install-hooks，则每次提交时都会由 pre-commit git 钩子自动运行同步。

在共享用户文件（AGENTS.md、CLAUDE.md、.github/copilot-instructions.md）中，fabric 内容位于受管理的标记块（…）内；同步只会重写标记之间的内容，因此你在标记之外添加的任何内容都会逐字节保留。

项目指令（v1.1）

除了软件包自身的协议指令外，你还可以定义项目指令——由人工精心编写、供每个参与代码库工作的 AI Agent 共享的开发指南。指令只是一个根目录分区文件 .ai-memory/<name>.md，带有 role: steering 前置元数据（如内置的 framework-rules 和 ubiquitous-language），并可包含两个可选的布尔路由键：

键	含义	默认值
sync	将指令包含在 sync-agents 生成的各工具文件中	true
context	将指令作为 Tier 0 注入 read_combined_context	内置指令为 true；用户指令为 false（文件读取型 Agent 已能获得同步后的副本）

ai-memory sync-agents 会将所有 sync: true 的 steering 分区组合成一份项目指令文档，并分发为 .agents/rules/project-directives.md、.cursor/rules/project-directives.mdc、.windsurf/rules/project-directives.md，以及 AGENTS.md/CLAUDE.md/.github/copilot-instructions.md 中的受管理标记块——这样，只读取 AGENTS.md 的客户端（Codex、OpenCode、Gemini）也能获取这些指令。删除最后一条已同步的指令时，这些内容也会全部移除。

对于 CI，ai-memory sync-agents --check 是一个漂移检测门禁：它不会写入任何内容；如果任一生成文件已过期，则以代码 1 退出。ai-memory doctor 还会在以下情况下发出警告：始终加载的上下文内容超出其令牌预算（默认值为 3000，MEMORY_FABRIC_DIRECTIVE_BUDGET）、手动编辑的 steering 文件包含疑似机密的信息，或受管理标记之外存在过时的 pre-1.1 fabric 块。

有关该架构的完整详情，请参阅 AGENTIC_ARCHITECTURE.md。

为什么这很重要

如果没有这些指令文件，Agent 往往会解释说它们“不会自动使用 MCP 工具”；更糟的是，它们可能会直接使用原生文件系统工具编写记忆 Markdown 文件——绕过机密扫描、令牌预算和后台 Dreaming 管理。

只需运行 ai-memory init，即可在整个 Agent 生态系统中获得零配置、开箱即用的能力。

---

在其他项目中使用 Memory Fabric

您可以在所有编码项目中使用同一个已安装的 Memory Fabric 实例：

1. 搭建目标项目： 导航到目标项目的根目录并进行初始化：

   cd /path/to/other-project
   ai-memory init --install-hooks
   

   这会自动创建 .ai-memory/，部署 Agentic Architecture 规则文件，设置 .gitignore，并安装 git post-commit 钩子。

2. 全局 MCP 配置： 确认 AI 助手的配置指向全局安装的 memory-fabric-mcp 可执行文件。MCP 工具会自动解析并使用助手通过 cwd 参数传入的当前项目路径，让单个全局 MCP 服务注册即可支持您的所有本地工作区。

---

项目记忆布局

Memory Fabric 采用存储优先模式：memory-store/ 是 Agent 手动写入事实的唯一位置，每个文件记录一条事实。根目录中的映射文件（architecture.md、decisions.md、debt.md、schemas.md、index.md）是由 Dreaming 根据对应的 memory-store/<category>/ 子树重新构建的生成视图——切勿直接编辑这些文件；它们带有 generated: true frontmatter，手动修改的内容会在下一次 Dream 时折回存储区以供审核。 例外是引导层级：任何带有 role: steering frontmatter 的根目录区段（内置文件 framework-rules.md 和 ubiquitous-language.md，以及您创建的任何项目指令）都由人工维护——人和 Agent 可以直接编辑这些文件（通过 MR 审核）。内置文件始终会完整加载到上下文中，不会生成，也不会因令牌预算而被移除；用户指令默认设为 context: false，并通过 sync-agents 的逐工具文件传递给 Agent。

.ai-memory/
|-- index.md                  # generated discovery index
|-- architecture.md           # generated map of memory-store/architecture/
|-- schemas.md                # generated map of memory-store/schemas/
|-- decisions.md              # generated map of memory-store/decisions/
|-- debt.md                   # generated map of memory-store/debt/
|-- ubiquitous-language.md    # hand-curated steering directive (always loaded)
|-- framework-rules.md        # hand-curated steering directive (always loaded)
|-- memory-store/             # the source of truth — one fact per file
|   |-- index.md              # generated store-wide index
|   |-- architecture/...
|   |-- decisions/...
|   |-- debt/...
|   |-- schemas/...
|   |-- failures/<slug>.md    # error -> fix pairs, deduplicated by normalized signature
|   |-- episodic/<date>.md    # agent-written session journals
|   `-- episodic/commits/<date>/<short-hash>.md  # one passively captured commit each
|-- evals/       # ignored local quality reports
|-- snapshots/   # ignored rollback baselines
|-- private/     # ignored personal notes + session markers
`-- .gitignore

所有记忆文件都使用 YAML frontmatter：

---
store_path: architecture/decisions/auth-service
summary: "One-line fallback used when the file exceeds the token budget."
priority: high
tags: [api, auth]
schema_version: "1.3"
last_updated: 2026-06-01T12:00:00-04:00
evidence: [src/auth.py:42, "commit:abc1234"]
---

Your memory content here.

可选的 evidence 字段用于注明记忆所依据的内容——某个文件、file:line 或 commit:<hash>。运行 ai-memory verify 可检查这些引用是否仍然有效；如果记忆引用的文件已重命名或删除，系统会将其标记出来，而不是任其悄然失效。

---

捕获可靠性

Agent 指令文件能让 Agent 在会话开始时可靠地读取记忆，但写入的一致性较差——长会话可能会压缩掉指令，而且有些客户端根本不会加载规则文件。有两种机制可以弥补这一差距，无需依赖任何 Agent 的配合——提交代码，项目大脑便会自动更新；结束会话时若没有日志，Stop 钩子就会阻止操作。

被动捕获。 使用 ai-memory init --install-hooks 后，每次提交都会自动记录为情景记忆：

ai-memory capture              # capture HEAD (this is what the post-commit hook runs)
ai-memory capture --commit abc1234

每次捕获都会为每次提交在 memory-store/episodic/commits/<date>/<short-hash>.md 写入一个文件，其中包含 source: passive-capture 和 review_status: pending frontmatter——这些记录可供审核，并且与 Agent 写入的日志条目相互区分。该过程按提交哈希幂等执行，无需大模型；这些记录是下一次 ai-memory dream 整合或提取事实的原始材料。

每次提交写入一个文件，而不是每天共用一个文件，这样可以让目录树保持可合并。捕获会在提交后运行，因此提交 N 的记录只能由提交 N+1 提交——两次提交之间，它始终处于未提交状态。如果共用一个每日文件，该文件就会一直是已跟踪且已修改的文件，而 git 会拒绝合并到该文件中（error: Your local changes to the following files would be overwritten by merge），且发生在任何合并机制运行之前——包括本可解决冲突的语义合并驱动程序。每次提交创建一个不同的新文件则会使其处于未跟踪状态，git 可以直接将其合并过来，而且两位开发者永远不会写入同一路径。 噪声提交（合并提交、作者为 [bot]、以 chore:/style:/ci:/build(deps) 开头的前缀、仅修改锁文件）默认会被跳过——并会明确告知，附带 skipped_reason，且可通过 --no-filter 选择不进行过滤，绝不会悄悄跳过——而 ai-memory dream --mode deep 会将 14 天前的提交记录归并为每周摘要，避免 episodic/commits/ 无限增长。完整设计请参阅 ROADMAP_CAPTURE_HOOKS.md。

会话结束强制检查。 ai-memory session-start 会标记会话开始时间； 如果自上次调用 write_session_journal_tool 以来尚未再次调用该工具，ai-memory guard-journal 会以非零状态码退出（原因会输出到 stderr）。ai-memory install --client <claude-code|gemini-cli|codex> --with-hooks 会自动完成配置——SessionStart 会标记会话并注入简短的上下文提醒，Stop 会阻止结束会话，直到日志存在；预压缩事件会运行一个非阻塞的本地整合检查点。ai-memory status 会报告本地捕获统计信息（最近的日志、提交捕获数量、过去 7 天写入的记忆），以便你确认捕获是否实际发生。

用证据说话，而非空口声称。 scripts/capture_rate_benchmark.py 会让一个完全不配合的模拟 Agent——它不会主动调用 write_session_journal_tool——在每种模式下经历 20 个会话：

模式	已写入日志的会话	提交捕获率
仅使用说明（无钩子）	0 / 20（0%）	20 / 20（100%）
启用钩子（强制执行 guard-journal）	20 / 20（100%）	20 / 20（100%）

无论采用哪种模式，被动提交捕获率都保持在 100%，因为它依托 git post-commit 钩子运行，而非客户端会话钩子。只有配置 Stop 钩子后，会话日志记录率才会从 0% 升至 100%——这证明的是机制有效（强制执行机制无法被悄悄跳过），而非对真实场景中 Agent 遵循要求情况的统计研究；后者属于独立且规模更大的基准测试工作（参见 ROADMAP.md 第 5 阶段）。你可以自行复现： python scripts/capture_rate_benchmark.py --sessions 20。

失败记忆。 对编码 Agent 来说，信号最强的类别是：“我以前遇到过这个错误，这是解决方法”：

ai-memory failure --error "KeyError: 'user_id' in handlers.py:12" --fix "Added a default value."

错误文本会经过规范化处理（去除路径和行号），生成稳定的签名，因此再次遇到同类错误时，会累加到同一个不断扩展的 memory-store/failures/<slug>.md 条目中，并增加 occurrences 计数，而不是散落在一堆近乎重复的文件里。

---

Git 原生信任

只有当记忆与其描述的代码存放在同一个 git 仓库中时，才能实现以下两项能力——向量数据库或云端记忆产品都无法提供。

语义合并驱动。 过去，两个分支各自在同一个存储文件中追加新事实时，即使实际新增的内容完全没有重叠，也会因为共享的 last_updated 行而产生冲突。ai-memory init --merge-driver 会注册一个自定义驱动，用来解决团队记忆实际产生的各类变更；对于无法安全解决的情况，则回退到 git 自带的文本合并——效果绝不会比未安装它更差。

ai-memory init --merge-driver

合并方式按优先级排列：

变更形态	解决方式
仅修改 Frontmatter	合并标签，优先级取更紧急的一方，last_updated 取较晚的一方
生成的视图（index.md、failures.md 和其他根目录映射文件）	合并——绝不会产生冲突；下次 Dreaming 运行时会从 memory-store/ 重新构建这些文件
两个分支都追加了新事实	保留两边内容，删除近似重复的行
两个分支都写入了不同的 ## 条目（两个 Agent 在同一天记录日志）	按块合并
两边都重写了同一个 ## 条目	交由 git 的文本合并处理——这是真正的意见分歧，由人来决定

这会将 .ai-memory/**/*.md merge=memory-fabric 写入 .gitattributes（提交并共享），并在本地 git config 中注册驱动命令（按 git 自身设计，每个克隆单独配置）。

团队注意：每个克隆单独配置的部分最容易出问题。 .gitattributes 会随仓库一起传递，但驱动命令不会——队友克隆仓库后如果未注册驱动就进行合并，.ai-memory/ 中仍会出现普通文本冲突，且没有任何提示说明原因。有两种方式可以弥补这一点：当克隆声明了驱动但尚未注册时，ai-memory doctor 会发出警告；而在此类克隆中运行任何 ai-memory init 时，都会自动注册驱动。

已经在合并过程中？ 不必重新合并——resolve-conflicts 会对 git 已记录的冲突应用相同的解决方式，并暂存已解决的内容：

ai-memory resolve-conflicts
# resolved: .ai-memory/failures.md, .ai-memory/memory-store/episodic/2026-07-28.md
git commit

对于需要人工处理的内容，该命令会以非零状态码退出，并保持文件原样不动——包括所有冲突标记，因此可以安全地对整个冲突中的合并运行该命令。

可自我验证的引用。 请参阅上文的 evidence 字段——ai-memory verify 命令会检查引用是否仍能解析，并标记无法解析的引用。

---

全局记忆

适用于所有项目的开发者级偏好存储在以下路径：

平台	路径
Windows	%APPDATA%\memory-fabric\global\
macOS	~/Library/Application Support/memory-fabric/global/
Linux	$XDG_CONFIG_HOME/memory-fabric/global/

global/directives.md 属于 Tier 0：始终完整加载，不受令牌预算限制。

---

CLI 参考

ai-memory [--cwd <path>] [--json] [--debug-llm] <command>

Commands:
  init            Create .ai-memory/ scaffolding (--install-hooks, --merge-driver)
  status          Show memory status and capture stats
  doctor          Validate memory files and environment
  verify          Check evidence citations still resolve (--no-mark for a read-only report)
  failure         Record an error -> fix pair (--error, --fix, --tags)
  merge-driver    Git merge driver backend (invoked by git itself, not for direct use)
  resolve-conflicts  Resolve conflicted .ai-memory files of an in-progress merge (--all)
  capture         Record a commit as episodic memory (--commit, default HEAD)
  session-start   Mark session start (for client SessionStart hooks)
  guard-journal   Exit non-zero if no session journal was written (for client Stop hooks)
  install         Configure an MCP client to use memory-fabric (--client <name|all>)
  eval            Score memory quality or Dreaming quality
  bench           Coding-memory benchmark: memory-on vs memory-off retrieval
  dream           Run memory maintenance (--mode light|deep)
  migrate         Split legacy hand-written sections into store entries (--dry-run, --section, --no-llm)
  query           Search memory
  store           CRUD operations on semantic memory store
  sync-agents     Regenerate agent instruction files from canonical templates
  sync-global     Preview local-to-global promotions
  rollback        Restore from a snapshot (--to <name>, or --list to discover valid names)
  clean           Prune old snapshots/candidates (--keep-snapshots, --keep-candidates, --dry-run)
  diary           Local field diary (approve|revoke|mute|unmute|status|checkpoint|wipe) — off by default, never sent

评估示例：

ai-memory eval
ai-memory eval --json
ai-memory eval --llm-review
ai-memory eval --dream latest
ai-memory eval --dream memory-20260601T140000_0400

可选的 LLM 审查默认绝不会启用。启用后，确定性的本地评分仍是判断依据；LLM 备注仅作参考，且审查前会对输入进行清理。

ai-memory bench
ai-memory bench --json
ai-memory bench --fixture . --suite .ai-memory/evals/bench.yaml

bench 会评估后续会话中的问题能否找回此前的决策（启用记忆与使用空存储的对比）。内置测试夹具和方法说明位于 benchmarks/coding-memory/。无需 LLM。

内置测试夹具（2026-08-15，ai-memory bench）：

任务	启用记忆时的召回率	未启用记忆时的召回率
TOT_LOCAL CAD 与系统列	1.00	0.00
test_*.py 命名	1.00	0.00
不使用 Django REST Framework	1.00	0.00
urnas_add_pos_calc PRD 0008/0009 调整	1.00	0.00
平均值 / 提升幅度	1.00	0.00（提升幅度 1.00）

---

LLM 配置与 MCP 抽样

Memory Fabric 使用大语言模型（LLM）执行语义记忆整合（Dreaming）和定性评估。你可以通过两种方式进行配置：使用直接环境变量，或使用零配置的 MCP Sampling。

优先级顺序

当某项操作需要大模型时，Memory Fabric 按以下顺序确定提供方：

1. 直接大模型提供方：如果环境中设置了 MEMORY_FABRIC_LLM_PROVIDER，并配置了相应的 API 密钥，则使用直接 API 调用。
2. 原生 MCP 采样：如果未设置直接提供方（或缺少已配置的密钥），并且命令是在支持采样功能的父级 Agent 所处的活动 MCP 会话中执行，Memory Fabric 会将大模型调用委托给该 Agent。
3. 本地平滑回退：如果两者都不可用，则平滑降级为基于本地确定性正则表达式的去重，不进行语义综合。

在 Dreaming 中使用 MCP 采样

MCP 采样让 Memory Fabric 无需配置任何本地 API 密钥或提供方环境变量，即可运行语义 Dreaming 和评估。它会使用宿主客户端（例如 Claude Code）的原生大模型连接。

工作原理

1. 当 AI 助手通过 MCP 调用 dream_tool 或 evaluate_memory_fabric_tool 时，Memory Fabric 服务会检查客户端会话是否支持采样功能。
2. 如果支持，且未配置直接提供方，服务会向客户端发送 create_message 请求。
3. 客户端助手会在底层执行大模型推理，并返回整合后的记忆 JSON 或评估说明。

主要优势

• 零配置： 无需向后台 MCP 服务进程配置或公开 GEMINI_API_KEY、OPENAI_API_KEY 或 ANTHROPIC_API_KEY。
• 统一上下文： 整合过程使用与你的主编码助手相同的模型和设置。

重要

CLI 限制： MCP 采样依赖活动的客户端—服务会话。独立终端 CLI（ai-memory）在 MCP 客户端之外运行，因此从命令行运行 ai-memory dream 无法使用 MCP 采样。若要通过 CLI 使用基于大模型的整合功能，必须配置直接大模型提供方。

客户端驱动／拆分工具 Dreaming（避免死锁和超时）

在某些顺序执行或阻塞式 MCP 客户端环境（例如 IDE 扩展或 Agent 循环）中，客户端等待工具响应时执行嵌套 MCP 采样请求（create_message），可能导致 JSON-RPC 死锁或执行超时。

为彻底避免此类重入问题，Memory Fabric 提供了由客户端驱动的拆分工具 Dreaming 协议：

1. 准备负载：Agent／客户端首先调用 prepare_dream_payload_tool。该工具会返回 consolidation_prompt 和 candidate_store ID，但不会执行阻塞式大模型推理。
2. 在本地执行：客户端使用自己的本地大模型连接／上下文执行返回的 consolidation_prompt，并获取原始 JSON 输出。
3. 应用结果：客户端通过调用 apply_dream_results_tool(candidate_store=..., llm_response=...) 将原始大模型 JSON 响应发回。Memory Fabric 会解析该响应，将整合后的更改应用到候选文件夹，并保存新的记忆状态。

直接配置大模型提供商

若要通过 CLI 使用大模型，或绕过 MCP Sampling 改用特定提供商，请设置以下环境变量：

提供商	环境变量	备注
Gemini	MEMORY_FABRIC_LLM_PROVIDER=gemini GEMINI_API_KEY=your_key	默认使用 gemini-2.5-flash
OpenAI	MEMORY_FABRIC_LLM_PROVIDER=openai OPENAI_API_KEY=your_key OPENAI_MODEL=gpt-4o-mini (可选) OPENAI_API_BASE=... (可选)	可连接自定义的本地或远程 OpenAI 兼容端点
Anthropic	MEMORY_FABRIC_LLM_PROVIDER=anthropic ANTHROPIC_API_KEY=your_key	默认使用 claude-3-5-haiku-20241022
Ollama	MEMORY_FABRIC_LLM_PROVIDER=ollama OLLAMA_HOST=... (可选) OLLAMA_MODEL=gemma2 (可选)	离线、本地推理

模型质量对深度 Dreaming 很重要。 整合质量（尤其是矛盾检测）会因本地小模型而下降，而且这种失败不会显现出来（模型只会返回一个空的 contradictions 列表）。在我们的测试中，8B 级模型（qwen3-vl:8b）漏掉了一个刻意设置的 TTL 冲突；若依赖 dream --mode deep 进行语义冲突检测，请优先选择约 14B 及以上的模型（或托管式提供商）。作为安全保障，无论大模型如何作答，Memory Fabric 始终会运行确定性启发式检测，标记措辞相似但数字不同的存储文件。

---

大模型调试

若要查看发送给大模型提供商（Gemini、OpenAI、Anthropic、Ollama）的确切提示词和收到的响应，可以启用大模型调试日志。

• 通过 CLI：在子命令之前传入全局标志 --debug-llm：

  ai-memory --debug-llm dream --mode deep
  

  日志会自动输出到 sys.stderr，并追加写入名为 llm_debug.log 的文件（若 .ai-memory/llm_debug.log 目录存在，则写入该目录；否则写入当前工作目录）。

• 通过环境变量：在环境中设置 MEMORY_FABRIC_LLM_DEBUG 变量：

  • stderr：仅将提示词和原始 JSON 响应输出到 sys.stderr。
  • 1 或 true：输出到 sys.stderr，并写入默认的 llm_debug.log 文件。
  • /path/to/log.txt（或任何其他自定义值）：将日志追加写入自定义文件路径。

为保护凭据和 API 密钥，调试日志中的 Authorization 和 x-api-key 等标头会自动替换为 [REDACTED]。

---

写入安全性

每条写入路径都会在保存前检测机密信息。检测到的机密会替换为 [REDACTED_SECRET]，并在响应的 redactions 字段中返回。文件锁可防止并发写入造成文件损坏。

Eval 会扫描现有记忆，查找可能的机密信息，但不会重写已有文件。它会报告需要人工审核的内容。

---

要求

• Python >= 3.11
• mcp >= 1.0.0（可选，仅 MCP 服务需要）
• rg（可选；ripgrep 可加快关键词搜索，若不可用则使用 Python 回退方案）

---

贡献

欢迎贡献。有关设置、CI 强制执行的检查以及存储优先约定，请参阅 CONTRIBUTING.md。对于任何涉及安全的事项，请参阅 SECURITY.md，而不要创建公开 issue。

许可证

MIT — © 2026 Memory Fabric Contributors。无遥测、无需账户、无云服务。