Claude 的记忆，你可以 cat、grep 和 git 的记忆。
一个面向 Claude 及任何支持 MCP 的代理的、以 markdown 为原生的记忆架构。你助手的记忆以纯 .md 文件的形式存放在你拥有的目录中——可以在文本编辑器中检查、可以用 git 做版本管理、可以跨机器移植——而不是存放在某个不透明的向量数据库中。
五种可组合的模式构建在同一个保险库之上：
Weave Core MCP — 对任意 markdown 目录提供 5 个动词的记忆工具
PPR 启动检索器 — 查询驱动的 Personalized PageRank，而非预烘焙的转储
双时间解析器 — 事实带有 valid_from / superseded_by；内置时间旅行查询
休眠期整合器 — 近期活动被回填到实体文件中；反思综合运行在学习日志之上
写入期冲突解析器 — k-NN + LLM 判定在 UPDATE 才是正确操作时拒绝 ADD 重复项
底层只是 markdown 和 YAML frontmatter。没有服务、没有嵌入数据库、没有 Ollama。5 动词工具零基础设施即可运行；更丰富的模式则叠加在同一套文件之上。
v0.4.0 新增内容：
通道防火墙（默认拒绝） — 通过 lane_map.yaml 将笔记路由到检索通道；跨通道泄漏在每个接缝处（密集搜索、PPR 种子、召回）都被阻断，同时匹配两个词汇表的桥接文件会中止构建，直到人工裁决，并且通道配置哈希门会拒绝过期的缓存。
Cortex 读取路径加固 — 一条格式错误的笔记只会降低该笔记本身的质量；故障会被报告，绝不会被隐藏；被隔离的文件在任何通道中都不可检索。
weave lint — 保险库 lint 动词，支持机器可读的 --paths 输出。
确定性冲突预过滤器 — 无关的写入完全跳过 LLM 判定。
咨询性写入门 — MCP 写入动词会附加一条咨询性冲突建议（默认放行；WEAVE_WRITE_GATE=0 可一键关闭）。
Windows 支持（测试版） — 参见 Windows（测试版）。
git clone https://github.com/TheWeaveSC/theweave.git ~/theweave
cd ~/theweave
pip install -e .
# verify the install end-to-end
weave-cli doctor
# try the included demo vault
weave-cli demo boot "ACME cutover with Marcus"
weave-cli demo current entity-ACME --as-of 2026-01-01 # time-travel
weave-cli demo consolidate --today 2026-05-23 # dry-run一次健康的安装看起来像：
🪶 Weave 2.0 Doctor
[Engine]
✓ Python 3.11.15 (≥3.11 required)
✓ Dependencies importable
mcp 1.27.1, networkx 3.6.1, frontmatter 1.3.0, click 8.4.1, ...
✓ CLI + MCP entry points importable
ℹ theweave 0.4.0
[Vault]
✓ Vault root resolves: ~/theweave/seed-vault
✓ Layout: flat (seed-vault style)
✓ 18 notes total — entities 6, sessions 7, signals 1, other 4
✓ Frontmatter parses on all notes
✓ Pattern 4 will scan 7 session(s)
✓ Pattern 2 graph: 18 nodes, 71 edges, 0 isolates (0%)
✓ Bi-temporal coverage: 6/6 entities (100%)
[Environment]
✓ Obsidian.app detected in /Applications/
ℹ ANTHROPIC_API_KEY not set — Pattern 4/5 will run in mock mode
All checks passed.需要 Python ≥ 3.11。如需零克隆安装路径（无需 GitHub 认证），请参见 安装。
Related MCP server: Mneme Memory MCP
TheWeave 是保险库原生的。你助手的身份——语气、工作风格、你们建立的关系——本身也只是保险库中的 markdown。人设记忆在每次会话时加载；事实记忆按需检索。相同的原语、相同的文件、不同的加载纪律。
这意味着人设只是一个你可以 fork 的入门保险库：
# clone a starter vault and verify the engine sees it
cp -R personas/sonnet ~/my-vault
weave-cli doctor --vault ~/my-vault --check-mcp
$EDITOR ~/my-vault/entities/entity-user.md # personalize the user identity本仓库附带的入门保险库：
seed-vault/ — 中立的虚构入门库（ACME / FOO 实体）。最适合用来试跑这五种模式。
personas/sonnet/ — 围绕一个简洁、审计纪律型的 Claude 协作者构建的入门库。语气、工作风格和关系脚手架已预接好。布局和 fork 说明请参见 personas/sonnet/README.md。
或者跳过入门库，直接让 TheWeave 指向任何现有的 markdown 目录——Obsidian、你的笔记仓库、dotfiles。引擎会适配你已有的任何布局。
TheWeave | 向量数据库记忆层 | |
存储 | 文件系统中的纯 | 厂商数据库 / Pinecone / pgvector |
检查 |
| API 查询或管理界面 |
版本管理 |
| 快照/导出工具 |
模式 | 开放的 YAML frontmatter | 厂商数据库模式 |
故障模式 | 一个可以用手编辑的坏 markdown 文件 | 一个必须用查询才能排除的坏行 |
厂商锁定 | 无——它只是一个文件夹 | 需要迁移工具 |
TheWeave 不是聊天记忆的附加组件。它是 Claude 的记忆层，适用于你希望数据留在自己机器上、留在文件系统中、以你能阅读的格式存在的时候。
┌──────────────────────────────────────┐
│ TheWeave — two-tier design │
└──────────────────────────────────────┘
╔════════════════════════════════════════════════════════════════════╗
║ WEAVE CORE (zero-infra, drop-in MCP server) ║
║ ║
║ ┌─────────────────────────────────────────────────────────────┐ ║
║ │ MCP server — 5 verbs over any markdown vault │ ║
║ │ view • create • str_replace • insert • delete │ ║
║ └─────────────────────────────────────────────────────────────┘ ║
║ │ ║
║ ▼ ║
║ ┌─────────────────────────────────────────────────────────────┐ ║
║ │ Vault (markdown + YAML frontmatter) │ ║
║ │ entities/ sessions/ wiki/ LearningLayer/ │ ║
║ └─────────────────────────────────────────────────────────────┘ ║
╚════════════════════════════════════════════════════════════════════╝
│
▼ (same vault, richer engine)
╔════════════════════════════════════════════════════════════════════╗
║ WEAVE PRO (Python engine on your machine) ║
║ ║
║ Pattern 2 — Query → entity-extract → Personalized PageRank → ║
║ top-N notes (bi-temporal-aware) ║
║ ║
║ Pattern 3 — Bi-temporal frontmatter (valid_from / valid_until / ║
║ superseded_by) + chain resolver ║
║ ║
║ Pattern 4 — Sleep-time consolidator: ║
║ recent sessions → per-entity activity patch ║
║ LearningLayer signals → reflect synthesis ║
║ (dry-run by default; --apply with _archive/ backup) ║
║ ║
║ Pattern 5 — Write-time: ║
║ TF-IDF k-NN candidates → LLM (or mock) → ║
║ ADD / UPDATE / DELETE / NOOP verdict ║
║ ║
║ ┌──────────────┐ ┌─────────────────┐ ║
║ │ mock_llm │ ◄─────► │ anthropic_llm │ ║
║ │ (offline) │ env │ (live Claude) │ ║
║ └──────────────┘ var └─────────────────┘ ║
╚════════════════════════════════════════════════════════════════════╝两个层级共享一个保险库。Core 零基础设施即可运行（在 claude_desktop_config.json 中添加一个 MCP 条目即可）。Pro 在不改变数据格式的前提下增加了更丰富的引擎。
# | 模式 | 实现 | LLM 依赖 |
1 | Weave Core MCP | 稳定 — 5 个动词，路径转义保护 | 无 |
2 | PPR 启动检索 | 稳定 — NetworkX、frontmatter 感知的 wikilink、双时间种子解析 | 无 |
3 | 双时间解析器 | 稳定 — | 无 |
4 | 休眠期整合器 | 稳定的扫描 + 补丁。反思综合默认使用模拟启发式；设置 | 可选 |
5 | 写入期冲突解析器 | 稳定的 TF-IDF + 判定流水线。默认使用模拟分类器；设置 | 可选 |
所有持久化都是纯 markdown。没有 ChromaDB、没有 Ollama、没有服务。5 动词底层承载了约 80% 的架构；只有模式 4 和 5 中的分类器步骤需要 LLM。
git clone https://github.com/TheWeaveSC/theweave.git ~/theweave
cd ~/theweave
pip install -e .
weave-cli doctorcurl -sSL https://github.com/TheWeaveSC/theweave/releases/latest/download/install-weave.sh | bash下载带标签的发布 tarball，在 ~/theweave/venv/ 设置 Python venv，安装包，并在 ~/.local/bin/ 在你的 PATH 中时将其符号链接到 weave-cli。以运行 weave-cli doctor 作为成功信号。无需 GitHub 认证——tarball 从公共发布端点获取。
可通过环境变量覆盖：WEAVE_VERSION、WEAVE_HOME、PYTHON。参见 install-weave.sh。
v0.4.0 增加了 Windows 支持：平台感知的 Claude Desktop 配置路径解析（%APPDATA%\Claude\claude_desktop_config.json）、平台原生的 cortex 缓存位置（%LOCALAPPDATA%\theweave\cache），以及一个 PowerShell 安装器：
irm https://github.com/TheWeaveSC/theweave/releases/latest/download/install-weave.ps1 | iex诚实的标签：Windows 路径已实现并通过代码审查，但尚未在 Windows 硬件上进行实地测试。如果你运行了它，请通过 issues 报告你遇到的情况——无论好坏。已知的范围限制：cortex install-nightly 仅限 macOS（launchd）；请改用任务计划程序每晚运行 weave-cli cortex dream。
将 docs/claude-desktop-config.snippet.json 复制到你的 Claude Desktop 配置中的 mcpServers 下——macOS：~/Library/Application Support/Claude/claude_desktop_config.json，Windows：%APPDATA%\Claude\claude_desktop_config.json，Linux：~/.config/Claude/claude_desktop_config.json。重启 Claude Desktop。5 个动词将以 weave-core/view、weave-core/create 等形式提供。
模式 4 和 5 默认使用确定性的模拟实现。要切换到实时模式：
pip install anthropic
export ANTHROPIC_API_KEY=...
export WEAVE_CLAUDE_MODEL=claude-sonnet-4-6 # optional
weave-cli demo consolidate # reflect step now uses Claude
weave-cli demo write /tmp/foo.md # verdict now uses Claudeweave/pro/llm.py 选择器会在设置 ANTHROPIC_API_KEY 时选择 anthropic_llm，否则回退到 mock_llm。代码路径完全相同；只有分类器会切换。
层 | 内容 | 必需？ |
引擎运行时 | Python ≥ 3.11； | 是 |
AI ↔ 保险库 | Claude Desktop、Cowork 或任何注册了 | 是 |
人 ↔ 保险库 | 任何 markdown 编辑器。推荐 Obsidian，因为它提供原生 wikilink + 反向链接图谱体验，但不是必需的。 | 推荐 |
模式 4 和 5 的实时模式 | 导出 | 可选 |
安装后，weave-cli doctor 会验证完整的技术栈——引擎、保险库、环境，以及可选的 Claude Desktop MCP 接线（使用 --check-mcp）。
诚实地列出尚不完善的地方：
冲突解析器中的 TF-IDF 对短文档很脆弱。 短候选笔记即使概念上完全相同，相似度得分也很低。名称匹配旁路覆盖了大部分这种情况；真正的嵌入（例如 nomic-embed-text）才是生产路径。
PPR 每次查询都在整个图上运行，没有缓存。对于约 1,000 条笔记以下的保险库没问题；更大的库需要预计算和缓存。
整合器的模拟反思步骤是关键词分桶。 诚实的桩实现，不能替代实时 Claude 的反思过程。
实时 LLM 模式仅支持 Claude。 没有 OpenAI / Gemini / Ollama 后端——欢迎贡献。
我们正在公开积极运行的可证伪问题。欢迎预注册协议和复现尝试——请开一个 issue。
# | 问题 | 迄今的证据 | 状态 |
1 | 冲突预过滤器释义盲区 — TF-IDF 预过滤器会漏掉释义型近似重复；密集嵌入判定评分能解决这个问题吗？ | 双装置证据：释义型近似重复的相似度得分为 0.28–0.38，低于 0.35 的阈值，因此真正的重复会绕过预过滤器 | 开放 — 欢迎预注册协议 |
docs/architecture.md — 更深入的技术文档
docs/v2-switchover-guide.md — 从 v1 迁移
CHANGELOG.md — 发布历史
This server cannot be deployed
One memory, every AI. A shared, user-owned markdown memory your AI clients read and write over MCP.
Persistent memory for AI agents across Claude, ChatGPT and any MCP client.
Token-efficient MCP memory for Markdown vaults. Tiered search, GraphRAG, AI memories.
Persistent AI memory shared across Claude, ChatGPT, coding agents, and compatible MCP clients.
