MemoryMesh

用于个人数据的通用 MCP 中心。本地优先，默认私有，旨在成为您未来构建的智能体的记忆层。

MemoryMesh 会索引您的本地文件（未来版本将支持电子邮件、日历、浏览器历史记录和聊天记录），并通过 Model Context Protocol 将其暴露出来。任何支持 MCP 的客户端（Claude Desktop、Cursor、Claude Code 或您自己的智能体）都可以对您实际拥有的数据进行语义提问，而无需向云端发送任何字节。

它是一个中心，而不是单一用途的 RAG。传输协议、嵌入模型、解析器和分块策略都在清晰的接口后可互换，因此同一个中心可以从“搜索我的笔记”扩展到“为我的智能体操作系统记住一切”。

为什么存在这个项目

个人数据分散在数十个应用程序中。没有任何 AI 智能体能以统一、私密的方式访问所有这些数据。Anthropic 的 MCP 定义了协议；MemoryMesh 填补了连接一切的中心空白——在本地运行，并将隐私作为前提而非设置。

Related MCP server: NOUZ MCP Server

工作原理

                   ┌──────────────────────────────┐
  MCP clients ───▶ │         MemoryMesh           │
(Claude Desktop,   │  ┌────────────────────────┐  │
 Cursor, agents)   │  │ MCP Tools (FastMCP):   │  │
                   │  │  search_memory         │  │
                   │  │  list_sources          │  │
                   │  │  get_document          │  │
                   │  │  index_now             │  │
                   │  └──────────┬─────────────┘  │
                   │             ▼                 │
                   │     Search Engine             │
                   │   dense + BM25 → RRF          │
                   │             │                 │
                   │   ┌─────────┴──────────┐      │
                   │   ▼                    ▼      │
                   │ ChromaDB            BM25      │
                   │ (embeddings)     (sparse)     │
                   │   ▲                    ▲      │
                   │   └──────── Indexer ───┘      │
                   │                ▲              │
                   │           Watchdog            │
                   └────────────────┬──────────────┘
                                    ▼
                             Your filesystem

索引流水线： 文件监视器检测更改 → SHA-256 去重跳过未更改的文件 → 解析器（txt/md/pdf/docx/代码） → 智能分块器（代码使用 tree-sitter，Markdown 按标题，文本递归分块） → 通过 sentence-transformers 生成嵌入 → 插入 ChromaDB + BM25 索引。

搜索流水线： 查询 → 密集搜索 (ChromaDB) + 稀疏搜索 (BM25) 过度获取 → 倒数排名融合 (RRF, k=60) → 返回包含路径、预览、分数和元数据的前 k 个结果。

有何不同

大多数同类工具只优化一个维度。MemoryMesh 是唯一同时满足以下所有维度的工具：

MCP 原生意味着它是从第一天起就为 MCP 构建的，而不是事后添加的。这 4 个工具（search_memory、list_sources、get_document、index_now）拥有稳定的 API，不会在版本更新中中断。

设计为基础设施意味着其架构预见到了多智能体访问、按智能体权限控制以及硬件智能体（ESP32、Arduino）查询同一中心的需求。请参阅 路线图。

状态

快速入门

前提条件： Python 3.11+ 和 uv。

# Install from PyPI
pip install memorymesh-mcp

或者克隆以进行开发：

# Clone and install
git clone https://github.com/kilhubprojects/memory-mesh.git
cd memory-mesh
uv sync

# Initialize state directory and copy example config
uv run memorymesh init

# Edit config.yaml — point it at the folders you want indexed
# (see Configuration section below)

# Index a folder
uv run memorymesh index ~/Documents

# Test a search
uv run memorymesh search "how did I configure the debounce"

作为守护进程运行（实时索引）

uv run memorymesh start --transport streamable-http --detach
uv run memorymesh status
# edit a file in one of your sources — it gets indexed within ~2s
uv run memorymesh search "the sentence you just typed"
uv run memorymesh stop

集成到 Claude Desktop

添加到您的 Claude Desktop 配置文件中：

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

• Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "memorymesh": {
      "command": "uv",
      "args": [
        "run",
        "--directory", "/absolute/path/to/memory-mesh",
        "memorymesh", "serve", "--stdio"
      ]
    }
  }
}

