LoreDocs

LoreDocs v0.1.31

你的 AI 项目知识库。井然有序、可搜索、带版本追踪。

LoreDocs 让 Claude 能持续访问项目文档——规格说明、指南、架构决策、参考文档——因此它不会在会话之间丢失上下文。支持 Claude Code、Cowork、Cursor、OpenAI Codex 和 Hermes Agent。

可直接从 Claude Code 插件市场安装，也可通过 PyPI 安装：uvx loredocs

快速开始

前置条件： uv（快速的 Python 包管理器）。

# Install uv: https://docs.astral.sh/uv/getting-started/installation/
# Clone and install
cd /path/to/loredocs
uv sync

详细安装说明请参阅 INSTALL.md。

直接使用 Claude Agent SDK？ git clone 公开仓库，并将 SDK 的本地目录插件加载器指向该仓库——仓库根目录本身就是一个完整的插件目录（.claude-plugin/plugin.json + .mcp.json）。无需也不存在单独的 SDK 可安装包。

使用 LoreDocs

Claude Code（终端）

claude --plugin-dir /path/to/loredocs

或者在现有会话中：

/plugin add /path/to/loredocs

加载后，Claude 会自动获得全部 48 个 LoreDocs MCP 工具。让 Claude“为这个项目创建一个知识库”或“查找架构文档”，它就会自行使用这些工具。

Cowork（桌面应用）

1. 点击提示词框旁边的 +
2. 选择 插件 > 添加插件
3. 浏览到 loredocs 源文件夹

共享数据库访问： Cowork 在沙盒虚拟机中运行。要访问通过 Claude Code 保存的文档，请让 Claude：

“挂载我的 ~/.loredocs 文件夹”

Hermes Agent

Hermes Agent 用户可在 ~/.hermes/config.yaml 的 mcp_servers: 下将 LoreDocs 添加为 MCP 服务（完整配置项请参阅 INSTALL.md），然后重启 Hermes。

此后，你就可以在 Hermes 会话中使用全部 48 个 LoreDocs MCP 工具。

Hermes 信息披露

在 Hermes Agent 中使用 LoreDocs 时：

• 安装： 首次运行时会通过 uvx 从 PyPI 下载你指定版本的 loredocs。不会自动更新。
• 数据存储： 所有知识库数据都以 SQLite 格式存储在本地 ~/.loredocs/。不会向云服务或外部服务发送任何数据。
• Pro 许可证验证： Pro 版激活时会使用离线 Ed25519 加密技术验证许可证密钥。验证期间不会发起网络请求。
• 遥测： LoreDocs 不会收集或传输遥测数据或使用数据。
• 网络调用： Pro 语义搜索首次使用时会从 Hugging Face 下载一次 BAAI/bge-small-en-v1.5 嵌入模型。可选的 Notion 导入功能会使用你提供的令牌调用 Notion API。LoreDocs 不会进行其他网络调用。

工作原理

LoreDocs 将知识整理到知识库中——知识库是用于存放相关文档的命名容器。每个知识库都可以存放规格说明、指南、决策、检查清单，或任何你希望 Claude 记住的文本。

~/.loredocs/loredocs.db          <-- SQLite database (metadata, search index)
~/.loredocs/vaults/<vault-id>/   <-- Document files on disk

核心概念：

• 知识库按项目或主题归类相关文档
• 文档是带有元数据（标签、类别、优先级、备注）的文本文件
• 版本历史追踪每份文档的每一次更改
• 全文搜索通过 SQLite FTS5 即时查找任何内容
• 注入按需将知识库内容加载到 Claude 的上下文中

你的数据始终可用

MCP 工具可用时，LoreDocs 会通过这些工具运行；不可用时，则会自动回退到内置脚本。无论 MCP 状态如何，你的知识库文档都安全无虞——添加、搜索和检索操作在两种情况下都能正常进行。你无需进行任何配置；插件技能会在后台静默切换。

验证安装

安装后，让 Claude 执行以下操作，以验证 LoreDocs 是否正常工作：

“运行 vault_list 并显示结果。”

