TiMemMCP Server 实战：给 Cursor / Claude Code 接入五层时序记忆的 config.toml 骨架

1. 为什么 Cursor 和 Claude Code 需要五层时序记忆如果你同时用 Cursor 写业务代码、用 Claude Code 跑重构任务大概率遇到过同一个尴尬昨天刚跟 AI 敲定的目录结构、命名规范、错误处理约定今天开个新会话它又像第一次进这个仓库一样从零开始猜你的意图。Context window 只在单次会话里有效会话一关记忆清零这不是模型变笨而是 AI IDE 本身没有跨会话持久化机制。TiMemMCP Server 想解决的就是这件事。它基于 MCPModel Context Protocol协议把一套五层时序记忆树TMT挂到 Cursor 和 Claude Code 上让 AI 在对话过程中能主动写入和检索历史。五层结构从下往上分别是 L1 原始对话片段、L2 会话摘要、L3 每日总结、L4 每周总结、L5 人物画像写入时逐层归纳查询时按问题复杂度自动选层。对需要跨会话保留上下文的开发者来说这相当于给 IDE 装了一个会自己整理笔记的长期记忆库。这篇不聊概念直接给可复制的config.toml/settings.json骨架再走一遍启动 MCP、验证五层记忆读写生效的完整动作。适合已经在用 Cursor 或 Claude Code、并且被“重复交代背景”折磨过的开发者。2. 前置准备TaoToken 统一 Key 通道与 TiMem 接入在动配置文件之前先把两件事理清楚模型调用的 Key 从哪来TiMem 的 Key 怎么配。模型侧我建议走 TaoToken 的统一 Key 通道。原因是 Cursor 和 Claude Code 经常要切换不同模型做对比如果每个模型单独申请 Key、单独改环境变量配置会散得到处都是。TaoToken 提供统一的 API 入口一个 Key 就能覆盖多种模型调用省掉反复换 Key 的麻烦。官网入口在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 地址是 https://taotoken.net/api 注意 API 地址不带 UTM 参数配置时别把查询串抄进去。TiMem 侧需要的是它自己的 API Key在 TiMem 控制台获取用于 MCP Server 访问记忆服务。这两个 Key 职责不同TaoToken 的 Key 管模型推理TiMem 的 Key 管记忆读写不要混用。环境上先装uvTiMem MCP Server 通过uvx拉起不需要你手动 clone 仓库curl -LsSf https://astral.sh/uv/install.sh | sh装完执行uvx --version确认可用。如果这一步报 command not found多半是 shell 的 PATH 没刷新重开一个终端即可。注意uvx会在首次运行时自动拉取timem-mcp包网络受限的环境可能卡住建议先单独跑一次uvx timem-mcp --help预热缓存。3. 可复制配置config.toml 与 settings.json 骨架这一节是全文的核心配置分三块Claude Code 的settings.json、Cursor 的mcp.json、以及可选的config.toml骨架。三者格式相近但字段位置有差异照抄时注意别串。3.1 Claude Code 的 settings.jsonClaude Code 读取~/.claude/settings.json把 MCP Server 挂在mcpServers下{ mcpServers: { TiMEM-MCP: { command: uvx, args: [timem-mcp], env: { TiMEM_API_KEY: your-timem-api-key, TiMEM_API_HOST: https://api.timem.cloud, TAOTOKEN_API_KEY: your-taotoken-key, TAOTOKEN_BASE_URL: https://taotoken.net/api } } } }command和args决定怎么启动 MCP Serverenv里前两个是 TiMem 记忆服务必需后两个是模型通道方便你在同一份配置里统一管理。如果你暂时只用 TiMem 记忆、模型走 IDE 自带通道后两个可以删掉。3.2 Cursor 的 mcp.jsonCursor 读取~/.cursor/mcp.json结构几乎一致{ mcpServers: { TiMEM-MCP: { command: uvx, args: [timem-mcp], env: { TiMEM_API_KEY: your-timem-api-key, TiMEM_API_HOST: https://api.timem.cloud } } } }3.3 config.toml 骨架有些团队习惯用 TOML 统一管理工具链配置下面这份骨架可以直接放进项目根目录的.timem/config.toml作为记忆域的声明文件[server] name TiMEM-MCP command uvx args [timem-mcp] [server.env] TiMEM_API_KEY your-timem-api-key TiMEM_API_HOST https://api.timem.cloud [memory] # 业务领域用于隔离不同项目的记忆 domain project-alpha # 智能体标识多 Agent 场景下区分 agent_id default-expert-001 # 默认检索层留空则由系统按问题复杂度自动选层 default_layer [memory.retrieval] limit 10 # 可选 L1-L5按需覆盖 layer domain这个字段值得单独说不同项目设不同 domain记忆完全隔离A 项目的技术规范不会串到 B 项目。我试过把两个仓库都设成默认 domain结果 Cursor 在写前端项目时突然引用后端项目的错误处理约定排查半天才发现是记忆串了。3.4 规则文件补充配置完 MCP 还不够得告诉 AI 什么时候用记忆工具。在CLAUDE.md或.cursorrules里加一段你可以使用 TiMEM MCP 服务器的记忆管理工具 - 使用 create_memory 将重要对话内容、技术决策、用户偏好存储为记忆 - 使用 search_memories 在开始新任务时检索相关历史记忆 - 检索时优先按 domain 过滤避免跨项目污染4. 启动 MCP 并验证五层记忆读写配置写完重启 IDE然后按下面的顺序验证。别跳过验证直接干活否则记忆没生效你也不知道。4.1 确认 MCP Server 已加载在 Claude Code 里输入/mcp查看已挂载的 Server 列表应该能看到TiMEM-MCP处于 connected 状态。Cursor 则在设置面板的 MCP 区域确认。如果显示 failed先看第 5 节的排查。4.2 写入一条 L1 记忆在对话里让 AI 调用create_memory参数结构如下{ messages: [ {role: user, content: 本项目统一用 Go数据库 PostgreSQL不用 ORM}, {role: assistant, content: 已记录Go PostgreSQL禁用 ORM} ], session_id: proj-alpha-20250101, agent_id: default-expert-001, domain: project-alpha }messages是 role content 的消息列表session_id标识本次会话domain决定记忆归属。写入成功后这条内容会以 L1 原始片段落库毫秒级可见。4.3 检索验证分层生效新开一个会话让 AI 调用search_memories{ query: 本项目用什么数据库和 ORM 策略, domain: project-alpha, limit: 10 }预期结果是 AI 能召回刚才写入的 Go PostgreSQL 约定。如果你想验证分层可以显式指定 layerlayer用途典型场景L1原始对话片段查具体某句话的细节L2会话摘要回顾某次讨论结论L3每日总结查近期状态L4每周总结提取中期规律L5人物画像查整体偏好查原始细节用layer: L1查近期状态用layer: L3查整体画像用layer: L5。不指定 layer 时系统按问题复杂度自动选层这也是 TiMem 和扁平记忆框架最核心的区别。4.4 验证跨会话持久化关掉 IDE重开新会话里直接问“我们项目的数据库选型是什么”。如果 AI 能通过search_memories答出 PostgreSQL说明跨会话记忆链路通了。这一步是整个接入的验收标准没通过就别往下走。5. 本篇常见错排查配置过程中踩坑概率最高的几个点按出现频率排MCP Server 显示 failed 或 not connected。九成是uvx不在 PATH 里。IDE 启动时继承的环境变量可能和你终端里不一样尤其是 macOS 上用 GUI 启动的情况。解决办法是在env里显式补上 PATH或者用uvx的绝对路径替换command字段。写入成功但检索不到。先检查domain是否一致。写入用project-alpha、检索用默认 domain两边对不上自然查不到。其次是agent_id多 Agent 场景下不同 agent 的记忆默认隔离。API Key 报 401。TiMem 的 Key 和 TaoToken 的 Key 别搞混前者填TiMEM_API_KEY后者填TAOTOKEN_API_KEY。另外确认TiMEM_API_HOST没写错末尾不要多加斜杠。首次调用超时。uvx首次拉包会慢属于正常现象。预热一次后后续调用会快很多。如果持续超时检查网络是否能访问包源。记忆串项目。回到 3.3 节给每个项目单独设domain这是最省事的隔离手段。提示排查时优先看 IDE 的 MCP 日志面板比在对话里猜快得多。Claude Code 可以用/mcp看连接状态Cursor 在设置里能看到 Server 的 stderr 输出。6. 把记忆通道固定下来接入完成后建议把 Key 管理也固定成一套流程避免每次换模型都重新配。模型调用走 TaoToken 的统一 Key 通道在 https://taotoken.net/api-keys 生成和管理 Key接入细节参考 https://taotoken.net/doc 记忆侧继续用 TiMem 自己的 Key。两套 Key 各管一摊配置文件里字段分开写后期维护不会乱。如果你主要用 Claude Code 做长期编码和 Agent 任务可以看下 Coding Plan 的用法把模型通道和记忆通道一起固化到项目模板里https://taotoken.net/coding-plan 。需要临时验证某个模型对记忆检索结果的理解能力直接用模型对话页试最快https://taotoken.net/chat 。配置过程中遇到 MCP 连接或 Key 鉴权问题对照接入文档逐项核对通常能定位https://taotoken.net/doc 。最后留一个实操建议把config.toml骨架提交到项目仓库的.timem/目录下新同事 clone 下来只需要填自己的 Keydomain 和 agent_id 直接复用团队记忆域就统一了。这比口头交代“记得开记忆”靠谱得多。