Memory, docs, and repo context layer for engineering agents.
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:
Most memory MCP servers focus on "store a note, recall a note."
agent-memory-mcp is aimed at a wider engineering context layer:
This makes it a better fit when the agent needs to answer questions like:
CLAUDE.md / .cursorrulesReference docs: HOOKS · MCP_TOOLS · SHARED_SERVICE · STEWARDSHIP · SEDIMENTATION · BACKUP_RESTORE · SECURITY · THREAT_MODEL · CONTRIBUTING · CHANGELOG
.env: run from your project root without manually sourcing environment variablesagent-memory-mcp reembed for memory migration and agent-memory-mcp index for RAG rebuilds after switching modelsstats 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 onlysource_type, confidence, freshness, owner, and last_verified_at, and ranking uses trust/freshness instead of similarity alone/console127.0.0.1 by default; non-loopback binds require auth unless you explicitly opt into unsafe unauthenticated accesssteward_run executes a full maintenance cycle — duplicate detection, conflict resolution, stale entry scanning, and canonical promotion candidates — with a single commanddrift_scan compares memory entries against live repo files and docs to find stale, missing, or changed referencesverify_entry and verification_candidates let agents and users track when knowledge was last verified and what needs attentionsteward_policy and environment variablesvalid_from / valid_until timestamps, and recall_as_of retrieves knowledge that was valid at a specific point in timemark_outdated with a superseding entry automatically builds bidirectional links (superseded_by / replaces) and sets temporal boundariesknowledge_timeline shows the chronological evolution of knowledge on a topicMCP_RECALL_HALFLIFE_DAYS, and note that MCP_RECALL_DECAY_TYPES (default working) decides which types age at all — the type axis matters more than the rateauto_merge_duplicate_min_confidence in steward_policy)The recommended path is: run locally first, prove value on one repo, then expand.
Run these commands from your project root.
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:
bge-m3 for a local setupcp .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/
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 AIagent-memory-mcp never calls OpenAI-compatible embedding APIsWhat still uses the network:
http://localhost:11434http://127.0.0.1:8080/v1If 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.
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.
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
-npsplits the context. Per-slot context isctx_size / n_parallel. bge-m3 is an encoder — every chunk must fit in one slot whole, and-b/-ubmust be ≥ the largest chunk in tokens, or it fails with "input too large to process". So with-np 4you need-c 32768to keep 8192 per slot; do not lower-c,-b, or-ubbelow 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
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
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
Once local mode is running against a project, index docs and search them:
agent-memory-mcp index
agent-memory-mcp search "recent ingress change"
Typical high-value sources include:
docs/README.mdCHANGELOG.mdWhen local mode proves useful, move in three steps:
Fastest shared-service path:
cd deploy/docker
cp .env.shared.example .env.shared
# edit MCP_HTTP_AUTH_TOKEN and MCP_PROJECT_ROOT
docker compose --env-file .env.shared up -d --build
This keeps the same retrieval stack, but packages it for team use.
Reference docs:
brew tap ipiton/tap
brew install agent-memory-mcp
brew services start agent-memory-mcp
This installs the binary, creates a default config, and starts the service on 127.0.0.1:18080 with memory enabled. RAG document search is disabled by default — enable it by editing the config:
# Edit config
nano $(brew --prefix)/etc/agent-memory-mcp/config.env
Set MCP_RAG_ENABLED=true, MCP_ROOT=/path/to/your/project, and MCP_INDEX_DIRS=docs,README.md. Changes are picked up automatically within ~30 seconds, or force reload with kill -HUP $(pgrep agent-memory-mcp).
Manage the service:
brew services restart agent-memory-mcp
brew services stop agent-memory-mcp
brew services info agent-memory-mcp
If you previously installed via Cask and want brew services:
brew uninstall --cask agent-memory-mcp
brew install ipiton/tap/agent-memory-mcp
Download a prebuilt archive from the Releases page.
The release archives include the version in their filename, so resolve the latest tag first:
# Resolve latest version once
VERSION=$(curl -fsSL https://api.github.com/repos/ipiton/agent-memory-mcp/releases/latest \
| grep '"tag_name"' | head -1 | cut -d'"' -f4 | sed 's/^v//')
# macOS (Apple Silicon)
curl -fsSL "https://github.com/ipiton/agent-memory-mcp/releases/download/v${VERSION}/agent-memory-mcp-${VERSION}-darwin-arm64.tar.gz" | tar xz
sudo mv agent-memory-mcp /usr/local/bin/
# macOS (Intel)
curl -fsSL "https://github.com/ipiton/agent-memory-mcp/releases/download/v${VERSION}/agent-memory-mcp-${VERSION}-darwin-amd64.tar.gz" | tar xz
sudo mv agent-memory-mcp /usr/local/bin/
# Linux (x86_64)
curl -fsSL "https://github.com/ipiton/agent-memory-mcp/releases/download/v${VERSION}/agent-memory-mcp-${VERSION}-linux-amd64.tar.gz" | tar xz
sudo mv agent-memory-mcp /usr/local/bin/
# Linux (arm64)
curl -fsSL "https://github.com/ipiton/agent-memory-mcp/releases/download/v${VERSION}/agent-memory-mcp-${VERSION}-linux-arm64.tar.gz" | tar xz
sudo mv agent-memory-mcp /usr/local/bin/
git clone https://github.com/ipiton/agent-memory-mcp.git
cd agent-memory-mcp
go build -o bin/agent-memory-mcp ./cmd/agent-memory-mcp
docker build -f deploy/docker/Dockerfile -t agent-memory-mcp .
docker run -p 18080:18080 \
-v memory-data:/data \
-e MCP_HTTP_MODE=http \
-e MCP_HTTP_HOST=0.0.0.0 \
-e MCP_HTTP_AUTH_TOKEN=replace-with-long-random-token \
agent-memory-mcp
Or with docker compose:
cd deploy/docker
cp .env.shared.example .env.shared
docker compose --env-file .env.shared up -d --build
The MCP HTTP endpoint will be available at http://localhost:18080/mcp.
By default, bare-metal HTTP mode now binds to 127.0.0.1. For shared/container deployments, set MCP_HTTP_HOST=0.0.0.0 and a bearer token.
The binary also works as a standalone CLI:
# Memory operations
agent-memory-mcp store -content "Project uses chi router" -type procedural -tags "go,chi"
agent-memory-mcp recall "router middleware"
agent-memory-mcp list -type procedural
agent-memory-mcp delete <memory-id>
# RAG search
agent-memory-mcp search "authentication flow"
agent-memory-mcp search -source-type runbook "ingress rollback"
agent-memory-mcp search -source-type runbook -debug "ingress rollback"
agent-memory-mcp index
# Project bank and session close
agent-memory-mcp project-bank canonical_overview
agent-memory-mcp close-session -summary "Updated payments rollback runbook after fixing ingress timeout" -context payments-api -service payments-api
agent-memory-mcp review-session -mode incident -stdin < notes/session.txt
agent-memory-mcp accept-session -summary "Added migration caveat for billing schema rename" -mode migration -context billing -service billing-api
agent-memory-mcp accept-session -raw-only -summary "Exploratory notes that are too noisy for consolidation"
# Utilities
agent-memory-mcp stats
agent-memory-mcp config claude-desktop
agent-memory-mcp reembed
agent-memory-mcp export > backup.json
agent-memory-mcp import backup.json
# JSON output for scripting
agent-memory-mcp recall "test" -json
agent-memory-mcp stats -json
Run agent-memory-mcp <command> -help for details on any command.
CLI memory commands and MCP memory tools now share the same validation and normalization rules:
verified timestamps are hidden from trust summaries in both CLI and MCP outputWhen no command is given (or flags start with -), the binary starts the MCP server as before -- full backward compatibility.
Use the built-in generator to produce a project-local config that starts the server from your repo root.
This is the recommended path because it:
.env loading working without duplicating settings into every MCP client.agent-memory/ relative to the project rootYou can override the detected project root or binary path with -root and -command.
Paste into ~/Library/Application Support/Claude/claude_desktop_config.json:
agent-memory-mcp config claude-desktop
Example generated output:
{
"mcpServers": {
"memory": {
"command": "/bin/sh",
"args": [
"-lc",
"cd '/path/to/your/project' && exec '/absolute/path/to/agent-memory-mcp'"
]
}
}
}
Paste into ~/.cursor/mcp.json:
agent-memory-mcp config cursor
Example generated output:
{
"mcpServers": {
"memory": {
"command": "/bin/sh",
"args": [
"-lc",
"cd '/path/to/your/project' && exec '/absolute/path/to/agent-memory-mcp'"
]
}
}
}
Paste into ~/.codex/config.toml:
agent-memory-mcp config codex
Example generated output:
[mcp_servers.memory]
command = "/bin/sh"
args = ["-lc", "cd '/path/to/your/project' && exec '/absolute/path/to/agent-memory-mcp'"]
agent-memory-mcp config claude-desktop \
-name engineering-memory \
-root /path/to/your/project \
-command /absolute/path/to/agent-memory-mcp
Without these snippets, the agent will only use basic store_memory and recall_memory. To unlock session close, engineering memory types, project bank, and consolidation, add relevant snippets to your agent's instructions.
Where to put them:
CLAUDE.md at the project root.cursorrules at the project rootAGENTS.mdPick the snippets that match your workflow. Start with "Start-of-session recall" and "Coding close" — they cover the most common case.
Before you start, recall the project context for this task.
Then recall recent changes related to the service or component I am touching.
Search for relevant runbooks, RFCs, changelog notes, or incident notes.
Prefer `summarize_project_context` or `project_bank_view view=canonical_overview` for the first pass and then drill into `search_runbooks` or `recall_similar_incidents`.
Summarize the constraints, caveats, and likely risks before making changes.
When the coding session ends, call `close_session` with a concise summary, service, and context.
Review the proposed `new`, `update`, `merge`, and `raw_only` actions plus the decision trace.
If the plan looks low risk, use `accept_session_changes`.
If the report is noisy or mostly exploratory, keep `save_raw_only` as the fallback.
Prefer `project_bank_view` at the next session start to confirm what became maintained knowledge.
When incident work stabilizes, call `close_session` or `review_session_changes` with `mode=incident`.
Expect stricter review-first behavior for updates, merges, and anything touching canonical operational knowledge.
Capture impact, mitigation, rollback, and unresolved follow-ups in the summary.
Apply only the low-risk actions automatically and leave ambiguous runbook or incident changes in review.
Follow up with `recall_similar_incidents` and `project_bank_view view=incidents` if you need to compare against existing knowledge.
When a migration session ends, call `close_session` with `mode=migration`, affected service, and the migration summary.
Prefer explicit notes about prerequisites, sequencing, rollback, and post-deploy verification.
Treat runbook replacements, caveat changes, and supersede proposals as review-first even when the textual match looks strong.
Use `accept_session_changes` only after checking the report for stale or superseded knowledge.
Finish by checking `project_bank_view view=migrations` to see the maintained migration notes.
If the session was exploratory, ambiguous, or too noisy, skip consolidation and save only the raw summary.
Use `close_session` / `review_session_changes` to inspect the plan first, then pick `save_raw_only`.
In CLI mode, `agent-memory-mcp accept-session -raw-only ...` is the explicit override.
This keeps the raw trace without forcing weak knowledge updates into the project bank.
Before making infra or platform changes, recall similar fixes, migrations, incidents, and known caveats.
Search for runbooks, postmortems, changelog notes, and recent project context related to this component.
Summarize blast radius, rollback options, and operational risks before editing files.
When memory has grown or a session just ended, run `steward_run` with `dry_run=true` to see what needs attention.
Review the report for duplicates, conflicts, stale entries, and canonical promotion candidates.
Check `steward_inbox` for pending review items and resolve them with `steward_inbox_resolve`.
Use `drift_scan` periodically to catch memories that reference files or docs that have changed.
Use `verification_candidates` to find knowledge that has not been verified recently.
When you need to understand what was true at a specific point in time, use `recall_as_of` with an RFC3339 timestamp.
To trace how knowledge about a topic evolved over time, use `knowledge_timeline`.
When superseding an old decision or runbook, use `mark_outdated` with the superseding entry ID to build a proper chain.
Start the server in HTTP mode:
# Standalone
MCP_HTTP_MODE=http \
MCP_HTTP_HOST=127.0.0.1 \
MCP_HTTP_PORT=18080 \
MCP_HTTP_AUTH_TOKEN=replace-with-long-random-token \
agent-memory-mcp
# Or with Docker
cd deploy/docker
docker compose --env-file .env.shared up -d --build
Then point your HTTP-capable MCP client or proxy at:
http://localhost:18080/mcp
The /mcp endpoint supports the MCP Streamable HTTP transport: JSON-RPC requests go over POST, and clients that need a server-push channel (Cursor and similar) open it with GET and Accept: text/event-stream. The server keeps that stream alive with periodic keepalive comments. A plain GET without the SSE Accept header still returns 405.
curl -N -H "Accept: text/event-stream" \
-H "Authorization: Bearer $MCP_HTTP_AUTH_TOKEN" \
http://localhost:18080/mcp
For retrieval inspection in a browser, open:
http://localhost:18080/console
The console is a lightweight UI for:
In shared mode, the page itself is static, but live queries from the console still require the same bearer token as /mcp.
For shared HTTP mode:
MCP_HTTP_HOST=127.0.0.1; this is the safe local defaultMCP_HTTP_HOST=0.0.0.0MCP_HTTP_AUTH_TOKEN to require Authorization: Bearer <token> on /mcpMCP_HTTP_AUTH_TOKEN, unless you explicitly set MCP_HTTP_INSECURE_ALLOW_UNAUTHENTICATED=true/health for load balancer or container health checkslocal -> team laptop -> shared service path| Command | Description |
|---|---|
serve | Start MCP server (stdio/http) -- default when no command given |
store | Store a memory (-content, -title, -type, -tags, -context, -importance, -stdin) |
recall | Memory recall with trust-aware ranking (positional query, -type, -tags, -limit, -json) |
list | List memories (-type, -context, -limit, -json) |
delete | Delete a memory by ID (positional) |
search | RAG hybrid search with trust metadata (positional query, -limit, -source-type, -debug, -json) |
index | Re-index documents for RAG |
close-session | Analyze an end-of-session summary and produce a close-session report (-summary, -stdin, -mode, -context, -service, -tags, -metadata, -started-at, -ended-at, -raw-only, -json) |
review-session | Review-oriented alias for close-session with the same inputs and report surface |
accept-session | Save the raw summary and auto-apply low-risk session changes (-summary, -stdin, -mode, -context, -service, -tags, -metadata, -started-at, -ended-at, -raw-only, -json) |
stats | Show memory statistics (-json) |
config | Generate ready MCP client config snippets |
project-bank | Show structured project bank views (canonical_overview, decisions, runbooks, incidents, caveats, migrations, review_queue) |
resolve-review-item | Resolve a pending review queue item (<id>, -resolution, -note, -owner, -json) |
reembed | Re-generate memory embeddings with the active model (-json; -truncated also re-encodes vectors built from a body's opening) |
export | Export all memories to JSON (-o file, default stdout) |
import | Import memories from JSON (positional file or stdin) |
index-triples | Retrofit (subj, rel, obj) triples for memories that lack them (-resume, -force, -limit, -context, -dry-run, -progress-every, -json). Powers the recall_multihop MCP tool — see MCP_TRIPLE_EXTRACTOR_* envs. |
dead-ends-stale | List dead_end memories older than -age (default 12 months) for re-evaluation (-limit, -json) |
setup | Auto-configure Claude Code hooks in ~/.claude/settings.json (-command, -dry-run, -force). See docs/HOOKS.md |
hooks-config | Print Claude Code hooks JSON for manual paste into settings.json (-command, -json) |
context-inject | SessionStart hook payload: recent memories + pending raw summaries (-limit, -pending-limit, -context, -service) |
auto-capture | SessionEnd hook: read transcript from stdin, run extract → plan → apply pipeline (-stdin, -summary, -mode, -context, -service, -tags, -dry-run, -json) |
checkpoint | PreCompact hook: save a raw session checkpoint before context compression (-stdin, -summary, -boundary, -context, -service, -tags) |
sweep-archive | Scan MCP_TASK_ARCHIVE_ROOTS and run end-task on every archived slug (T47) |
end-task | Consolidate working/procedural memories tied to one archived task slug (T47) |
mark-dead-end | Record an abandoned approach with its failure rationale (T46) |
sediment-cycle | Apply layer transitions for memory sedimentation: trivial promotions auto-apply, the rest queue for review (T48) |
recount-refs | Backfill referenced_by_count metadata from existing cross-memory edges (idempotent) |
| Tool | Description |
|---|---|
store_memory | Store a memory with content, type, tags, and importance |
recall_memory | Recall memories by semantic/text query with optional filters and trust-aware ranking |
update_memory | Update an existing memory by ID |
delete_memory | Delete a memory by ID |
list_memories | List all memories with optional type/context filtering |
memory_stats | Get memory statistics (counts by type) |
merge_duplicates | Merge duplicate memories into a primary entry and archive the rest |
mark_outdated | Mark a memory as outdated or superseded so trust-aware recall downranks it |
promote_to_canonical | Promote a memory to canonical knowledge and boost its trust ranking |
conflicts_report | Report duplicate candidates, conflicting statuses, and multiple canonical entries |
list_canonical_knowledge | List canonical knowledge entries projected from confirmed memories |
recall_canonical_knowledge | Recall canonical knowledge only, excluding raw memories from results |
recall_multihop | Multi-hop graph-walk recall over the (subj, rel, obj) triple corpus — returns memories ranked by aggregated path score with the chain of triples that reached each result. Use for cross-memory reasoning queries that single-hop search cannot trace. Requires MCP_TRIPLE_EXTRACTOR_* populated; backfill via index-triples CLI. |
| Tool | Description |
|---|---|
semantic_search | Hybrid search across indexed documents with optional source_type, trust metadata, and debug explain mode |
index_documents | Re-index documents for RAG search |
| Tool | Description |
|---|---|
repo_list | List files and folders under allowlisted paths |
repo_read | Read a file from allowlisted paths |
repo_search | Text search across allowlisted paths |
| Tool | Description |
|---|---|
store_decision | Store an engineering decision with rationale, status, and consequences |
store_incident | Store an incident with impact, root cause, resolution, service, and severity |
store_runbook | Store a runbook with procedure, trigger, verification, and rollback notes |
store_postmortem | Store a postmortem with root cause and action items |
close_session | Analyze a finished session into raw summary metadata, candidate knowledge items, and review-safe consolidation actions |
analyze_session | Compatibility alias for close_session with the same planning and reporting behavior |
review_session_changes | Render the explainable review report for a finished session without forcing writes |
accept_session_changes | Persist the raw summary and auto-apply only low-risk consolidation actions |
resolve_review_item | Resolve a pending review queue item so it disappears from the active inbox while keeping an audit trail |
search_runbooks | Search runbook memories plus indexed runbook docs |
recall_similar_incidents | Recall similar incidents from memory and indexed postmortems |
end_task | Consolidate memory for an archived task slug: outdate working/procedural entries, route high-importance ones to the review queue |
sweep_archive | Pull-mode scan over MCP_TASK_ARCHIVE_ROOTS that runs end_task on every archived slug |
store_dead_end | Record an attempted approach that failed (plus the why and the alternative used) so retrieval can surface it as a pitfall warning on related queries. Use this for standalone failures with no decision context. Use store_decision -avoided-dead-end-id <id> when the dead end is part of a larger architectural decision and you want to link both records into one rationale chain (T46) |
promote_sediment | Promote a memory to a higher sediment layer (surface → episodic → semantic → character). See docs/SEDIMENTATION.md |
demote_sediment | Demote a memory one sediment layer down |
sediment_cycle | Run the sediment transition cycle — auto-applies trivial promotions, routes non-trivial ones to the review queue |
summarize_project_context | Summarize recent decisions, runbooks, incidents, and related docs |
project_bank_view | Show a structured project bank view for canonical knowledge, decisions, runbooks, incidents, caveats, migrations, the review queue, or sediment promotion candidates |
| Tool | Description |
|---|---|
steward_run | Run a knowledge stewardship cycle: scan for duplicates, conflicts, stale entries, and canonical promotion candidates |
steward_report | Retrieve the latest stewardship report or a specific one by run ID |
steward_policy | Get or update the stewardship policy that controls detection thresholds, auto-apply rules, and scheduling |
steward_status | Show current stewardship status: policy mode, last run summary, pending review count, next scheduled run |
drift_scan | Compare memory entries against live sources (repo files, docs) to detect drift, missing references, and stale unverified knowledge |
verification_candidates | List memories that need verification, ranked by urgency |
verify_entry | Mark a memory as verified, updating its verification metadata |
steward_inbox | List stewardship inbox items — review-required actions from maintenance runs, drift scans, and session consolidation |
steward_inbox_resolve | Resolve a steward inbox item by applying an action: merge, mark_outdated, promote, verify, suppress, or defer |
| Tool | Description |
|---|---|
recall_as_of | Retrieve knowledge that was valid at a specific point in time, filtering by temporal validity |
knowledge_timeline | Show the chronological evolution of knowledge on a topic — how entries were created, superseded, and replaced over time |
Every MCP client loads the full JSON schema of every tool at initialize time —
before your first message. With ~40 tools that schema payload alone can occupy
tens of KB of the model's context window on every session. Two secondary costs
compound it: LLMs get measurably worse at picking the right tool as the count
climbs past ~20–40, and frequent session reloads re-pay the whole cost.
Set MCP_TOOL_GROUPING=true to collapse the core toolset into a handful of
grouped meta-tools, each dispatching by a required action discriminator:
// Grouped form // Equivalent legacy form
{ "name": "memory", { "name": "store_memory",
"arguments": { "arguments": { "content": "…" } }
"action": "store", "content": "…" } }
Groups: repo · memory · memory_admin · engineering · search ·
session, plus the index_documents and project_bank_view singletons — the
default surface drops from 41 tools to 8 (~42% smaller schema payload).
false; the flag only changes what
tools/list returns.tools/call accepts the grouped form
(memory + action=store) and the legacy name (store_memory) regardless
of the flag, so existing scripts never break.steward_inbox_resolve already uses its own
action argument — grouping deliberately leaves them ungrouped.Trade-off: each grouped call carries a slightly larger per-call schema (the union
of its actions' arguments). Prefer grouping for high-volume agent runs where
discovery cost dominates; leave it off for interactive debugging where seeing
each tool by name is clearer. Policy reference: docs/concepts/lifecycle.md
covers the related archive-sweep surface.
All configuration is via environment variables. See .env.example for the full list.
Config files are loaded in this order (each file only fills in values not already set):
--config /path/to/file (explicit path, skips chain; accepted by every command, not just serve).env in the current directory~/.config/agent-memory-mcp/config.env (XDG)$(brew --prefix)/etc/agent-memory-mcp/config.env (Homebrew)For solo local mode, copy .env.example to .env in your project root. For brew services, the config is auto-created at $(brew --prefix)/etc/agent-memory-mcp/config.env.
When running as a service (HTTP mode), the config file is watched for changes every 30 seconds. RAG-related settings (index dirs, embedding keys, enabled/disabled) are applied without restart. HTTP settings (port, host) require a full restart.
You can also force an immediate reload:
kill -HUP $(pgrep agent-memory-mcp)
| Variable | Default | Description |
|---|---|---|
MCP_ROOT | Current dir | Project root path |
MCP_ALLOW_DIRS | "" (only MCP_ROOT) | Comma-separated extra repo-relative paths the file tools (repo_list, repo_read, repo_search) may read. Paths must stay under MCP_ROOT; absolute paths or .. traversal are rejected at config load. Critical for shared/HTTP mode — keep narrow |
MCP_MAX_FILE_BYTES | 2097152 | Max file size (bytes) repo_read will return; larger files are rejected |
MCP_MAX_SEARCH_RESULTS | 200 | Hard cap for repo_search result count |
MCP_MAX_DEPTH | 3 | Max directory recursion depth for repo_list |
MCP_STDIO_MODE | line | Stdio framing: line (newline-delimited) or lsp (Content-Length headers) |
MCP_TOOL_GROUPING | false | Collapse the core toolset into grouped meta-tools on tools/list to cut the discovery schema payload (~42% smaller, 41→8 tools). tools/call accepts both grouped (memory+action) and legacy names regardless. See Tool grouping mode |
MCP_MEMORY_ENABLED | true | Enable memory tools |
MCP_MEMORY_PREVIEW_RUNES | 0 | Override the per-surface truncation cap (rune-based) for memory content/summary fields in MCP tool responses (recall_memory, list_memories, search_runbooks, …). 0 keeps the built-in caps (150/220/300); a positive value forces that single cap on all surfaces; a negative value disables truncation (full text). |
MCP_RAG_ENABLED | true | Enable RAG/search tools (Homebrew service preset overrides this to false until you set MCP_ROOT) |
MCP_HTTP_MODE | stdio | Transport: stdio or http |
MCP_HTTP_HOST | 127.0.0.1 | HTTP bind host; set 0.0.0.0 for shared/container deployments |
MCP_HTTP_PORT | 18080 | HTTP port (when in HTTP mode) |
MCP_HTTP_AUTH_TOKEN | - | Bearer token required for non-loopback/shared HTTP mode |
MCP_HTTP_INSECURE_ALLOW_UNAUTHENTICATED | false | Explicit unsafe override for non-loopback HTTP without auth |
JINA_API_KEY | - | Jina AI API key for embeddings |
OPENAI_API_KEY | - | OpenAI API key (or compatible: Together, Mistral) |
OPENAI_BASE_URL | https://api.openai.com/v1 | OpenAI-compatible base URL |
OPENAI_EMBEDDING_MODEL | text-embedding-3-small | Embedding model name |
OLLAMA_BASE_URL | http://localhost:11434 | Ollama URL (local fallback) |
LLAMACPP_BASE_URL | - | llama.cpp OpenAI-compatible base URL (e.g. http://127.0.0.1:8080/v1); empty disables it |
LLAMACPP_EMBEDDING_MODEL | bge-m3 | llama.cpp embedding model label (used only when LLAMACPP_BASE_URL is set). The label is part of the derived model id stored on every record, so changing it invalidates the bank exactly as changing the model does — see docs/EMBEDDING_MIGRATION.md |
MCP_EMBEDDING_MODE | auto | Embedding mode: auto or local-only |
MCP_EMBEDDING_DIMENSION | 1024 | Vector dimension (change requires re-indexing) |
MCP_EMBEDDING_TIMEOUT | 5s | Per-request embedding timeout; raise on slow local backends |
MCP_EMBEDDING_MAX_RETRIES | 1 | Embedding retry count on transient failures |
MCP_INDEX_DIRS | docs | Comma-separated directories and individual files to index for RAG. Code fallback is docs; the shipped .env.example preset sets docs,README.md,CHANGELOG.md for a typical project layout |
MCP_RAG_AUTO_INDEX | true | Index documents on startup. Code default is true (good for HTTP/service mode); the solo-local .env.example preset turns it off so you control indexing with explicit agent-memory-mcp index runs |
MCP_RAG_FILE_WATCHER | false | Watch MCP_INDEX_DIRS for changes and reindex incrementally; useful for long-running shared/service instances |
MCP_INDEX_EXCLUDE_DIRS | built-in defaults | Extra directory names or repo-relative paths to exclude from RAG indexing |
MCP_INDEX_EXCLUDE_GLOBS | - | Extra glob patterns matched against repo-relative paths, for example docs/internal/*.md |
MCP_REDACT_SECRETS | true | Redact common secret-like content before documents are indexed |
MCP_ARCHIVE_SWEEP_ENABLED | true | Zero-ops consolidation: a background loop marks archived-task working memories outdated (or promotes durable ones) with no manual runs. Auto-discovers <MCP_ROOT>/tasks/archive; no-op if absent. See Zero-ops consolidation |
MCP_ARCHIVE_SWEEP_INTERVAL | 1h | Background archive-sweep cadence. 0 disables the loop |
MCP_SESSION_TRACKING_ENABLED | true | Enable background session tracking, auto raw summaries, and low-risk close-session orchestration |
MCP_SESSION_IDLE_TIMEOUT | 10m | Idle timeout before the active background session auto-closes |
MCP_SESSION_CHECKPOINT_INTERVAL | 30m | Interval for periodic raw checkpoint snapshots during active sessions |
MCP_SESSION_MIN_EVENTS | 2 | Minimum tracked MCP tool calls before background auto-close runs |
MCP_DATA_PATH | data | Base path for data storage |
MCP_RAG_INDEX_PATH | <MCP_DATA_PATH>/rag-index | Override the SQLite vector index location |
MCP_MEMORY_DB_PATH | <MCP_DATA_PATH>/memory-store/memories.db | Override the SQLite memory database path |
MCP_LOG_PATH | <MCP_DATA_PATH>/logs/mcp-diagnostics.log | Override the diagnostics log file path |
MCP_STATS_ENABLED | false | Append per-call usage records (jsonl) for self-observability |
MCP_STATS_PATH | <MCP_DATA_PATH>/logs/mcp-usage.jsonl | Stats jsonl output path |
MCP_STATS_SAMPLE_RATE | 1.0 | Fraction (0.0–1.0) of calls to record when stats are enabled |
MCP_STEWARD_ENABLED | auto | Enable knowledge stewardship (auto-enabled in HTTP mode with memory) |
MCP_STEWARD_MODE | manual | Stewardship mode: off, manual, scheduled, event_driven |
MCP_STEWARD_SCHEDULE_INTERVAL | 24h | Interval between scheduled stewardship runs |
MCP_STEWARD_DUPLICATE_THRESHOLD | 0.85 | Similarity threshold for duplicate detection |
MCP_STEWARD_STALE_DAYS | 30 | Days before a memory is considered stale |
MCP_STEWARD_CANONICAL_MIN_CONFIDENCE | 0.80 | Minimum confidence for canonical promotion candidates |
MCP_CHECKPOINT_DEDUP_THRESHOLD | 0.9 | Jaccard similarity threshold above which a checkpoint is considered a duplicate of the previous one in the same context |
MCP_CHECKPOINT_DEDUP_WINDOW | 10m | Time window for the dedup lookup — only checkpoints newer than this are compared |
MCP_CHECKPOINT_DEDUP_MIN_CHARS | 100 | Minimum content length (chars) before a checkpoint is eligible to be saved; shorter content is dropped as empty |
MCP_CHECKPOINT_DEDUP_DISABLED | false | Escape hatch: disable checkpoint-hook deduplication entirely |
MCP_TASK_ARCHIVE_ROOTS | - | Colon-separated archive roots for sweep-archive / end-task (e.g. /home/you/tasks/archive). Empty disables the feature |
MCP_TASK_SLUG_PATTERN | - | Optional regex filtering archive subdirectory names; invalid regex fails config load |
MCP_RERANK_ENABLED | false | Master gate for the neural reranker stage after hybrid search. Must be true AND MCP_RERANK_PROVIDER must be a real provider (jina) for the reranker to run |
MCP_RERANK_PROVIDER | `disabled |
This listing does not have a supported local package template. Use the maintainer’s documentation for its hosted endpoint, authentication, and client-specific setup. No install command has been inferred.