企业官网建设流程全解析

使用 Klavis 仓库中的 Knowledge Graph Memory MCP Server 为 AI Agent 构建持久化记忆

【免费下载链接】klavisKlavis AI: MCP integration platforms that let AI agents use tools reliably at any scale项目地址: https://gitcode.com/GitHub_Trending/kl/klavis

本篇技术指南以 Klavis 仓库内置的 Knowledge Graph Memory Server（@modelcontextprotocol/server-memory）为对象，讲解如何通过本地知识图谱为 Claude 等 AI Agent 提供跨会话持久记忆能力。读完本文，你将掌握实体、关系、观察三类核心概念，理解 8 个 MCP 工具的作用与调用契约，并能在 Claude Desktop、VS Code 中完成从安装、配置到定制记忆策略的完整落地。

为什么 AI Agent 需要记忆

大语言模型本身是无状态的：每一次会话结束后，模型都不会保留任何关于用户的偏好、项目背景或历史结论。Klavis 仓库中的这个 memory MCP Server 提供了一种轻量、可持久化的解决方案——用本地知识图谱（Knowledge Graph）作为 AI Agent 的"长期记忆"，让 Claude 等客户端在跨会话场景下仍然"记得"用户。

从源码结构看，该服务位于 mcp_servers/local/memory/，核心实现集中在 index.ts，其本质是一个运行在 stdio 传输层之上的 MCP 服务器：它用 TypeScript 基于@modelcontextprotocol/sdk构建，通过 JSONL 文件落盘，将每次会话中值得沉淀的信息写入本地，供后续会话检索。这与 MCP 生态中"工具即接口、文件即存储"的思路一致，既不需要数据库，也不需要外部服务，非常适合个人助手、轻量级 Agent 场景。

核心概念：实体、关系与观察

知识图谱由三种基本元素构成，三者共同描述了"谁是谁、与谁相关、有什么特点"。

实体（Entities）

实体是知识图谱中的主要节点，每个实体包含三个字段：

示例：

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

从源码看，实体在 index.ts 中被定义为Entity接口，并在保存时以type: "entity"标记写入 JSONL 文件。

关系（Relations）

关系定义实体之间的有向连接，始终使用主动语态（active voice）描述，例如works_at、knows、reports_to。

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

对应源码中的Relation接口（index.ts）：from是起点实体名，to是终点实体名，relationType是关系类型。保存时以type: "relation"标记落盘。

观察（Observations）

观察是附着在具体实体上的离散信息片段，具备以下特征：

• 以字符串形式存储；
• 附着于特定实体；
• 可以独立增删；
• 应当保持原子性（一条观察只表达一个事实）。

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

存储格式：JSONL

所有数据最终以JSONL（每行一个 JSON 对象）的形式持久化在memory.jsonl文件中。每次写操作都会加载整份文件、修改内存图结构并整体回写。测试 knowledge-graph.test.ts 验证了格式：实体行与关系行各占一行，首行实体带type: "entity"，次行关系带type: "relation"。文件不存在时loadGraph()会静默返回空图（index.ts）。

完整工具 API：8 个 MCP 工具详解

服务共注册 8 个工具，覆盖了知识图谱的增、删、查三类操作。以下参数说明与"忽略重复/静默失败"等边界行为均可在 index.ts 的registerTool调用及测试用例中找到依据。

创建类工具

create_entities—— 批量创建新实体。

• 输入：entities（对象数组），每个对象包含：
  • name（string）：实体标识符；
  • entityType（string）：类型分类；
  • observations（string[]）：关联的观察列表。
• 行为：自动忽略已存在的同名实体。源码中通过filter(e => !graph.entities.some(...))实现去重（index.ts），测试 knowledge-graph.test.ts 验证了重复创建返回空数组且图内实体数不变。

create_relations—— 批量创建实体间关系。

• 输入：relations（对象数组），每个对象包含：
  • from（string）：起点实体名；
  • to（string）：终点实体名；
  • relationType（string）：主动语态的关系类型。
• 行为：跳过完全重复的关系（from+to+relationType三者同时相同视为重复，index.ts）。

add_observations—— 为已有实体追加观察。

• 输入：observations（对象数组），每个对象包含：
  • entityName（string）：目标实体；
  • contents（string[]）：要新增的观察内容。
• 行为：返回每个实体的实际新增列表addedObservations；若实体不存在则直接抛错（Entity with name X not found，index.ts）。去重同样内置：已存在的观察内容不会被重复添加（测试见 knowledge-graph.test.ts）。

删除类工具

delete_entities—— 删除实体及其关联关系。

• 输入：entityNames（string[]）。
• 行为：级联删除所有from或to指向被删实体的关系（index.ts）；实体不存在时静默操作。测试 knowledge-graph.test.ts 验证了删除中间节点后相关关系被全部清空。

delete_observations—— 从实体上删除指定观察。

• 输入：deletions（对象数组），每个对象包含：
  • entityName（string）：目标实体；
  • observations（string[]）：要删除的观察内容。
• 行为：观察不存在或实体不存在时静默操作，不抛错（index.ts）。

delete_relations—— 从图中删除指定关系。

