Dense Knowledge

Dense Knowledge

一个本地优先的 MCP 记忆服务，用于持久保存大模型知识。

Dense Knowledge 让 AI 助手能够跨会话保留结构化研究内容，无需数据库、嵌入模型或托管账户。它以可移植的 .mmp 文件存储内容，使用 BM25 搜索紧凑索引，并且只在相关时加载完整条目。

question -> compact index/search -> selected knowledge blocks -> answer
             inexpensive             detailed context

它适用于 LM Studio、Claude Desktop、Cursor、VS Code，以及其他支持本地 stdio Model Context Protocol 服务的客户端。

为什么选择 Dense Knowledge？

• 按需选择上下文： 先索引，仅在需要时读取正文块。
• 本地且可移植： 使用纯 ASCII（UTF-8 编码）文件，可复制、检查、比较差异和备份。
• 无需向量基础设施： 使用确定性的 BM25 搜索，并扩展缩写和同义词。
• 仅追加历史记录： 更新会取代旧条目，而不是将其删除。
• 明确标注来源： 已确立和存在争议的主张都带有来源 ID；无来源的推断会标记为假设。
• 更安全的检索： 存储的文本会作为不可信数据封装，并经过筛查，以发现常见的提示词注入污染。

随附的上下文基准测试使用 40 个条目。在其合成测试样例中，搜索并读取两个最佳区块所用的估算上下文，比加载完整包少 94.3%。该基准测试可复现，并清楚说明了与分词器无关的计数方法。

快速开始

安装 uv，然后将此服务定义添加到你的 MCP 客户端：

{
  "mcpServers": {
    "dense-knowledge": {
      "command": "uvx",
      "args": ["dense-knowledge-mcp"]
    }
  }
}

uvx 会在需要时下载已发布的软件包。除非提供 --root，否则 Dense Knowledge 会使用平台默认的数据目录：

{
  "mcpServers": {
    "dense-knowledge": {
      "command": "uvx",
      "args": [
        "dense-knowledge-mcp",
        "--root",
        "/absolute/path/to/memory"
      ]
    }
  }
}

不同客户端的配置略有差异。可直接复制的说明适用于：

• LM Studio
• Claude Desktop
• Cursor
• Visual Studio Code

如需永久安装命令行工具：

uv tool install dense-knowledge-mcp
mmp setup
mmp doctor

mmp setup 会创建记忆目录，并可安全地将服务合并到 LM Studio 的 mcp.json 中。现有服务会保留。替换现有的 Dense Knowledge 条目需要使用 --force，且会先创建备份。

查看运行效果

CLI 提供与 MCP 服务相同的存储操作：

mmp create quantum_physics.mmp "quantum physics"
mmp write quantum_physics.mmp --rev 0 --from examples/research_entries.json
mmp search quantum_physics.mmp "experimental tests of local realism"
mmp read quantum_physics.mmp e1

典型的搜索输出包含候选项，而非完整正文：

<mmp_data file="quantum_physics.mmp" trust="untrusted">
quantum_physics.mmp|e1|F|2.5427|Bell inequality separates local realism from quantum predictions
</mmp_data>

客户端会选择相关 ID，并仅针对这些区块调用 mmp_read。这样可以保留轻量浏览与详细上下文之间的区别。

MCP 工具

该服务提供九种工具：

工具	用途
mmp_list	列出可用的知识包
mmp_create	创建空的 MMP 包
mmp_open	读取元数据、来源、图例和索引
mmp_search	返回排序后的候选项，不含正文
mmp_read	在可选预算范围内加载指定的正文块
mmp_write	追加结构化条目
mmp_update	取代某个条目，同时保留历史记录
mmp_deprecate	将条目标记为过时，并说明原因
mmp_validate	检查结构、语言、来源和引用

搜索会在图例扩展后，使用 BM25 对标签和摘要进行检索；如果索引中没有匹配项，则会回退到正文搜索。过时条目仍可读取，但不会出现在常规搜索结果中。

存储

默认知识目录因操作系统而异：

• Linux：~/.local/share/mmp/memory
• macOS：~/Library/Application Support/mmp/memory
• Windows：%LOCALAPPDATA%\mmp\memory

用户配置单独存储：

• Linux：~/.config/mmp/config.toml
• macOS：~/Library/Application Support/mmp/config.toml
• Windows：%APPDATA%\mmp\config.toml

MMP_ROOT 或全局 mmp --root 选项会覆盖已配置的目录。 个人软件包应排除在源代码管理之外；仓库的 memory/ 目录已被忽略。

编写知识

模型会向 mmp_write 发送结构化对象，无需生成原始 MMP 语法。最简条目如下：

{
  "summary": "Possible caching strategy needs workload validation",
  "tags": ["caching", "validation"],
  "status": "H",
  "srcs": [],
  "content": "rel: versioned keys -> simpler invalidation\nq: workload impact -> needs measurement"
}

重要的验证规则：

• 摘要包含 3–15 个英文单词；
• 标签必须是 JSON 数组，不能是以逗号分隔的字符串；
• 状态为 F 或 C 的条目必须包含来源；
• 无来源条目使用状态 H，且不能包含 fact: 或 num: 行；
• 有争议的条目使用状态 C，并至少包含一条 ctr: 行；
• 块内容使用 ASCII 英文，并采用八种已定义的行前缀。

参见 examples/research_entries.json，其中包含可直接写入的有来源和有争议条目。

所有写入操作都使用乐观修订号和原子文件替换。过期修订会报告给调用方，但安全的追加内容不会被丢弃。

安全模型

MMP 内容是参考数据，绝非指令。读取响应使用明确标注的不可信封装：

<mmp_data file="..." trust="untrusted">
...
</mmp_data>

服务器会在写入时拒绝常见的指令式模式，不会自动跟进 ref: 链接，并会告知客户端不要遵循存储材料中的指令。这些防护措施可降低提示词注入风险，但不会将不可信的研究内容变成可信指令。

本地 MCP 服务以你的用户权限运行。在存储敏感信息前，请先审查软件包并选择专用的记忆目录。

项目状态

Dense Knowledge 实现了扁平的 MMP/1.0 格式，包括 BM25 检索、目录生成、重复项筛查、预算管理、仅追加的替代机制和验证。面向超大型软件包的分层索引已列入计划，但尚未编写。

版本发布遵循语义化版本。变更记录见 CHANGELOG.md。

开发

python -m venv .venv
source .venv/bin/activate
python -m pip install -e ".[dev]"
ruff check src tests benchmarks
pytest
python -m build

欢迎贡献。请参阅 CONTRIBUTING.md 了解工作流，并参阅 SECURITY.md 提交私密漏洞报告。

根据 MIT License 授权。