重启 Claude Desktop。这四个工具将自动出现。

MCP 工具

所有工具均向后兼容。v0.1 的签名已冻结 — 在 v0.2 中添加 extended_preview 是增量式的，不会破坏兼容性。

配置

所有配置都在 config.yaml 中。请参阅 config.example.yaml 获取带有完整注释的参考。主要亮点：

sources:
  - name: documents
    path: ~/Documents
    recursive: true
    extensions: [.txt, .md, .pdf, .docx]

  - name: projects
    path: ~/Projects
    recursive: true
    extensions: [.py, .js, .ts, .go, .rs, .md]

embeddings:
  model: all-MiniLM-L6-v2   # swap to paraphrase-multilingual-MiniLM-L12-v2 for PT/EN

search:
  mode: hybrid               # hybrid | dense | sparse
  top_k: 10

server:
  transport: stdio           # stdio | streamable-http

全局忽略列表默认保护敏感路径：.env, *.key, id_rsa*, secrets/, .ssh/, .aws/, .git/, node_modules/。

基准测试

基准测试将在 v0.2 在所有三个平台上落地 CI 后发布。目标是可复现的数据，而不是“在我机器上很快”。

脚本已在 benchmarks/ 中，可在本地运行：

• bench_indexing.py — 合成语料库上的索引吞吐量 (chunks/s, MB/s)

• bench_search_latency.py — 混合/密集/稀疏模式下的 p50/p95/p99 搜索延迟

• bench_embedding_models.py — 三种嵌入模型之间的速度与质量对比

隐私与安全

三个在版本更新中保持不变的硬性承诺：

1. 数据不出本地。 无遥测。除非您明确选择加入，否则不会进行外部 API 调用 — 即使加入，日志中也会有 WARNING 提示。

2. HTTP 监听器默认仅绑定到 127.0.0.1。 暴露给其他接口需要明确的配置覆盖。

3. 日志绝不包含明文的文档内容或查询。 审计日志记录的是查询的哈希值，而非查询本身。

静态加密在 路线图 中。如果您的磁盘在操作系统层面已加密，那么您已处于 MemoryMesh 设计的威胁模型保护之下。

路线图

详细信息请参阅 ROADMAP.md。

故障排除

• 文本文件出现 UnicodeDecodeError — MemoryMesh 会按顺序尝试 UTF-8, UTF-8 BOM, cp1252, latin-1。如果文件仍然失败，它会被记录并跳过，不会导致程序崩溃。

• 监视器在网络驱动器 / WSL 挂载上不触发 — 在 config.yaml 中设置 watcher.use_polling: true。

• 找不到 Tesseract — 请在系统层面安装它并确保其在 PATH 中。Windows 用户：UB-Mannheim 安装程序。

• 更改配置后嵌入模型不匹配 — 运行 memorymesh reindex --all。如果 ChromaDB 中存储的模型 ID 与配置不匹配，CLI 将拒绝启动。

关于本项目

MemoryMesh 是一个使用 vibe coding（与 LLM 高速紧密协作编写代码）构建的个人项目，并在每个阶段进行了结构化的架构审查。流程：LLM 提出代码，架构师审查正确性、设计缺陷和规范违规，测试套件确认。漏掉的 Bug（协调系统中的启动顺序、BM25 封装违规、CLI 中错误的构造函数参数）在运行到生产环境之前就在审查中被捕获了。

这就是当你认真对待审查步骤时 vibe coding 的样子：一个 172 个测试的套件、一个真正的混合搜索流水线、一个协调系统，以及一个旨在延续到智能体操作系统的架构。

贡献

MemoryMesh 暂不接受外部贡献 — 目前还没有 CI 或贡献指南。这将在 v0.2 中改变。请关注仓库或届时查看。

许可证

MIT。请参阅 LICENSE。

致谢

架构参考了 LlamaIndex、LangChain、PrivateGPT、AnythingLLM、MemGPT 和 Haystack 的研究 — 理解了它们各自的优缺点。感谢 chroma-mcp 和 MCP Python SDK 展示了 MCP 原生在实践中是什么样子。