# Total Agent Memory

> Total Agent Memory is an open-source MCP server for knowledge and memory. Local persistent memory for coding agents, with a temporal knowledge graph. It runs locally on your machine and is started by your AI client.

- **Kind:** MCP server
- **Pricing:** Open source
- **Platforms:** CLI, self-hosted, macOS, Windows, Linux
- **Website:** https://totalmemory.dev
- **Repository:** https://github.com/vbcherepanov/total-agent-memory
- **MCP Registry name:** io.github.vbcherepanov/total-agent-memory
- **Categories:** knowledge and memory, developer tools
- **Listing updated:** 2026-11-14

## About

Coding agents forget decisions between sessions, so conventions get explained again. This server keeps decisions, fixes, facts, errors and session summaries in a SQLite database on your own machine and returns them to any MCP client. The site's example saves a decision to use pgvector over ChromaDB in one session, then recalls the reasoning days later in another repo.

Recall fuses full-text BM25, locally computed embeddings, fuzzy matching and a knowledge graph with reciprocal rank fusion, then reranks with a local cross-encoder. The default profile makes no LLM call on write or search. Facts can carry validity intervals, and a newer value for a single-valued fact retires the older one. The release notes mention 79 tools. The maker reports 0.607 recall at 5 on LoCoMo and 0.448 on BEAM at 1M tokens, measured on 13.x.

The same package can run as a team server with personal, team and shared areas, roles, authorship and an audit trail. Setup needs Python 3.11 or newer, and the first start downloads about 330 MB of models. A setup wizard registers it with clients such as Claude Code, Codex, Cursor, Windsurf and Gemini CLI. It is MIT-licensed, with no telemetry; paid plans buy support and installation.

## Features

- **Local-first storage:** Memories live in SQLite files on your machine, with embeddings computed locally.
- **Hybrid recall:** Combines BM25, embeddings, fuzzy matching and a knowledge graph, then reranks.
- **Temporal facts:** Facts carry validity intervals and newer values can retire older ones.
- **No LLM in default path:** Saving and searching make no LLM call, so retrieval can be benchmarked offline.
- **Team server:** Personal, team and shared memory with roles, authorship and audit history.
- **Setup wizard:** Detects and registers with Claude Code, Codex, Cursor, Windsurf, Gemini CLI and others.
- **Private text stripping:** Private blocks and credentials are stripped on every write path.

## Good for

- Carry architecture decisions across sessions and repos
- Stop re-explaining project conventions to an agent
- Share team knowledge through a self-hosted server
- Run a local memory baseline for research

## Install

### Claude Code (Terminal)

```sh
claude mcp add total-agent-memory -- uvx total-agent-memory
```

### Claude Desktop (claude_desktop_config.json)

```json
{
  "mcpServers": {
    "total-agent-memory": {
      "command": "uvx",
      "args": [
        "total-agent-memory"
      ]
    }
  }
}
```

### Cursor (~/.cursor/mcp.json)

```json
{
  "mcpServers": {
    "total-agent-memory": {
      "command": "uvx",
      "args": [
        "total-agent-memory"
      ]
    }
  }
}
```

### VS Code (.vscode/mcp.json)

```json
{
  "servers": {
    "total-agent-memory": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "total-agent-memory"
      ]
    }
  }
}
```

### Windsurf (~/.codeium/windsurf/mcp_config.json)

```json
{
  "mcpServers": {
    "total-agent-memory": {
      "command": "uvx",
      "args": [
        "total-agent-memory"
      ]
    }
  }
}
```

### Other clients (your client's MCP settings (most use this shape))

```json
{
  "mcpServers": {
    "total-agent-memory": {
      "command": "uvx",
      "args": [
        "total-agent-memory"
      ]
    }
  }
}
```

## Tools

- `memory_save`: Save a decision, fact or other memory
- `memory_recall`: Recall memories matching a query
- `kg_add_fact`: Add a fact to the knowledge graph with validity
- `kg_at`: Query the knowledge graph as of a point in time

## FAQ

### Is it free?

The software is MIT-licensed and free; paid plans cover support, installation and response commitments.

### Does it call an LLM?

Not in the default save and search path; optional features use a provider you configure, which can be local.

### What does it need?

Python 3.11 or newer; the first start downloads about 330 MB of models.

### Is hosting offered?

Not yet; it is built to run on your own infrastructure.

### Is Total Agent Memory free?

Yes. Total Agent Memory is open source, so you can use and self-host it for free.

### How do I add Total Agent Memory to Claude Code?

Run this command in your terminal: claude mcp add total-agent-memory -- uvx total-agent-memory

### What are the best alternatives to Total Agent Memory?

The closest alternatives to Total Agent Memory are REA, Codebase Memory, GitHub, Serena MCP: the IDE for your agent and XERJ.

## Alternatives

- [REA](https://ai-powered.com/mcp/rea): REA is an open-source MCP server for developer tools.
- [Codebase Memory](https://ai-powered.com/mcp/codebase-memory): Codebase Memory is an open-source MCP server for knowledge and memory.
- [GitHub](https://ai-powered.com/mcp/github-2): GitHub is an open-source MCP server for developer tools.
- [Serena MCP: the IDE for your agent](https://ai-powered.com/mcp/serena-mcp-the-ide-for-your-agent): Serena MCP: the IDE for your agent is an open-source MCP server for developer tools.
- [XERJ](https://ai-powered.com/mcp/xerj): XERJ is an open-source MCP server for knowledge and memory.
- [Ouroboros](https://ai-powered.com/mcp/ouroboros): Ouroboros is an open-source MCP server for developer tools.
- [Claude Code Ultimate Guide](https://ai-powered.com/mcp/claude-code-ultimate-guide): Claude Code Ultimate Guide is an open-source MCP server for ai models and llm tooling.
- [Nautilus Compass Memory](https://ai-powered.com/mcp/nautilus-compass-memory): Nautilus Compass Memory is an open-source MCP server for knowledge and memory.

---
Source: https://ai-powered.com/mcp/total-agent-memory
