★ FEATURED ARTICLE 1. Claude Code 记忆系统到底解决了什么问题Claude Code 的记忆系统简单说就是让 AI 编程助手在会话结束后还能记得你的项目背景、技术偏好和历史决策。它由短期记忆会话内的上下文窗口和实时对话流和长期记忆跨会话的文件式记忆、观察者记录、知识图谱、会话桥接两部分组成适合所有用 Claude Code 做长期项目的开发者尤其是那些每次重开对话都要重新解释一遍项目背景的人。我刚开始用 Claude Code 的时候最头疼的就是每次新开会话它就像失忆一样。昨天刚跟它说清楚项目用的是 FastAPI PostgreSQL今天再问它写个接口它又默认给你生成 Flask 的代码。你跟它解释了半天架构决策关掉终端再打开全部归零。这不是模型能力问题是记忆机制没配置好。Claude Code 本身内置了一套自主记忆系统但很多人只用了最基础的部分甚至完全没意识到长期记忆机制的存在。结果就是每次对话都从零开始效率极低。这篇文章会把短期记忆和长期记忆的协作机制拆开讲清楚然后给出可以直接复制的配置片段和验证步骤让你在真实项目里把短期记忆到长期记忆的转化跑通。核心要解决的问题有三个第一会话内的上下文窗口有限超出部分会被截断AI 看不到第二会话结束后上下文窗口清空所有信息丢失第三新会话启动时AI 不知道你是谁、在做什么项目、之前做了什么决策。Claude Code 的记忆系统就是围绕这三个问题设计的而且整个过程尽量做到自动化不需要你手动说记住这个。理解这套机制的关键在于搞清楚一个转化链路短期记忆怎么变成长期记忆谁来决定该记住什么新会话怎么把长期记忆重新注入上下文。下面按这个链路逐步拆解。2. TaoToken 前置配置与 Claude Code 接入准备在深入记忆系统之前需要先把 Claude Code 的运行环境搭好。Claude Code 需要对接模型服务这里用 TaoToken 来做接入它提供了兼容 Anthropic 接口的 API 端点配置起来比较直接。TaoToken 的官网地址是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentAPI 端点是 https://taotoken.net/api。你需要先在控制台创建一个 API Key然后配置到 Claude Code 的环境变量里。具体操作路径打开 https://taotoken.net/api-keys 创建密钥然后在终端里设置环境变量。Claude Code 读取的是ANTHROPIC_BASE_URL和ANTHROPIC_API_KEY这两个变量。# 设置 TaoToken 的 API 端点和密钥 export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_API_KEY你的TaoToken密钥 # 验证环境变量是否生效 echo $ANTHROPIC_BASE_URL echo $ANTHROPIC_API_KEY如果你用的是 Windows PowerShell设置方式略有不同$env:ANTHROPIC_BASE_URL https://taotoken.net/api $env:ANTHROPIC_API_KEY 你的TaoToken密钥设置完之后安装 Claude Codenpm install -g anthropic-ai/claude-code安装完成后进入你的项目目录直接运行claude就能启动。第一次启动时它会读取环境变量里的 API 配置如果配置正确你就能正常对话了。这里有个容易踩的坑环境变量只在当前终端会话有效关掉终端就没了。如果你希望永久生效需要写进 shell 配置文件。比如 bash 用户写进~/.bashrczsh 用户写进~/.zshrc# 追加到 ~/.zshrc 或 ~/.bashrc echo export ANTHROPIC_BASE_URLhttps://taotoken.net/api ~/.zshrc echo export ANTHROPIC_API_KEY你的TaoToken密钥 ~/.zshrc source ~/.zshrc配置好之后Claude Code 的短期记忆机制上下文窗口 Transcript 实时流会自动生效不需要额外配置。长期记忆的五个机制里Auto Memory 和 Transcript 归档也是零配置自动运行的另外三个claude-mem、memory MCP、session-bridge需要手动安装和配置。如果你还没创建 API Key可以先到 https://taotoken.net/api-keys 生成一个。模型选择方面Claude Code 默认会调用 Claude 系列模型TaoToken 的接口兼容这套调用方式不需要额外改模型 ID。3. 可复制的记忆系统配置片段这一节给出完整的配置文件片段包括 Claude Code 的 settings 配置、claude-mem 的安装、memory MCP 的注册、以及 session-bridge 的 hooks 配置。你可以直接复制到对应路径。3.1 Claude Code settings.json 配置Claude Code 的全局配置文件在~/.claude/settings.json项目级配置在项目根目录的.claude/settings.json。记忆系统相关的配置主要涉及 hooks 和 MCP 服务注册。{ hooks: { SessionStart: [ { matcher: , hooks: [ { type: command, command: python3 ~/.claude/scripts/session-bridge.py start } ] } ], SessionEnd: [ { matcher: , hooks: [ { type: command, command: python3 ~/.claude/scripts/session-bridge.py end } ] } ] }, mcpServers: { memory: { command: npx, args: [-y, modelcontextprotocol/server-memory] } } }这个配置做了两件事注册了 SessionStart 和 SessionEnd 两个 hook分别调用 session-bridge 脚本的 start 和 end 子命令注册了 memory MCP 服务让 AI 可以在对话中主动构建知识图谱。3.2 claude-mem 安装配置claude-mem 是一个通过 hooks 自动拦截工具调用并记录观察的插件。安装方式# 添加插件源 claude plugins add thedotmack/claude-mem # 安装 claude-mem 运行时 npx claude-mem install安装完成后claude-mem 会自动注册 UserPromptSubmit、PostToolUse、SessionEnd 三个 hook。你可以在~/.claude/settings.json里看到它追加的配置。claude-mem 的数据存在 SQLite 和 ChromaDB 里路径默认在~/.claude-mem/下。3.3 session-bridge.py 脚本session-bridge 的核心逻辑是一个 Python 脚本负责在会话结束时保存指针在会话启动时读取上次的 transcript 并提取摘要注入上下文。把下面的脚本保存到~/.claude/scripts/session-bridge.py#!/usr/bin/env python3 import json import sys import os from datetime import datetime, timezone from pathlib import Path CLAUDE_DIR Path.home() / .claude LAST_SESSION_FILE CLAUDE_DIR / last-session.json def handle_session_end(): data json.load(sys.stdin) info { session_id: data.get(session_id), cwd: data.get(cwd), transcript_path: data.get(transcript_path), ended_at: datetime.now(timezone.utc).isoformat(), } CLAUDE_DIR.mkdir(parentsTrue, exist_okTrue) with open(LAST_SESSION_FILE, w) as f: json.dump(info, f, indent2) def handle_session_start(): if not LAST_SESSION_FILE.exists(): return with open(LAST_SESSION_FILE) as f: last json.load(f) transcript_path last.get(transcript_path) if not transcript_path or not os.path.exists(transcript_path): return messages [] with open(transcript_path) as f: for line in f: try: entry json.loads(line) except json.JSONDecodeError: continue if entry.get(type) user: content entry.get(message, {}).get(content, ) if isinstance(content, str) and content.strip(): messages.append((user, content[:250])) elif entry.get(type) assistant: content entry.get(message, {}).get(content, []) if isinstance(content, list): for block in content: if block.get(type) text: messages.append((assistant, block[text][:250])) recent messages[-16:] if recent: print( 上次会话摘要 ) for role, text in recent: print(f[{role}] {text}) print( 摘要结束 ) if __name__ __main__: cmd sys.argv[1] if len(sys.argv) 1 else if cmd end: handle_session_end() elif cmd start: handle_session_start()保存后给执行权限chmod x ~/.claude/scripts/session-bridge.py3.4 Auto Memory 文件结构Auto Memory 是 Claude Code 内置的机制不需要额外配置但你需要知道它的文件结构方便排查问题。记忆文件存在项目路径编码对应的目录下~/.claude/projects/ └── C--Users-Administrator--myproject/ └── memory/ ├── MEMORY.md ├── user_tech_stack.md ├── feedback_code_style.md ├── project_architecture.md └── reference_jira.md每个记忆文件的格式是带 frontmatter 的 Markdown--- name: project-architecture description: 项目使用 FastAPI PostgreSQL Redis metadata: type: project --- 后端框架是 FastAPI数据库用 PostgreSQL缓存用 Redis。 **Why:** 团队技术栈统一新成员需要快速了解。 **How to apply:** 生成后端代码时默认用 FastAPI 风格数据库操作走 SQLAlchemy。MEMORY.md 是索引文件每次会话启动时 Claude Code 会自动加载它然后根据当前问题判断哪些记忆文件需要读取。4. 验证记忆系统是否生效配置完成后需要验证短期记忆和长期记忆是否真的在工作。下面给出具体的验证步骤和预期结果。4.1 验证短期记忆上下文窗口 Transcript启动 Claude Code随便聊几句然后检查 transcript 文件是否在实时写入# 找到当前项目的 transcript 目录 ls ~/.claude/projects/ # 进入对应项目目录查看最新的 jsonl 文件 ls -lt ~/.claude/projects/C--Users-Administrator--myproject/*.jsonl | head -5 # 实时查看写入内容 tail -f ~/.claude/projects/C--Users-Administrator--myproject/session-id.jsonl如果配置正确你在 Claude Code 里每发一条消息jsonl 文件就会追加一行 JSON。每行的结构类似{type:user,message:{content:帮我写一个用户登录接口}} {type:assistant,message:{content:[{type:text,text:好的我来写...}]}}这说明 Transcript 实时流在工作。这是短期记忆的底层保障即使其他机制都失灵原始记录还在。4.2 验证 Auto Memory在 Claude Code 里告诉它一个项目背景信息比如这个项目用的是 FastAPI 框架数据库是 PostgreSQL缓存用 Redis。然后检查记忆目录是否生成了文件ls ~/.claude/projects/C--Users-Administrator--myproject/memory/ cat ~/.claude/projects/C--Users-Administrator--myproject/memory/MEMORY.md如果 Auto Memory 生效你应该能看到新生成的记忆文件和更新后的索引。注意Auto Memory 是 AI 自主判断的不是所有信息都会写入。如果你说的信息它认为不值得长期保存可能不会生成文件。这是设计如此避免记忆被垃圾信息污染。4.3 验证 session-bridge退出 Claude Code然后重新启动。如果 session-bridge 配置正确新会话启动时你应该能看到上次会话的摘要被注入。验证方式# 检查 last-session.json 是否生成 cat ~/.claude/last-session.json # 手动运行 bridge 脚本的 start 命令看输出 python3 ~/.claude/scripts/session-bridge.py start如果输出里有上次会话摘要和几条对话记录说明 bridge 在工作。新会话启动时这些摘要会通过 SessionStart hook 注入到 Claude 的上下文里。4.4 验证 memory MCP在 Claude Code 里让它创建一个知识图谱实体请用 memory MCP 创建一个项目实体名字叫用户中心类型是 project。然后查询请用 memory MCP 读取整个知识图谱。如果 MCP 配置正确你应该能看到刚才创建的实体。memory MCP 的数据默认存在内存里进程重启会丢失如果需要持久化需要在 MCP 配置里指定存储路径。4.5 验证 claude-memclaude-mem 是自动拦截的验证方式是检查它的数据库# 查看 claude-mem 数据目录 ls ~/.claude-mem/ # 查询 SQLite 里的观察记录 sqlite3 ~/.claude-mem/observations.db SELECT COUNT(*) FROM observations;如果计数在增长说明 claude-mem 在自动记录工具调用。你不需要手动触发它通过 PostToolUse hook 自动捕获。5. 常见报错与排查配置记忆系统时容易遇到几类报错下面按真实错误信息给出排查路径。5.1 401 错误API Key 无效Error: 401 Unauthorized {error:{type:authentication_error,message:invalid x-api-key}}这个错误说明 TaoToken 的 API Key 没配置对。排查步骤第一确认ANTHROPIC_API_KEY环境变量已经设置用echo $ANTHROPIC_API_KEY检查第二确认 Key 没有多余空格或换行第三到 https://taotoken.net/api-keys 确认 Key 还在有效期内。如果用的是项目级配置检查.claude/settings.json里有没有覆盖全局环境变量。5.2 local proxy failed本地代理连接失败Error: local proxy failed to connect这个错误通常出现在 Claude Code 尝试连接 API 端点时。排查确认ANTHROPIC_BASE_URL设置的是https://taotoken.net/api注意末尾不要多加斜杠。另外检查网络是否能正常访问该地址curl -I https://taotoken.net/api如果返回 200 或 401说明网络通问题在 Key 配置。如果超时检查本地网络设置。5.3 reading choices响应解析失败Error: reading choices field failed这个错误说明返回的响应格式不符合预期。Claude Code 期望的是 Anthropic 格式的响应如果 API 端点返回的是 OpenAI 格式就会报这个错。确认ANTHROPIC_BASE_URL指向的是兼容 Anthropic 接口的端点。TaoToken 的/api端点兼容 Anthropic 调用方式如果配置正确不会出现这个问题。5.4 OAuth 相关报错Error: OAuth token expiredClaude Code 某些版本会尝试 OAuth 登录流程。如果你用的是 API Key 方式接入不需要 OAuth。排查确认没有设置CLAUDE_CODE_USE_OAUTH之类的环境变量如果有就取消掉。另外检查~/.claude/下有没有残留的 OAuth token 文件有的话删掉。5.5 session-bridge 脚本不执行如果 SessionStart hook 没触发检查第一~/.claude/settings.json里的 hooks 配置路径是否正确第二脚本是否有执行权限chmod x第三Python 路径是否正确有些系统用python而不是python3。可以手动运行脚本看报错python3 ~/.claude/scripts/session-bridge.py start如果报FileNotFoundError说明last-session.json还没生成先正常退出一次 Claude Code 让它生成。5.6 claude-mem 数据库锁定Error: database is lockedclaude-mem 用 SQLite 存储多个进程同时写入会锁库。排查确认没有多个 Claude Code 实例同时运行检查~/.claude-mem/下有没有残留的.db-journal文件有的话删掉。claude-mem 的设计原则是写入失败静默降级不影响主流程所以这个错误一般不会阻塞你使用。5.7 记忆文件不生成如果 Auto Memory 一直不生成文件检查第一项目路径编码目录是否存在第二memory/子目录是否有写权限第三跟 AI 说的信息是否属于它认为值得保存的类型。代码模式、git 历史、bug 修复方案这些它不会存因为可以直接从代码里读。项目背景、技术栈偏好、外部系统地址这些才会存。6. 把记忆系统用起来的几个实操建议配置跑通之后怎么让它真正在项目里发挥作用有几个实操层面的建议。第一项目启动时主动给 AI 喂一次背景信息。虽然 Auto Memory 会自动判断但你在项目初期明确告诉它技术栈、架构决策、团队约定能大幅提高记忆的命中率。比如新项目开始时说一句这个项目用 FastAPI PostgreSQL代码风格遵循 PEP8测试用 pytest它大概率会写入 project 类型记忆。第二定期检查 MEMORY.md 的内容。Auto Memory 是 AI 自主判断的有时候它会记一些你不需要的东西或者漏记关键信息。每隔一段时间打开~/.claude/projects/项目/memory/MEMORY.md看看手动补充或删除条目。这个文件是纯 Markdown你可以直接编辑。第三session-bridge 的摘要长度可以调。默认脚本截取最后 8 轮对话每条截断到 250 字符。如果你的项目对话轮次多可以调大这个值但注意别把上下文窗口撑爆。改脚本里的messages[-16:]和[:250]这两个参数即可。第四claude-mem 的语义搜索在项目大了之后特别有用。它会把你之前的工具调用和观察记录做向量化新会话时通过 UserPromptSubmit hook 注入相关历史。你不需要手动查但知道它在工作能让你更放心地把重复性操作交给它。第五memory MCP 适合用来维护项目级的实体关系。比如你有多个微服务可以用它建实体和关系AI 在需要了解服务依赖时能直接查图谱。这个机制需要 AI 主动调用你可以在对话里明确说用 memory MCP 记录一下这个服务的依赖关系。第六如果发现记忆系统没生效按这个顺序排查先看 Transcript 有没有写入最底层保障再看 Auto Memory 目录有没有文件然后看 session-bridge 的 last-session.json 有没有生成最后看 claude-mem 的数据库有没有记录。从底层往上层查能快速定位是哪一层出了问题。第七长期编码项目建议配合 Coding Plan 使用这样记忆系统的效果能持续累积。你可以到 https://taotoken.net/coding-plan 了解具体的方案把 API 调用和记忆机制结合起来减少每次重新解释项目背景的时间。记忆系统的价值在于累积效应。单次会话可能感觉不明显但用了一两周之后你会发现新开会话时 AI 已经知道你的项目结构、代码风格、常用命令不需要你重复解释。这个体验的提升是实打实的。配置一次后面都是收益。
阅读完成 · 觉得有帮助？
