# Compound Memory

> Compound Memory is an open-source MCP server for knowledge and memory. Local Markdown-and-git memory shared by several AI agents, exposed through five MCP tools. It runs locally on your machine and is started by your AI client.

- **Kind:** MCP server
- **Pricing:** Open source
- **Platforms:** CLI, self-hosted, macOS, Linux, Windows
- **Repository:** https://github.com/chinwe/compound-memory
- **MCP Registry name:** io.github.chinwe/compound-memory
- **Categories:** [knowledge and memory](https://ai-powered.com/categories/knowledge-and-memory), [developer tools](https://ai-powered.com/categories/developer-tools)
- **Listing updated:** 2026-11-18

## About

Memories are plain Markdown files with frontmatter, stored on your own disk and committed to a local git history on every write. The idea is that they strengthen with confirmed use, fade into a revivable archive when ignored, and get merged by distillation into fewer, denser entries.

The MCP surface is deliberately small: memory_write, memory_search, memory_get, memory_link and memory_feedback. A shared namespace is readable by every host, while each agent keeps a private agent-* namespace. Setting COMPOUND_MEMORY_AGENT_ID is required for multi-agent stores so identity comes from the process, not from what the model claims, and validation from a different host counts as independent evidence.

Search is lexical by default, with optional vector recall through sqlite-vec and BGE embeddings that falls back gracefully. It installs from PyPI via uvx, needs Python 3.11 or later, and has plugins for Claude Code, WorkBuddy/CodeBuddy and ZCode.

## Features

- **Five-tool surface:** write, search, get, link and feedback cover all reads and writes.
- **Plain Markdown storage:** Human-readable files with git auto-commit on each write.
- **Compounding recall:** Confirmed use raises confidence; neglected memories decay into an archive.
- **Per-host namespaces:** A shared space plus private agent namespaces, with host-attested identity.
- **Optional vector search:** Semantic recall with automatic fallback to lexical search.
- **Host plugins:** Packaged for Claude Code, WorkBuddy/CodeBuddy and ZCode.

## Good for

- Share project conventions across several coding agents
- Stop re-asking the same preferences each session
- Keep an auditable git history of agent memory
- Cross-validate memories between different agent hosts

## Install

### Claude Code (Terminal)

```sh
claude mcp add compound-memory -- uvx compound-memory
```

### Claude Desktop (claude_desktop_config.json)

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

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

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

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

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

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

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

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

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

## Tools

- `memory_write`: Write a memory to the store.
- `memory_search`: Search memories and return hits.
- `memory_get`: Fetch a specific memory.
- `memory_link`: Link related memories.
- `memory_feedback`: Record feedback that confirms or disputes a memory.

## FAQ

### Does any data leave my machine?

The README describes it as local-first: nothing leaves your machine, and memory lives in Markdown files on disk.

### Where is the store?

By default ~/.agents/memory, changeable with COMPOUND_MEMORY_ROOT.

### Why set COMPOUND_MEMORY_AGENT_ID?

It is required for a multi-agent store so a forged source cannot write another host's namespace.

### What does it require?

Python 3.11 or later and uv; the server launches with uvx from PyPI.

### Is Compound Memory free?

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

### How do I add Compound Memory to Claude Code?

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

### What are the best alternatives to Compound Memory?

The closest alternatives to Compound Memory are REA, Context7, Chrome DevTools MCP, Codebase Memory and GitHub.

## Where this comes from

- Description: written from the project's README.
- Install steps: from the official MCP Registry entry.

## Alternatives

- [REA](https://ai-powered.com/mcp/rea): REA is an open-source MCP server for developer tools.
- [Context7](https://ai-powered.com/mcp/context7): Context7 is a freemium MCP server for developer tools.
- [Chrome DevTools MCP](https://ai-powered.com/mcp/chrome-devtools-mcp-2): Chrome DevTools MCP is an open-source MCP server for browser automation.
- [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.
- [awesome-mcp-servers](https://ai-powered.com/mcp/awesome-mcp-servers-2): awesome-mcp-servers 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.

---
Source: https://ai-powered.com/mcp/compound-memory
