基于MCP协议构建轻量级AI记忆服务器：原理、实现与集成指南

1. 项目概述：一个轻量级记忆管理MCP服务器的诞生

最近在折腾AI应用开发，特别是围绕MCP（Model Context Protocol）协议构建工具链时，发现一个挺普遍的需求：如何让AI助手拥有稳定、可控且可扩展的“记忆”能力？不是那种简单的对话历史记录，而是能够结构化存储、按需检索、跨会话持久化的记忆系统。这让我想起了开源项目thuupx/memory-mcp-lite。这个项目本质上是一个实现了MCP协议的轻量级服务器，专门用于为AI助手（比如Claude Desktop、Cursor等）提供记忆管理功能。你可以把它理解为一个专为AI打造的“外接大脑”或“智能记事本”。

这个项目解决的核心痛点在于，当前许多AI助手虽然强大，但其上下文窗口有限，且对话结束后，有价值的讨论、决策、代码片段或知识要点就“消失”了。下次再开启新会话，又得从头解释背景。memory-mcp-lite就是为了打破这个限制而生的。它通过标准化的MCP协议，让AI助手能够调用外部的工具（即这个服务器），来执行“记住这个”、“根据关键词查找我之前说过什么”等操作。这样一来，AI就能拥有超越单次会话的长期记忆，极大地提升了协作的连续性和效率。

它适合谁呢？首先是AI应用开发者，你可以将它集成到自己的AI Agent框架中，快速获得记忆能力。其次是重度AI工具使用者，比如程序员、研究员、写作者，如果你经常与Claude、Cursor等工具进行深度、长期的协作，这个工具能让你和AI的对话变得更有“积累性”，形成真正的知识库。最后，它也是对MCP协议感兴趣的学习者一个极佳的实践案例，代码清晰，功能聚焦，是理解MCP服务器如何工作的好样板。

2. 核心架构与设计思路拆解

2.1 为什么选择MCP协议？

要理解memory-mcp-lite，必须先搞懂MCP。MCP，即模型上下文协议，是由Anthropic提出的一套开放标准。它的目标是为AI模型（尤其是大语言模型）提供一个标准化的方式来发现、调用外部工具和资源。你可以把它类比为AI世界的“USB协议”或“插件系统”。在MCP之前，每个AI应用要接入外部能力（如搜索、计算、数据库），都需要定制化的集成，非常繁琐。MCP定义了统一的通信格式（JSON-RPC over stdio/SSE）、资源（Resources）和工具（Tools）模型，使得AI模型可以以一种声明式、可发现的方式使用外部功能。

memory-mcp-lite选择基于MCP构建，带来了几个显著优势：

1. 标准化与兼容性：只要宿主AI应用（如Claude Desktop）支持MCP客户端，就能无缝接入这个记忆服务器，无需为每个应用单独开发适配器。
2. 关注点分离：记忆管理的复杂性被封装在独立的服务器进程中。AI模型本身不需要关心数据如何存储、索引和检索，它只需要通过标准的MCP调用发起“记忆”或“回忆”请求。
3. 安全性：MCP服务器运行在独立的进程或环境中，与AI模型主进程隔离。记忆数据存储在用户可控的本地，避免了隐私数据上传到云端模型服务的风险。

2.2 轻量级（Lite）的设计哲学

项目名中的“Lite”是关键。这意味着它没有追求大而全的企业级记忆系统，而是聚焦于核心功能的简单、高效实现。这种设计哲学体现在以下几个方面：

1. 存储后端简单：它默认使用本地文件系统（如SQLite数据库或JSON文件）来存储记忆条目，避免了引入复杂的数据库依赖。这使得部署极其简单，开箱即用。
2. 功能聚焦：核心功能很可能围绕“增删改查”（CRUD）展开，即创建记忆、读取（搜索）记忆、更新记忆和删除记忆。它可能不会包含复杂的向量检索、语义相似度计算（至少在Lite版本中），而是采用关键词匹配、标签过滤等更轻量的检索方式。
3. 依赖最小化：项目会尽量保持依赖库的数量和体积较小，确保快速安装和低资源占用，适合在个人开发环境或边缘设备上运行。

