# agent-memory

A local project memory server for AI coding agents. It stores decisions and codebase facts in Markdown and lets you review changes before they land.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 15
- Author: xChuCx
- License: Apache-2.0 · policy=link-only · description only; the file stays with the author
- Source: https://github.com/xChuCx/agent-memory
- Updated: 2026-10-02
- HTML: https://affpapa.org/en/nevibecode/mcp/xchucx-agent-memory

## What it does

agent-memory keeps task state, decisions, conventions, pitfalls, and module facts in Markdown within a Git repository. An agent can propose a memory update, stage it, show the exact diff, and apply it after review. Branch-aware storage and write-time scanning help keep project memory organized and secret-safe.

The server runs locally rather than using cloud storage or a vector database, with Markdown serving as the canonical record. It provides three MCP tools plus a CLI, and supports merging concurrent section edits. Claude Code can connect through `npx -y @xchucx/agent-memory` using `claude mcp add`. For the reader, the practical difference is clear: memory changes remain visible in Git instead of appearing as silent edits.

## Requirements
- Needs: Node.js (commands run via npx)

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add agent-memory -- npx -y @xchucx/agent-memory
```

### Codex

**Platform CLI**
```bash
codex mcp add xchucx-agent-memory -- npx -y @xchucx/agent-memory
```

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "xchucx-agent-memory": {
            "command": "npx",
            "args": [
                "-y",
                "@xchucx/agent-memory"
            ]
        }
    }
}
```

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "xchucx-agent-memory": {
            "type": "stdio",
            "command": "npx",
            "args": [
                "-y",
                "@xchucx/agent-memory"
            ]
        }
    }
}
```

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add xchucx-agent-memory npx -y @xchucx/agent-memory
```

## When to use it
- preserve decisions across agent sessions
- record conventions for individual modules
- review memory changes before applying them
- retrieve stored project facts with `fetch`
- scan new entries for secrets and PII

## Example prompts
- Record the decision about the library choice and stage it for review.
- Show me the pending memory diff, then apply it after I approve it.
- Use `fetch` to find the conventions for this module before editing the code.

## Similar
- [Engram](https://affpapa.org/en/nevibecode/mcp/rwnalds-engram.md) — MCP server · ★ 17
- [Cathedral — Persistent Memory for AI Agents](https://affpapa.org/en/nevibecode/mcp/cathedral-persistent-memory-for-ai-agents.md) — MCP server · ★ 10
- [commit-context](https://affpapa.org/en/nevibecode/skills/commit-context.md) — skill · 13700 installs
- [agent-knowledge](https://affpapa.org/en/nevibecode/mcp/agent-knowledge.md) — MCP server · ★ 19
- [memory-management](https://affpapa.org/en/nevibecode/skills/aaron-he-zhu-memory-management.md) — skill · 4900 installs
- [cursor-memory-curator](https://affpapa.org/en/nevibecode/skills/cursor-memory-curator.md) — skill · 2700 installs

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md