total-agent-memory：AI 编程智能体的持久化记忆层

技能简介

total-agent-memory（简称 TAM）是一个完全本地化运行的持久化记忆系统，专为 AI 编程智能体（Claude Code、Codex CLI、Cursor 及所有兼容 MCP 协议的客户端）设计。它将智能体的工作记忆转化为可跨会话、跨项目、跨设备持久化的结构化知识资产。

该工具以 MCP（Model Context Protocol）服务器形式提供服务，内置 77 个工具函数，覆盖时序知识图谱、程序性记忆、情景记忆、AST 代码库解析、编辑预检守卫和错误自动归集等核心能力。最新 v14.6.0 版本新增团队服务器功能，支持仪表盘、角色权限、新人培训、PostgreSQL 后端和连续备份，让个人和工作团队的代码上下文管理进入企业级可用阶段。

核心能力

• 时序知识图谱（Temporal Knowledge Graph）：以时间轴方式存储实体、关系和事件，支持跨时间的事实演变追踪，检索时可按时间衰减排序。
• 程序性记忆（Procedural Memory）：记录智能体执行工作流程时的步骤序列和决策逻辑，新项目可借鉴相似任务的标准操作流程。
• 情景记忆（Episodic Memory）：以会话为单位保存关键上下文快照，支持按项目、日期或关键词回溯历史决策状态。
• AST 代码库解析：通过抽象语法树对代码仓库进行深度解析，构建代码结构知识图谱，支持跨项目的类/函数/变量血缘追踪。
• 编辑预检守卫（Pre-Edit Guard）：在智能体执行文件修改前，基于历史模式预判潜在冲突或危险操作，减少无效编辑循环。
• 77 工具函数全 MCP 覆盖：list_memory、search_memory、memory_write、memory_delete、codebase_ingest、graph_query、memory_report 等，构成完整的记忆生命周期管理。
• PostgreSQL 团队后端（v14.6.0 新增）：企业部署可选 PostgreSQL 作为存储引擎，同等性能下数据可靠性更高；支持连续备份至 S3 兼容存储。
• 多端安装支持：PyPI、npm、Docker（GHCR）、Homebrew 多渠道分发，Claude Code / Codex / Cursor 直接可用。

安装配置

方式一：通过 pip 安装（推荐）

# Python 3.11+ 环境
pip install total-agent-memory

# 验证安装
tam --version

方式二：通过 uvx 免安装运行

uvx total-agent-memory

方式三：通过 npm 安装（Node.js 环境）

npm install -g total-agent-memory

方式四：Docker 部署（团队服务器）

docker pull ghcr.io/vbcherepanov/total-agent-memory:latest
docker run -p 7400:7400 -v tam-data:/data ghcr.io/vbcherepanov/total-agent-memory

安装完成后，在 Claude Code 或 Codex 的 MCP 配置文件（~/.claude/mcp.json 或项目根目录 .mcp.json）中添加：

{
  "mcpServers": {
    "total-agent-memory": {
      "command": "tam",
      "args": ["mcp", "serve"]
    }
  }
}

使用步骤

第一步：初始化记忆存储

tam setup

交互式向导会询问「仅本人使用」或「团队服务器」，选择后自动配置存储路径和数据库连接。第一次运行会在 ~/.local/share/total-agent-memory/（Linux）或对应系统目录创建本地 SQLite 数据库。

第二步：将当前代码库导入记忆层

tam codebase ingest /path/to/your/project

该命令对项目进行 AST 深度解析，提取类结构、函数签名、依赖关系和重要常量，写入情景记忆供后续会话参考。

第三步：在智能体会话中调用记忆

在 Claude Code 对话中直接通过 MCP 工具调用记忆功能：

# 检索与当前任务相关的历史记忆
memory_search "OAuth 认证流程"

# 保存当前会话关键上下文
memory_write --type episodic --project my-app --content "已实现 JWT 刷新机制，待完成前端 token 刷新拦截器"

# 查询代码结构知识图谱
graph_query --type function --name "authenticate_user"

第四步：生成记忆报告（可选）

tam memory-report --period week --format markdown

生成指定时间段内的记忆活动报告，包含新增记录数、检索频次、代码热点等分析数据，帮助团队了解知识沉淀状况。

适用场景

• 跨会话大型重构：持续数周的重构工作，每次会话无需重新描述上下文，TAM 自动衔接上次进度和决策理由。
• 多成员代码审查协作：团队成员可将审查结论和代码决策写入共享记忆层，新成员加入时快速获取项目知识积累。
• 技术债务追踪：长期项目中的临时方案、已知缺陷和延期决策以情景记忆形式保存，形成可检索的技术债务台账。
• 跨项目最佳实践复用：程序性记忆存储标准操作流程，相似新项目可直接参考历史最优路径，减少重复探索。
• 企业知识管理（v14.6.0）：PostgreSQL 后端 + 角色权限系统支撑部门级新人培训，记忆资产成为组织知识而非个人笔记。
• AI 代理审计与回归测试：通过 memory_report 分析智能体行为轨迹，识别高频错误模式并进行针对性提示词优化。

适用人群

• 长期从事大型代码库维护的工程师（尤其是 6 个月以上的多阶段项目）
• 多成员协作开发团队，需要共享技术上下文和决策历史
• AI 编程深度用户（Claude Code / Codex / Cursor），希望记忆积累不被会话周期打断
• 技术负责人或架构师，关注团队知识沉淀和新人上手效率
• 企业部署场景，需要本地化数据存储和访问权限控制

工作原理

TAM 的核心是一套基于本地 SQLite（或 PostgreSQL）的时序知识存储引擎。记忆数据分为四层：

第一层：情景记忆（Episodic）——以会话为单位，一次工作会话对应一条记录，包含时间戳、项目标识、摘要和完整上下文文本。每次 memory_write 调用产生一条带 created_at 和 updated_at 的条目。

第二层：程序性记忆（Procedural）——存储工作流程模板和操作序列。当智能体执行「先查日志、再跑测试、最后部署」这类规律性流程时，TAM 提取为可复用步骤，存入程序性记忆供相似任务调用。

第三层：知识图谱（Graph）——通过 AST 解析器对代码库结构化，生成节点（函数/类/变量）和边（调用/包含/继承）关系图。检索时支持基于嵌入向量的语义搜索和基于关系路径的结构化查询。

第四层：守卫层（Guard）——在智能体发起编辑前，Guard 查询历史编辑模式，判断当前修改是否与历史决策冲突或存在已知风险，直接返回警告而非事后纠正。

所有数据默认存储在本地磁盘，遵循「本地优先」原则，不依赖任何云服务。v14.6.0 团队服务器版本支持加密存储和 HTTPS 传输，满足企业内网部署要求。

官方链接

• PyPI 安装包：https://pypi.org/project/total-agent-memory/
• npm 安装包：https://www.npmjs.com/package/total-agent-memory
• GitHub 仓库：https://github.com/vbcherepanov/total-agent-memory
• Docker 镜像：https://github.com/vbcherepanov/total-agent-memory/pkgs/container/total-agent-memory
• 官方文档：https://github.com/vbcherepanov/total-agent-memory/blob/main/docs/