total-agent-memory：为 AI 编程助手打造的记忆层

当 Claude Code 忘了你上周做了什么

想象一下这个场景：周一下午，你让 Claude Code 重构了一个支付模块，加了超时重试逻辑。周五上午，你打开一个新会话，想让 AI 继续在这个模块上实现退款功能——结果 Claude Code 完全不记得之前的设计决策，反复问你「超时时间设多少秒」。这不是 Claude 的 bug，而是所有 AI 编程助手共同的「短命记忆」问题：每次会话都是独立的，跨会话的上下文全部丢失。

total-agent-memory（简称 TAM）正是为了解决这个痛点而生的。它是一个持久化记忆层，专门为 Claude Code、Codex CLI、Cursor 等 AI 编程助手设计，通过知识图谱、嵌入向量和 Web 可视化，让 AI 真正「记住」你的项目和工作方式。

技术实现：四层记忆架构

TAM 的核心设计围绕四种互补的记忆类型展开：

程序性记忆（Procedural Memory）：这是 TAM 最独特的创新点。它不只是存储「代码是什么」，而是自动提取「代码是怎么写的」——你偏好的命名风格、函数结构、设计模式、甚至注释习惯。当 AI 在新会话中遇到类似任务时，会主动调用这些记忆，复现你的编码风格，而不是生成一段「标准但陌生」的代码。在 LongMemEval 基准测试中，TAM 达到了 97.45% 的 R@5 准确率，远超竞品 Supermemory（86.6%）。

情景记忆（Episodic Memory）：记录每一次会话中发生的重大决策、错误修复和设计变更。AI 可以检索「上次在这里遇到什么坑」「我们当时为什么选择了这个方案」，真正实现跨会话的上下文连续性。

语义记忆（Semantic Memory）：基于知识图谱的结构化存储，将项目中的概念、模块和它们之间的关系编码为图结构。不同于简单的向量检索，知识图谱能捕捉「A 是 B 的一部分」「C 依赖 D」这类关系语义。

工作记忆（Working Memory）：轻量级快速访问层，用于当前会话的即时上下文。hot path 路径完全不调用 LLM，延迟低至 0.065ms（p50，热启动），保证 IDE 响应的流畅性。

核心功能：46 个 MCP 工具

TAM 通过 MCP（Model Context Protocol）协议暴露了 46 个工具，覆盖了编程助手工作流中的各个环节：

• 上下文注入类：inject_context、inject_code_snippets、inject_recent_changes：在需要时向 AI 会话注入相关记忆片段
• 知识提取类：extract_entities、extract_relations、pattern_discovery：从代码变更中自动提取结构化知识
• 图谱操作类：create_node、link_nodes、query_graph：直接操作知识图谱
• 会话管理类：start_session、end_session、session_summary：管理会话生命周期和记忆归档
• AST 解析类：支持直接解析代码抽象语法树，提取函数签名、依赖关系和代码结构

这些工具通过 MCP server（HTTP 模式，端口 37337）对外提供服务，可以被任何支持 MCP 协议的客户端调用。README 披露支持 9 种 IDE，包括 Claude Code、Codex CLI、Cursor、Cline 等主流工具。

一键部署体验

对于想要快速体验的开发者，TAM 提供了开箱即用的 Docker 部署方案：

docker compose up -d --build

一条命令即可启动包含 6 个服务的完整栈：

• ollama：本地 LLM 运行时（默认使用 qwen2.5-coder:7b 和 nomic-embed-text 嵌入模型）
• mcp：MCP HTTP server（端口 37337）
• dashboard：Web 可视化界面（端口 37737），支持 3D WebGL 知识图谱可视化
• reflection：文件监听守护进程，实时处理 reflection 队列
• scheduler：定时任务（每日孤儿回填 4 次，每周检查更新）

Dockerfile 采用了多阶段构建，基于 python:3.12-slim，镜像体积经过优化。对于不想使用 Ollama 的用户，也可以完全本地运行（TAM 支持纯 CPU 模式，MEMORY_MODE=fast 路径零 LLM 调用）。

技术栈与架构

TAM 的主力技术栈清晰明了：

• 语言：Python 3.10+
• 持久化存储：ChromaDB（向量数据库）+ SQLite（知识图谱）
• 嵌入模型：sentence-transformers（默认）+ FastEmbed（可选加速）
• 协议：MCP（Model Context Protocol），开放标准
• Web 框架：Starlette + Uvicorn（HTTP transport）
• 依赖管理：setuptools + pyproject.toml

项目采用模块化架构：total_agent_memory/ 为主核心，claude_total_memory/ 面向 Claude Code 集成，codex-skill/ 面向 Codex CLI 集成，src/ 包含共享工具库。skills/ 目录提供了大量预制 skill，覆盖代码审查、文档生成等高频场景。

局限与取舍

没有工具是银弹，TAM 也不例外：

Ollama 的算力门槛：虽然 hot path 不需要 LLM 调用，但知识提取、图谱更新等 deep mode 功能依赖 Ollama 运行时。qwen2.5-coder:7b 模型在纯 CPU 上运行效率较低，配备 GPU 的机器体验会更好（README 建议 16GB+ 内存）。

记忆质量依赖代码规范：TAM 的程序性记忆提取高度依赖代码结构的一致性。如果项目代码风格混乱（不同模块使用截然不同的命名约定），提取出的「习惯」会包含噪声，反而可能误导 AI。

增量同步的延迟：reflection daemon 监听文件变更，但知识图谱更新存在一定延迟。极短时间内的连续修改可能导致记忆不一致，需要依赖 scheduled 任务做批量对账。

行业意义：填补 AI 编程的「记忆真空」

TAM 的出现反映了一个趋势：当 AI 编程助手的能力越来越强，如何让它们真正成为项目的「长期参与者」而非「每次都失忆的新人」，正在成为下一个技术焦点。

当前市面上的记忆方案（如 mem0、Letta、Zep）主要面向通用 Agent 场景，对编程助手特有的代码结构、AST 语义和 IDE 集成需求覆盖不足。TAM 精准卡位这个细分市场，通过程序性记忆这一差异化特性，在 LongMemEval 评测中领先 Supermemory 超过 10 个百分点（+10.8pp）。

从开源生态角度看，TAM 同时支持 PyPI（pip install total-agent-memory）、npm（npm install）和 Homebrew 多渠道分发，并提供了详尽的跨平台安装脚本（支持 Linux/macOS/Windows），生态覆盖度在同类项目中处于领先。