Total Agent Memory

MCP文档知识

提供方 未标注

文档知识 stdio · 本地进程 API Key 社区 / 第三方 Claude DesktopClaudeCursorVS Code
查看接入方式

为 AI 编码代理(Claude Code、Codex、Cursor)通过 MCP 提供本地持久化记忆:混合搜索、时序事实、团队作用域。

一句话选型结论

按资料字段整理

Total Agent Memory 属于文档知识类 MCP 服务器,stdio · 本地进程,API Key,可直接接入 Claude Desktop、Claude、Cursor 等,有可直接执行的安装命令。接入前先确认权限范围;涉及写入、删除或付款的操作,建议先在测试环境验证。

分类文档知识 传输方式stdio · 本地进程 鉴权API Key 部署方式本地部署
GitHub 星标 未标注 仓库热度,无公开仓库时显示未标注
工具数 未标注 暴露给模型的工具数量
资源 / 提示词 0 / 0 资源与提示词模板数量
维护方 社区 / 第三方 核验等级 仅资料核对

工具与能力

文档知识
数量来自来源目录的标注,具体工具清单以官方文档为准
工具数量未标注暴露给模型可调用的工具个数
资源数量0可读取的资源条目
提示词数量0内置提示词模板数量

能力标签

支持客户端

适用场景

记忆

安装与配置

stdio · 本地进程 API Key
客户端在本机拉起子进程,数据不出本机
pip install total-agent-memory # or: pipx install total-agent-memory uvx total-agent-memory # run once without installing

这条命令只是入口,具体启动参数请按官方文档补齐,不要直接照搬到别的服务器。

  1. 1
    准备运行环境

    stdio 服务在本地起进程,需要先装好 Node.js 等运行时,再按安装命令拉取依赖。

  2. 2
    安装服务

    复制上面的安装命令执行;命令里带占位符的位置,换成自己的密钥或路径。

  3. 3
    写入客户端配置

    在客户端的 MCP 配置里填好启动命令和参数,保存后完全退出客户端再打开,让新配置生效。

  4. 4
    验证是否可用

    连接成功后随便调一个只读工具,确认能返回结果,再接入正式流程。

典型使用场景

3 类
按分类与标签整理的常见用法,具体以官方文档为准
文档检索问答

在你的文档库里按问题找答案。

知识库读写

把新资料写进知识库,随用随取。

内容整理

把零散资料归纳成结构化笔记。

选择建议

选之前先看这几条
按条目字段给出的判断,不替你决定用不用

值得选的地方

  • 有现成的安装命令,不用自己找入口,照着跑就能起服务。
  • 已适配 Claude Desktop、Claude、Cursor,换客户端不用重新研究配置。

先想清楚的地方

  • stdio 方式要求本地装好运行时(如 Node.js),换机器要重新装一遍。
  • 使用前要准备好API Key对应的凭据,并按最小权限配置。
  • 资料没标注工具数量,实际能力要装好后确认。
  • 版本更新与行为细节以官方仓库为准。

更适合

  • 需要在文档知识场景里让模型直接调用外部能力的人。
  • 已经在用 Claude Desktop、Claude 的用户,接入路径最短。
  • 想先快速试一下、能接受在本地或自有环境跑服务的人。

不太适合

  • 完全不想在本地装环境的人。
  • 不方便管理密钥或第三方授权的人。
  • 需要厂商级 SLA 和技术支持的生产环境。

同类对比

6 个同类
同分类里挑最接近的几条,字段以各自详情页为准
MCP 服务器工具数传输方式部署方式安装命令最后核验
Total Agent Memory当前 未标注 stdio · 本地进程 本地部署 有 2026-11-20
dify 未标注 stdio · 本地进程 本地部署 有 2026-04-11
open-webui 未标注 stdio · 本地进程 本地部署 有 2026-04-11
JeecgBoot 未标注 stdio · 本地进程 本地部署 有 2026-04-11
Cherry Studio 未标注 未标注 未标注 无 2026-05-17
mempalace 未标注 stdio · 本地进程 本地部署 有 2026-04-11