2.3 预期的核心工作流程

基于MCP协议和项目目标，我们可以推断出其核心工作流程：

1. 启动与注册：用户启动memory-mcp-lite服务器。服务器通过stdio或SSE与AI应用（MCP客户端）建立连接，并向客户端宣告自己提供的“工具”（Tools）列表，例如create_memory,search_memories,update_memory,delete_memory。
2. 工具调用：当用户在AI助手的对话中提出需要记忆或回忆的需求时（例如，“记住我项目的API密钥是xxx”，或“我之前关于用户认证的方案是什么？”），AI模型会识别出这个意图，并选择调用对应的MCP工具。
3. 请求处理：AI应用将工具调用请求（包含参数如内容、标签、关键词等）按照MCP格式发送给memory-mcp-lite服务器。
4. 服务器执行：服务器解析请求，执行相应的业务逻辑（如将记忆内容写入数据库，或从数据库中执行查询）。
5. 结果返回：服务器将执行结果（成功状态、或查询到的记忆列表）格式化为MCP响应，返回给AI应用。
6. 内容呈现：AI应用将结果嵌入到模型的上下文中，模型再组织语言将记忆操作的结果告知用户。

这个流程将AI的“思考”与具体的“记忆操作”解耦，形成了一个清晰、可扩展的架构。

3. 核心功能与接口深度解析

虽然我们没有看到thuupx/memory-mcp-lite的具体源码，但根据其项目定位和MCP规范，我们可以深入探讨其必须实现的核心功能模块，以及这些功能如何通过MCP工具（Tools）和资源（Resources）暴露出来。

3.1 记忆的数据模型设计

一个记忆条目（Memory Item）应该包含哪些信息？这是设计的基础。一个合理的设计可能包括：

实操心得：在tags的设计上，我建议支持空格分隔的字符串输入（如“project-api auth-design”），并在服务器端自动分割为数组存储。这样对用户（AI）更友好。同时，可以考虑内置一些系统标签，如#auto-gen（由AI自动创建的记忆）和#user-provided（用户明确要求创建的）。

3.2 MCP工具（Tools）定义

MCP服务器通过工具来提供能力。memory-mcp-lite至少需要提供以下工具：

1. create_memory

   • 描述：创建一条新的记忆。
   • 输入参数：
     • content(string, required): 记忆内容。
     • tags(array of strings, optional): 关联标签。
     • summary(string, optional): 自定义摘要。若为空，服务器可尝试自动生成（Lite版可能省略此功能）。
   • 返回结果：成功创建的记忆条目ID及状态。

2. search_memories

   • 描述：根据条件搜索记忆。
   • 输入参数（设计检索方式是核心）：
     • query(string, optional): 关键词全文搜索，在content和summary中匹配。
     • tags(array of strings, optional): 按标签精确过滤。
     • limit(integer, optional): 返回结果数量上限。
     • offset(integer, optional): 用于分页。
   • 返回结果：符合条件的内存条目列表，按相关性或时间排序。

3. update_memory

   • 描述：更新已存在的记忆内容或元数据。
   • 输入参数：
     • id(string, required): 要更新的记忆ID。
     • content(string, optional): 新的内容。
     • tags(array of strings, optional): 新的标签集合（注意：是覆盖而非追加，除非设计为增量更新）。
   • 返回结果：更新后的记忆条目。

4. delete_memory

   • 描述：删除一条记忆。
   • 输入参数：
     • id(string, required): 要删除的记忆ID。
   • 返回结果：删除操作的成功状态。

注意事项：在MCP协议中，工具的参数需要使用JSON Schema进行严格定义。这不仅能帮助AI模型更好地理解如何调用工具，也能在服务器端进行有效的参数验证。例如，tags参数应定义为{“type”: “array”, “items”: {“type”: “string”}}。

3.3 存储层实现选择

“Lite”体现在存储上，通常有以下几种选择：

