Total Agent Memory

为 AI 编码 Agent 提供持久化的本地记忆：适用于 Claude Code、Codex CLI、Cursor 及任何 MCP 客户端。

网站和文档：totalmemory.dev · 快速入门 · Claude Code 指南 · 基准测试 · 与其他工具比较

total-agent-memory (TAM) 是一个面向 AI 编码 Agent 的开源记忆服务。 编码 Agent 每次启动会话时都无法记住之前的内容，因此决策、修复和项目约定都必须再次说明。TAM 会在你的设备上存储决策、解决方案、事实、错误和会话摘要，并通过 Model Context Protocol (MCP) 提供这些内容，因此任何 MCP 客户端都可以直接使用，无需修改代码。

每个存储都是一个基于 SQLite 数据库构建的目录。检索结合了全文 BM25、本地计算的稠密嵌入、模糊匹配和知识图谱，并通过倒数排名融合合并排序列表；还可以选择使用交叉编码器重新排序结果。默认配置在写入或搜索时都不会调用大模型，因此可以离线评估检索效果，且重复运行会得到相同结果。事实可以带有有效期区间（kg_add_fact、kg_at），单值事实有新值时，旧值可以失效。

TAM 面向每天使用编码 Agent 的开发者，也面向需要可在本地运行、检查和修改记忆基准的研究人员。同一个软件包还可以作为团队服务运行：个人、部门和公司区域分别使用独立存储，并通过一个网关统一提供服务，同时具备角色、作者归属和审计跟踪（团队服务）。

安装

TAM 需要 Python 3.11 或更高版本。CI 会在 Ubuntu、Windows 和 macOS 上测试 Python 3.11、3.12 和 3.13。

从 PyPI 安装（使用虚拟环境，或 pipx / uvx）：

pip install total-agent-memory          # or: pipx install total-agent-memory
uvx total-agent-memory                  # run once without installing

这会安装 total-agent-memory（别名为 tam）MCP 服务，以及 tam-team、tam-remote 和 lookup-memory 命令。可选的交叉编码器重排序器需要安装 PyTorch，属于额外依赖： pip install "total-agent-memory[rerank]"。团队服务的 PostgreSQL 后端属于 [postgres] 额外依赖。

向客户端注册。 在终端运行 tam setup。向导会询问“仅我使用”还是“公司服务”，检测 Claude Code、Claude Desktop、Codex、Cursor、Windsurf、Gemini CLI、Cline 和 OpenCode，并将服务注册到你选择的客户端中（设置向导）。

其他渠道：

渠道	命令
Docker（linux/amd64、linux/arm64）	docker run -p 3737:3737 -p 37737:37737 -v ~/.tam:/data ghcr.io/vbcherepanov/total-agent-memory:14.9.0 — 通过 :3737/mcp 提供 MCP over HTTP，仪表板位于 :37737
npx 连接器	npx -y total-agent-memory connect claude-code（或 codex、cursor、cline、continue、aider、windsurf、gemini-cli、opencode）
Claude Code 插件（服务、技能和捕获钩子）	/plugin marketplace add vbcherepanov/total-agent-memory /plugin install total-agent-memory@vbcherepanov
面向 Claude Code 和 Cowork 的插件，来自插件仓库（服务和技能，无钩子；需要 uv）	/plugin marketplace add vbcherepanov/total-agent-memory-plugin /plugin install total-agent-memory@vbcherepanov
同一插件，适用于 Codex CLI	codex plugin marketplace add vbcherepanov/total-agent-memory-plugin codex plugin add total-agent-memory@vbcherepanov
含 IDE 钩子和后台服务的源码检出	git clone https://github.com/vbcherepanov/total-agent-memory.git && cd total-agent-memory && ./install.sh --ide claude-code（Windows：install.ps1 -Ide claude-code）

Claude Code 的两个插件只选一个使用。各平台详情、WSL2、IDE 矩阵、卸载和故障排查请参阅安装指南。

快速开始

1. 安装软件包并运行 tam setup，或手动将服务添加到客户端。Claude Code 的配置如下：

   claude mcp add memory -- total-agent-memory
   

   对于使用 mcpServers 文件的客户端：

   { "mcpServers": { "memory": { "command": "total-agent-memory" } } }
   

   如果安装在虚拟环境中，请使用其中 total-agent-memory 可执行文件的完整路径。

2. 重启客户端。除非 TAM_MEMORY_DIR 指向其他位置，否则记忆会存储在 ~/.tam/ 中。

3. 让 Agent 记住某件事（“记住我们选择 PostgreSQL 作为账单数据库，因为它支持行级安全”）。它会调用 memory_save。在之后的会话中，询问“我们选择了哪个数据库来处理账单？”，它会调用 memory_recall 并取回记录。

