Agent Memory

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.