1. SQLite：这是最平衡的选择。它是一个单文件、零配置的数据库，支持完整的SQL查询，性能对于个人使用绰绰有余。可以轻松实现复杂的查询（如多标签AND/OR查询、按时间排序、关键词模糊匹配）。memory-mcp-lite很可能采用此方案。
2. 本地JSON文件：更简单，但不适合频繁读写和复杂查询。当记忆条目成千上万时，每次操作都读写整个文件会非常低效。仅适用于原型验证或极轻量的使用。
3. 内存存储（带持久化）：启动时将数据从文件加载到内存，所有操作在内存中进行，定期或退出时保存到文件。速度快，但存在数据丢失风险（如进程崩溃）。

我的建议与理由：对于这样一个旨在“可靠记忆”的工具，SQLite是首选。它提供了ACID事务保证，确保记忆不会在写入中途损坏。我们可以这样设计表结构：

CREATE TABLE memories ( id TEXT PRIMARY KEY, content TEXT NOT NULL, summary TEXT, tags TEXT, -- 存储为JSON数组字符串，如 '["project", "bug"]' created_at DATETIME DEFAULT CURRENT_TIMESTAMP, last_accessed_at DATETIME DEFAULT CURRENT_TIMESTAMP ); -- 为了支持按标签高效查询，可以创建一张关联表，但Lite版也可用JSON函数查询

使用SQLite的json_each函数或简单的LIKE查询（WHERE tags LIKE '%\"project\"%'）可以实现基本的标签过滤，在数据量不大时完全可行。

4. 从零搭建与配置实操指南

假设我们现在要仿照memory-mcp-lite的思路，自己搭建一个最小可用的记忆MCP服务器。我们将使用Node.js环境（这是实现MCP服务器的常见选择），并选择SQLite作为存储。

4.1 项目初始化与依赖安装

首先，创建一个新的项目目录并初始化。

mkdir my-memory-mcp-server && cd my-memory-mcp-server npm init -y

安装核心依赖：

• @modelcontextprotocol/sdk：Anthropic官方的MCP服务器SDK，极大简化开发。
• sqlite3：SQLite数据库驱动。
• better-sqlite3：一个性能更好、同步API的SQLite库，更适合此类应用。

npm install @modelcontextprotocol/sdk better-sqlite3

4.2 构建MCP服务器骨架

创建一个server.js文件，开始搭建服务器骨架。

const { Server } = require('@modelcontextprotocol/sdk/server/index.js'); const { StdioServerTransport } = require('@modelcontextprotocol/sdk/server/stdio.js'); const Database = require('better-sqlite3'); // 1. 初始化数据库 const db = new Database('memories.db'); db.exec(` CREATE TABLE IF NOT EXISTS memories ( id TEXT PRIMARY KEY, content TEXT NOT NULL, summary TEXT, tags TEXT, created_at DATETIME DEFAULT CURRENT_TIMESTAMP, last_accessed_at DATETIME DEFAULT CURRENT_TIMESTAMP ) `); // 2. 创建MCP服务器实例 const server = new Server( { name: 'my-memory-mcp-server', version: '0.1.0', }, { capabilities: { tools: {}, // 我们将在后面添加工具 }, } ); // 3. 定义工具（此处先留空，后续填充） // ... 工具处理逻辑将在这里添加 // 4. 设置传输层并启动服务器 async function main() { const transport = new StdioServerTransport(); await server.connect(transport); console.error('Memory MCP server running on stdio...'); } main().catch((error) => { console.error('Server error:', error); process.exit(1); });

这个骨架完成了三件事：初始化数据库、创建MCP服务器实例、准备通过标准输入输出与客户端通信。console.error用于输出日志，因为标准输出（stdout）需要用于MCP协议通信。

4.3 实现核心工具处理逻辑

现在，我们在server.js中为之前定义的四个工具添加处理逻辑。我们需要使用server.setRequestHandler来处理工具调用。

首先，添加一些工具函数（在定义服务器之后，启动之前）：

