MemoryClaw MCP 服务器

关键词

内存管理向量检索本地存储多用户隔离嵌入

使用说明（Markdown 格式）

  • 项目简介 MemoryClaw MCP 服务器是一套基于 Model Context Protocol（MCP）的后端实现。它向 LLM 客户端提供统一的上下文服务能力，核心包括对内存资源的托管、对工具的注册与执行，以及对提示/模板的渲染支持。服务器通过标准的 MCP 请求/响应进行通信，默认传输采用标准输入输出（stdio），并且支持多用户隔离、向量和关键词混合检索等特性，方便将记忆、搜索与外部功能整合到 LLM 的工作流中。

  • 主要功能点

    • MCP 服务端实现：完整处理 MCP 请求、响应，提供工具列表与调用能力，支持 stdio 传输。
    • 资源管理（Memory Storage）：读取 MEMORY.md 与 memory/ 下的 md 文件，进行分块、嵌入、存储与检索。
    • 工具集 (Tools)：memory_search、memory_get、memory_store、memory_delete、memory_context、memory_add 等工具，供 LLM 调用。
    • 多用户隔离：通过 userId 实现工作区隔离（默认值为 default；支持显式传入 userId）。
    • 本地存储与索引：基于 SQLite 的 chunks、files、embedding_cache 等表，支持 FTS5 与可选向量扩展。
    • 嵌入提供者：支持 OpenAI 嵌入（需要 API Key）或测试用的 Mock 提供者。
    • 混合检索：向量检索与关键词检索结合，提供 vectorWeight 与 textWeight 的加权合并。
    • 安全性与边界：实现对路径遍历的防护、对 .md 文件及指定工作区结构的约束、文件大小上限等。
    • 自然扩展点：便于未来添加向量扩展、向量检索和上下文管理等阶段性特性。

  • 安装与运行步骤

    1. 安装依赖
      • 需要 Node.js 18 及以上版本，按照仓库中的说明安装依赖。
    2. 构建
      • 将代码构建成可执行分发包（通常使用 pnpm build）。
    3. 配置工作空间
      • 为每个使用方创建一个工作空间目录，其中包含 MEMORY.md 和 memory/ 下的 md 文件，MemoryClaw 会对这些文件进行索引和检索。
    4. 启动 MCP 服务器
      • 通过 MCP 客户端（如 n8n、其他实现）连接时需要提供一个服务器配置，其中包含 serverName、command 与 args 等信息，服务器通过 MCP 的 stdio 传输接收请求。
    5. API Key 与 Embedding
      • 如果使用 OpenAI 嵌入，需要通过环境变量 OPENAI_API_KEY 提供 API Key；若未提供有效 Key，服务器会回退到模拟实现以便测试。

  • 服务器配置（MCP 客户端使用的配置，client 不需要直接运行代码） 说明：下面的配置用于 MCP 客户端启动并连接到 MemoryClaw 的 MCP 服务器。serverName 为服务器的标识，command 与 args 指定如何启动服务器进程。请确保将 absolutePath 替换为实际路径，并根据需要配置工作空间路径。

    { "serverName": "MemoryClaw", "command": "node", "args": ["/absolute/path/to/memory-claw/packages/mcp-server/dist/cli.js", "--workspace", "/absolute/path/to/workspace"] }

    说明与注释

    • serverName: MCP 客户端用于标识和管理服务器的名称，建议与实际服务对接时保持唯一性。
    • command: 启动服务器所用的命令，MemoryClaw 使用 Node.js 运行 dist/cli.js（MCP 的入口实现）。
    • args: 命令参数，包含 --workspace 指定工作空间路径。其他参数可根据实际部署需要增加，例如指定不同的嵌入提供器或数据库路径。
    • API Key 与 embedding：若使用 OpenAI 嵌入，应通过环境变量 OPENAI_API_KEY 提供密钥（MCP 客户端本身配置不要求客户端提供 API Key，服务端在启动时会读取环境变量或配置）。

  • 基本使用方法

    • 启动后，MCP 客户端可以向 MemoryClaw 服务器发送标准的 MCP 请求（例如 memory_search、memory_store、memory_get、memory_delete、memory_context、memory_add）。
    • 通过 memory_store 保存新的内存条目，MemoryClaw 会自动建立工作区并对 MEMORY.md 与 memory/ 下的新文件进行索引。
    • 使用 memory_search 进行语义或关键词检索，MemoryClaw 将返回相关碎片及分数，LLM 可据此生成应答。
    • memory_add 支持将新信息合并到现有记忆或新建记忆条目，必要时通过嵌入计算实现向量化比较与去重。

  • 关键词 内存管理, 向量检索, 本地存储, 多用户隔离, 嵌入

  • 分类 6

服务器信息

访问项目