如果你看到知识库列表（如果是首次使用，也可能是空列表），则说明 LoreDocs 已连接。如果出现缺少工具的错误，请重新运行 uv sync 并重新加载插件。

推荐的 CLAUDE.md 设置

为获得最佳体验，请将以下代码片段添加到 ~/.claude/CLAUDE.md（全局配置）或项目的 CLAUDE.md 中。这样可以告诉 Claude 如何在各个会话中以一致的方式使用 LoreDocs。

## LoreDocs (persistent project knowledge)

At session start:
1. Call `vault_list` to see available knowledge vaults.
2. Call `vault_inject_summary` for any vaults relevant to the current project.
3. Use this context to understand project architecture, decisions, and reference docs.

During the session:
- If you create significant documentation, add it to LoreDocs with `vault_add_doc`.
- Tag documents for easy cross-vault discovery with `vault_tag_doc`.

At session end:
- If new docs were created or updated, ensure they are stored in LoreDocs for future sessions.

Cowork 用户须知： Cowork 不会自动运行钩子。请在项目的 CLAUDE.md 中添加说明，要求在会话开始时调用 vault_list 和 vault_inject_summary。

项目的权威知识

在多 Agent 环境中，不同的工具和 Agent 经常会为共享技能或配置内容临时创建副本——例如操作手册、风格指南和共享参考文档。这些副本会逐渐偏离。一个 Agent 更新了源文件，另一个却仍在读取过时的副本。同一项目中的两个 Agent 最终依据不同的知识开展工作，却没有明显迹象表明出了问题。

LoreDocs 通过将知识库设为所有 Agent 读取的唯一权威来源来避免这一问题。每个 Agent 不再加载本地文件副本，而是在会话开始时调用 vault_inject_by_tag，获取由知识库管理的相同版本。

推荐模式

将共享内容（操作手册、团队指南、共享规范）存储为知识库文档，而不是存为 Agent 会复制或镜像的本地文件。

Agent 在会话开始时加载内容：

vault_inject_by_tag: team-playbook

所有 Agent——无论使用何种界面（Claude Code、Cowork、命令行或任何未来的 AI 工具）——都会调用同一个知识库并获取相同的最新版本。更新内容时只需编辑一次知识库文档；所有 Agent 都会在下次会话开始时获取更改。

本地文件（.claude/skills/、.agents/ 或特定界面的配置）只作为指针或引导存根，而不是权威内容。知识库才是唯一可信来源。

示例：在 Agent 团队中共享操作手册

# Session start for any agent on the team:
# 1. Inject the shared playbook by tag
vault_inject_by_tag("team-playbook")

# 2. Inject any project-specific reference docs
vault_inject_by_tag("project-architecture")

# Working context is now current -- no local file copies needed.

要将共享内容存入知识库（仅需一次，或每次更新时执行）：

# Store (or update) the shared playbook:
vault_update_doc(vault="team-knowledge", doc_id="playbook-id", content=open("PLAYBOOK.md").read())

# Or add it fresh (path= reads directly from disk -- no need to load into context):
vault_add_doc(vault="team-knowledge", name="Team Playbook", path="/absolute/path/to/PLAYBOOK.md", tags=["team-playbook"])

任何调用 vault_inject_by_tag("team-playbook") 的 Agent 都会读取同一份文档。没有副本，没有镜像，也不会出现偏差。

套餐：免费版与 Pro 版

LoreDocs 采用本地优先模式，可免费使用。Pro 版（$9/月）取消存储限制，并解锁语义（基于含义的）检索。无论使用哪个套餐，所有内容都在你的设备上运行——Pro 版不会添加任何云端组件。

	免费版	Pro 版（$9/月）
知识库数量	3	不限
每个知识库的文档数	50	不限
存储空间	500 MB	不限
每个文档的版本历史	5 个版本	不限
全文搜索（FTS5）	是	是
核心 MCP 工具（创建、搜索、版本、标签、注入、导入/导出）	是	是
本地优先、无云端、无遥测	是	是
语义搜索（vault_search semantic=true、vault_rebuild_index）	--	是
基于嵌入的文档关系（vault_find_related）	仅关键词共现	关键词 + 嵌入自动链接
跨产品会话链接（vault_link_session + 另外 2 个）	--	是（也需要 LoreConvo Pro）