服务器档案

文档知识
字段来自项目仓库与公开索引,中文说明由本站标注
提供方未标注上游标注的维护方 未标注
分类文档知识本站按上游分类展示
连接方式stdio · 本地进程客户端在本机拉起子进程,数据不出本机
鉴权方式API Key远程服务建议用最小权限凭据
维护方社区 / 第三方核验等级 仅资料核对
包名 / 运行时未标注 · 未标注本地安装时用到的包标识与运行时
部署类型本地部署上游给出的部署形态
最近核验2026-11-20上游最后核验时间

详细介绍

11.5 KB
来自项目仓库与上游目录的原文,未做删改

English | 简体中文

> Persistent, local memory for AI coding agents: Claude Code, Codex CLI, Cursor and any MCP client.
>
> Website and documentation: totalmemory.dev · Quick start · Claude Code guide · Benchmarks · Compare with other tools

total-agent-memory (TAM) is an open-source memory server for AI coding agents.
Coding agents start every session without memory of earlier ones, so decisions,
fixes and project conventions have to be explained again. TAM stores decisions,
solutions, facts, errors and session summaries on your machine and returns them
through the Model Context Protocol (MCP), so
any MCP client can use it without code changes.

Each store is one directory built around a SQLite database. Recall combines
full-text BM25, dense embeddings computed locally, fuzzy matching and a
knowledge graph, and fuses the ranked lists with reciprocal rank fusion. A local
cross-encoder then reranks the result: by default it starts as soon as its model
has loaded in the background, and MEMORY_CROSS_RERANK=off turns it off. The
default profile makes no LLM call on write or search, so retrieval can be
measured offline. With the cross-encoder off, reruns on fresh stores returned
the same ranking for every LoCoMo question. With the default setting the first
queries of a process can run before the model has loaded, so reruns are not
guaranteed to match. Facts can carry validity intervals (kg_add_fact, kg_at),
and a newer value of a single-valued fact can retire the older one.

TAM is for developers who use coding agents daily and for researchers who need
a memory baseline they can run locally, inspect and change. The same package
can also run as a team server: personal, department and company areas are
separate stores behind one gateway, with roles, authorship and an audit trail
(team server).

Installation

TAM needs Python 3.11 or newer. CI tests Python 3.11, 3.12 and 3.13 on
Ubuntu, Windows and macOS.

From PyPI (use a virtual environment, or pipx / uvx):```bash
pip install total-agent-memory # or: pipx install total-agent-memory
uvx total-agent-memory # run once without installing


This installs the `total-agent-memory` (alias `tam`) MCP server and the
`tam-team`, `tam-remote` and `lookup-memory` commands. The default cross-encoder
runs on ONNX through fastembed and needs no extra. A separate
sentence-transformers reranker pulls in PyTorch and is an extra:
`pip install "total-agent-memory[rerank]"`. The PostgreSQL backend of the team
server is the `[postgres]` extra.

**Register it with your clients.** Run `tam setup` at a terminal. The wizard
asks "Just me" or "Company server", detects Claude Code, Claude Desktop, Codex,
Cursor, Windsurf, Gemini CLI, Cline and OpenCode, and registers the server with
the ones you pick (setup wizard).

**First start.** With no command, `tam` starts the MCP server on stdio, which
is how MCP clients run it. `tam --help` lists the commands and `tam --version`
prints the version (from 14.11; earlier versions start the server for any
argument, so use `tam setup --help` there). The first start downloads about
330 MB of models: the text embedder (about 240 MB) and the cross-encoder (about
90 MB). The cross-encoder loads in the background, so a short script that exits
after a few queries gets the fused order without it. fastembed keeps the models
in the system temp directory, which macOS clears from time to time; set
`TAM_MODEL_CACHE=~/.tam/models` to keep them.

**Other channels:**

| Channel | Command |
|---|---|
| Docker (linux/amd64, linux/arm64) | `docker run -p 127.0.0.1:3737:3737 -p 127.0.0.1:37737:37737 -v ~/.tam:/data ghcr.io/vbcherepanov/total-agent-memory:15.0.0` — MCP over HTTP on `:3737/mcp`, dashboard on `:37737`; both need the token in `~/.tam/state/http-token` (`Authorization: Bearer`, dashboard: open `/login#token=...`, the token stays in the URL fragment and is exchanged for an opaque session cookie) |
| npx connector | `npx -y total-agent-memory connect claude-code` (or `codex`, `cursor`, `cline`, `continue`, `aider`, `windsurf`, `gemini-cli`, `opencode`) |
| Claude Code plugin (server, skill and capture hooks) | `/plugin marketplace add vbcherepanov/total-agent-memory`