// 工具函数：生成唯一ID function generateId() { return `${Date.now()}-${Math.random().toString(36).substr(2, 9)}`; } // 工具函数：标准化标签输入（字符串转数组，去重，去空） function normalizeTags(tagsInput) { if (!tagsInput) return JSON.stringify([]); let tagsArray; if (typeof tagsInput === 'string') { tagsArray = tagsInput.split(/\s+/).filter(t => t.trim() !== ''); } else if (Array.isArray(tagsInput)) { tagsArray = tagsInput; } else { tagsArray = []; } // 去重并排序，便于比较和存储 const uniqueTags = [...new Set(tagsArray.map(t => t.trim().toLowerCase()))].sort(); return JSON.stringify(uniqueTags); }

然后，注册create_memory工具：

server.setRequestHandler( // 指定处理工具调用请求 'tools/call', async (request) => { if (request.params.name === 'create_memory') { const { content, tags, summary } = request.params.arguments || {}; if (!content) { throw new Error('Content is required to create a memory.'); } const id = generateId(); const normalizedTags = normalizeTags(tags); const stmt = db.prepare( 'INSERT INTO memories (id, content, summary, tags) VALUES (?, ?, ?, ?)' ); stmt.run(id, content, summary || '', normalizedTags); return { content: [ { type: 'text', text: `Memory created successfully with ID: ${id}`, }, ], }; } // ... 后续会在这里添加其他工具的判断 } );

接着，注册search_memories工具： 这是一个重点，我们需要实现一个简单但有效的检索。假设我们支持关键词query在content和summary中模糊匹配，并支持tags过滤。

// 在 `tools/call` 的 handler 中添加 `else if` 分支 else if (request.params.name === 'search_memories') { const { query, tags, limit = 10 } = request.params.arguments || {}; let sql = 'SELECT * FROM memories WHERE 1=1'; const params = []; // 关键词查询 (LIKE 模糊匹配) if (query && query.trim()) { // 注意：LIKE 查询在数据量大时可能慢，需要FTS。这里为Lite版演示。 sql += ' AND (content LIKE ? OR summary LIKE ?)'; const likeTerm = `%${query.trim()}%`; params.push(likeTerm, likeTerm); } // 标签过滤 (使用 JSON 函数，假设tags字段存储的是JSON数组字符串) if (tags && Array.isArray(tags) && tags.length > 0) { // 这是一个简化的实现：检查tags字段是否包含所有提供的标签。 // 更严谨的做法是使用json_each，但查询会复杂。 // 这里我们使用一种简单方法：确保每个标签都能在tags字符串中找到。 const lowerTags = tags.map(t => t.toLowerCase()); lowerTags.forEach(tag => { sql += ' AND tags LIKE ?'; params.push(`%\"${tag}\"%`); // 搜索JSON字符串中的标签 }); } sql += ' ORDER BY last_accessed_at DESC LIMIT ?'; params.push(limit); const stmt = db.prepare(sql); const memories = stmt.all(...params); // 更新最后访问时间 const updateStmt = db.prepare('UPDATE memories SET last_accessed_at = CURRENT_TIMESTAMP WHERE id = ?'); memories.forEach(mem => updateStmt.run(mem.id)); return { content: [ { type: 'text', text: memories.length > 0 ? `Found ${memories.length} memory(s):\n` + memories.map(m => `- [${m.id}] ${m.summary || m.content.substring(0, 50)}...`).join('\n') : 'No memories found matching your criteria.', }, ], }; }

最后，补充update_memory和delete_memory工具：

else if (request.params.name === 'update_memory') { const { id, content, tags } = request.params.arguments || {}; if (!id) throw new Error('Memory ID is required for update.'); const updates = []; const params = []; if (content !== undefined) { updates.push('content = ?'); params.push(content); } if (tags !== undefined) { updates.push('tags = ?'); params.push(normalizeTags(tags)); } if (updates.length === 0) { throw new Error('No fields provided to update.'); } params.push(id); // WHERE id = ? const sql = `UPDATE memories SET ${updates.join(', ')}, last_accessed_at = CURRENT_TIMESTAMP WHERE id = ?`; const stmt = db.prepare(sql); const result = stmt.run(...params); if (result.changes === 0) { throw new Error(`Memory with ID ${id} not found.`); } return { content: [{ type: 'text', text: `Memory ${id} updated successfully.` }], }; } else if (request.params.name === 'delete_memory') { const { id } = request.params.arguments || {}; if (!id) throw new Error('Memory ID is required for deletion.'); const stmt = db.prepare('DELETE FROM memories WHERE id = ?'); const result = stmt.run(id); if (result.changes === 0) { throw new Error(`Memory with ID ${id} not found.`); } return { content: [{ type: 'text', text: `Memory ${id} deleted successfully.` }], }; }

4.4 向客户端宣告工具列表

服务器需要告诉客户端它提供了哪些工具。这通过实现tools/list请求来完成。

server.setRequestHandler('tools/list', async () => { return { tools: [ { name: 'create_memory', description: 'Create a new memory entry with content and optional tags.', inputSchema: { type: 'object', properties: { content: { type: 'string', description: 'The main content to remember.' }, tags: { type: 'array', items: { type: 'string' }, description: 'Optional tags for categorization (e.g., ["project-x", "api-key"]).' }, summary: { type: 'string', description: 'Optional short summary of the content.' }, }, required: ['content'], }, }, { name: 'search_memories', description: 'Search for memories based on keywords and/or tags.', inputSchema: { type: 'object', properties: { query: { type: 'string', description: 'Keywords to search in content and summary.' }, tags: { type: 'array', items: { type: 'string' }, description: 'Filter memories that have ALL of these tags.' }, limit: { type: 'number', description: 'Maximum number of results to return.', default: 10 }, }, }, }, // 类似地，定义 update_memory 和 delete_memory 的 schema { name: 'update_memory', description: 'Update an existing memory\'s content or tags.', inputSchema: { type: 'object', properties: { id: { type: 'string', description: 'The unique ID of the memory to update.' }, content: { type: 'string', description: 'New content (optional).' }, tags: { type: 'array', items: { type: 'string' }, description: 'New set of tags (optional, replaces existing tags).' }, }, required: ['id'], }, }, { name: 'delete_memory', description: 'Permanently delete a memory by its ID.', inputSchema: { type: 'object', properties: { id: { type: 'string', description: 'The unique ID of the memory to delete.' }, }, required: ['id'], }, }, ], }; });

至此，一个具备基本CRUD功能的记忆MCP服务器就完成了。你可以通过node server.js启动它。但要让AI客户端（如Claude Desktop）使用它，还需要进行配置。

5. 客户端配置与集成实战

不同的MCP客户端配置方式不同。这里以目前最流行的Claude Desktop为例。

5.1 配置Claude Desktop接入自定义MCP服务器

Claude Desktop允许通过配置文件添加自定义的MCP服务器。配置文件通常位于：

• macOS:~/Library/Application Support/Claude/claude_desktop_config.json
• Windows:%APPDATA%\Claude\claude_desktop_config.json
• Linux:~/.config/Claude/claude_desktop_config.json

如果文件不存在，就创建它。配置内容如下：

{ "mcpServers": { "my-memory-server": { "command": "node", "args": ["/ABSOLUTE/PATH/TO/YOUR/my-memory-mcp-server/server.js"], "env": { // 可以在这里传递环境变量，比如数据库路径 } } } }

重要提示：必须使用Node.js的绝对路径。你可以通过终端输入which node来找到它。同样，server.js的路径也必须是绝对路径。

配置完成后，重启Claude Desktop。如果配置正确，在新建会话时，你应该能在界面中看到可用的工具（通常在输入框附近有一个工具图标）。点击后，应该能看到create_memory,search_memories等工具列表。

5.2 在对话中使用记忆工具

配置成功后，你就可以在对话中直接使用了。例如：

• 保存记忆：你可以对Claude说：“请帮我把‘项目的部署服务器SSH地址是 192.168.1.100，用户名是 deploy’ 记住，并打上#infra#deployment标签。” Claude应该会识别出这个意图，并调用create_memory工具。
• 搜索记忆：几天后，在新会话中，你可以问：“我之前保存的关于部署服务器的信息是什么？” Claude可以调用search_memories工具，查询标签包含#infra或内容包含“部署服务器”的记忆，并将结果返回给你。

5.3 其他客户端的集成思路

• Cursor IDE：Cursor也支持MCP。其配置方式可能与Claude Desktop类似，通常也是在设置文件或图形界面中添加MCP服务器命令。
• 自定义AI应用：如果你在构建自己的AI应用，可以使用MCP客户端SDK（如@modelcontextprotocol/sdk/client）来连接这个记忆服务器。流程是：启动服务器子进程 -> 通过SDK建立连接 -> 调用listTools()获取工具列表 -> 在需要时调用callTool()。

6. 性能优化与高级功能展望

基础版本已经可用，但要打造一个更健壮、更实用的memory-mcp-lite，还有不少可以优化和扩展的地方。

6.1 检索功能的增强

当前的LIKE查询在记忆条目超过几千条后性能会下降，且无法实现语义搜索。以下是优化方向：

1. 引入全文搜索（FTS）：SQLite支持FTS5扩展模块，可以为content和summary字段创建虚拟表，实现快速的全文索引和更丰富的查询语法（如前缀搜索、短语搜索）。

   CREATE VIRTUAL TABLE memories_fts USING fts5(content, summary, tags, content='memories', content_rowid='rowid'); -- 然后使用 `memories_fts` 表进行 MATCH 查询，效率远高于 LIKE。

2. 简单的语义检索（Lite版也可尝试）：虽然“Lite”，但可以集成一个轻量级的句子嵌入模型（如all-MiniLM-L6-v2，通过ONNX Runtime运行）。在创建记忆时计算内容向量的简化表示（如哈希或降维后的值）并存储。搜索时，计算查询词的向量，并在数据库中进行近似查找。这需要引入额外的依赖，但能极大提升检索质量。

6.2 数据管理与维护

1. 自动摘要生成：在create_memory时，如果用户未提供summary，可以调用一个本地轻量级文本摘要模型或简单的启发式规则（如提取前N个词）自动生成摘要，提升搜索效率。
2. 记忆去重：在创建新记忆时，可以计算其与已有记忆的相似度（如通过文本哈希或简单向量比较），如果高度相似，则提示用户是否合并或更新，而非创建重复条目。
3. 定期清理：可以实现一个后台任务或一个额外的MCP工具（如cleanup_old_memories），根据最后访问时间或创建时间，自动归档或删除非常陈旧的记忆，防止数据库无限膨胀。

6.3 安全性考虑

1. 输入验证与清理：对所有用户输入（来自AI模型）进行严格的验证和清理，防止SQL注入。我们使用better-sqlite3的预处理语句已经很大程度上避免了这一点，但对tags等参数的格式仍需检查。
2. 访问控制（可选）：可以为记忆条目添加scope或namespace字段。服务器启动时可以接受一个namespace参数，所有操作都限定在该命名空间内。这样可以为不同项目或不同AI助手实例隔离记忆。
3. 数据库加密：如果记忆内容敏感，可以考虑使用SQLite的加密扩展（如SQLCipher）来加密数据库文件。

7. 常见问题与故障排查实录

在实际部署和使用过程中，你可能会遇到以下问题。这里记录了我踩过的一些坑和解决方法。

7.1 服务器启动失败或客户端无法连接

7.2 工具调用无响应或报错

7.3 性能与数据问题

7.4 一个关键的实操心得：关于工具描述的“咒语工程”

让AI模型准确地调用你的工具，一半靠代码，一半靠“描述”。MCP工具的description和参数的description字段，就像是给AI的“使用说明书”。写得好，AI调用得精准；写得模糊，AI就可能不理解或误用。

• 坏的描述：“搜索记忆。”
• 好的描述：“根据关键词和标签组合搜索记忆库。关键词会在记忆内容和摘要中进行模糊匹配。提供的所有标签将用于过滤，只有包含全部指定标签的记忆才会被返回。”

在参数描述中，明确说明格式和意图：

• tags:“一个字符串数组，用于分类和过滤记忆，例如 ['work', 'urgent']。提供多个标签时，将只返回同时包含所有这些标签的记忆。”

通过精心设计这些描述，你可以极大地提升AI助手使用你记忆服务器的体验，减少不必要的来回澄清。这可能是开发MCP工具时最容易忽视但效果最显著的一个技巧。