Memory

知识图谱记忆服务

使用本地知识图谱实现的基础持久化记忆。这样 Claude 就能在不同聊天中记住关于用户的信息。

已在 npm 上发布为 @modelcontextprotocol/server-memory。

核心概念

实体

实体是知识图谱中的主要节点。每个实体包含：

• 唯一名称（标识符）
• 实体类型（例如“person”“organization”“event”）
• 观察列表

示例：

{
  "name": "John_Smith",
  "entityType": "person",
  "observations": ["Speaks fluent Spanish"]
}

关系

关系定义实体之间的有向连接。关系始终以主动语态存储，用于描述实体如何交互或彼此关联。

示例：

{
  "from": "John_Smith",
  "to": "Anthropic",
  "relationType": "works_at"
}

观察

观察是关于某个实体的离散信息片段。它们：

• 以字符串形式存储
• 附属于特定实体
• 可以独立添加或删除
• 应当是原子性的（每条观察只包含一个事实）

示例：

{
  "entityName": "John_Smith",
  "observations": [
    "Speaks fluent Spanish",
    "Graduated in 2019",
    "Prefers morning meetings"
  ]
}

API

工具

• create_entities

  • 在知识图谱中创建多个新实体
  • 输入：entities（对象数组）
    • 每个对象包含：
      • name（字符串）：实体标识符
      • entityType（字符串）：类型分类
      • observations（string[]）：关联的观察
  • 忽略名称已存在的实体（以及同一次调用中较早出现过的重复名称）；不会添加它们的观察
  • 返回已创建的实体。如果有实体被跳过，结构化结果还会在 skipped 中列出其名称，并添加第二条文本说明哪些实体被跳过（使用 add_observations 扩展现有实体）

• create_relations

  • 在实体之间创建多个新关系
  • 输入：relations（对象数组）
    • 每个对象包含：
      • from（字符串）：源实体名称
      • to（字符串）：目标实体名称
      • relationType（字符串）：以主动语态表示的关系类型
  • 跳过重复关系
  • 如果源实体或目标实体不存在，则失败

• add_observations

  • 为现有实体添加新观察
  • 输入：observations（对象数组）
    • 每个对象包含：
      • entityName（字符串）：目标实体
      • contents（string[]）：要添加的新观察
  • 返回每个实体新增的观察
  • 如果实体不存在，则失败

• delete_entities

  • 删除实体及其关系
  • 输入：entityNames（string[]）
  • 级联删除相关关系
  • 如果实体不存在，不会报错；响应会报告未找到的名称

• delete_observations

  • 删除实体中的特定观察
  • 输入：deletions（对象数组）
    • 每个对象包含：
      • entityName（字符串）：目标实体
      • observations（string[]）：要删除的观察
  • 如果观察不存在，不会报错；响应会报告删除的数量

• delete_relations

  • 从图谱中删除特定关系
  • 输入：relations（对象数组）
    • 每个对象包含：
      • from（字符串）：源实体名称
      • to（字符串）：目标实体名称
      • relationType（字符串）：关系类型
  • 如果关系不存在，不会报错；响应会报告删除的数量

• read_graph

  • 读取整个知识图谱
  • 无需输入
  • 返回包含所有实体和关系的完整图谱结构

• search_nodes

  • 根据查询搜索节点
  • 输入：query（字符串）
  • 搜索范围包括：
    • 实体名称
    • 实体类型
    • 观察内容
  • 返回匹配的实体及其关系

• open_nodes

  • 按名称检索特定节点
  • 输入：names（string[]）
  • 返回：
    • 请求的实体
    • 请求实体之间的关系
  • 静默跳过不存在的节点

资源

• knowledge-graph（memory://knowledge-graph）
  • 可读的 MCP 资源，包含完整知识图谱
  • MIME 类型：application/json
  • 返回与 read_graph 相同的数据结构（实体和关系）
  • 变更工具（create_entities、create_relations、add_observations、delete_entities、delete_observations、delete_relations）会为此 URI 发送 notifications/resources/updated，因此已订阅的客户端可以看到实时变更
  • 客户端的订阅方式取决于其协议版本：2026-07-28 客户端会在 subscriptions/listen 请求的 resourceSubscriptions 中指定该 URI，并在该数据流中接收更新；2025 年代客户端则调用 resources/subscribe

协议版本

服务器会在同一进程的 stdio 上同时支持这两个协议时期。客户端的首条消息决定连接所用的协议时期：2026-07-28 客户端通过 server/discover 开始连接，并在每个请求中发送其协议版本、身份和能力；2025 年代客户端则通过 initialize 握手开始连接。两种协议下的工具和资源相同。

要求

通过 npx 运行服务器或从源代码运行时，需要 Node.js 24 或更高版本。

与 Claude Desktop 搭配使用

设置

将以下内容添加到 claude_desktop_config.json 中：

Docker

{
  "mcpServers": {
    "memory": {
      "command": "docker",
      "args": ["run", "-i", "-v", "claude-memory:/app/dist", "--rm", "mcp/memory"]
    }
  }
}

NPX

