Agent Memory Mcp

agent-memory-mcp

A memory, docs, and repo context layer for engineering agents.

agent-memory-mcp helps agents work with live engineering context, not just isolated notes. It combines typed memory, document retrieval, and repository-aware tools so Claude, Cursor, Codex, and other MCP clients can recall decisions, search runbooks, inspect project docs, and reuse operational knowledge across sessions.

It is designed for engineering workflows such as:

• DevOps and platform operations
• infrastructure changes and rollback planning
• runbooks, changelogs, RFCs, and postmortems
• project-level memory that stays attached to the repo

Who This Is For

• teams using AI agents on real codebases, docs, and operational workflows
• DevOps, platform, and infra engineers who need more than chat history
• projects that want local-first memory today and a shared service path later

Why Not Just A Memory Tool

Most memory MCP servers focus on "store a note, recall a note."

agent-memory-mcp is aimed at a wider engineering context layer:

• typed memory for decisions, facts, patterns, and working context
• RAG indexing for project docs, changelogs, and knowledge files
• repo/file tools for reading and searching allowed project paths
• local SQLite storage with stdio today and HTTP/JSON-RPC when you need to share it

This makes it a better fit when the agent needs to answer questions like:

• "Why did we disable HPA on this service?"
• "What changed recently that could explain this regression?"
• "Which runbook or RFC matches this incident?"

Table of Contents

