1. 为什么我要折腾本地记忆层接入 AgentAgent 这东西只要真上手做过一个稍微像样的项目很快就会撞到同一堵墙会话一断记忆全丢。你辛辛苦苦调教出来的偏好、上下文、历史决策在下一轮对话里荡然无存。我最早的做法是把记忆塞进 prompt 里简单粗暴但很快发现这条路走不通——token 成本飙升、上下文窗口被挤爆、检索精度还一塌糊涂。后来我把记忆抽出来做成独立的本地记忆层用文件加向量库的方式存Agent 通过工具调用去读写。这个方案能跑但每接一个新 Agent 框架就要重写一遍适配层Claude 的工具调用格式、某国产框架的 function schema、另一个平台的插件协议全是各写各的。接入成本高、复用性差这是当时最大的痛点。MCPModel Context Protocol出现之后情况变了。它本质上是一套标准化的协议把工具/资源怎么暴露给模型这件事统一了。你可以把它理解成 USB-C以前每个设备一个专用接口现在一根线通吃。我把本地记忆层包成一个 MCP Server理论上任何支持 MCP 的 Agent 都能直接接进来不用再改记忆层本身的代码。这篇东西就是记录我这次接入的完整过程怎么设计记忆层、怎么用 MCP 把它暴露出去、怎么在 Agent 侧接进来、踩了哪些坑。适合已经写过一点 Agent、想认真解决记忆问题的朋友纯小白也能看懂思路但最好有点 Python 和命令行基础。2. 整体设计记忆层与 MCP 的职责边界2.1 先想清楚记忆层到底存什么很多人一上来就想着我要做个记忆系统然后开始堆功能最后做出来一个四不像。我的经验是先把记忆按用途分层不同层用不同的存储和检索策略。我把它分成三类事实记忆Fact用户是谁、偏好什么、项目背景。这类数据量小、变更少、要求强一致我直接用 SQLite 存字段清晰查询快。情景记忆Episodic某次对话发生了什么、做了什么决策、结论是什么。这类数据量大、需要语义检索我用向量库存配合时间戳做衰减。工作记忆Working当前任务链路的临时状态比如正在处理第 3 步。这类生命周期短我直接放内存字典任务结束就清。分层的意义在于不是所有记忆都值得做向量检索。事实记忆用 SQL 精确查比向量检索又快又准情景记忆才需要语义相似度。混在一起做只会让系统又慢又乱。2.2 为什么选 MCP 而不是自己写适配层在决定用 MCP 之前我认真评估过自己写适配层的方案。结论是短期省事长期挖坑。自己写适配层的问题在于每接一个新框架你都要维护一份映射代码。框架升级了、工具调用格式变了你得跟着改。三个框架就是三份维护成本五个框架就是五份。而 MCP 把这件事标准化了记忆层只需要实现一次 MCP Server暴露标准的 tools 和 resourcesAgent 侧只要支持 MCP 就能接。这里有个概念要澄清一下热词里有人问mcp 是软件协议硬件协议那个概念叫什么来着——硬件领域对应的标准化接口概念典型的就是各种总线协议和接口标准思路是一样的用统一契约解耦生产方和消费方。MCP 在软件层面干的就是这个事。MCP 里有两个核心概念要分清概念用途我的记忆层怎么用Tools模型主动调用的动作写入记忆、检索记忆、删除记忆Resources模型可读取的数据暴露记忆统计、当前工作记忆快照Tools 是动词Resources 是名词。写入和检索是动作用 Tools查看记忆状态是读取用 Resources。这个区分很关键用错了会导致模型行为怪异。2.3 整体架构长什么样架构其实很简单三层存储层SQLite事实 向量库情景 内存工作MCP Server 层把存储层的能力包装成标准 tools/resourcesAgent 层通过 MCP 客户端连接 Server在需要时调用关键在于记忆层完全不知道 Agent 的存在。它只认 MCP 协议谁来调都一样。这就是可复用的核心——换 Agent 不用动记忆层换记忆层实现也不用动 Agent。3. 核心细节MCP Server 的工具设计3.1 工具粒度怎么切这是最容易做错的地方。我第一版设计的时候把工具切得很细add_fact、add_episodic、update_fact、search_fact、search_episodic……结果模型根本不知道该调哪个经常调错。后来我改成按意图切不按存储切。模型不需要知道底层是 SQLite 还是向量库它只需要知道我要记一件事和我要回忆一件事。所以最终工具收敛成四个remember写入一条记忆内部根据类型路由到不同存储recall检索记忆内部做混合检索精确 语义forget删除或失效某条记忆memory_stats查看记忆概况工具少而语义清晰模型调用准确率明显提升。这是血泪教训工具设计要面向模型的认知不是面向你的数据库表结构。3.2 参数设计里的坑remember这个工具的参数我改了三版。第一版要求模型传memory_typefact/episodic/working结果模型经常传错。第二版我干脆去掉类型参数让服务端根据内容自动判断——但自动判断也不准。最终方案是类型参数保留但给足默认值和枚举约束同时在工具描述里写清楚每种类型的判断标准。比如用户偏好、身份信息用 fact对话过程、决策记录用 episodic。描述写清楚了模型判断准确率就上来了。另一个坑是时间戳。我一开始让模型传时间结果它经常传错格式。后来改成服务端自动打时间戳模型不用管。凡是服务端能确定的信息就不要让模型传这是减少错误的基本原则。3.3 检索策略混合检索才是正解纯向量检索的问题在于它对精确匹配不敏感。用户问我上次说的那个项目叫什么来着向量检索可能召回一堆语义相近但不对的结果。纯关键词检索又抓不住语义。我的做法是混合检索先用关键词/元数据过滤缩小范围再做向量相似度排序。具体流程如果查询里有明确实体项目名、人名先做精确匹配精确匹配结果不足时补充向量检索两路结果按加权分数合并排序按时间衰减调整最终分数时间衰减这块我用的是指数衰减score base_score * exp(-λ * days_ago)。λ 取 0.01 左右意味着一个月前的记忆权重降到约 0.74。这个参数不是拍脑袋定的是根据实际使用中多久之前的记忆还有参考价值调出来的。4. 实操从零把记忆层接进 Agent4.1 环境准备与依赖我用的技术栈很朴素不追求花哨python 3.11 mcp # MCP 官方 SDK sqlite3 # Python 内置 chromadb # 轻量向量库本地跑够用 sentence-transformers # 本地 embedding 模型选 chromadb 而不是更重的方案是因为本地记忆层不该有外部依赖。它要能在离线环境跑要能单机部署要启动快。chromadb 支持本地持久化够用。embedding 模型我用的是多语言小模型本地推理不依赖外部 API——记忆数据是隐私敏感数据不该往外发。安装就一行pip install mcp chromadb sentence-transformers4.2 存储层实现要点SQLite 部分没什么好说的建两张表facts和episodics。关键是给每条记忆加一个importance字段写入时由模型或规则打分检索时参与排序。这个字段的价值在于有些记忆天生重要比如用户是素食主义者不该被时间衰减冲淡。向量库部分我每条记忆存三样东西原文、embedding、元数据时间戳、类型、importance。检索时先按元数据过滤再算相似度。这里有个性能细节embedding 要批量算不要一条一条算。我一开始每条记忆单独调 embedding写入慢得离谱。改成攒一批再算速度提升十倍不止。4.3 MCP Server 的骨架代码Server 的核心就是注册工具和处理调用。骨架大概长这样from mcp.server import Server from mcp.types import Tool, TextContent app Server(local-memory) app.list_tools() async def list_tools(): return [ Tool( nameremember, description写入一条记忆。fact 用于用户偏好/身份episodic 用于对话过程/决策, inputSchema{ type: object, properties: { content: {type: string}, memory_type: {type: string, enum: [fact, episodic]}, importance: {type: number, default: 0.5} }, required: [content, memory_type] } ), # recall / forget / memory_stats 同理 ] app.call_tool() async def call_tool(name, arguments): if name remember: return await handle_remember(arguments) # ...工具描述description这块我要强调它是给模型看的不是给人看的。所以要写得像给模型下指令把判断标准、边界情况都写清楚。我见过太多人把 description 写成一句话然后抱怨模型调不对工具。4.4 Agent 侧接入Agent 侧接入分两步配置 MCP Server 连接、在对话循环里处理工具调用。配置这块不同 Agent 框架写法不同但本质都是告诉它有这么个 Server地址在哪怎么启动。我用的是 stdio 方式Agent 启动时拉起 Server 进程通过标准输入输出通信。这种方式的好处是不需要网络端口不需要额外服务管理进程生命周期跟着 Agent 走。对话循环里关键是把工具调用结果正确回灌给模型。MCP 返回的是结构化内容要转成模型能理解的格式。这块容易出错的地方是错误处理——工具调用失败时要把错误信息也回灌给模型让它知道发生了什么而不是静默失败。4.5 一次完整的记忆读写流程我拿一个真实场景走一遍用户说我最近在做一个用 Rust 写的 CLI 工具主要处理日志分析。Agent 判断这是值得记的信息调用remembercontent 是这句话type 是 factimportance 给 0.7Server 收到写入 SQLite同时算 embedding 存进向量库三天后用户问我之前说的那个项目用什么语言写的Agent 调用recallquery 是项目 语言Server 混合检索命中那条 fact返回Agent 把结果拼进上下文回答Rust整个链路里记忆层完全不知道 Agent 是谁Agent 也不关心记忆存在哪。这就是解耦的价值。5. 常见问题与排查实录5.1 模型不调用记忆工具怎么办这是最高频的问题。原因通常有三个工具描述不够清晰模型不知道什么时候该用。解决方法是把 description 写得更具体甚至给出示例场景。系统提示没引导在 system prompt 里明确告诉模型你有记忆能力重要信息要主动记。这一步很多人漏掉。工具太多模型选择困难。回到 3.1 的原则工具要少而清晰。我的经验是system prompt 里加一句遇到值得长期记住的信息主动调用 remember调用率立刻上来。5.2 检索结果不相关排查顺序先看 embedding 模型是否适合你的语言和领域。中文场景用小模型经常翻车换个大点的多语言模型。再看是否做了混合检索。纯向量检索在实体查询上表现差。最后看时间衰减参数是否过激。衰减太快老记忆全被压下去。5.3 记忆越存越多检索变慢这是必然的要提前设计。我的做法定期归档超过一定时间且 importance 低的记忆移到冷存储不参与默认检索。去重写入前做相似度检查高度相似的合并而不是新增。索引优化SQLite 给常用查询字段建索引向量库定期重建索引。5.4 常见问题速查表现象可能原因排查方向模型不调工具描述不清/无引导改 description加 system prompt检索不准纯向量/模型不匹配上混合检索换 embedding写入慢逐条算 embedding改批量计算记忆膨胀无归档无去重加归档策略和去重工具调错工具粒度太细按意图合并工具5.5 几个我踩过的坑坑一把工作记忆也持久化了。工作记忆生命周期短持久化只会污染检索结果。后来我严格区分工作记忆只放内存。坑二embedding 模型换了没重建索引。换了模型旧向量和新查询向量不在同一空间检索全乱。换模型必须重建全部索引。坑三没做并发保护。多个 Agent 同时写 SQLite 会锁库。后来加了写入队列串行化写入。坑四工具返回内容太长。一次 recall 返回十条记忆把上下文挤爆。后来限制返回条数和单条长度让模型按需二次检索。6. 这套方案还能怎么扩展跑通之后我陆续加了几个扩展都挺实用。记忆重要性自动评估写入时用一个轻量模型给 importance 打分而不是让调用方传。这样记忆质量更稳定。记忆关联图把相关记忆连起来检索时能顺着关联扩展。比如查到Rust 项目能带出日志分析这个关联记忆。多 Agent 共享记忆层因为记忆层是独立的 MCP Server多个 Agent 可以连同一个 Server共享记忆。这在多 Agent 协作场景里很有用——一个 Agent 学到的东西另一个能直接用。记忆导出与迁移MCP 的 resources 机制很适合做这个把记忆导出成标准格式换环境时直接导入。最后分享一个我个人的体会记忆层的价值不在于存得多而在于取得准。我见过太多人拼命往记忆里塞东西结果检索质量一塌糊涂。与其做一个大而全的记忆库不如先把什么该记、怎么取准这两件事做扎实。MCP 解决的是接入标准化的问题但记忆本身的设计还是得靠你对业务场景的理解。