升级至 Pro 版——$9/月

结账后，许可证密钥会自动发送到你结账时使用的邮箱地址，通常几分钟内即可收到。有疑问请联系：[email protected]。

免费版的使用上限会在写入前强制执行；Pro 版则取消这些限制。随时使用 vault_tier_status 查看当前套餐和用量。使用 vault_set_tier 激活 Pro 许可证。

Pro 版的语义功能使用本地嵌入模型（BGE-small-en-v1.5）和 LanceDB 索引——数据仍不会离开你的设备。

功能

• 知识库组织：按项目整理文档，并关联项目元数据
• 文档版本管理：保留完整历史记录，可回滚到任意历史版本
• 标签与分类：为文档添加标签，便于跨知识库查找
• 优先级：将文档标记为关键、高、普通或低优先级
• 全文搜索：在所有知识库和文档中快速搜索关键词
• 上下文注入：将指定文档、标签或知识库摘要加载到 Claude 的上下文中
• 批量操作：导入目录、批量添加标签、导出清单
• 文档关联：关联不同知识库中的相关文档
• 基于嵌入的文档关联（Pro）：vault_find_related 会为 Pro 用户同时返回关键词共现和基于嵌入的自动关联。使用 BGE-small-en-v1.5，余弦相似度 >= 0.75，限定在同一知识库内。若从 Pro 降级为 Free，嵌入关联会归档。
• 跨产品会话关联（Pro）：自动将知识库文档关联到最相关的 LoreConvo 会话，反之亦然。包含三个工具：vault_link_session、vault_get_session_links、vault_get_linked_sessions。需要同时拥有 LoreDocs Pro 和 LoreConvo Pro。
• 层级管理：Free/Pro 层级，并可配置限制
• 本地优先：使用 SQLite 数据库，不依赖云端，API 费用为零

MCP 工具

LoreDocs 默认提供 48 个 MCP 工具（安装 notion 扩展后为 49 个；设置 LOREDOCS_ENABLE_CAP_TOOLS=1 并安装 notion 扩展后为 50 个），按功能分类：

知识库管理（8 个工具）

工具	功能
vault_create	创建知识库并设置名称和描述
vault_list	列出所有知识库及其文档数量和大小
vault_info	获取知识库详细信息
vault_archive	归档知识库（保留数据，并从列表中隐藏）
vault_delete	永久删除知识库及其所有文档
vault_link_project	将知识库关联到项目目录
vault_open_workspace	打开或创建限定到某个目录路径的知识库
loredocs_onboard	首次安装时使用初始知识库设置工作区

文档操作（10 个工具）

工具	功能
vault_add_doc	向知识库添加新文档（内联内容或从文件路径导入）
vault_update_doc	更新文档内容（创建版本历史记录）
vault_remove_doc	从知识库中移除文档
vault_get_doc	获取文档及其完整内容
vault_list_docs	列出知识库中的文档，并支持筛选和排序
vault_copy_doc	将文档复制到另一个知识库
vault_move_doc	将文档移至另一个知识库
vault_doc_history	查看文档的版本历史记录
vault_doc_restore	将文档还原到以前的版本

搜索与发现（5 个工具）

工具	功能
vault_search	在所有知识库中进行全文搜索
vault_search_by_tag	按标签查找所有知识库中的文档
vault_find_related	查找与指定文档相关的文档（仅限 Pro）
vault_suggest	主动推荐值得加载的相关文档
vault_rebuild_index	重建 LanceDB 语义搜索索引（仅限 Pro；安装 Pro 依赖后运行一次）

组织管理（5 个工具）

工具	功能
vault_tag_doc	为文档添加标签
vault_bulk_tag	一次为多个文档添加标签
vault_categorize	设置文档类别（规范、指南、决策等）
vault_set_priority	设置文档优先级
vault_add_note	为文档添加备注或注释

上下文注入（9 个工具）

