# Agent Memory Mcp

> MCP server that gives AI agents persistent memory with semantic search

- **Type:** MCP server
- **Install:** `agentstack add mcp-ipiton-agent-memory-mcp`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [ipiton](https://agentstack.voostack.com/s/ipiton)
- **Installs:** 0
- **Category:** [Search](https://agentstack.voostack.com/c/search)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [ipiton](https://github.com/ipiton)
- **Source:** https://github.com/ipiton/agent-memory-mcp

## Install

```sh
agentstack add mcp-ipiton-agent-memory-mcp
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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/MCP_TOOLS.md](docs/MCP_TOOLS.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) · [MCP_TOOLS](docs/MCP_TOOLS.md) · [SHARED_SERVICE](docs/SHARED_SERVICE.md) · [STEWARDSHIP](docs/STEWARDSHIP.md) · [SEDIMENTATION](docs/SEDIMENTATION.md) · [BACKUP_RESTORE](docs/BACKUP_RESTORE.md) · [SECURITY](docs/SECURITY.md) · [THREAT_MODEL](docs/THREAT_MODEL.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:

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

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

Then configure one embedding provider:

- [Jina AI API key](https://jina.ai/) for the quickest hosted setup
- [OpenAI API key](https://platform.openai.com/) or another OpenAI-compatible endpoint
- [Ollama](https://ollama.ai/) with `bge-m3` for a local setup

### 1. Configure local mode

```bash
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:

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

## Local-Only Mode

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

```bash
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.

```bash
# 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:

```bash
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:

```bash
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):

```bash
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:

```bash
agent-memory-mcp
```

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

```bash
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

```bash
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:

```bash
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](https://github.com/ipiton)
- **Source:** [ipiton/agent-memory-mcp](https://github.com/ipiton/agent-memory-mcp)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-ipiton-agent-memory-mcp
- Seller: https://agentstack.voostack.com/s/ipiton
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.