要在没有 Agent 的情况下试用服务，可以运行此脚本：它使用 MCP Python SDK（作为依赖项安装）通过 stdio 启动服务，保存一条记录并将其取回。该 SDK 默认只向服务传递少量变量，因此脚本会传递完整环境，包括 TAM_MEMORY_DIR：

import asyncio
import os

from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client


async def main() -> None:
    server = StdioServerParameters(command="total-agent-memory", env=dict(os.environ))
    async with stdio_client(server) as (read, write):
        async with ClientSession(read, write) as session:
            await session.initialize()
            await session.call_tool("memory_save", {
                "type": "decision",
                "content": "Chose PostgreSQL over MySQL for the billing service",
                "context": "WHY: row-level security per tenant",
                "project": "demo",
            })
            result = await session.call_tool("memory_recall", {
                "query": "which database for billing", "project": "demo", "limit": 3,
            })
            print(result.content[0].text)


asyncio.run(main())

TAM_MEMORY_DIR="$(mktemp -d)" python quickstart.py

首次运行时会下载默认嵌入模型。输出为 JSON，其中保存的决策位于 results.decision 下。更多示例请参阅工具和接口。

运行测试

测试需在源码检出目录中运行。以下命令与 .github/workflows 中的 CI 工作流一致：

git clone https://github.com/vbcherepanov/total-agent-memory.git
cd total-agent-memory
python3 -m venv .venv
.venv/bin/pip install -e . -r requirements-dev.txt

export FASTEMBED_CACHE_PATH="$PWD/.tam-models" TAM_MEMORY_DIR="$PWD/.tam-test-memory"
.venv/bin/python tests/smoke/prewarm_models.py   # downloads the text and code embedding models and the cross-encoder (~940 MB) once
.venv/bin/python -m pytest tests -q

测试无需 API 密钥或大模型；完整测试套件在笔记本电脑上需要 15 到 20 分钟。运行完整测试套件时，请勿设置 MEMORY_LLM_ENABLED=false：配置测试会检查 LLM 自动检测。缺少所需服务的测试会被跳过：

• PostgreSQL（团队服务后端）：安装额外依赖 .venv/bin/pip install -e ".[postgres]"，然后运行 .venv/bin/python -m pytest tests -m postgres --backend=postgres 或 --backend=both。如果未设置 TAM_TEST_PG_URL，测试夹具会通过 Docker 启动 pgvector 容器。详见 CONTRIBUTING.md 和 .github/workflows/postgres.yml。
• 浏览器测试（tests/browser，使用 Chromium、Firefox 和 WebKit 的 Playwright）在基于 docker/Dockerfile.browser 构建的镜像中运行；详见 .github/workflows/smoke.yml 中的 browser 任务。
• 已安装程序包冒烟测试：python tests/smoke/installed_runtime.py 会通过本地和远程 MCP 检查已安装的 wheel。

重现基准测试

检索基准测试（LoCoMo、LongMemEval、BEAM）无需 API 密钥；下载公开数据集后，可通过 benchmarks/ 中的脚本运行。使用默认配置文件 v13.0.0 得到的结果：

基准测试	指标	结果
LongMemEval（470 个问题）	R@5（recall_any）	95.1%
LoCoMo（1,536 个问题）	R@5	0.607
BEAM，1M-token 规模（625 个探测样本）	R@5	0.448

数据集位置、命令、端到端（由 LLM 评判）的准确率、负向对照、延迟以及 14.x 系列研究，详见 docs/benchmarks.md。

文档

• 安装指南：所有渠道、各平台设置、WSL2、IDE 矩阵、故障排除
• 设置向导：tam setup 和团队服务的网页向导
• 工具和接口：79 个 MCP 工具、CLI、TypeScript SDK、仪表板
• 配置：环境变量、LLM 提供商、性能调优
• 本地设置页面和内部 LLM 设置
• 架构
• 团队服务快速入门，以及仪表板、PostgreSQL、备份、入职指南和报告
• 基准测试和与其他系统的比较（2026 年 4 月快照）
• 更新和升级
• 14.x 新特性、路线图及 v8–v13 历史、CHANGELOG
• 安全策略

引用

一篇介绍 TAM 的论文目前正在 Journal of Open Source Software 审稿 （paper/paper.md）。在论文发表之前，请引用该软件和预印本：

Cherepanov, V. total-agent-memory（版本 14.9.0）[软件]。 https://github.com/vbcherepanov/total-agent-memory

预印本：doi:10.5281/zenodo.23011523

该软件的引用元数据见 CITATION.cff。

贡献

欢迎提交问题、拉取请求和基准测试复现。开发环境设置、拉取请求规则和提交约定详见 CONTRIBUTING.md。请按照 SECURITY.md 中的说明私下报告安全问题。 支持开发的捐赠：PayPal。

许可证

MIT。详见 LICENSE。第三方许可证列于 THIRD-PARTY-LICENSES.md。