• [Who This Is For](#who-this-is-for)
• [Why Not Just A Memory Tool](#why-not-just-a-memory-tool)
• [Features](#features)
• [What Improved For Users](#what-improved-for-users)
• [Start Local In 3 Minutes](#start-local-in-3-minutes)
• [Local-Only Mode](#local-only-mode)
• [Index Your Repo In 2 Commands](#index-your-repo-in-2-commands)
• [Turn It Into A Team Service Later](#turn-it-into-a-team-service-later)
• [Installation Options](#installation-options) — Homebrew, binary, source, Docker
• [CLI Mode](#cli-mode)
• [MCP client configuration](#mcp-client-configuration) — Claude Desktop, Cursor, Codex
• [Recommended Workflow Snippets](#recommended-workflow-snippets) — what to paste into CLAUDE.md / .cursorrules
• [CLI commands](#cli-commands)
• [MCP tools reference](#mcp-tools-reference) — and JSON examples in [docs/MCPTOOLS.md](docs/MCPTOOLS.md)
• [Configuration](#configuration) — env vars, hot-reload, indexing safety
• [Security And Operations](#security-and-operations)
• [Architecture](#architecture)
• [macOS service installation](#macos-service-installation)
• [Troubleshooting / FAQ](#troubleshooting--faq)
• [Development](#development)

Reference docs: [HOOKS](docs/HOOKS.md) · [MCPTOOLS](docs/MCPTOOLS.md) · [SHAREDSERVICE](docs/SHAREDSERVICE.md) · [STEWARDSHIP](docs/STEWARDSHIP.md) · [SEDIMENTATION](docs/SEDIMENTATION.md) · [BACKUPRESTORE](docs/BACKUPRESTORE.md) · [SECURITY](docs/SECURITY.md) · [THREATMODEL](docs/THREATMODEL.md) · [CONTRIBUTING](docs/CONTRIBUTING.md) · [CHANGELOG](docs/CHANGELOG.md)

Features

• Automatic session capture — Claude Code hooks auto-capture knowledge at session end, save checkpoints before context compression, and compile pending summaries at session start
• Typed persistent memory with 4 types: episodic, semantic, procedural, working
• Hybrid retrieval that combines embeddings with keyword/BM25-like ranking
• RAG indexing for project docs, changelogs, and knowledge archives (enabled by default in stdio/CLI mode; disabled by default in the Homebrew service preset — see [Installation Options](#installation-options))
• Repo-aware file tools for listing, reading, and searching allowlisted paths
• Knowledge stewardship — automated maintenance: duplicate detection, conflict resolution, stale detection, drift scanning, and a review inbox
• Temporal knowledge model — track when knowledge was valid, build supersession chains, and query "what was true at time T"
• Dual transport: stdio for MCP clients, HTTP/JSON-RPC for APIs and shared setups
• SQLite storage for both memory and vector index -- no external databases needed
• Auto-indexing with file watcher for long-running local or service mode

What Improved For Users

• Lower memory usage: memory store now reads from SQLite directly instead of loading everything into RAM — large memory banks no longer risk OOM
• Opinionated solo-local setup: one recommended layout, one data directory, one quick smoke path
• Auto-loaded .env: run from your project root without manually sourcing environment variables
• Local-only embedding mode: keep hosted providers disabled and send text only to your local Ollama endpoint
• Safer semantic recall: memories from a different embedding model no longer produce misleading matches
• Explicit migration flow: use agent-memory-mcp reembed for memory migration and agent-memory-mcp index for RAG rebuilds after switching models
• Better visibility: stats and memory_stats now show how many memories belong to each embedding model
• Ready MCP client configs: generate copy-paste snippets for Claude Desktop, Cursor, and Codex
• Safer indexing defaults: built-in directory excludes, optional per-path exclude globs, and secret redaction before documents are indexed
• Source-aware retrieval: docs, ADRs, RFCs, changelogs, runbooks, postmortems, CI configs, Helm, Terraform, and K8s files are classified and surfaced with source metadata
• Hybrid ranking for search: semantic similarity is now combined with keyword matches, recency, and source-aware weighting instead of cosine similarity alone
• Trust-aware retrieval: memory and document results now expose source_type, confidence, freshness, owner, and last_verified_at, and ranking uses trust/freshness instead of similarity alone
• Explainable retrieval: opt-in debug output shows filters, score components, and applied boosts for every result
• DevOps-first tools: store decisions, incidents, runbooks, and postmortems with domain-specific MCP tools instead of generic memory calls
• Memory lifecycle: memories move through statuses — active, outdated, superseded, canonical — so stale knowledge gets downranked automatically instead of polluting recall
• Manual consolidation workflow: merge duplicates, mark outdated notes, promote canonical entries, and inspect conflict groups without deleting history
• Explicit canonical knowledge layer: list and recall confirmed knowledge separately from raw memory, and surface canonical context first in project summaries
• Project bank views: see maintained knowledge organized by category — decisions, runbooks, incidents, caveats, migrations, review queue — instead of a flat memory list
• Session close pipeline: when a session ends, memory is analyzed, classified, and consolidated with existing knowledge instead of blindly appended
• Explainable consolidation: session close reports show what will be added, merged, outdated, or promoted, with a decision trace and risk level for each action
• DevOps session modes: close-session adapts behavior based on session type — incident and migration sessions get stricter review-first policy, coding sessions auto-apply low-risk updates
• Shared service packaging: a working Docker Compose recipe, shared env template, nginx reverse proxy example, and a dedicated shared deployment guide
• Built-in retrieval console: inspect hybrid ranking, trust, and normal-vs-debug retrieval in a lightweight HTTP UI at /console
• Safer HTTP defaults: HTTP mode binds to 127.0.0.1 by default; non-loopback binds require auth unless you explicitly opt into unsafe unauthenticated access
• Consistent CLI and MCP behavior: memory type validation, tag normalization, query/content limits, and trust summaries now follow the same policy across both interfaces
• Knowledge stewardship: steward_run executes a full maintenance cycle — duplicate detection, conflict resolution, stale entry scanning, and canonical promotion candidates — with a single command
• Stewardship inbox: review-required actions from maintenance runs, drift scans, and session consolidation land in one actionable queue instead of being silently applied or lost
• Drift detection: drift_scan compares memory entries against live repo files and docs to find stale, missing, or changed references
• Verification model: verify_entry and verification_candidates let agents and users track when knowledge was last verified and what needs attention
• Canonical health diagnostics: steward runs now include a health summary for canonical entries — stale, unverified, conflicting, and low-support
• Policy-governed automation: stewardship thresholds, auto-apply rules, and scheduling are configurable via steward_policy and environment variables
• Temporal knowledge: memories can carry valid_from / valid_until timestamps, and recall_as_of retrieves knowledge that was valid at a specific point in time
• Supersession chains: mark_outdated with a superseding entry automatically builds bidirectional links (superseded_by / replaces) and sets temporal boundaries
• Knowledge timeline: knowledge_timeline shows the chronological evolution of knowledge on a topic
• Age-aware recall: recall scoring applies a configurable exponential age decay so stale, non-evergreen memories sink in results while canonical knowledge and character/identity stay put — tune the half-life with MCP_RECALL_HALFLIFE_DAYS (default 30 days; 0 disables)
• Self-healing duplicate cleanup: the steward can auto-merge high-confidence, near-identical duplicate groups instead of only queuing them for review — opt-in and guarded by a content-similarity threshold so nothing unique is archived (auto_merge_duplicate_min_confidence in steward_policy)
• No more double session-close records: closing a task folds the auto-captured session summary into the finalize record instead of writing a second near-identical memory per slug, cutting the duplicate pairs the steward used to flag as false contradictions

Start Local In 3 Minutes

The recommended path is: run locally first, prove value on one repo, then expand.

Run these commands from your project root.

Prerequisites

Install the binary with one of these options:

# Homebrew (macOS/Linux) — recommended, auto-configures Claude Code hooks
brew tap ipiton/tap
brew install agent-memory-mcp

# go install
go install github.com/ipiton/agent-memory-mcp/cmd/agent-memory-mcp@latest

Then configure one embedding provider:

• Jina AI API key for the quickest hosted setup
• OpenAI API key or another OpenAI-compatible endpoint
• Ollama with bge-m3 for a local setup

1. Configure local mode

cp .env.example .env
# Edit .env:
# - keep the solo-local defaults unless you need to change them
# - enable at least one embedding provider
#   JINA_API_KEY, OPENAI_API_KEY, or OLLAMA_BASE_URL

The binary auto-loads .env from the current directory, so you do not need source .env.

The recommended solo-local preset keeps all runtime state inside one directory:

.agent-memory/
  rag-index/
  memory-store/
  logs/

Local-Only Mode

Use local-only mode when you want embeddings without sending text to hosted APIs.

cp .env.example .env
# Then set:
# MCP_EMBEDDING_MODE=local-only
# JINA_API_KEY=
# OPENAI_API_KEY=

In local-only mode:

• agent-memory-mcp never calls Jina AI
• agent-memory-mcp never calls OpenAI-compatible embedding APIs
• embeddings are generated only through a local backend: Ollama or llama.cpp

What still uses the network:

• the local Ollama HTTP endpoint, typically http://localhost:11434
• or a local llama.cpp server, typically http://127.0.0.1:8080/v1

If no local backend is running or no supported local model is available, embedding requests fail with a local-only specific error telling you to start the backend or disable MCP_EMBEDDING_MODE=local-only.

Alternative local backend: llama.cpp

If you already run llama.cpp (Apple Silicon native, GGUF models), point the server at its OpenAI-compatible /v1/embeddings endpoint instead of installing Ollama. It is opt-in — set LLAMACPP_BASE_URL to enable it. Once set it joins the fallback chain before Ollama (Jina → OpenAI → llama.cpp → Ollama) and works in local-only mode.

# Start llama.cpp with an embedding model
llama-server -m bge-m3.gguf --embedding --pooling cls -c 8192 -ub 8192

# Then configure the MCP server
LLAMACPP_BASE_URL=http://127.0.0.1:8080/v1
LLAMACPP_EMBEDDING_MODEL=bge-m3
MCP_EMBEDDING_MODE=local-only

llama.cpp returns the model's native embedding dimension, so make sure MCP_EMBEDDING_DIMENSION matches it (1024 for bge-m3) — a mismatch is rejected at recall time.

On slow self-hosted hardware (Ollama with bge-m3 on a low-core or ARM VPS), a single chunk can take 4-7 seconds to embed and the default 5s timeout will fire repeatedly. Raise the limits:

MCP_EMBEDDING_TIMEOUT=30s      # default 5s
MCP_EMBEDDING_MAX_RETRIES=3    # default 1

Invalid values fall back to the defaults, so the service still starts.

Concurrency tuning when auto-index / file watcher is on

A single-slot llama-server processes requests strictly serially. With MCP_RAG_AUTO_INDEX / MCP_RAG_FILE_WATCHER enabled, background reindex batches (50 chunks each) hold the only slot for tens of seconds, so interactive recall / semantic_search / index_documents queue behind them and hit context deadline exceeded — the server looks "degraded" even though throughput is fine. Give the embedding server parallel slots so interactive calls slip in alongside the batch:

llama-server -m bge-m3.gguf --embedding --pooling cls \
  -c 32768 -b 8192 -ub 8192 \   # 8192 ctx PER SLOT (see note) — fits the largest chunk
  -np 4 -cb \                   # 4 slots + continuous batching: interactive calls don't wait for the batch
  --metrics                     # exposes Prometheus /metrics; /slots shows live slot occupancy

> -np splits the context. Per-slot context is ctx_size / n_parallel. bge-m3 is an encoder — every chunk must fit in one slot whole, and -b/-ub must be ≥ the largest chunk in tokens, or it fails with "input too large to process". So with -np 4 you need -c 32768 to keep 8192 per slot; do not lower -c, -b, or -ub below the single-slot value when adding slots.

Measured effect (Apple Silicon, bge-m3 Q8_0): a 50-input batch drops from ~50s to ~5s, and an interactive probe under batch load drops from 8–20s to ~0.03s.

Also smooth the reindex avalanche for large, frequently-edited files (whole-file re-chunk on every edit can re-trigger mid-cycle):

MCP_RAG_DEBOUNCE=2m         # default 30s — collapses bursts of edits into one reindex
MCP_RAG_WATCH_INTERVAL=5m   # periodic full-scan cadence

2. Start the local server

For MCP clients such as Claude Desktop, Cursor, or Codex:

agent-memory-mcp

For direct CLI use, the same binary already works without an MCP client:

agent-memory-mcp store -content "Ingress rollback uses previous Helm revision" -type procedural -tags "helm,rollback"
agent-memory-mcp recall "helm rollback"
agent-memory-mcp stats

3. Run a smoke check

agent-memory-mcp store -content "Solo local smoke check" -type working -tags "smoke,local"
agent-memory-mcp recall "solo local smoke"
agent-memory-mcp index
agent-memory-mcp search "agent memory"

If you are working from the source checkout, you can run the same flow with:

make local-smoke

Index Your Repo In 2 Commands

Once local mode is running against a project

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: ipiton
• Source: ipiton/agent-memory-mcp
• License: MIT

Install and usage instructions live in the source repository linked above.