{
  "mcpServers": {
    "memory": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-memory"
      ]
    }
  }
}

在 Windows 上，使用 cmd /c 启动 npx：

{
  "mcpServers": {
    "memory": {
      "command": "cmd",
      "args": [
        "/c",
        "npx",
        "-y",
        "@modelcontextprotocol/server-memory"
      ]
    }
  }
}

使用自定义设置的 NPX

可以使用以下环境变量配置服务器：

{
  "mcpServers": {
    "memory": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-memory"
      ],
      "env": {
        "MEMORY_FILE_PATH": "/path/to/custom/memory.jsonl"
      }
    }
  }
}

在 Windows 上，使用：

{
  "mcpServers": {
    "memory": {
      "command": "cmd",
      "args": [
        "/c",
        "npx",
        "-y",
        "@modelcontextprotocol/server-memory"
      ],
      "env": {
        "MEMORY_FILE_PATH": "/path/to/custom/memory.jsonl"
      }
    }
  }
}

• MEMORY_FILE_PATH：内存存储 JSONL 文件的路径（默认值：服务器目录中的 memory.jsonl）

在多个客户端之间共享同一个内存文件

每个 MCP 客户端都会启动自己的服务器进程，因此两个使用相同 MEMORY_FILE_PATH（或都使用默认值）的客户端会由两个进程共同写入同一个文件。每个写入工具在读取、修改和保存图谱时，都会在内存文件旁创建独占锁文件 <memory file>.lock，因此不同进程的写入会依次进行，不会丢失任何写入。锁文件仅在写入期间存在，因此存放内存文件的目录必须可写（原子保存本身也要求目录可写）。

• 如果服务器在写入过程中崩溃，遗留的锁会自动移除：如果已知其进程在同一台机器上退出，则立即移除；否则，在 30 秒未刷新后移除（持有锁的服务器在工作期间每 15 秒刷新一次）。同一时间只有一个等待中的服务器可以清除过期锁，此过程由临时的 <memory file>.lock.break 文件保护。
• 如果写入在 60 秒内无法获取锁，则会报工具错误，而不会覆盖文件。
• 此锁依赖独占创建文件，本地文件系统支持此功能；不遵守此机制的网络文件系统无法通过这种方式安全共享。

VS Code 安装说明

如需快速安装，请使用下方的一键安装按钮：

如需手动安装，可使用以下任一方法配置 MCP 服务：

方法 1：用户配置（推荐） 将配置添加到用户级 MCP 配置文件中。打开命令面板（Ctrl + Shift + P），并运行 MCP: Open User Configuration。这将打开用户的 mcp.json 文件，你可以在其中添加服务配置。

方法 2：工作区配置 或者，你可以将配置添加到工作区中的 .vscode/mcp.json 文件。这样便可与他人共享配置。

如需了解 VS Code 中 MCP 配置的更多详情，请参阅 VS Code 官方 MCP 文档。

NPX

{
  "servers": {
    "memory": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-memory"
      ]
    }
  }
}

在 Windows 上，请使用：

{
  "servers": {
    "memory": {
      "command": "cmd",
      "args": [
        "/c",
        "npx",
        "-y",
        "@modelcontextprotocol/server-memory"
      ]
    }
  }
}

Docker

{
  "servers": {
    "memory": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "-v",
        "claude-memory:/app/dist",
        "--rm",
        "mcp/memory"
      ]
    }
  }
}

系统提示词

用于利用记忆的提示词取决于使用场景。更改提示词有助于模型确定创建记忆的频率和类型。

以下是一个用于聊天个性化的提示词示例。你可以在 Claude.ai Project 的“Custom Instructions”字段中使用此提示词。

Follow these steps for each interaction:

1. User Identification:
   - You should assume that you are interacting with default_user
   - If you have not identified default_user, proactively try to do so.

2. Memory Retrieval:
   - Always begin your chat by saying only "Remembering..." and retrieve all relevant information from your knowledge graph
   - Always refer to your knowledge graph as your "memory"

3. Memory
   - While conversing with the user, be attentive to any new information that falls into these categories:
     a) Basic Identity (age, gender, location, job title, education level, etc.)
     b) Behaviors (interests, habits, etc.)
     c) Preferences (communication style, preferred language, etc.)
     d) Goals (goals, targets, aspirations, etc.)
     e) Relationships (personal and professional relationships up to 3 degrees of separation)

4. Memory Update:
   - If any new information was gathered during the interaction, update your memory as follows:
     a) Create entities for recurring organizations, people, and significant events
     b) Connect them to the current entities using relations
     c) Store facts about them as observations

构建

Docker：

docker build -t mcp/memory -f src/memory/Dockerfile . 

请注意：先前的 mcp/memory 卷中包含一个 index.js 文件，新容器可能会覆盖该文件。如果你使用 Docker 卷进行存储，请在启动新容器之前删除旧 Docker 卷中的 index.js 文件。

许可证

此 MCP 服务采用 MIT 许可证。这意味着你可以自由使用、修改和分发该软件，但须遵守 MIT 许可证的条款和条件。详情请参阅项目仓库中的 LICENSE 文件。