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/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` show how many memories belong to each embedding model, and name the ones no semantic query can reach — records the encoder refused outright, and records embedded from their opening only
- **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 (opt-in)**: recall scoring can apply an exponential age decay so stale memories sink while canonical knowledge and character/identity stay put — off by default since T121 measured it costing Hit@5 0.7217 → 0.1942 at the old 30-day setting. Enable with `MCP_RECALL_HALFLIFE_DAYS`, and note that `MCP_RECALL_DECAY_TYPES` (default `working`) decides which types age at all — the type axis matters more than th