工具	功能
vault_inject	将按排名排列的知识库文档载入上下文，并控制在令牌预算内
vault_inject_by_tag	将所有匹配标签的文档载入上下文，并控制在令牌预算内
vault_inject_summary	载入知识库摘要，包含文档标题和说明
vault_prime	按优先级预先载入所有知识库文档（相当于不带查询调用 vault_inject）
vault_get_injection_cap	获取知识库注入工具的已配置令牌上限
vault_set_injection_cap	设置知识库注入令牌上限（需要 LOREDOCS_ENABLE_CAP_TOOLS=1）
vault_get_session_token	为注入工具生成每个会话的缓存键
vault_estimate_tokens	在执行注入调用前估算其使用的令牌数
vault_get_server_capabilities	报告此服务版本支持哪些注入／令牌预算功能

导入／导出（5 个工具）

工具	功能
vault_import_dir	将目录中的文件导入知识库
vault_import_notion	将 Notion 页面和数据库导入知识库（一次性导入，不会实时同步）
vault_import_notion_setup	报告 Notion 导入的就绪状态及启用方法（只读）
vault_export	将文档导出到磁盘上的文件
vault_export_manifest	将知识库元数据导出为 JSON 清单

文档链接（2 个工具）

工具	功能
vault_link_doc	在两个文档之间创建链接
vault_unlink_doc	移除文档之间的链接

管理（4 个工具）

工具	功能
vault_tier_status	检查当前套餐的限制和用量
vault_set_tier	设置启用的套餐（免费或专业版）
get_license_tier	检查当前套餐和许可证密钥状态
vault_verify	检查文档版本历史的完整性，并可选择修复

跨产品会话链接（3 个工具，专业版）

工具	功能
vault_link_session	手动创建 LoreConvo 会话与 LoreDocs 文档之间的链接
vault_get_session_links	返回链接到 LoreDocs 文档的 LoreConvo 会话
vault_get_linked_sessions	返回链接到指定 LoreConvo 会话的 LoreDocs 文档

便携式项目工作区

LoreDocs 和 LoreConvo 共同构成 一个适用于所有 Claude 的便携式项目工作区——包含会话记忆和结构化知识， 所有数据都保存在你的设备上。

• LoreConvo 会记住你讨论过什么、做过什么决定，以及有哪些未完成事项（情景记忆 + 语义记忆）
• LoreDocs 存储 Claude 所需的参考文档、规范和指南（持久知识）

云端 AI 工作区会将你绑定到单一生态系统，而 LoreConvo + LoreDocs 可用于 Claude Code、Cursor、OpenAI Codex、Hermes Agent 和 Cowork。两者都使用 SQLite 在本地存储数据， 都不会向外部服务发送任何内容。

要求

• Python 3.10+
• macOS 或 Linux
• uv 包管理器
• mcp 和 pydantic（由 uv sync 自动安装）

支持的存储底层

LoreDocs 将文档内容作为普通文件存储在磁盘上。持久性保证取决于文件系统底层：

保管库根目录位置	支持情况	保证
本地磁盘（本地卷上的 APFS、ext4、NTFS）	支持	保证有效：错误报告写入结果的底层系统可能会导致最近一次保存丢失，但绝不会破坏或损坏已写入磁盘的版本。
云同步文件夹（Dropbox、iCloud Drive、OneDrive、Google Drive）	尽力而为	最新保存的内容可能会丢失，或被同步客户端恢复。
网络挂载（SMB、NFS、sshfs）	尽力而为	建议锁可能不起作用，因此并发客户端可能会导致更新丢失。
容器绑定挂载 / WSL 跨操作系统路径	尽力而为	保证与底层文件系统相同。

当检测到保管库根目录位于已知云同步目录下时，系统会发出一次性警告。使用 LOREDOCS_SUPPRESS_SUBSTRATE_WARNING=1 可禁止此警告。

每个文档目录中的 metadata.json 文件严格由 SQLite 数据库生成——数据库才是事实来源。请勿直接编辑 metadata.json；更改会在下次更新文档时被覆盖。

版本历史完整性

LoreDocs v0.1.21+ 包含版本存储完整性功能：

