# xChuCx/agent-memory [Health: Active]

**Category:** 🧠 Knowledge & Memory  
**Repository:** https://github.com/xChuCx/agent-memory  
**GitHub Stars:** 9  
**Views:** 3  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/xchucx-agent-memory

## Description
Git-native project memory for coding agents: Markdown source of truth committed to your repo, reviewable staged updates (review --diff → apply), secret/PII-safe, branch-aware — no cloud, no vector DB.

## Tools
Capabilities this server exposes over MCP:

- **memory.fetch_context** — Read a budgeted Markdown context pack.
- **memory.propose_update** — Submit structured edits (apply or stage).
- **memory.status** — Report memory health: file counts, staged proposals (with drift), security/git/lock posture.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "agent-memory": {
    "command": "npx",
    "args": ["-y","@xchucx/agent-memory"]
  }
}
```

## Documentation

## What xChuCx/agent-memory MCP server does

The xChuCx/agent-memory MCP server stores durable project knowledge in Markdown under a repository-managed memory area. Its intended content includes current task state, decisions, coding conventions, pitfalls, and facts about individual modules. Git remains the synchronization and review mechanism, so memory changes can be inspected with normal repository workflows rather than hidden in a hosted service or database.

The system is designed for local use and supports branch-aware memory. It complements instruction files such as `AGENTS.md` or `CLAUDE.md`: those files describe how an agent should behave, while this project records searchable, reviewed knowledge about the codebase.

## How it works

Agents communicate through three MCP tools:

- `memory.fetch_context` returns a budget-limited Markdown context pack. It can provide a bootstrap context or retrieve information using a query.
- `memory.propose_update` accepts structured memory edits. Working notes and pitfalls can apply immediately, while durable categories can be staged for approval.
- `memory.status` reports memory health, including file counts, staged proposals and drift, plus security, Git, and lock posture.

Staged durable changes follow a review gate: inspect the generated diff with `agent-memory review --diff`, then use `agent-memory apply` or reject the proposal. This prevents durable edits from being written without approval. Writes also scan for secrets and personally identifiable information before content is stored.

The project includes a section-aware merge driver for concurrent team edits. Later releases also include multi-store search, a deterministic SHA-256 Merkle digest for active memory, and the VTP-1 lifecycle with task specification, claims, receipts, verification, and settlement. The README describes isolated-seat enforcement for verification and line-ending normalization for cross-platform digest consistency.

## Setup and configuration

Install a prebuilt `agent-memory` binary from the project’s latest release, or run the published package with `npx -y @xchucx/agent-memory`. A Go 1.25 or newer toolchain can alternatively install the binary with `go install`, and the repository can be built from source.

Inside the target repository, initialize memory with `agent-memory init --name my-project`. Start the MCP process with `agent-memory mcp`. The server resolves its repository root from the `--root` option, then `CLAUDE_PROJECT_DIR`, and finally the current working directory. A root should be scoped to the project being served; a single user-level registration with a hardcoded repository can send another project’s writes to the wrong location.

The `agent-memory install claude` command creates the Claude Code skill and merges a project-scoped `.mcp.json`. Other runtimes can use the same server through their adapter or MCP configuration. The README explicitly identifies Cursor, Claude Code, Codex/`AGENTS.md`, and Gemini CLI as supported runtime contexts.

## Tools and capabilities

The xChuCx/agent-memory MCP server exposes context retrieval, structured update proposals, and health reporting over MCP. Its broader CLI includes initialization, fetch, review, apply, rejection, status, synchronization, digest, and VTP operations. Memory is plain text, byte-preserving, Git-versioned, and usable without cloud access or a vector database.

## Limitations and notes

This release is repository-local; the roadmap identifies system-level and multi-repository memory as future work. Durable knowledge requires an explicit review and apply workflow. The README also describes the retrieval evaluation as an offline benchmark, not as a guarantee for every repository or query. Homebrew, Scoop, and winget packages are listed as planned rather than available installation methods.

_Full upstream README: https://allmcps.com/mcp/xchucx-agent-memory/readme_