[{"_1":2,"_3":-5,"_4":-5},"loaderData",{"_5":6,"_7":8,"_9":10},"actionData","errors","root",{"_107":108},"routes/modules.$creator.$moduleId",{"_14":15,"_16":17,"_18":19,"_20":21},"routes/modules.$creator.$moduleId.endpoints",{"_11":12,"_13":-5},"error","Module not found","tools","module",{"_20":22,"_23":24,"_25":26,"_27":28,"_29":30,"_31":32,"_33":34,"_35":26,"_36":37,"_38":-5,"_39":-5,"_40":-5,"_41":42,"_43":44,"_45":46,"_47":48,"_49":50,"_51":52,"_53":54,"_55":-5,"_56":48,"_57":58,"_59":60,"_61":-5,"_62":-5,"_63":-5,"_64":-5,"_65":66,"_67":68,"_69":70,"_71":72,"_73":74,"_75":-5,"_76":-5,"_77":-5,"_78":48,"_79":-5,"_80":81,"_82":83,"_84":85,"_86":87,"_88":89,"_90":91,"_92":93},"apiUrl","https://odel.app/api","creator","ipiton","moduleId","agent-memory-mcp","@ipiton/agent-memory-mcp","displayName","Agent Memory MCP","tagline","Memory, docs, and repo context layer for engineering agents.","iconKey","https://avatars.githubusercontent.com/u/3993311?v=4","category","local","status","published","visibility","public","metaDescription","deploymentType","external","workerName","bindingName","mcpConfig","pricingModel","free","creatorUserId","system:external-import","createdAt",1786596476000,"updatedAt",1788583148000,"sourceRegistry","official-mcp-registry","sourceUrl","https://registry.modelcontextprotocol.io/v0/servers?search=io.github.ipiton%2Fagent-memory-mcp","sourceVerified",true,"sourceMissingSince","importedAt","upstreamStars",41,"upstreamUpdatedAt",1788548899000,"detectedTransport","detectedAuthType","probeStatus","lastProbedAt","githubRepoUrl","https://github.com/ipiton/agent-memory-mcp","githubRepoFullName","ipiton/agent-memory-mcp","releaseId","ext-ipiton-agent-memory-mcp","version","0.13.3","descriptionMarkdown","# agent-memory-mcp\n\nA memory, docs, and repo context layer for engineering agents.\n\n`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.\n\nIt is designed for engineering workflows such as:\n\n- DevOps and platform operations\n- infrastructure changes and rollback planning\n- runbooks, changelogs, RFCs, and postmortems\n- project-level memory that stays attached to the repo\n\n## Who This Is For\n\n- teams using AI agents on real codebases, docs, and operational workflows\n- DevOps, platform, and infra engineers who need more than chat history\n- projects that want local-first memory today and a shared service path later\n\n## Why Not Just A Memory Tool\n\nMost memory MCP servers focus on \"store a note, recall a note.\"\n\n`agent-memory-mcp` is aimed at a wider engineering context layer:\n\n- typed memory for decisions, facts, patterns, and working context\n- RAG indexing for project docs, changelogs, and knowledge files\n- repo/file tools for reading and searching allowed project paths\n- local SQLite storage with stdio today and HTTP/JSON-RPC when you need to share it\n\nThis makes it a better fit when the agent needs to answer questions like:\n\n- \"Why did we disable HPA on this service?\"\n- \"What changed recently that could explain this regression?\"\n- \"Which runbook or RFC matches this incident?\"\n\n## Table of Contents\n\n- [Who This Is For](#who-this-is-for)\n- [Why Not Just A Memory Tool](#why-not-just-a-memory-tool)\n- [Features](#features)\n- [What Improved For Users](#what-improved-for-users)\n- [Start Local In 3 Minutes](#start-local-in-3-minutes)\n- [Local-Only Mode](#local-only-mode)\n- [Index Your Repo In 2 Commands](#index-your-repo-in-2-commands)\n- [Turn It Into A Team Service Later](#turn-it-into-a-team-service-later)\n- [Installation Options](#installation-options) — Homebrew, binary, source, Docker\n- [CLI Mode](#cli-mode)\n- [MCP client configuration](#mcp-client-configuration) — Claude Desktop, Cursor, Codex\n- [Recommended Workflow Snippets](#recommended-workflow-snippets) — what to paste into `CLAUDE.md` / `.cursorrules`\n- [CLI commands](#cli-commands)\n- [MCP tools reference](#mcp-tools-reference) — and JSON examples in [docs/MCP_TOOLS.md](https://github.com/ipiton/agent-memory-mcp/blob/main/docs/MCP_TOOLS.md)\n- [Configuration](#configuration) — env vars, hot-reload, indexing safety\n- [Security And Operations](#security-and-operations)\n- [Architecture](#architecture)\n- [macOS service installation](#macos-service-installation)\n- [Troubleshooting / FAQ](#troubleshooting--faq)\n- [Development](#development)\n\nReference docs: [HOOKS](https://github.com/ipiton/agent-memory-mcp/blob/main/docs/HOOKS.md) · [MCP_TOOLS](https://github.com/ipiton/agent-memory-mcp/blob/main/docs/MCP_TOOLS.md) · [SHARED_SERVICE](https://github.com/ipiton/agent-memory-mcp/blob/main/docs/SHARED_SERVICE.md) · [STEWARDSHIP](https://github.com/ipiton/agent-memory-mcp/blob/main/docs/STEWARDSHIP.md) · [SEDIMENTATION](https://github.com/ipiton/agent-memory-mcp/blob/main/docs/SEDIMENTATION.md) · [BACKUP_RESTORE](https://github.com/ipiton/agent-memory-mcp/blob/main/docs/BACKUP_RESTORE.md) · [SECURITY](https://github.com/ipiton/agent-memory-mcp/blob/main/docs/SECURITY.md) · [THREAT_MODEL](https://github.com/ipiton/agent-memory-mcp/blob/main/docs/THREAT_MODEL.md) · [CONTRIBUTING](https://github.com/ipiton/agent-memory-mcp/blob/main/docs/CONTRIBUTING.md) · [CHANGELOG](https://github.com/ipiton/agent-memory-mcp/blob/main/docs/CHANGELOG.md)\n\n## Features\n\n- **Automatic session capture** — Claude Code hooks auto-capture knowledge at session end, save checkpoints before context compression, and compile pending summaries at session start\n- **Typed persistent memory** with 4 types: episodic, semantic, procedural, working\n- **Hybrid retrieval** that combines embeddings with keyword/BM25-like ranking\n- **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))\n- **Repo-aware file tools** for listing, reading, and searching allowlisted paths\n- **Knowledge stewardship** — automated maintenance: duplicate detection, conflict resolution, stale detection, drift scanning, and a review inbox\n- **Temporal knowledge model** — track when knowledge was valid, build supersession chains, and query \"what was true at time T\"\n- **Dual transport**: stdio for MCP clients, HTTP/JSON-RPC for APIs and shared setups\n- **SQLite storage** for both memory and vector index -- no external databases needed\n- **Auto-indexing** with file watcher for long-running local or service mode\n\n## What Improved For Users\n\n- **Lower memory usage**: memory store now reads from SQLite directly instead of loading everything into RAM — large memory banks no longer risk OOM\n- **Opinionated solo-local setup**: one recommended layout, one data directory, one quick smoke path\n- **Auto-loaded `.env`**: run from your project root without manually sourcing environment variables\n- **Local-only embedding mode**: keep hosted providers disabled and send text only to your local Ollama endpoint\n- **Safer semantic recall**: memories from a different embedding model no longer produce misleading matches\n- **Explicit migration flow**: use `agent-memory-mcp reembed` for memory migration and `agent-memory-mcp index` for RAG rebuilds after switching models\n- **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\n- **Ready MCP client configs**: generate copy-paste snippets for Claude Desktop, Cursor, and Codex\n- **Safer indexing defaults**: built-in directory excludes, optional per-path exclude globs, and secret redaction before documents are indexed\n- **Source-aware retrieval**: docs, ADRs, RFCs, changelogs, runbooks, postmortems, CI configs, Helm, Terraform, and K8s files are classified and surfaced with source metadata\n- **Hybrid ranking for search**: semantic similarity is now combined with keyword matches, recency, and source-aware weighting instead of cosine similarity alone\n- **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\n- **Explainable retrieval**: opt-in debug output shows filters, score components, and applied boosts for every result\n- **DevOps-first tools**: store decisions, incidents, runbooks, and postmortems with domain-specific MCP tools instead of generic memory calls\n- **Memory lifecycle**: memories move through statuses — active, outdated, superseded, canonical — so stale knowledge gets downranked automatically instead of polluting recall\n- **Manual consolidation workflow**: merge duplicates, mark outdated notes, promote canonical entries, and inspect conflict groups without deleting history\n- **Explicit canonical knowledge layer**: list and recall confirmed knowledge separately from raw memory, and surface canonical context first in project summaries\n- **Project bank views**: see maintained knowledge organized by category — decisions, runbooks, incidents, caveats, migrations, review queue — instead of a flat memory list\n- **Session close pipeline**: when a session ends, memory is analyzed, classified, and consolidated with existing knowledge instead of blindly appended\n- **Explainable consolidation**: session close reports show what will be added, merged, outdated, or promoted, with a decision trace and risk level for each action\n- **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\n- **Shared service packaging**: a working Docker Compose recipe, shared env template, nginx reverse proxy example, and a dedicated shared deployment guide\n- **Built-in retrieval console**: inspect hybrid ranking, trust, and normal-vs-debug retrieval in a lightweight HTTP UI at `/console`\n- **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\n- **Consistent CLI and MCP behavior**: memory type validation, tag normalization, query/content limits, and trust summaries now follow the same policy across both interfaces\n- **Knowledge stewardship**: `steward_run` executes a full maintenance cycle — duplicate detection, conflict resolution, stale entry scanning, and canonical promotion candidates — with a single command\n- **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\n- **Drift detection**: `drift_scan` compares memory entries against live repo files and docs to find stale, missing, or changed references\n- **Verification model**: `verify_entry` and `verification_candidates` let agents and users track when knowledge was last verified and what needs attention\n- **Canonical health diagnostics**: steward runs now include a health summary for canonical entries — stale, unverified, conflicting, and low-support\n- **Policy-governed automation**: stewardship thresholds, auto-apply rules, and scheduling are configurable via `steward_policy` and environment variables\n- **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\n- **Supersession chains**: `mark_outdated` with a superseding entry automatically builds bidirectional links (`superseded_by` / `replaces`) and sets temporal boundaries\n- **Knowledge timeline**: `knowledge_timeline` shows the chronological evolution of knowledge on a topic\n- **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 the rate\n- **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`)\n- **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\n\n## Start Local In 3 Minutes\n\nThe recommended path is: run locally first, prove value on one repo, then expand.\n\nRun these commands from your project root.\n\n### Prerequisites\n\nInstall the binary with one of these options:\n\n```bash\n# Homebrew (macOS/Linux) — recommended, auto-configures Claude Code hooks\nbrew tap ipiton/tap\nbrew install agent-memory-mcp\n```\n\n```bash\n# go install\ngo install github.com/ipiton/agent-memory-mcp/cmd/agent-memory-mcp@latest\n```\n\nThen configure one embedding provider:\n\n- [Jina AI API key](https://jina.ai/) for the quickest hosted setup\n- [OpenAI API key](https://platform.openai.com/) or another OpenAI-compatible endpoint\n- [Ollama](https://ollama.ai/) with `bge-m3` for a local setup\n\n### 1. Configure local mode\n\n```bash\ncp .env.example .env\n# Edit .env:\n# - keep the solo-local defaults unless you need to change them\n# - enable at least one embedding provider\n# JINA_API_KEY, OPENAI_API_KEY, or OLLAMA_BASE_URL\n```\n\nThe binary auto-loads `.env` from the current directory, so you do not need `source .env`.\n\nThe recommended solo-local preset keeps all runtime state inside one directory:\n\n```text\n.agent-memory/\n rag-index/\n memory-store/\n logs/\n```\n\n## Local-Only Mode\n\nUse local-only mode when you want embeddings without sending text to hosted APIs.\n\n```bash\ncp .env.example .env\n# Then set:\n# MCP_EMBEDDING_MODE=local-only\n# JINA_API_KEY=\n# OPENAI_API_KEY=\n```\n\nIn `local-only` mode:\n\n- `agent-memory-mcp` never calls Jina AI\n- `agent-memory-mcp` never calls OpenAI-compatible embedding APIs\n- embeddings are generated only through a local backend: Ollama or llama.cpp\n\nWhat still uses the network:\n\n- the local Ollama HTTP endpoint, typically `http://localhost:11434`\n- or a local llama.cpp server, typically `http://127.0.0.1:8080/v1`\n\nIf 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`.\n\n### Alternative local backend: llama.cpp\n\nIf 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.\n\n```bash\n# Start llama.cpp with an embedding model\nllama-server -m bge-m3.gguf --embedding --pooling cls -c 8192 -ub 8192\n\n# Then configure the MCP server\nLLAMACPP_BASE_URL=http://127.0.0.1:8080/v1\nLLAMACPP_EMBEDDING_MODEL=bge-m3\nMCP_EMBEDDING_MODE=local-only\n```\n\nllama.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.\n\nOn 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:\n\n```bash\nMCP_EMBEDDING_TIMEOUT=30s # default 5s\nMCP_EMBEDDING_MAX_RETRIES=3 # default 1\n```\n\nInvalid values fall back to the defaults, so the service still starts.\n\n#### Concurrency tuning when auto-index / file watcher is on\n\nA 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:\n\n```bash\nllama-server -m bge-m3.gguf --embedding --pooling cls \\\n -c 32768 -b 8192 -ub 8192 \\ # 8192 ctx PER SLOT (see note) — fits the largest chunk\n -np 4 -cb \\ # 4 slots + continuous batching: interactive calls don't wait for the batch\n --metrics # exposes Prometheus /metrics; /slots shows live slot occupancy\n```\n\n> **`-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.\n\nMeasured 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.\n\nAlso smooth the reindex avalanche for large, frequently-edited files (whole-file re-chunk on every edit can re-trigger mid-cycle):\n\n```bash\nMCP_RAG_DEBOUNCE=2m # default 30s — collapses bursts of edits into one reindex\nMCP_RAG_WATCH_INTERVAL=5m # periodic full-scan cadence\n```\n\n### 2. Start the local server\n\nFor MCP clients such as Claude Desktop, Cursor, or Codex:\n\n```bash\nagent-memory-mcp\n```\n\nFor direct CLI use, the same binary already works without an MCP client:\n\n```bash\nagent-memory-mcp store -content \"Ingress rollback uses previous Helm revision\" -type procedural -tags \"helm,rollback\"\nagent-memory-mcp recall \"helm rollback\"\nagent-memory-mcp stats\n```\n\n### 3. Run a smoke check\n\n```bash\nagent-memory-mcp store -content \"Solo local smoke check\" -type working -tags \"smoke,local\"\nagent-memory-mcp recall \"solo local smoke\"\nagent-memory-mcp index\nagent-memory-mcp search \"agent memory\"\n```\n\nIf you are working from the source checkout, you can run the same flow with:\n\n```bash\nmake local-smoke\n```\n\n## Index Your Repo In 2 Commands\n\nOnce local mode is running against a project, index docs and search them:\n\n```bash\nagent-memory-mcp index\nagent-memory-mcp search \"recent ingress change\"\n```\n\nTypical high-value sources include:\n\n- `docs/`\n- `README.md`\n- `CHANGELOG.md`\n- RFC / ADR folders\n- runbooks and incident notes\n\n## Turn It Into A Team Service Later\n\nWhen local mode proves useful, move in three steps:\n\n1. solo local\n2. team laptop with auto-indexing and file watching\n3. shared service with HTTP mode, auth token, and reverse proxy\n\nFastest shared-service path:\n\n```bash\ncd deploy/docker\ncp .env.shared.example .env.shared\n# edit MCP_HTTP_AUTH_TOKEN and MCP_PROJECT_ROOT\ndocker compose --env-file .env.shared up -d --build\n```\n\nThis keeps the same retrieval stack, but packages it for team use.\n\nReference docs:\n\n- [Shared Service Guide](https://github.com/ipiton/agent-memory-mcp/blob/main/docs/SHARED_SERVICE.md)\n- [Security Policy](https://github.com/ipiton/agent-memory-mcp/blob/main/docs/SECURITY.md)\n- [Backup And Restore](https://github.com/ipiton/agent-memory-mcp/blob/main/docs/BACKUP_RESTORE.md)\n\n## Installation Options\n\n### Homebrew (recommended for macOS)\n\n```bash\nbrew tap ipiton/tap\nbrew install agent-memory-mcp\nbrew services start agent-memory-mcp\n```\n\nThis 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:\n\n```bash\n# Edit config\nnano $(brew --prefix)/etc/agent-memory-mcp/config.env\n```\n\nSet `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)`.\n\nManage the service:\n\n```bash\nbrew services restart agent-memory-mcp\nbrew services stop agent-memory-mcp\nbrew services info agent-memory-mcp\n```\n\nIf you previously installed via Cask and want `brew services`:\n\n```bash\nbrew uninstall --cask agent-memory-mcp\nbrew install ipiton/tap/agent-memory-mcp\n```\n\n### Download a binary\n\nDownload a prebuilt archive from the [Releases](https://github.com/ipiton/agent-memory-mcp/releases) page.\n\nThe release archives include the version in their filename, so resolve the latest tag first:\n\n```bash\n# Resolve latest version once\nVERSION=$(curl -fsSL https://api.github.com/repos/ipiton/agent-memory-mcp/releases/latest \\\n | grep '\"tag_name\"' | head -1 | cut -d'\"' -f4 | sed 's/^v//')\n\n# macOS (Apple Silicon)\ncurl -fsSL \"https://github.com/ipiton/agent-memory-mcp/releases/download/v${VERSION}/agent-memory-mcp-${VERSION}-darwin-arm64.tar.gz\" | tar xz\nsudo mv agent-memory-mcp /usr/local/bin/\n\n# macOS (Intel)\ncurl -fsSL \"https://github.com/ipiton/agent-memory-mcp/releases/download/v${VERSION}/agent-memory-mcp-${VERSION}-darwin-amd64.tar.gz\" | tar xz\nsudo mv agent-memory-mcp /usr/local/bin/\n\n# Linux (x86_64)\ncurl -fsSL \"https://github.com/ipiton/agent-memory-mcp/releases/download/v${VERSION}/agent-memory-mcp-${VERSION}-linux-amd64.tar.gz\" | tar xz\nsudo mv agent-memory-mcp /usr/local/bin/\n\n# Linux (arm64)\ncurl -fsSL \"https://github.com/ipiton/agent-memory-mcp/releases/download/v${VERSION}/agent-memory-mcp-${VERSION}-linux-arm64.tar.gz\" | tar xz\nsudo mv agent-memory-mcp /usr/local/bin/\n```\n\n### Build from source\n\n```bash\ngit clone https://github.com/ipiton/agent-memory-mcp.git\ncd agent-memory-mcp\ngo build -o bin/agent-memory-mcp ./cmd/agent-memory-mcp\n```\n\n### Docker\n\n```bash\ndocker build -f deploy/docker/Dockerfile -t agent-memory-mcp .\ndocker run -p 18080:18080 \\\n -v memory-data:/data \\\n -e MCP_HTTP_MODE=http \\\n -e MCP_HTTP_HOST=0.0.0.0 \\\n -e MCP_HTTP_AUTH_TOKEN=replace-with-long-random-token \\\n agent-memory-mcp\n```\n\nOr with docker compose:\n\n```bash\ncd deploy/docker\ncp .env.shared.example .env.shared\ndocker compose --env-file .env.shared up -d --build\n```\n\nThe MCP HTTP endpoint will be available at `http://localhost:18080/mcp`.\n\nBy 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.\n\n## CLI Mode\n\nThe binary also works as a standalone CLI:\n\n```bash\n# Memory operations\nagent-memory-mcp store -content \"Project uses chi router\" -type procedural -tags \"go,chi\"\nagent-memory-mcp recall \"router middleware\"\nagent-memory-mcp list -type procedural\nagent-memory-mcp delete \n\n# RAG search\nagent-memory-mcp search \"authentication flow\"\nagent-memory-mcp search -source-type runbook \"ingress rollback\"\nagent-memory-mcp search -source-type runbook -debug \"ingress rollback\"\nagent-memory-mcp index\n\n# Project bank and session close\nagent-memory-mcp project-bank canonical_overview\nagent-memory-mcp close-session -summary \"Updated payments rollback runbook after fixing ingress timeout\" -context payments-api -service payments-api\nagent-memory-mcp review-session -mode incident -stdin < notes/session.txt\nagent-memory-mcp accept-session -summary \"Added migration caveat for billing schema rename\" -mode migration -context billing -service billing-api\nagent-memory-mcp accept-session -raw-only -summary \"Exploratory notes that are too noisy for consolidation\"\n\n# Utilities\nagent-memory-mcp stats\nagent-memory-mcp config claude-desktop\nagent-memory-mcp reembed\nagent-memory-mcp export > backup.json\nagent-memory-mcp import backup.json\n\n# JSON output for scripting\nagent-memory-mcp recall \"test\" -json\nagent-memory-mcp stats -json\n```\n\nRun `agent-memory-mcp -help` for details on any command.\n\nCLI memory commands and MCP memory tools now share the same validation and normalization rules:\n\n- invalid memory types are rejected consistently\n- comma-separated tags are trimmed and deduplicated the same way\n- zero `verified` timestamps are hidden from trust summaries in both CLI and MCP output\n\nWhen no command is given (or flags start with `-`), the binary starts the MCP server as before -- full backward compatibility.\n\n## MCP client configuration\n\nUse the built-in generator to produce a project-local config that starts the server from your repo root.\n\nThis is the recommended path because it:\n\n- keeps `.env` loading working without duplicating settings into every MCP client\n- keeps `.agent-memory/` relative to the project root\n- gives you one copy-paste snippet per client\n\nYou can override the detected project root or binary path with `-root` and `-command`.\n\n### Claude Desktop\n\nPaste into `~/Library/Application Support/Claude/claude_desktop_config.json`:\n\n```bash\nagent-memory-mcp config claude-desktop\n```\n\nExample generated output:\n\n```json\n{\n \"mcpServers\": {\n \"memory\": {\n \"command\": \"/bin/sh\",\n \"args\": [\n \"-lc\",\n \"cd '/path/to/your/project' && exec '/absolute/path/to/agent-memory-mcp'\"\n ]\n }\n }\n}\n```\n\n### Cursor\n\nPaste into `~/.cursor/mcp.json`:\n\n```bash\nagent-memory-mcp config cursor\n```\n\nExample generated output:\n\n```json\n{\n \"mcpServers\": {\n \"memory\": {\n \"command\": \"/bin/sh\",\n \"args\": [\n \"-lc\",\n \"cd '/path/to/your/project' && exec '/absolute/path/to/agent-memory-mcp'\"\n ]\n }\n }\n}\n```\n\n### Codex\n\nPaste into `~/.codex/config.toml`:\n\n```bash\nagent-memory-mcp config codex\n```\n\nExample generated output:\n\n```toml\n[mcp_servers.memory]\ncommand = \"/bin/sh\"\nargs = [\"-lc\", \"cd '/path/to/your/project' && exec '/absolute/path/to/agent-memory-mcp'\"]\n```\n\n### Rename the server or override paths\n\n```bash\nagent-memory-mcp config claude-desktop \\\n -name engineering-memory \\\n -root /path/to/your/project \\\n -command /absolute/path/to/agent-memory-mcp\n```\n\n## Recommended Workflow Snippets\n\nWithout 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.\n\nWhere to put them:\n\n- **Claude Code** — paste into `CLAUDE.md` at the project root\n- **Cursor** — paste into `.cursorrules` at the project root\n- **Codex** — paste into the system prompt or `AGENTS.md`\n- **Claude Desktop** — paste into the system prompt field in the project settings\n\nPick the snippets that match your workflow. Start with \"Start-of-session recall\" and \"Coding close\" — they cover the most common case.\n\n### Start-of-session recall\n\n```text\nBefore you start, recall the project context for this task.\nThen recall recent changes related to the service or component I am touching.\nSearch for relevant runbooks, RFCs, changelog notes, or incident notes.\nPrefer `summarize_project_context` or `project_bank_view view=canonical_overview` for the first pass and then drill into `search_runbooks` or `recall_similar_incidents`.\nSummarize the constraints, caveats, and likely risks before making changes.\n```\n\n### Coding close\n\n```text\nWhen the coding session ends, call `close_session` with a concise summary, service, and context.\nReview the proposed `new`, `update`, `merge`, and `raw_only` actions plus the decision trace.\nIf the plan looks low risk, use `accept_session_changes`.\nIf the report is noisy or mostly exploratory, keep `save_raw_only` as the fallback.\nPrefer `project_bank_view` at the next session start to confirm what became maintained knowledge.\n```\n\n### Incident close\n\n```text\nWhen incident work stabilizes, call `close_session` or `review_session_changes` with `mode=incident`.\nExpect stricter review-first behavior for updates, merges, and anything touching canonical operational knowledge.\nCapture impact, mitigation, rollback, and unresolved follow-ups in the summary.\nApply only the low-risk actions automatically and leave ambiguous runbook or incident changes in review.\nFollow up with `recall_similar_incidents` and `project_bank_view view=incidents` if you need to compare against existing knowledge.\n```\n\n### Migration close\n\n```text\nWhen a migration session ends, call `close_session` with `mode=migration`, affected service, and the migration summary.\nPrefer explicit notes about prerequisites, sequencing, rollback, and post-deploy verification.\nTreat runbook replacements, caveat changes, and supersede proposals as review-first even when the textual match looks strong.\nUse `accept_session_changes` only after checking the report for stale or superseded knowledge.\nFinish by checking `project_bank_view view=migrations` to see the maintained migration notes.\n```\n\n### Raw-only fallback\n\n```text\nIf the session was exploratory, ambiguous, or too noisy, skip consolidation and save only the raw summary.\nUse `close_session` / `review_session_changes` to inspect the plan first, then pick `save_raw_only`.\nIn CLI mode, `agent-memory-mcp accept-session -raw-only ...` is the explicit override.\nThis keeps the raw trace without forcing weak knowledge updates into the project bank.\n```\n\n### Before-changing-infra check\n\n```text\nBefore making infra or platform changes, recall similar fixes, migrations, incidents, and known caveats.\nSearch for runbooks, postmortems, changelog notes, and recent project context related to this component.\nSummarize blast radius, rollback options, and operational risks before editing files.\n```\n\n### Stewardship run\n\n```text\nWhen memory has grown or a session just ended, run `steward_run` with `dry_run=true` to see what needs attention.\nReview the report for duplicates, conflicts, stale entries, and canonical promotion candidates.\nCheck `steward_inbox` for pending review items and resolve them with `steward_inbox_resolve`.\nUse `drift_scan` periodically to catch memories that reference files or docs that have changed.\nUse `verification_candidates` to find knowledge that has not been verified recently.\n```\n\n### Temporal recall\n\n```text\nWhen you need to understand what was true at a specific point in time, use `recall_as_of` with an RFC3339 timestamp.\nTo trace how knowledge about a topic evolved over time, use `knowledge_timeline`.\nWhen superseding an old decision or runbook, use `mark_outdated` with the superseding entry ID to build a proper chain.\n```\n\n### HTTP mode (Docker, remote server, shared instance)\n\nStart the server in HTTP mode:\n\n```bash\n# Standalone\nMCP_HTTP_MODE=http \\\nMCP_HTTP_HOST=127.0.0.1 \\\nMCP_HTTP_PORT=18080 \\\nMCP_HTTP_AUTH_TOKEN=replace-with-long-random-token \\\nagent-memory-mcp\n\n# Or with Docker\ncd deploy/docker\ndocker compose --env-file .env.shared up -d --build\n```\n\nThen point your HTTP-capable MCP client or proxy at:\n\n```text\nhttp://localhost:18080/mcp\n```\n\nThe `/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`.\n\n```bash\ncurl -N -H \"Accept: text/event-stream\" \\\n -H \"Authorization: Bearer $MCP_HTTP_AUTH_TOKEN\" \\\n http://localhost:18080/mcp\n```\n\nFor retrieval inspection in a browser, open:\n\n```text\nhttp://localhost:18080/console\n```\n\nThe console is a lightweight UI for:\n\n- running document, raw-memory, and canonical-knowledge queries\n- comparing normal vs debug mode for document retrieval\n- inspecting source types, trust/freshness, and score breakdowns\n\nIn shared mode, the page itself is static, but live queries from the console still require the same bearer token as `/mcp`.\n\nFor shared HTTP mode:\n\n- default bare-metal bind is `MCP_HTTP_HOST=127.0.0.1`; this is the safe local default\n- for shared/container deployments set `MCP_HTTP_HOST=0.0.0.0`\n- set `MCP_HTTP_AUTH_TOKEN` to require `Authorization: Bearer ` on `/mcp`\n- startup now fails on non-loopback binds without `MCP_HTTP_AUTH_TOKEN`, unless you explicitly set `MCP_HTTP_INSECURE_ALLOW_UNAUTHENTICATED=true`\n- keep `/health` for load balancer or container health checks\n- terminate TLS at a reverse proxy or load balancer\n- do not expose the service directly on the public internet without auth and TLS\n- use [deploy/nginx/agent-memory-mcp.conf](https://github.com/ipiton/agent-memory-mcp/blob/main/deploy/nginx/agent-memory-mcp.conf) as the starting reverse proxy recipe\n- use [docs/SHARED_SERVICE.md](https://github.com/ipiton/agent-memory-mcp/blob/main/docs/SHARED_SERVICE.md) for the full `local -> team laptop -> shared service` path\n\n## CLI commands\n\n| Command | Description |\n|---------|-------------|\n| `serve` | Start MCP server (stdio/http) -- default when no command given |\n| `store` | Store a memory (`-content`, `-title`, `-type`, `-tags`, `-context`, `-importance`, `-stdin`) |\n| `recall` | Memory recall with trust-aware ranking (positional query, `-type`, `-tags`, `-limit`, `-json`) |\n| `list` | List memories (`-type`, `-context`, `-limit`, `-json`) |\n| `delete` | Delete a memory by ID (positional) |\n| `search` | RAG hybrid search with trust metadata (positional query, `-limit`, `-source-type`, `-debug`, `-json`) |\n| `index` | Re-index documents for RAG |\n| `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`) |\n| `review-session` | Review-oriented alias for `close-session` with the same inputs and report surface |\n| `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`) |\n| `stats` | Show memory statistics (`-json`) |\n| `config` | Generate ready MCP client config snippets |\n| `project-bank` | Show structured project bank views (`canonical_overview`, `decisions`, `runbooks`, `incidents`, `caveats`, `migrations`, `review_queue`) |\n| `resolve-review-item` | Resolve a pending review queue item (``, `-resolution`, `-note`, `-owner`, `-json`) |\n| `reembed` | Re-generate memory embeddings with the active model (`-json`) |\n| `export` | Export all memories to JSON (`-o` file, default stdout) |\n| `import` | Import memories from JSON (positional file or stdin) |\n| `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. |\n| `dead-ends-stale` | List dead_end memories older than `-age` (default 12 months) for re-evaluation (`-limit`, `-json`) |\n| `setup` | Auto-configure Claude Code hooks in `~/.claude/settings.json` (`-command`, `-dry-run`, `-force`). See [docs/HOOKS.md](https://github.com/ipiton/agent-memory-mcp/blob/main/docs/HOOKS.md) |\n| `hooks-config` | Print Claude Code hooks JSON for manual paste into `settings.json` (`-command`, `-json`) |\n| `context-inject` | SessionStart hook payload: recent memories + pending raw summaries (`-limit`, `-pending-limit`, `-context`, `-service`) |\n| `auto-capture` | SessionEnd hook: read transcript from stdin, run extract → plan → apply pipeline (`-stdin`, `-summary`, `-mode`, `-context`, `-service`, `-tags`, `-dry-run`, `-json`) |\n| `checkpoint` | PreCompact hook: save a raw session checkpoint before context compression (`-stdin`, `-summary`, `-boundary`, `-context`, `-service`, `-tags`) |\n| `sweep-archive` | Scan `MCP_TASK_ARCHIVE_ROOTS` and run `end-task` on every archived slug (T47) |\n| `end-task` | Consolidate working/procedural memories tied to one archived task slug (T47) |\n| `mark-dead-end` | Record an abandoned approach with its failure rationale (T46) |\n| `sediment-cycle` | Apply layer transitions for memory sedimentation: trivial promotions auto-apply, the rest queue for review (T48) |\n| `recount-refs` | Backfill `referenced_by_count` metadata from existing cross-memory edges (idempotent) |\n\n## MCP tools reference\n\n### Memory tools\n\n| Tool | Description |\n|------|-------------|\n| `store_memory` | Store a memory with content, type, tags, and importance |\n| `recall_memory` | Recall memories by semantic/text query with optional filters and trust-aware ranking |\n| `update_memory` | Update an existing memory by ID |\n| `delete_memory` | Delete a memory by ID |\n| `list_memories` | List all memories with optional type/context filtering |\n| `memory_stats` | Get memory statistics (counts by type) |\n| `merge_duplicates` | Merge duplicate memories into a primary entry and archive the rest |\n| `mark_outdated` | Mark a memory as outdated or superseded so trust-aware recall downranks it |\n| `promote_to_canonical` | Promote a memory to canonical knowledge and boost its trust ranking |\n| `conflicts_report` | Report duplicate candidates, conflicting statuses, and multiple canonical entries |\n| `list_canonical_knowledge` | List canonical knowledge entries projected from confirmed memories |\n| `recall_canonical_knowledge` | Recall canonical knowledge only, excluding raw memories from results |\n| `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. |\n\n### RAG tools\n\n| Tool | Description |\n|------|-------------|\n| `semantic_search` | Hybrid search across indexed documents with optional `source_type`, trust metadata, and `debug` explain mode |\n| `index_documents` | Re-index documents for RAG search |\n\n### File tools\n\n| Tool | Description |\n|------|-------------|\n| `repo_list` | List files and folders under allowlisted paths |\n| `repo_read` | Read a file from allowlisted paths |\n| `repo_search` | Text search across allowlisted paths |\n\n### Engineering workflow tools\n\n| Tool | Description |\n|------|-------------|\n| `store_decision` | Store an engineering decision with rationale, status, and consequences |\n| `store_incident` | Store an incident with impact, root cause, resolution, service, and severity |\n| `store_runbook` | Store a runbook with procedure, trigger, verification, and rollback notes |\n| `store_postmortem` | Store a postmortem with root cause and action items |\n| `close_session` | Analyze a finished session into raw summary metadata, candidate knowledge items, and review-safe consolidation actions |\n| `analyze_session` | Compatibility alias for `close_session` with the same planning and reporting behavior |\n| `review_session_changes` | Render the explainable review report for a finished session without forcing writes |\n| `accept_session_changes` | Persist the raw summary and auto-apply only low-risk consolidation actions |\n| `resolve_review_item` | Resolve a pending review queue item so it disappears from the active inbox while keeping an audit trail |\n| `search_runbooks` | Search runbook memories plus indexed runbook docs |\n| `recall_similar_incidents` | Recall similar incidents from memory and indexed postmortems |\n| `end_task` | Consolidate memory for an archived task slug: outdate working/procedural entries, route high-importance ones to the review queue |\n| `sweep_archive` | Pull-mode scan over `MCP_TASK_ARCHIVE_ROOTS` that runs `end_task` on every archived slug |\n| `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 `** when the dead end is part of a larger architectural decision and you want to link both records into one rationale chain (T46) |\n| `promote_sediment` | Promote a memory to a higher sediment layer (surface → episodic → semantic → character). See `docs/SEDIMENTATION.md` |\n| `demote_sediment` | Demote a memory one sediment layer down |\n| `sediment_cycle` | Run the sediment transition cycle — auto-applies trivial promotions, routes non-trivial ones to the review queue |\n| `summarize_project_context` | Summarize recent decisions, runbooks, incidents, and related docs |\n| `project_bank_view` | Show a structured project bank view for canonical knowledge, decisions, runbooks, incidents, caveats, migrations, the review queue, or sediment promotion candidates |\n\n### Stewardship tools\n\n| Tool | Description |\n|------|-------------|\n| `steward_run` | Run a knowledge stewardship cycle: scan for duplicates, conflicts, stale entries, and canonical promotion candidates |\n| `steward_report` | Retrieve the latest stewardship report or a specific one by run ID |\n| `steward_policy` | Get or update the stewardship policy that controls detection thresholds, auto-apply rules, and scheduling |\n| `steward_status` | Show current stewardship status: policy mode, last run summary, pending review count, next scheduled run |\n| `drift_scan` | Compare memory entries against live sources (repo files, docs) to detect drift, missing references, and stale unverified knowledge |\n| `verification_candidates` | List memories that need verification, ranked by urgency |\n| `verify_entry` | Mark a memory as verified, updating its verification metadata |\n| `steward_inbox` | List stewardship inbox items — review-required actions from maintenance runs, drift scans, and session consolidation |\n| `steward_inbox_resolve` | Resolve a steward inbox item by applying an action: merge, mark_outdated, promote, verify, suppress, or defer |\n\n### Temporal knowledge tools\n\n| Tool | Description |\n|------|-------------|\n| `recall_as_of` | Retrieve knowledge that was valid at a specific point in time, filtering by temporal validity |\n| `knowledge_timeline` | Show the chronological evolution of knowledge on a topic — how entries were created, superseded, and replaced over time |\n\n### Tool grouping mode (token efficiency)\n\nEvery MCP client loads the full JSON schema of every tool at `initialize` time —\nbefore your first message. With ~40 tools that schema payload alone can occupy\ntens of KB of the model's context window on every session. Two secondary costs\ncompound it: LLMs get measurably worse at picking the right tool as the count\nclimbs past ~20–40, and frequent session reloads re-pay the whole cost.\n\nSet `MCP_TOOL_GROUPING=true` to collapse the core toolset into a handful of\n**grouped meta-tools**, each dispatching by a required `action` discriminator:\n\n```jsonc\n// Grouped form // Equivalent legacy form\n{ \"name\": \"memory\", { \"name\": \"store_memory\",\n \"arguments\": { \"arguments\": { \"content\": \"…\" } }\n \"action\": \"store\", \"content\": \"…\" } }\n```\n\nGroups: `repo` · `memory` · `memory_admin` · `engineering` · `search` ·\n`session`, plus the `index_documents` and `project_bank_view` singletons — the\ndefault surface drops from **41 tools to 8** (~42% smaller schema payload).\n\n- **Opt-in, zero regression.** Default is `false`; the flag only changes what\n `tools/list` returns.\n- **Both call forms always work.** `tools/call` accepts the grouped form\n (`memory` + `action=store`) *and* the legacy name (`store_memory`) regardless\n of the flag, so existing scripts never break.\n- **Administrative & steward tools stay individual.** Rarely listed in\n high-volume agent runs, and `steward_inbox_resolve` already uses its own\n `action` argument — grouping deliberately leaves them ungrouped.\n\nTrade-off: each grouped call carries a slightly larger per-call schema (the union\nof its actions' arguments). Prefer grouping for **high-volume agent runs** where\ndiscovery cost dominates; leave it off for **interactive debugging** where seeing\neach tool by name is clearer. Policy reference: [`docs/concepts/lifecycle.md`](https://github.com/ipiton/agent-memory-mcp/blob/main/docs/concepts/lifecycle.md)\ncovers the related archive-sweep surface.\n\n## Configuration\n\nAll configuration is via environment variables. See [`.env.example`](https://github.com/ipiton/agent-memory-mcp/blob/main/.env.example) for the full list.\n\nConfig files are loaded in this order (each file only fills in values not already set):\n\n1. `--config /path/to/file` (explicit path, skips chain; accepted by every command, not just `serve`)\n2. `.env` in the current directory\n3. `~/.config/agent-memory-mcp/config.env` (XDG)\n4. `$(brew --prefix)/etc/agent-memory-mcp/config.env` (Homebrew)\n\nFor 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`.\n\n### Hot-reload\n\nWhen 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.\n\nYou can also force an immediate reload:\n\n```bash\nkill -HUP $(pgrep agent-memory-mcp)\n```\n\n### Key variables\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `MCP_ROOT` | Current dir | Project root path |\n| `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 |\n| `MCP_MAX_FILE_BYTES` | `2097152` | Max file size (bytes) `repo_read` will return; larger files are rejected |\n| `MCP_MAX_SEARCH_RESULTS` | `200` | Hard cap for `repo_search` result count |\n| `MCP_MAX_DEPTH` | `3` | Max directory recursion depth for `repo_list` |\n| `MCP_STDIO_MODE` | `line` | Stdio framing: `line` (newline-delimited) or `lsp` (Content-Length headers) |\n| `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](#tool-grouping-mode-token-efficiency) |\n| `MCP_MEMORY_ENABLED` | `true` | Enable memory tools |\n| `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). |\n| `MCP_RAG_ENABLED` | `true` | Enable RAG/search tools (Homebrew service preset overrides this to `false` until you set `MCP_ROOT`) |\n| `MCP_HTTP_MODE` | `stdio` | Transport: `stdio` or `http` |\n| `MCP_HTTP_HOST` | `127.0.0.1` | HTTP bind host; set `0.0.0.0` for shared/container deployments |\n| `MCP_HTTP_PORT` | `18080` | HTTP port (when in HTTP mode) |\n| `MCP_HTTP_AUTH_TOKEN` | - | Bearer token required for non-loopback/shared HTTP mode |\n| `MCP_HTTP_INSECURE_ALLOW_UNAUTHENTICATED` | `false` | Explicit unsafe override for non-loopback HTTP without auth |\n| `JINA_API_KEY` | - | Jina AI API key for embeddings |\n| `OPENAI_API_KEY` | - | OpenAI API key (or compatible: Together, Mistral) |\n| `OPENAI_BASE_URL` | `https://api.openai.com/v1` | OpenAI-compatible base URL |\n| `OPENAI_EMBEDDING_MODEL` | `text-embedding-3-small` | Embedding model name |\n| `OLLAMA_BASE_URL` | `http://localhost:11434` | Ollama URL (local fallback) |\n| `LLAMACPP_BASE_URL` | - | llama.cpp OpenAI-compatible base URL (e.g. `http://127.0.0.1:8080/v1`); empty disables it |\n| `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` |\n| `MCP_EMBEDDING_MODE` | `auto` | Embedding mode: `auto` or `local-only` |\n| `MCP_EMBEDDING_DIMENSION` | `1024` | Vector dimension (change requires re-indexing) |\n| `MCP_EMBEDDING_TIMEOUT` | `5s` | Per-request embedding timeout; raise on slow local backends |\n| `MCP_EMBEDDING_MAX_RETRIES` | `1` | Embedding retry count on transient failures |\n| `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 |\n| `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 |\n| `MCP_RAG_FILE_WATCHER` | `false` | Watch `MCP_INDEX_DIRS` for changes and reindex incrementally; useful for long-running shared/service instances |\n| `MCP_INDEX_EXCLUDE_DIRS` | built-in defaults | Extra directory names or repo-relative paths to exclude from RAG indexing |\n| `MCP_INDEX_EXCLUDE_GLOBS` | - | Extra glob patterns matched against repo-relative paths, for example `docs/internal/*.md` |\n| `MCP_REDACT_SECRETS` | `true` | Redact common secret-like content before documents are indexed |\n| `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 `/tasks/archive`; no-op if absent. See [Zero-ops consolidation](#zero-ops-task-memory-consolidation) |\n| `MCP_ARCHIVE_SWEEP_INTERVAL` | `1h` | Background archive-sweep cadence. `0` disables the loop |\n| `MCP_SESSION_TRACKING_ENABLED` | `true` | Enable background session tracking, auto raw summaries, and low-risk close-session orchestration |\n| `MCP_SESSION_IDLE_TIMEOUT` | `10m` | Idle timeout before the active background session auto-closes |\n| `MCP_SESSION_CHECKPOINT_INTERVAL` | `30m` | Interval for periodic raw checkpoint snapshots during active sessions |\n| `MCP_SESSION_MIN_EVENTS` | `2` | Minimum tracked MCP tool calls before background auto-close runs |\n| `MCP_DATA_PATH` | `data` | Base path for data storage |\n| `MCP_RAG_INDEX_PATH` | `/rag-index` | Override the SQLite vector index location |\n| `MCP_MEMORY_DB_PATH` | `/memory-store/memories.db` | Override the SQLite memory database path |\n| `MCP_LOG_PATH` | `/logs/mcp-diagnostics.log` | Override the diagnostics log file path |\n| `MCP_STATS_ENABLED` | `false` | Append per-call usage records (jsonl) for self-observability |\n| `MCP_STATS_PATH` | `/logs/mcp-usage.jsonl` | Stats jsonl output path |\n| `MCP_STATS_SAMPLE_RATE` | `1.0` | Fraction (0.0–1.0) of calls to record when stats are enabled |\n| `MCP_STEWARD_ENABLED` | auto | Enable knowledge stewardship (auto-enabled in HTTP mode with memory) |\n| `MCP_STEWARD_MODE` | `manual` | Stewardship mode: `off`, `manual`, `scheduled`, `event_driven` |\n| `MCP_STEWARD_SCHEDULE_INTERVAL` | `24h` | Interval between scheduled stewardship runs |\n| `MCP_STEWARD_DUPLICATE_THRESHOLD` | `0.85` | Similarity threshold for duplicate detection |\n| `MCP_STEWARD_STALE_DAYS` | `30` | Days before a memory is considered stale |\n| `MCP_STEWARD_CANONICAL_MIN_CONFIDENCE` | `0.80` | Minimum confidence for canonical promotion candidates |\n| `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 |\n| `MCP_CHECKPOINT_DEDUP_WINDOW` | `10m` | Time window for the dedup lookup — only checkpoints newer than this are compared |\n| `MCP_CHECKPOINT_DEDUP_MIN_CHARS` | `100` | Minimum content length (chars) before a checkpoint is eligible to be saved; shorter content is dropped as empty |\n| `MCP_CHECKPOINT_DEDUP_DISABLED` | `false` | Escape hatch: disable checkpoint-hook deduplication entirely |\n| `MCP_TASK_ARCHIVE_ROOTS` | - | Colon-separated archive roots for `sweep-archive` / `end-task` (e.g. `/home/you/tasks/archive`). Empty disables the feature |\n| `MCP_TASK_SLUG_PATTERN` | - | Optional regex filtering archive subdirectory names; invalid regex fails config load |\n| `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 |\n| `MCP_RERANK_PROVIDER` | `disabled` | Reranker provider: `jina` or `disabled`. With `disabled` (or empty) the pipeline degrades to hybrid-only ranking even when `MCP_RERANK_ENABLED=true` |\n| `JINA_RERANKER_MODEL` | `jina-reranker-v2-base-multilingual` | Jina reranker model id |\n| `MCP_RERANK_TIMEOUT` | `5s` | Hard timeout for one rerank call; on timeout the hybrid order is kept and `rerank_failed:timeout` is added to debug signals |\n| `MCP_RERANK_TOP_N` | `40` | Number of top hybrid candidates sent to the reranker; clamped to `100` at call time |\n| `MCP_RETRIEVAL_STRICT` | `false` | Turn silent degradation on the read path into a failed call: an embedding provider falling through to the next one, a reranker timing out, a multihop query with no graph to walk. Intended for measurement runs (`make eval` enables it) and for diagnosing a half-configured install — **leave it off in production**, where a worse answer beats no answer. Regardless of this flag, every `semantic_search` response carries a `retrieval` block naming the path that actually served it |\n| `MCP_SEDIMENT_ENABLED` | `false` | Enable layer-aware retrieval scoring (character always surfaced, surface excluded outside context). Schema migration + backfill always run; only retrieval weighting is gated. See `docs/SEDIMENTATION.md` |\n| `MCP_RECALL_CENTERED` | `true` | Score memory recall over mean-centered embeddings instead of raw cosine. Adopted on a measured win (T76a): on 345 machine-labelled queries against a live bank, Hit@5 went 0.6232 → 0.7217 and MRR 0.4922 → 0.5739. Raw cosine on real corpora is anisotropic — unrelated pairs sat at a median of 0.555, so `minScore` cleared 100% of candidates and gated nothing; centered, the same sample clears it at 34.1%. Banks with fewer than 100 embeddings ignore this and use raw cosine, since a mean over a handful of vectors is dominated by the vectors it must cancel. Set `false` to score the way earlier releases did |\n| `MCP_RECALL_HALFLIFE_DAYS` | `0` | T68 exponential age decay on recall scoring (half-life in days; a card this old scores at half weight). `0` disables decay — the default since T121 measured it: over 345 machine-labelled queries Hit@5 was 0.7217 with decay off against 0.1942 at the previous 30-day default, monotone in between (365d 0.6087, 180d 0.4609, 90d 0.2870), and no age bucket where decay paid for itself. Preferring the current version of a fact is already handled semantically by supersession and lifecycle status; a calendar multiplier cannot tell \"written a while ago\" from \"no longer true\". Evergreen entries (canonical knowledge, character layer) never decay |\n| `MCP_RECALL_DECAY_TYPES` | `working` | Which memory types age when decay is enabled at all. The type axis dominates the rate: at the same 30-day half-life, decaying every type scored Hit@5 0.1942 while decaying only `working` scored 0.7043 — the old behaviour aged patterns and facts, which is the knowledge the bank exists to accumulate. Empty means every type decays |\n| `MCP_RAG_KEEP_NOISE` | `false` | T49 escape hatch: keep noisy Markdown sections (Table of Contents / References / Changelog / etc.) in the index instead of dropping them at chunking time |\n| `MCP_RAG_MAX_CHUNKS_PER_DOC` | `1` | How many chunks of one document may occupy a search result list. Adjacent chunks of a file carry nearly the same score, so an uncapped top-5 unfolded into **2.07** distinct documents on 250 questions — over half the list spent on more of a file already shown. At one chunk per document that is 5.00, R@5 by document 0.5104 → 0.8676 and nDCG@5 0.6184 → 0.8927, while first-hit metrics hold (Hit@5 0.9600 → 0.9640, MRR 0.9580 → 0.9590); 207 of 250 queries improved and none got worse (T127). The cap is a preference, not a quota — when fewer documents exist than the limit asks for, the skipped chunks are added back rather than the list coming up short. `0` restores the uncapped order, `2` is the middle position (3.11 documents, R@5 0.7648) |\n| `MCP_TRIPLE_EXTRACTOR_ENABLED` | `false` | T50 knowledge-graph layer. Enable to fire an async LLM call on every memory write that extracts 3-7 (subj, rel, obj) triples powering `recall_multihop` |\n| `MCP_TRIPLE_EXTRACTOR_BASE_URL` | - | OpenAI-compatible `/chat/completions` endpoint (DeepSeek, Together, Groq, Qwen, …); falls back to `OPENAI_BASE_URL` when empty |\n| `MCP_TRIPLE_EXTRACTOR_API_KEY` | - | Bearer token for the extractor. Falls back to `OPENAI_API_KEY` **only** when `MCP_TRIPLE_EXTRACTOR_BASE_URL` is empty or equal to `OPENAI_BASE_URL`. Pointing the extractor at a third-party endpoint without giving it its own key disables extraction with an explicit message — the OpenAI key is never sent to an address it was not issued for |\n| `MCP_TRIPLE_EXTRACTOR_MODEL` | - | Model id passed to the extractor (e.g. `deepseek-chat`, `qwen2.5-72b-instruct`) |\n| `MCP_TRIPLE_EXTRACTOR_TIMEOUT` | `30s` | Per-request timeout for the extractor HTTP call |\n\n### Data paths\n\nThe server creates these directories under `MCP_DATA_PATH`:\n\n- `rag-index/` -- SQLite vector index for document search\n- `memory-store/` -- SQLite database for agent memories\n\nThe recommended solo-local preset stores them under `.agent-memory/`.\n\n### Indexing safety controls\n\nRAG indexing scans supported docs and engineering text files, but you can further reduce risk with explicit controls:\n\n- built-in excluded directories such as `.git`, `.agent-memory`, `node_modules`, `logs`, and `.terraform`\n- `MCP_INDEX_EXCLUDE_DIRS` for repo-relative path excludes such as `docs/private,runbooks/internal`\n- `MCP_INDEX_EXCLUDE_GLOBS` for glob-style excludes such as `docs/internal/*.md`\n- `MCP_REDACT_SECRETS=true` to redact common secret-like lines and private key blocks before indexing\n\nThis is especially important if you use hosted embedding providers or shared HTTP mode.\n\n### Automatic session tracking\n\nWhen the MCP server is running with the default session-tracking policy, it keeps a lightweight background session buffer.\n\nCurrent behavior:\n\n- successful MCP tool calls are grouped into an active session automatically\n- idle timeout or server shutdown triggers a background `close_session` run\n- clients can explicitly flush or checkpoint the active session with `notifications/session_event` and `event=task_done|final_summary|checkpoint|reset`\n- raw session summaries are persisted automatically\n- low-risk updates can auto-apply under the existing `safe_auto_apply` policy\n- risky or ambiguous changes are stored as review inbox items instead of silently rewriting maintained knowledge\n- periodic raw checkpoints provide crash-recovery breadcrumbs during long sessions\n\nTo inspect the inbox, use `project_bank_view view=review_queue` or `agent-memory-mcp project-bank -view review_queue`.\nTo close an item after manual review, use `resolve_review_item` or `agent-memory-mcp resolve-review-item `.\n\nExample notification payload:\n\n```json\n{\n \"jsonrpc\": \"2.0\",\n \"method\": \"notifications/session_event\",\n \"params\": {\n \"event\": \"task_done\",\n \"summary\": \"Incident stabilized, workaround verified, follow-up is to replace the temporary fix.\",\n \"context\": \"payments\",\n \"service\": \"api\",\n \"mode\": \"incident\",\n \"tags\": [\"done\", \"verification\"]\n }\n}\n```\n\nIf you want to tune or disable this behavior, use `MCP_SESSION_TRACKING_ENABLED`, `MCP_SESSION_IDLE_TIMEOUT`, `MCP_SESSION_CHECKPOINT_INTERVAL`, and `MCP_SESSION_MIN_EVENTS`.\n\n### Index integrity and recovery\n\nDocument indexing now treats chunk updates and tracking metadata as one logical state.\n\n- each run marks the index state as `dirty` before changing chunks\n- a successful final commit flips the state back to `ready` together with `indexed_files`, `embedding_model`, and `last_indexed`\n- if a run is interrupted or the final tracking-state commit fails, the next `index_documents` / `agent-memory-mcp index` run detects the dirty state and forces a rebuild\n\nThis makes incremental indexing more predictable after crashes, provider interruptions, or storage errors.\n\n### Source-aware ingestion\n\nThe indexer now classifies engineering sources and carries that metadata into retrieval.\n\nSupported source types:\n\n- `docs` for `README.md` and general Markdown docs\n- `adr` and `rfc` for architecture decision and RFC-style documents\n- `changelog` for `CHANGELOG.md` and release-note style docs\n- `runbook` and `postmortem` for operational knowledge\n- `ci_config` for GitHub Actions, GitLab CI, and Jenkins pipeline files\n- `helm`, `terraform`, and `k8s` for source-aware infra files\n\nUse `source_type` when you want to narrow retrieval to a specific class of knowledge:\n\n```bash\nagent-memory-mcp search -source-type runbook \"ingress rollback\"\nagent-memory-mcp search -source-type adr \"cache invalidation decision\"\n```\n\nThe MCP `semantic_search` tool also accepts `source_type` and `debug`.\n\n### Hybrid retrieval\n\nSearch now uses multiple ranking signals instead of cosine similarity alone.\n\nCurrent ranking signals:\n\n- semantic similarity from the active embedding model\n- keyword/BM25-like scoring across chunk title, path, and content\n- `source_type` filtering when you want a narrower retrieval set\n- recency boost for recently updated operational context\n- source-aware weighting so runbooks, changelogs, ADRs, and other source classes can rank higher for matching query intent\n\nThe retrieval pipeline now works in two stages:\n\n- semantic top-K candidate generation from the vector index\n- keyword top-K candidate generation from a precomputed in-memory keyword index\n\nOnly the merged candidate set is reranked. This keeps shared-service retrieval more predictable as the indexed corpus grows.\n\nThis means a strong keyword hit in a runbook or changelog can outrank a semantically similar but less task-relevant document.\n\n### Trust-aware retrieval\n\nRetrieval now carries explicit trust metadata for both stored memories and indexed docs.\n\nEach result can expose:\n\n- `source_type`\n- `confidence`\n- `last_verified_at`\n- `owner`\n- `freshness_score`\n\nWhat this means in practice:\n\n- accepted decisions and verified runbooks rank above draft or low-confidence notes when the textual match is similar\n- ADRs, runbooks, postmortems, and changelogs can carry different trust weights even before you add a full canonical layer\n- CLI `search` / `recall` and MCP `semantic_search` / `recall_memory` now show trust summaries in human-readable output\n\nEngineering workflow tools also stamp stored entries with `last_verified_at` so fresh operational knowledge is easier to trust and rank.\n\n### Explainable retrieval\n\nUse debug mode when you want retrieval to explain why a document was returned.\n\nCLI:\n\n```bash\nagent-memory-mcp search -source-type runbook -debug \"ingress rollback\"\n```\n\nMCP:\n\n- call `semantic_search` with `debug: true`\n- keep `debug` unset or `false` for the normal compact response\n\nDebug mode adds:\n\n- applied filters such as `source_type=runbook`\n- ranking signals used for the response\n- candidate counts: indexed, filtered out, discarded as noise, returned\n- per-result trust summary: `source`, `confidence`, `freshness`, `owner`, `verified`\n- per-result score breakdown: `semantic`, `keyword_raw`, `keyword_normalized`, `recency_boost`, `source_boost`, `confidence_boost`, `final_score`\n- per-result applied boosts, for example `keyword_match` or `source_type:runbook`\n\n### Retrieval console\n\nIf you want a faster inspection workflow than raw CLI or JSON-RPC calls, use the built-in console in HTTP mode:\n\n```text\n/console\n```\n\nWhat it is good for:\n\n- compare normal vs debug retrieval side by side\n- inspect document search, raw memory recall, and canonical knowledge recall in one place\n- see source type, trust layer, confidence, freshness, owner, and verification time\n- open raw JSON for the same structured response the UI is rendering\n\nThe console is intentionally lightweight and does not replace MCP tools or CLI workflows.\n\n### Engineering workflow tools\n\nThese MCP tools map domain-specific workflows onto the existing memory and retrieval backends.\n\nRecommended starting points:\n\n- `store_decision` for architectural or operational choices such as disabling HPA or pinning an ingress version\n- `store_incident` for short-lived operational facts you want to recall during active debugging\n- `store_runbook` for procedural steps, rollback instructions, and verification notes\n- `store_postmortem` for durable incident learnings and action items\n- `close_session` when you want an explicit end-of-session plan with rationale, traces, and review-safe actions\n- `accept_session_changes` when the close-session report is low risk and you want to persist the raw summary plus apply safe updates\n- `resolve_review_item` when the background inbox already contains a reviewed item and you want to clear it without deleting the audit trail\n- `search_runbooks` when you need a fix path and want both memory-stored runbooks and indexed runbook docs\n- `recall_similar_incidents` when you are triaging an outage or regression\n- `summarize_project_context` at session start to get a compact operational briefing\n- `project_bank_view` when you want maintained knowledge by view instead of raw recall results, including `review_queue` for pending background decisions\n\nThese workflow tools also add verification metadata so that retrieval can treat newly stored operational knowledge as fresher and more trustworthy than anonymous raw notes.\n\n### Memory consolidation\n\nThe memory layer now supports a manual consolidation workflow without deleting historical notes.\n\nUse these MCP tools when the same project knowledge starts to drift:\n\n- `merge_duplicates` to consolidate repeated notes into one primary memory and archive the rest as merged duplicates\n- `mark_outdated` to demote stale runbooks, superseded decisions, or obsolete incident notes without losing them\n- `promote_to_canonical` to mark the current best memory as canonical knowledge\n- `conflicts_report` to surface `duplicate_candidates`, `status_conflict`, and `multiple_canonical` groups\n\nCurrent behavior:\n\n- merged or archived memories stay accessible, but trust-aware recall pushes them down\n- canonical memories get a trust boost and higher minimum importance\n- outdated or superseded memories are automatically archived and downranked\n- conflict reporting is manual and safe: nothing is deleted unless you explicitly choose to delete it\n\n### Zero-ops task-memory consolidation\n\nEvery closed task leaves behind working memories (`Task started`, per-phase\nnotes, `Session close`, auto-extracted review items). Left alone they accumulate\nlinearly and keep surfacing in recall for tasks that are already done. The\nservice consolidates them automatically — no cron, no manual cleanup, no config:\n\n- A background loop (on by default, `MCP_ARCHIVE_SWEEP_INTERVAL`, default 1h)\n sweeps archived tasks: durable entries (procedural, or importance ≥ 0.70) are\n promoted, the rest are marked `outdated`. It runs a first pass shortly after\n startup, which also backfills any archive that accumulated before the loop\n existed.\n- **Zero configuration.** With `MCP_TASK_ARCHIVE_ROOTS` unset it watches the\n `/tasks/archive` convention; a missing directory is a silent no-op.\n- **Safe by construction.** Promotion goes through the provenance gate: a\n conversational-origin memory is routed to the review queue, never\n auto-canonicalized (see [Memory poisoning defense](https://github.com/ipiton/agent-memory-mcp/blob/main/docs/THREAT_MODEL.md)).\n- The `end_task` and `sweep_archive` tools default to the same consolidating\n behavior, so an explicit `/end-task` consolidates immediately.\n\nPolicy details (state derivation, promotion threshold, idempotency,\nsymlink/t","changelogMarkdown","videoKey","requiredSecretsJson","publishedAt","priceCents","trialDays",0,"iconType","image","upstream",{"_96":97,"_98":99,"_100":101,"_102":103,"_104":66,"_105":106},"requiredSecrets",[],"tags",[],"assets",[],"stats",{"_94":81,"_95":81},"ratingAvg","reviewCount","topics",[],"license","MIT","language","Go","registryName","io.github.ipiton/agent-memory-mcp","homepage","packages",[],"ENV",{"_109":110,"_111":112,"_113":114},"ENVIRONMENT","production","TURNSTILE_SITE_KEY","0x4AAAAAAB8-rEI2gNDf_QhU","SENTRY_DSN","https://45fd1229f78089d5c3ee78be128030e1@o4510583261757440.ingest.de.sentry.io/4510584253448272"]