`/plugin install total-agent-memory@vbcherepanov` |
Plugin for Claude Code and Cowork, from the plugin repository (server and skill, no hooks; needs uv) · `/plugin marketplace add vbcherepanov/total-agent-memory-plugin`
`/plugin install total-agent-memory@vbcherepanov` |
The same plugin for Codex CLI · `codex plugin marketplace add vbcherepanov/total-agent-memory-plugin`
`codex plugin add total-agent-memory@vbcherepanov` |
Source checkout with IDE hooks and background services · `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`)

Use one of the two Claude Code plugins, not both. Per-platform details, WSL2,
the IDE matrix, uninstalling and troubleshooting are in the
installation guide.

## Quick start

1. Install the package and run `tam setup`, or add the server to your client by
   hand. For Claude Code:```bash
   claude mcp add memory -- total-agent-memory
   ```

   For clients that use an `mcpServers` file:```json
   { "mcpServers": { "memory": { "command": "total-agent-memory" } } }
   ```

   If you installed into a virtual environment, use the full path to its
   `total-agent-memory` executable.

2. Restart the client. Memory is stored in `~/.tam/` unless `TAM_MEMORY_DIR`
   points elsewhere.

3. Ask the agent to remember something ("remember that we chose PostgreSQL
   for billing because of row-level security"). It calls `memory_save`. In a
   later session, ask "which database did we choose for billing?"; it calls
   `memory_recall` and gets the record back.

To try the server without an agent, this script starts it over stdio with the
MCP Python SDK (installed as a dependency), saves one record and recalls it.
The SDK passes only a few variables to the server by default, so the script
hands over the full environment, including `TAM_MEMORY_DIR`:```python
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())
``````bash
TAM_MEMORY_DIR="$(mktemp -d)" python quickstart.py

The first run downloads the default embedding model. The output
is JSON with the saved decision under results.decision. More examples:
tools and interfaces.

Running the tests

The tests run from a source checkout. These commands mirror the CI workflows
in .github/workflows:```bash
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
```

The tests need no API keys and no LLM; the full suite takes 15 to 20 minutes
on a laptop. Do not set MEMORY_LLM_ENABLED=false for the full suite: the
configuration tests check LLM auto-detection. Tests that need services you do not
have are skipped:

  • PostgreSQL (team server backend): install the extra with
    .venv/bin/pip install -e ".[postgres]", then run
    .venv/bin/python -m pytest tests -m postgres --backend=postgres or
    --backend=both. Without TAM_TEST_PG_URL the fixtures start a pgvector
    container through Docker. See CONTRIBUTING.md and
    .github/workflows/postgres.yml.
  • Browser tests (tests/browser, Playwright with Chromium, Firefox and
    WebKit) run in the image built from
    docker/Dockerfile.browser; see the browser
    job in .github/workflows/smoke.yml.
  • Installed-package smoke test: python tests/smoke/installed_runtime.py
    checks an installed wheel over local and remote MCP.

Reproducing the benchmarks

The retrieval benchmarks (LoCoMo, LongMemEval, BEAM) need no API key and run
with scripts in benchmarks/ once the public datasets are
downloaded. The table below was measured on v13.0.0, before the cross-encoder
became the default in 14.5, so it describes retrieval without the cross-encoder
and not a default install of the current version:

Benchmark Metric Result
LongMemEval (470 questions) R@5 (recall_any) 95.1%
LoCoMo (1,536 questions) R@5 0.607
BEAM, 1M-token scale (625 probes) R@5 0.448

Default settings score higher on LoCoMo and take much longer per query. In the
JOSS review of
v14.6.0 the editor measured R@5 of about 0.745 at about 495 ms median with the
defaults, against 0.607 at about 18 ms with MEMORY_CROSS_RERANK=off. Our own
runs of v14.6.0, three on a fresh store per setting, gave R@5 0.611 with the
cross-encoder off and 0.746 with the default and with on, at about 0.95-1.0 s
median per query on an Apple M2 Max; the median depends on the CPU. Each setting
returned the same ranking for every question in all three runs. With the default,
the first query of a process can arrive before the cross-encoder has loaded and
keeps the fused order; in these runs that changed one question out of 1,986
(rows, reports and commands). On v15.0.0,
whose default cross-encoder is multilingual, the same machine gave R@5 0.745 at
about 0.9 s median with the default and 0.609 at about 50 ms with the
cross-encoder off.

Dataset locations, commands, end-to-end (LLM-judged) accuracy, negative
controls, latency and the 14.x studies are in
docs/benchmarks.md.

Documentation

  • Installation guide: all channels, per-platform setup, WSL2, IDE matrix, troubleshooting
  • Setup wizard: tam setup and the team server's web wizard
  • Tools and interfaces: the 79 MCP tools, CLI, TypeScript SDK, dashboard
  • Configuration: environment variables, LLM providers, performance tuning
  • Local settings page and internal LLM settings
  • Architecture
  • Benchmarks and comparison with other systems (April 2026 snapshot)
  • Updating and upgrading
  • What is new in 14.x, roadmap and v8–v13 history, CHANGELOG
  • Security policy

Citation

A paper describing TAM is under review at the Journal of Open Source Software
(paper/paper.md). Until it is published, please cite the
software and the preprint:

> Cherepanov, V. total-agent-memory (version 15.0.0) [software].
> https://github.com/vbcherepanov/total-agent-memory
>
> Preprint: doi:10.5281/zenodo.23011523

Citation metadata for the software is in CITATION.cff.

Contributing

Issues, pull requests and benchmark reproductions are welcome. See
CONTRIBUTING.md for the development setup, the rules for a
pull request and the commit convention. Report security issues privately as
described in SECURITY.md.
Donations to support development: PayPal.

License

MIT. See LICENSE. Third-party licenses are listed in
THIRD-PARTY-LICENSES.md.

常见问题

8 问
答案由本站依据条目字段整理,不引用上游原文
Total Agent Memory 怎么安装?

在客户端按下面的安装命令接入:pip install total-agent-memory # or: pipx install total-agent-memory uvx total-agent-memory # run once without installing。装完在客户端配置里引用同一个包或端点。

Total Agent Memory 怎么在 Claude Desktop、Claude、Cursor 里配置?

它的传输方式是stdio · 本地进程,在客户端的 MCP 配置里填好启动命令和参数,保存后完全退出客户端再打开,配置才会生效。

Total Agent Memory 收费吗?

本站不代收费用,也没有标注具体价格。是否收费取决于服务本身和背后的接口额度,正式使用前按官方说明确认。

Total Agent Memory 需要 API Key 吗?

资料标注需要API Key认证,使用前准备好对应凭据,并按最小权限配置。

Total Agent Memory 支持哪些客户端?

资料标注支持 Claude Desktop、Claude、Cursor、VS Code、Windsurf、Cline;其他客户端只要能配置 MCP Server,也能用同样的命令或地址接入。

Total Agent Memory 能提供哪些能力?

资料显示能力标签包括 记忆。具体工具清单以官方文档为准。

Total Agent Memory 需要什么运行环境?

属于本地进程,需要在本机装好运行环境。

Total Agent Memory 是本地还是远程?

它是本地进程(stdio),由客户端在本机拉起。传输方式为stdio · 本地进程。

热门专题

按标签挑服务器
全部专题 →

服务器信息以作者仓库与官方文档为准;分类、传输方式与鉴权方式的中文说明为中文整理,最近核验 2026-11-20。