• 原子写入：每次变更都使用临时文件加重命名，绝不直接写入目标路径。发生崩溃或磁盘空间不足时，现有数据不会受到影响。
• 意图日志：通过受哈希校验保护的幂等重放进行崩溃恢复。
• 五源分配器：版本号在内容文件、sidecar 文件、数据库计数器、重置标记和 highwater 之间保持单调递增。
• 差异检测：检测并报告历史丢失、跳号、回滚和缺口。发现差异时会拒绝写入；读取会继续，并通过 divergence 字段标记问题。
• 每版本 sidecar 文件：history/v{N}.meta.json 会记录每个版本的保存时间、作者、会话 ID、更改说明和操作类型。
• 保留轮换：免费版为每个文档保留 5 个版本；Pro 保留 100 个。最旧的版本会自动轮换（绝不重新编号）。
• vault_verify：用于报告完整性问题并可执行仅增量修复的诊断工具。升级 LoreDocs 前，请运行 vault_verify --pre-upgrade 检查旧版保管库是否存在异常。

数据与隐私

LoreDocs 采用本地优先模式。所有数据都存储在你计算机上的 ~/.loredocs/ 中。

• **收集的数据：**存储文档时由你提供的文档名称、内容、标签、类别和保管库名称。不会自动收集遥测数据、使用分析数据或标识符。
• **存储：**SQLite 数据库位于 ~/.loredocs/loredocs.db；文档文件位于 ~/.loredocs/vaults/。不使用云存储。使用 LOREDOCS_ROOT 环境变量可覆盖根目录。
• **第三方共享：**无。数据绝不会离开你的计算机。
• **保留：**数据会一直保留，直到你通过 vault_remove_doc、vault_delete 删除，或手动移除数据库文件。不会自动过期。
• **联系方式：**[email protected]

完整隐私政策：https://labyrinthanalyticsconsulting.com/privacy

故障排查

在 Claude Code 中看不到 MCP 工具？ 请先确保运行了 uv sync。虚拟环境必须存在，且已安装依赖项。

出现“没有名为 'mcp' 的模块”错误？ .mcp.json 指向虚拟环境中的 Python。如果你移动了文件夹，请重新运行 uv sync。

Cowork 看不到在 Code 中保存的文档？ 请让 Claude“挂载我的 ~/.loredocs 文件夹”，这样 Cowork 就能访问共享数据库。

备用脚本（直接访问数据库）

如果 MCP 服务无法访问（例如在计划任务或自动化脚本中），scripts/query_loredocs.py 可直接对 SQLite 数据库执行相同的核心操作。

# List all vaults
python scripts/query_loredocs.py --list

# Show vault details and document manifest
python scripts/query_loredocs.py --info "My Project Docs"

# Search documents across all vaults
python scripts/query_loredocs.py --search "architecture"

# Add a document to a vault
python scripts/query_loredocs.py --add-doc \
    --vault "My Project Docs" \
    --name "Architecture Overview" \
    --file docs/architecture.md \
    --tags '["architecture", "design"]'

# Add a document from stdin (type content, then Ctrl-D)
python scripts/query_loredocs.py --add-doc \
    --vault "My Project Docs" \
    --name "Quick Note" \
    --stdin <<'EOF'
# Quick Note
EOF

脚本会自动查找位于 ~/.loredocs/loredocs.db 的数据库（也可以显式传入 --db-path）。它会写入与 MCP 工具相同的架构，包括 FTS 索引和磁盘文件存储。

更新内容

v0.1.31（2026-10-16）

安全性

• 将 MCP 库（mcp[cli]）从 1.28.1 更新到 1.30.0，以修复 CVE-2026-59951。现在启动兼容性检查要求使用 1.30.0。

改进

• 语义搜索会在每个进程中加载一次嵌入模型并共享它，从而减少内存 使用量和重复加载时间。

查看完整的 更新日志，了解完整的发布历史。

许可证

Business Source License 1.1（BSL 1.1）- Labyrinth Analytics Consulting

个人／非商业用途免费（最多 3 个知识库）。商业用途需要付费许可证。将于 2030-03-31 转换为 Apache 2.0。详情请参阅 LICENSE。

mcp-name: io.github.labyrinth-analytics/loredocs