Agent 的上下文窗口再大也装不下长期记忆。今天看一个偏工程实现的开源项目MCP Memory。它把 Google 开源的 OKF 序列化格式和 SQLite FTS5 全文搜索组合在一起做成一个标准 MCP 服务解决 Agent 的长期记忆存储与召回问题。整个方案没有 GPU 门槛不依赖外部向量数据库数据落在一个本地 SQLite 文件里轻量到可以直接嵌进个人知识库或自动化工具链。这个项目最值得关注的点有几个。一个是存储层很干净OKF 负责结构化数据的紧凑编码SQLite FTS5 负责全文索引和相关性排序同一个文件里同时完成存储和检索。另一个是接入方式走 MCP 标准协议意味着 Claude Desktop、Cursor、自研 Agent 这类支持 MCP 的客户端都能直接对接。对于万级到几十万级记忆条目的中小场景用这套组合去替代 Elasticsearch 或独立向量库成本和运维负担都会小很多。本文会从核心能力、适用场景、环境准备、安装部署、功能测试、接口调用、性能观察和常见排查几个方向展开。如果你想给 Agent 加记忆又不想引入一堆重型组件这篇文章值得看完后先收藏。1. MCP Memory 核心能力速览先给一张速览表快速判断这个项目是不是你的菜。能力项说明项目类型MCP Server面向 Agent 的长期记忆存储与检索服务存储格式Google OKF 二进制序列化负责结构化记忆数据的紧凑编码全文索引SQLite FTS5内置 BM25 相关性排序硬件门槛极低无 GPU 需求普通桌面或服务器即可数据形态本地 SQLite 文件单文件存储无独立服务进程接入方式MCP 标准协议支持 stdio是否支持 HTTP 传输以项目文档为准是否支持 API支持通过 MCP Tools/Resources 暴露给客户端调用是否支持批量任务记忆批量写入可由上层 Agent 循环调用服务端是否提供批量接口需按实际文档确认适合场景个人 Agent、本地知识库、轻量自动化任务、学习 MCP 开发数据敏感度本地存储默认数据不出本机从技术选型看这个项目走的是轻量优先路线。SQLite 是嵌入式数据库没有网络监听端口没有独立守护进程一个文件就是一个库。FTS5 是 SQLite 自带的全文字搜扩展从 SQLite 3.9.0 开始内置不需要额外编译插件。OKF 则是 Google 开源的二进制 KV 序列化格式目标是替代部分 JSON 和 MessagePack 场景提供更紧凑的编码和更快的解析速度。三者叠加后的实际效果是即使记忆条目达到十万级单个文件也能轻松承载不会像外部数据库那样需要安装、配置、维护一套环境。2. 适用场景与使用边界2.1 适合谁用MCP Memory 这类方案最适合以下这些场景。第一个人 Agent 的记忆。比如你的 Agent 需要记住用户偏好、历史对话摘要、任务执行状态、项目背景资料。这些数据特征是单机、单用户、低频写入、高频查询和 SQLite 的能力模型完全匹配。第二本地知识库检索。如果你有一批文档、笔记、代码片段想快速按关键词召回FTS5 的 BM25 排序足够用。相比向量检索关键词检索的可解释性更强不会出现语义漂移导致的莫名其妙结果。第三自动化任务的状态记录。CI/CD 流程里的构建记录、数据同步任务的断点信息、定时脚本的运行日志都可以统一存成结构化记忆用 MCP 暴露给 Agent 查询。第四想学习 MCP 服务端开发的人。这个项目的结构是典型的 MCP Server 样例通过 Tools 暴露记忆写入和检索能力通过 Resources 暴露底层数据。把它拆开看一遍基本能理解 MCP 的通信模型。2.2 不适合什么场景千万级以上的数据量。FTS5 单机跑得动但到了分布式、多副本、高可用这个层面SQLite 的定位就不合适了。纯语义相似度召回。FTS5 是关键词匹配不是 embedding。你想用找一段意思相近但字完全不沾边的话关键词检索做不到需要向量模型或混合检索。多进程高并发写入。SQLite 的写锁机制决定了它不适合像 MySQL/PostgreSQL 那样的并发写入模型。如果多个 Agent 实例同时频繁写记忆会出现database is locked。需要跨机房共享记忆的场景。单文件存储天然是单机的跨机器共享只能通过文件系统同步或额外封装网络层。2.3 合规边界Agent 记忆本质上是一份长期保存的用户行为数据。使用这类项目时要注意几点写入记忆前明确告知用户数据会被保存涉及姓名、联系方式、健康记录等个人信息时尽量脱敏后再写入如果 MCP 服务开启了 HTTP 传输必须限制监听地址避免暴露到公网发布或商用前对召回结果做人工复核防止隐私内容被不当提取。3. MCP Memory 本地部署环境准备3.1 运行环境检查清单虽然具体依赖以项目 README 为准但这类 JS/Python 生态的项目通常需要下面几项环境。检查项建议版本说明操作系统Windows 10 / macOS / Linux全平台可跑SQLite建议 3.35需要 FTS5 和 trigram tokenizer 时用新版本Node.js18如果项目是 TypeScript/JavaScript 实现Python3.10如果项目是 Python 实现包管理器npm / pnpm / pip / uv按项目实际选择MCP 客户端Claude Desktop / Cursor / VS Code 等用于体验对话级记忆调用磁盘空间初始只需几十 MB数据库文件随记忆量增长先检查系统基础环境命令行执行sqlite3 --version python3 --version node --version npm --version再确认 SQLite 是否编译了 FTS5sqlite3 :memory: SELECT sqlite_version(); SELECT * FROM pragma_compile_options WHERE compile_options LIKE ENABLE_FTS5%;正常输出会包含ENABLE_FTS5。如果使用的是系统自带旧版 SQLite建议安装新版本或使用项目自带的 SQLite 运行时。3.2 为什么不需要 GPUMCP Memory 的存储和检索路径是纯数据结构和文本索引不涉及神经网络推理。OKF 编码解码是 CPU 操作FTS5 索引构建和查询也是 CPU 操作。唯一可能用到 GPU 的场景是上层把记忆内容转成 embedding 做混合检索这在 MCP Memory 核心链路之外。所以普通笔记本、云服务器、树莓派这类设备都能跑。4. MCP Memory 安装部署与启动方式4.1 通用安装命令由于该项目的具体安装方式需要以 GitHub README 为准下面给出几种常见形态的通用模板替换为实际包名即可。如果项目通过 npm 发布npm install -g mcp-memory如果项目通过 PyPI 发布pip install mcp-memory如果选择源码运行git clone https://github.com/your-name/mcp-memory.git cd mcp-memory npm install npm run build node dist/index.js --db ./agent_memory.db注意这里的mcp-memory是演示占位名请替换成项目真实名称。源代码仓库地址也需要改成项目实际地址。4.2 命令行启动以最常见的--db指向数据库文件为例mcp-memory --db ./agent_memory.db启动后进程会等待 MCP 客户端通过 stdin/stdout 建立连接。正常日志会输出 MCP server 已就绪、数据库路径、加载的记忆条目数量等信息。如果你的客户端需要指定数据目录可以传目录参数并在目录下自动创建数据库文件。具体参数名以 README 为准。4.3 配置 Claude Desktop在claude_desktop_config.json里增加 MCP Server 配置{ mcpServers: { memory: { command: mcp-memory, args: [--db, /absolute/path/to/agent_memory.db] } } }关键点是command必须能在系统 PATH 中找到args里的数据库路径尽量用绝对路径否则会因为在不同工作目录下启动而找不到同一个文件。配置完后重启 Claude Desktop在对话里应该能看到 Memory 相关工具被加载。4.4 使用 MCP Inspector 调试MCP Inspector 是官方调试工具不需要写代码就能验证服务是否正常npx modelcontextprotocol/inspector mcp-memory --db ./agent_memory.db打开浏览器进入 Inspector 页面后可以看到 Tools、Resources、Prompts 三个面板。点击 Tools 列表里的记忆写入和检索方法直接传 JSON 参数调用这是验证服务是否可用的最快路径。5. MCP Memory 功能测试与效果验证下面给出一套完整的验证流程不依赖特定 UI按步骤执行即可判断服务是否按预期工作。5.1 用 MCP Inspector 建立连接启动 Inspector选择memory服务并连接。如果连接成功Tools 列表会展示项目暴露的记忆方法。通常一个 Agent Memory 服务会暴露以下几类操作工具语义作用典型参数remember写入一条记忆entity、content、tags、metadatarecall按关键词召回相关记忆query、top_k、filterssearch全文搜索query、offset、limitlist列出记忆列表scope、type、cursorupdate / forget更新或删除记忆id、content、fields具体工具名和参数以项目实际实现为准但语义基本一致。5.2 记忆写入测试在 Inspector 中调用记忆写入工具传入一条结构化记忆{ entity: user_10001, content: 用户偏好使用 Python 和 Vue常用开发工具是 VS Code。, tags: [preference, profile, code] }如果写入成功返回结果会包含新记忆的 id 和时间戳。这一步验证的是 OKF 序列化链路是否正常——内容会被编码后写进 SQLiteFTS5 索引同步建立。5.3 全文检索测试继续写入几条不同主题的记忆然后用检索工具召回{ query: Python, top_k: 5 }返回结果里应该包含刚才写入的偏好 Python那条记忆并且 FTS5 会给每条结果返回相关性分数。判断标准是关键词命中准确、排序合理、无重复返回。更细一点可以测试带过滤条件的召回{ query: 开发工具, top_k: 10, filters: { tags: code } }这一步验证的是 FTS5 全文搜索与结构化字段过滤的组合能力。5.4 中文检索专项测试中文检索是 FTS5 的常见坑。默认的 unicode61 分词器会把中文字符按整句切分导致用户偏好和偏好匹配不到。如果你发现中文召回效果差建议检查项目是否启用了 SQLite 3.34 的trigramtokenizer或者是否在写入时会同步生成针对中文的分词字段。标准 FTS5 表写法可以参考CREATE VIRTUAL TABLE IF NOT EXISTS memory_fts USING fts5( entity, content, tags, tokenize trigram );trigram模式对中文支持比unicode61好代价是索引体积更大。测试时可以用偏好、Python、Vue这几个词分别检索判断中文和英文的召回效果。5.5 在真实 Agent 中验证如果你用的是 Claude Desktop 或 Cursor配置好后直接在对话里说记住我平时主要用 Python 和 Vue然后新开一个会话问我之前说过用什么语言。一个正常的 MCP Memory 服务应该能把之前写入的记忆召回并作为上下文带给模型。这一步是端到端验证链路长但最能说明问题。判断成功的标准是新会话里模型能回忆起旧信息。检索结果没有张冠李戴比如把用户 A 的偏好返回给用户 B。多次查询后数据库文件大小正常增长没有异常膨胀。6. MCP Memory 接口调用与批量任务6.1 MCP 协议调用方式MCP 不是 REST API它是一个标准的客户端-服务端协议。调用工具的方式是通过 MCP 客户端 SDK 发起tools/call请求。下面用 Python 的 MCP SDK 写一个最小调用示例import asyncio from mcp import ClientSession, StdioServerParameters from mcp.client.stdio import stdio_client async def main(): server_params StdioServerParameters( commandmcp-memory, args[--db, ./agent_memory.db], envNone, ) async with stdio_client(server_params) as (read, write): async with ClientSession(read, write) as session: await session.initialize() tools await session.list_tools() print(可用工具:, [tool.name for tool in tools]) result await session.call_tool( remember, arguments{ entity: user_10001, content: 用户偏好使用 Python 和 Vue, tags: [preference] } ) print(写入结果:, result) asyncio.run(main())这段代码的关键点是command和args要与启动服务的方式一致工具名remember需要和项目实际导出的名称一致。如果项目用的是 Node.js SDK方式类似只是语言 API 不同。6.2 批量写入记忆服务端即使没有单独的批量接口上层也可以用循环调用实现批量写入。但要注意几个问题。第一SQLite 写入并发能力有限循环写入建议加小延迟避免大量并发请求打到同一个数据库文件。第二写入时带上幂等键比如任务 id、来源 id。这样失败重试时不会在数据库里塞入重复记忆。标准做法是给记忆表加唯一索引CREATE TABLE IF NOT EXISTS memories ( id INTEGER PRIMARY KEY AUTOINCREMENT, entity TEXT NOT NULL, content TEXT NOT NULL, tags TEXT, source_key TEXT UNIQUE, created_at TEXT DEFAULT CURRENT_TIMESTAMP );第三大批量导入时如果项目没有暴露批量接口可以考虑关闭 MCP 服务直接用 SQL 脚本写库再重建 FTS5 索引速度会快很多。导入完成后再启动 MCP 服务。6.3 批量召回任务批量召回常见于离线分析任务输入一批 query逐个检索记忆输出结构化结果。伪代码如下import json import requests # 这里以本地 HTTP 包装服务为例实际 MCP 调用请使用 SDK queries [Python 偏好, 项目进度, 用户联系方式] for q in queries: payload { query: q, top_k: 5 } # 替换为实际服务地址 resp requests.post(http://127.0.0.1:8080/recall, jsonpayload, timeout30) data resp.json() print(json.dumps(data, ensure_asciiFalse, indent2))批量任务最重要的是日志和失败重试。给每个 query 增加唯一任务 id写入日志失败后按指数退避重试最大重试次数 3 次最终把失败列表单独输出方便人工复核。6.4 REST 包装层如果团队习惯 REST API可以在 MCP Server 前面加一层薄薄的 HTTP 服务把 MCP 工具映射成 HTTP 端点。比如HTTP 方法路径作用POST/remember写入记忆POST/recall召回记忆GET/memories列出记忆DELETE/memories/{id}删除记忆注意这层包装需要自己做MCP Memory 项目本身不一定提供。包装层一定要做鉴权和访问控制默认绑定 127.0.0.1不要直接暴露到公网。7. 资源占用与性能观察7.1 预期资源占用由于没有 GPU 推理MCP Memory 的资源占用主要集中在 CPU 和内存上。SQLite 在进程内运行内存占用和索引加载量直接相关。刚启动时数据库文件不大内存占用可能只有几十 MB随着记忆条目增加和 FTS5 索引膨胀内存占用会逐步上升但通常远低于一个常规向量数据库服务。具体占用多少需要以本机测试为准。建议用小数据集压测写入 1 万条记忆反复查询观察内存和 CPU。这个规模下如果单条查询超过几百毫秒说明索引策略或查询写法可能有问题。7.2 性能观察方法启动 MCP 服务后用系统监控工具观察进程的 CPU 和内存。在 Linux 上可以用top或pidstat在 macOS 上用top -o mem按内存排序在 Windows 上用任务管理器。同时可以打开 SQLite CLI 直达数据库检查索引大小sqlite3 agent_memory.db执行下面的 SQL 查看各表大小SELECT name, (SELECT sum(pgsize) FROM dbstat WHERE name m.name) AS size FROM sqlite_master m WHERE type IN (table, index) ORDER BY size DESC;FTS5 索引体积通常比原始正文大一倍左右这是正常现象。如果索引膨胀得厉害考虑清理无效记忆或重建索引。7.3 降低资源占用的手段开启 SQLite WAL 模式提升读并发和写入稳定性PRAGMA journal_modeWAL;对旧记忆做归档。超过一定时间或不再活跃的记忆移出主表减少 FTS5 索引体积。写入时对 content 做摘要压缩。Agent 记忆不一定要存全量原文结构化摘要加关键实体就够了。限制单条 content 长度避免超大文本拖慢索引构建。8. MCP Memory 常见问题与排查方法问题现象可能原因排查方式解决方案MCP Server 启动即退出命令找不到或依赖缺失检查报错日志确认 PATH使用绝对路径启动重装依赖客户端连不上服务配置的 command 或 args 错误用 MCP Inspector 单独调试修正配置优先用绝对路径写入记忆失败数据库路径不可写检查目录权限调整权限或更换数据目录中文搜索没有结果FTS5 分词器不适用中文用 SQLite CLI 手动 MATCH 查询启用 trigram 或自定义分词查询报no such table数据库文件路径不一致找到实际创建的 db 文件统一 db 路径多个进程同时写入报锁SQLite 写并发冲突观察是否多进程写同一 db开启 WAL减少写并发查询结果排序不对劲BM25 参数或查询文本问题打印相关性分数检查查询语法增加过滤条件数据库文件增长过快FTS5 索引膨胀或重复写入检查表大小定期清理、VACUUM、去重重启后记忆丢失启动参数里改了 db 路径核对每次启动路径固定数据库路径重点排查思路依赖装不上先确认 Node 或 Python 版本再看项目要求的包管理器。npm 安装失败常见于网络问题切换国内 npm 镜像或 pnpm 镜像源后重试。MCP 配置不生效改完配置文件必须完全退出客户端再重启加载配置的进程不会热更新。FTS5 查询语法报错MATCH 查询里用到了特殊字符比如-、(、)。解决方案是对用户输入转义或者把查询词的引号处理好。SQLite FTS5 的正确查询示例SELECT bm25(memory_fts, 5.0) AS score, entity, content FROM memory_fts WHERE memory_fts MATCH Python NEAR Vue ORDER BY score;这个查询要求 Python 和 Vue 在文档中距离较近适合做短语组合召回。如果你只是普通关键词直接用SELECT entity, content, bm25(memory_fts) AS score FROM memory_fts WHERE memory_fts MATCH Python OR Vue ORDER BY score;9. MCP Memory 最佳实践与使用建议9.1 数据模型设计记住一个原则Agent Memory 不是关系型业务表它本质上是结构化摘要 全文原文 元数据标签的混合体。建议每条记忆包含entity记忆主体人、项目、任务都可以。content正文支持 FTS5 索引。tags标签数组用于结构化过滤。metadata来源、时间、优先级、过期时间。source_key幂等键防止重复写入。9.2 分层记忆策略对上万条记忆直接全量 FTS5 召回会影响精度。更稳的方案是三层第一层短期记忆最近 N 天的完整对话摘要写入即索引。第二层长期记忆对短期记忆做二次摘要压缩成结构化条目。第三层事实库用户基本信息、项目关键决策单独打标签优先召回。召回时先查事实库再查长期记忆最后看短期记忆。这样既保证响应速度又不会让噪音干扰核心结果。9.3 工程落地注意点第一次使用先小参数测试不要一上来就灌百万条数据。保留最小可运行配置数据库文件、配置文件、启动脚本分别归档。批量任务要加日志和失败重试不要裸奔。定期执行VACUUM参数是sqlite3 agent_memory.db VACUUM;数据备份直接拷贝.db和-wal文件。备份前最好先执行 checkpointsqlite3 agent_memory.db PRAGMA wal_checkpoint(TRUNCATE);涉及用户隐私内容时先脱敏再写入。对外提供 MCP 服务时务必加认证。9.4 和 Agent Skill 的区别MCP 管的是工具调用解决模型如何访问外部数据和系统的问题。Agent Skill 管的是能力包装通常是一段提示词加脚本模板解决模型如何完成某类任务的问题。MCP Memory 属于前者是基础设施Skill 通常构建在 MCP 之上把记忆调用封装成一种行为模式。两者不冲突反而是互补关系。10. 总结与下一步MCP Memory 这个项目最值得试的点是它证明了不用 GPU、不用向量数据库也能给 Agent 一个可用的长期记忆方案。OKF 负责结构化数据的紧凑编码SQLite FTS5 负责全文检索和 BM25 排序MCP 负责统一接入。三层叠起来就是一个跑在单文件上的轻量记忆服务。部署后建议按这样的顺序验证先启动 MCP 服务用 Inspector 连上写入几条记忆确认返回 id用关键词召回观察排序是否合理最后接 Claude Desktop 或 Cursor 做端到端对话测试。最容易踩坑的地方是 FTS5 对中文的分词支持和 MCP 配置里的数据库路径这两个问题只要提前注意基本能一次跑通。后续如果想扩展可以先从混合检索开始在 FTS5 关键词召回的基础上叠加本地 embedding 模型做向量召回最后用融合排序把两类结果合并。另一条路线是给记忆加时间衰减和过期策略让不活跃的记忆自动进入冷归档。整体来看MCP Memory 的技术选型足够克制适合作为 Agent 记忆基础设施的起点也适合作为学习 MCP 服务端开发的参考样例。