• 输入：relations（对象数组），每个对象包含from、to、relationType。
• 行为：只删除精确匹配三元组的关系；关系不存在时静默操作（index.ts）。测试 knowledge-graph.test.ts 展示了同一对实体存在多条不同关系时可定向删除其中一条。

查询类工具

read_graph—— 读取整个知识图谱。

• 输入：无。
• 行为：返回包含全部entities与relations的完整图结构（index.ts）。文件尚未创建时返回空图。

search_nodes—— 按查询关键词搜索节点。

• 输入：query（string）。
• 行为：对实体名、实体类型、观察内容三处做不区分大小写的子串匹配；返回命中实体，以及仅存在于命中实体之间的关系（index.ts）。测试 knowledge-graph.test.ts 覆盖了按名称、类型、观察内容搜索及大小写不敏感等场景。

open_nodes—— 按名称精确取回指定节点。

• 输入：names（string[]）。
• 行为：返回请求的实体及请求实体相互之间的关系；不存在的节点静默跳过（index.ts）。注意与search_nodes的区别：它不做模糊匹配，只按精确名称取节点。

安装与配置：Claude Desktop

Docker 方式

在claude_desktop_config.json中添加：

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

其中-v claude-memory:/app/dist将数据卷挂载到容器内的/app/dist目录，使记忆数据在容器重建后依然保留；--rm保证容器退出即清理。

NPX 方式

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

NPX + 自定义存储路径

服务器支持通过环境变量MEMORY_FILE_PATH指定记忆存储文件：

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

MEMORY_FILE_PATH：记忆存储 JSONL 文件的路径，默认值为服务器目录下的memory.jsonl。

从源码看，该环境变量的解析逻辑位于 index.ts 的ensureMemoryFilePath()：绝对路径按原样使用，相对路径会基于服务器安装目录拼接为绝对路径。测试 file-path.test.ts 对绝对路径、相对路径和 Windows 盘符路径均有覆盖。

此外，ensureMemoryFilePath()还内置了向后兼容迁移：若检测到旧版遗留的memory.json而新文件memory.jsonl不存在，会自动重命名迁移，并在 stderr 打印DETECTED: Found legacy memory.json file...与COMPLETED: Successfully migrated...两条提示；若两个文件同时存在则直接使用新的 JSONL 文件、不做迁移（file-path.test.ts）。

安装与配置：VS Code

一键安装（NPX / Docker）

VS Code 支持通过 MCP 安装重定向链接实现一键安装（NPX 与 Docker 各有 Stable / Insiders 两种版本），安装后会在 VS Code 中自动注册名为memory的 MCP 服务器。

手动配置

手动安装有两种方式：

方式一：用户级配置（推荐）。打开命令面板（Ctrl + Shift + P），运行MCP: Open User Configuration，在用户级mcp.json中添加服务器配置。

方式二：工作区配置。在工作区根目录创建.vscode/mcp.json并添加配置，便于与团队共享。

注意：VS Code 的配置键为servers（与 Claude Desktop 的mcpServers不同）：

NPX 方式：

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

Docker 方式：

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

关于 VS Code MCP 配置的更多细节，可查阅官方 VS Code MCP 文档中的相关章节。

用 System Prompt 驱动记忆策略

工具本身只提供"存储能力"，而"存什么、何时存"由系统提示词（System Prompt）决定。调整提示词可以让模型决定创建记忆的频率与类型。以下是针对聊天个性化场景的示例提示词，可直接放入 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

这段提示词把模型引导为一个"记忆管理员"：先识别用户、检索图谱，再按身份、行为、偏好、目标、关系五类信息决定是否沉淀，最后通过"创建实体 → 建立关系 → 写入观察"三步完成记忆更新——恰好对应create_entities、create_relations、add_observations三个工具的使用节奏。

从源码构建与自测

仓库提供了完整的构建与测试链路。首先可以运行单元测试验证核心逻辑：

cd mcp_servers/local/memory npm install npm test

测试基于 Vitest 编写（vitest.config.ts），覆盖了去重、级联删除、搜索语义、JSONL 持久化、跨实例数据保持以及旧文件迁移等关键行为。

Docker 构建方式如下：

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

仓库内的 Dockerfile 采用多阶段构建：第一阶段在node:22.12-alpine中编译 TypeScript 产出dist，第二阶段在node:22-alpine中只安装生产依赖并以node dist/index.js作为入口。

构建与升级提醒：如果此前曾用 Docker 卷存放记忆数据，旧卷中可能存在index.js文件，会被新容器覆盖。若你使用 Docker 卷存储，请在启动新容器前删除旧卷中的index.js文件。

许可证

本 MCP Server 基于MIT License开源（见仓库 LICENSE），允许自由使用、修改和分发，仅需遵守 MIT 许可条款。在 Klavis 仓库中，你可以将本服务与仓库内的其他 MCP Server 一并纳入自己的 Agent 工具集，构建具备持久记忆的完整智能体方案。

【免费下载链接】klavisKlavis AI: MCP integration platforms that let AI agents use tools reliably at any scale项目地址: https://gitcode.com/GitHub_Trending/kl/klavis