接入你的智能体
从发布者处安装。不是 PlugMCP 端点。
远程 URL 还是本机命令？ 两种安装方式的区别
来自发布者
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.
MCP server that gives AI agents persistent memory with semantic search
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 pathEvery 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)
The server creates these directories under MCP_DATA_PATH:
rag-index/ -- SQLite vector index for document searchmemory-store/ -- SQLite database for agent memoriesThe recommended solo-local preset stores them under .agent-memory/.
RAG indexing scans supported docs and engineering text files, but you can further reduce risk with explicit controls:
.git, .agent-memory, node_modules, logs, and .terraformMCP_INDEX_EXCLUDE_DIRS for repo-relative path excludes such as docs/private,runbooks/internalMCP_INDEX_EXCLUDE_GLOBS for glob-style excludes such as docs/internal/*.mdMCP_REDACT_SECRETS=true to redact common secret-like lines and private key blocks before indexingThis is especially important if you use hosted embedding providers or shared HTTP mode.
When the MCP server is running with the default session-tracking policy, it keeps a lightweight background session buffer.
Current behavior:
close_session runnotifications/session_event and event=task_done|final_summary|checkpoint|resetsafe_auto_apply policyTo inspect the inbox, use project_bank_view view=review_queue or agent-memory-mcp project-bank -view review_queue.
To close an item after manual review, use resolve_review_item or agent-memory-mcp resolve-review-item <id>.
Example notification payload:
{
"jsonrpc": "2.0",
"method": "notifications/session_event",
"params": {
"event": "task_done",
"summary": "Incident stabilized, workaround verified, follow-up is to replace the temporary fix.",
"context": "payments",
"service": "api",
"mode": "incident",
"tags": ["done", "verification"]
}
}
If 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.
Document indexing now treats chunk updates and tracking metadata as one logical state.
dirty before changing chunksready together with indexed_files, embedding_model, and last_indexedindex_documents / agent-memory-mcp index run detects the dirty state and forces a rebuildThis makes incremental indexing more predictable after crashes, provider interruptions, or storage errors.
The indexer now classifies engineering sources and carries that metadata into retrieval.
Supported source types:
docs for README.md and general Markdown docsadr and rfc for architecture decision and RFC-style documentschangelog for CHANGELOG.md and release-note style docsrunbook and postmortem for operational knowledgeci_config for GitHub Actions, GitLab CI, and Jenkins pipeline fileshelm, terraform, and k8s for source-aware infra filesUse source_type when you want to narrow retrieval to a specific class of knowledge:
agent-memory-mcp search -source-type runbook "ingress rollback"
agent-memory-mcp search -source-type adr "cache invalidation decision"
The MCP semantic_search tool also accepts source_type and debug.
Search now uses multiple ranking signals instead of cosine similarity alone.
Current ranking signals:
source_type filtering when you want a narrower retrieval setThe retrieval pipeline now works in two stages:
Only the merged candidate set is reranked. This keeps shared-service retrieval more predictable as the indexed corpus grows.
This means a strong keyword hit in a runbook or changelog can outrank a semantically similar but less task-relevant document.
Retrieval now carries explicit trust metadata for both stored memories and indexed docs.
Each result can expose:
source_typeconfidencelast_verified_atownerfreshness_scoreWhat this means in practice:
search / recall and MCP semantic_search / recall_memory now show trust summaries in human-readable outputEngineering workflow tools also stamp stored entries with last_verified_at so fresh operational knowledge is easier to trust and rank.
Use debug mode when you want retrieval to explain why a document was returned.
CLI:
agent-memory-mcp search -source-type runbook -debug "ingress rollback"
MCP:
semantic_search with debug: truedebug unset or false for the normal compact responseDebug mode adds:
source_type=runbooksource, confidence, freshness, owner, verifiedsemantic, keyword_raw, keyword_normalized, recency_boost, source_boost, confidence_boost, final_scorekeyword_match or source_type:runbookIf you want a faster inspection workflow than raw CLI or JSON-RPC calls, use the built-in console in HTTP mode:
/console
What it is good for:
The console is intentionally lightweight and does not replace MCP tools or CLI workflows.
These MCP tools map domain-specific workflows onto the existing memory and retrieval backends.
Recommended starting points:
store_decision for architectural or operational choices such as disabling HPA or pinning an ingress versionstore_incident for short-lived operational facts you want to recall during active debuggingstore_runbook for procedural steps, rollback instructions, and verification notesstore_postmortem for durable incident learnings and action itemsclose_session when you want an explicit end-of-session plan with rationale, traces, and review-safe actionsaccept_session_changes when the close-session report is low risk and you want to persist the raw summary plus apply safe updatesresolve_review_item when the background inbox already contains a reviewed item and you want to clear it without deleting the audit trailsearch_runbooks when you need a fix path and want both memory-stored runbooks and indexed runbook docsrecall_similar_incidents when you are triaging an outage or regressionsummarize_project_context at session start to get a compact operational briefingproject_bank_view when you want maintained knowledge by view instead of raw recall results, including review_queue for pending background decisionsThese workflow tools also add verification metadata so that retrieval can treat newly stored operational knowledge as fresher and more trustworthy than anonymous raw notes.
The memory layer now supports a manual consolidation workflow without deleting historical notes.
Use these MCP tools when the same project knowledge starts to drift:
merge_duplicates to consolidate repeated notes into one primary memory and archive the rest as merged duplicatesmark_outdated to demote stale runbooks, superseded decisions, or obsolete incident notes without losing thempromote_to_canonical to mark the current best memory as canonical knowledgeconflicts_report to surface duplicate_candidates, status_conflict, and multiple_canonical groupsCurrent behavior:
Every closed task leaves behind working memories (Task started, per-phase
notes, Session close, auto-extracted review items). Left alone they accumulate
linearly and keep surfacing in recall for tasks that are already done. The
service consolidates them automatically — no cron, no manual cleanup, no config:
MCP_ARCHIVE_SWEEP_INTERVAL, default 1h)
sweeps archived tasks: durable entries (procedural, or importance ≥ 0.70) are
promoted, the rest are marked outdated. It runs a first pass shortly after
startup, which also backfills any archive that accumulated before the loop
existed.MCP_TASK_ARCHIVE_ROOTS unset it watches the
<MCP_ROOT>/tasks/archive convention; a missing directory is a silent no-op.end_task and sweep_archive tools default to the same consolidating
behavior, so an explicit /end-task consolidates immediately.Policy details (state derivation, promotion threshold, idempotency,
symlink/traversal guards): docs/concepts/lifecycle.md.
Turn the loop off with MCP_ARCHIVE_SWEEP_ENABLED=false.
The project now exposes two distinct layers:
raw memory: captured notes, incidents, decisions, and procedural memories as they were storedcanonical knowledge: confirmed entries projected from memories promoted with promote_to_canonicalWhat this changes:
list_canonical_knowledge gives you the current confirmed knowledge set without raw noiserecall_canonical_knowledge searches only canonical entriessummarize_project_context surfaces canonical knowledge before raw memory sections when canonical entries existlayer=raw, layer=canonical, or layer=documentMigration story:
promote_to_canonicaldecision or service:api are still recognized by the canonical layerThe stewardship layer provides automated and manual knowledge maintenance.
steward_run executes a full maintenance cycle in one call:
dry_run=false, applies safe actions and sends the rest to the stewardship inboxdrift_scan compares memory entries against live repo files:
source_changed when a referenced file was modified after the memory was last verifiedsource_missing when a referenced file path no longer existsstale_unverified when entries exceed the stale thresholdverification_candidates ranks memories that need verification:
verification_failed or needs_update status: high urgencysteward_inbox is the single place for all review-required actions. Resolve items with steward_inbox_resolve using actions like merge, mark_outdated, promote, verify, suppress, or defer.
Stewardship is auto-enabled in HTTP mode when memory is available. Configure thresholds and mode via MCP_STEWARD_* environment variables. See steward_policy for runtime configuration.
For a detailed guide, see Stewardship Guide.
Memories can carry temporal metadata that tracks when knowledge was valid and how it evolved:
valid_from / valid_until — the time window during which this knowledge was truesuperseded_by / replaces — bidirectional links forming supersession chainsobserved_at — when knowledge was first observed (may differ from created_at)recall_as_of retrieves knowledge that was valid at a specific timestamp. This is useful for questions like "what was our database strategy in January?" or "what changed between these two dates?"
knowledge_timeline shows the chronological evolution of entries matching a query, ordered by valid_from.
When mark_outdated is called with a superseding entry, the system automatically sets valid_until on the old entry and valid_from + replaces on the new entry, building a navigable chain.
Core deployment guidance:
MCP_HTTP_MODE=stdio, prefer MCP_EMBEDDING_MODE=local-only if you need no-send semanticsMCP_HTTP_HOST=0.0.0.0, set MCP_HTTP_AUTH_TOKEN, keep TLS at the reverse proxy, and scope MCP_ALLOW_DIRS narrowlyMCP_INDEX_EXCLUDE_DIRS / MCP_INDEX_EXCLUDE_GLOBS.agent-memory/ or use agent-memory-mcp export for memory-only backupsReference docs:
┌──────────────────────────────────────────────────┐
│ MCP Protocol Layer │
│ (stdio or HTTP/JSON-RPC) │
├────────────┬──────────┬───────────┬───────────────┤
│Memory Tools│RAG Tools │File Tools │Steward Tools │
├────────────┼──────────┼───────────┼───────────────┤
│MemoryStore │RAGEngine │ PathGuard │ Steward │
│ (SQLite) │ │ │ Service │
│ │┌────────┐│ │ Scheduler │
│ Embedder◄──┤│DocSvc ││ │ Inbox │
│ ││VecSvc ││ │ Drift/Verify │
│ │└────────┘│ │ Policy │
│ │ (SQLite) │ │ (SQLite) │
└────────────┴──────────┴───────────┴───────────────┘
The server supports three embedding providers in auto mode:
jina-embeddings-v3, native 1024 dimensions, multilingualtext-embedding-3-small or any OpenAI-compatible API. Native dimension is 1536; the server requests dimensions=1024 via the OpenAI MRL parameter to match the rest of the stackbge-m3, native 1024 dimensions, runs locally for freeAll three are normalized to the same vector dimension (MCP_EMBEDDING_DIMENSION, default 1024), but they are not interchangeable: each model has its own embedding space. Matching dimensions do not make cosine similarity safe across different models — that is why the server tags every memory with its embedding_model and refuses to mix them at recall time.
What auto mode means in practice:
embedding_model they were created withembedding_model does not match the current query model and falls back to text matching for those recordsThis avoids the dangerous case where provider fallback returns confident but incorrect semantic matches.
If you change provider or model intentionally, treat it as a migration:
# rebuild document index for the new embedding model
agent-memory-mcp index
# re-embed stored memories for the new embedding model
agent-memory-mcp reembed
# inspect how many memories still belong to older models
agent-memory-mcp stats -json
You can increase the dimension via MCP_EMBEDDING_DIMENSION for higher accuracy (for example 3072 with text-embedding-3-large), but any dimension or model change requires re-indexing and re-embedding.
If you set MCP_EMBEDDING_MODE=local-only, hosted providers are skipped entirely and only Ollama is used for embeddings.
auto mode without silent corruption of semantic recallagent-memory-mcp statsbrew install ipiton/tap/agent-memory-mcp
brew services start agent-memory-mcp
See Installation Options for details and config location.
./scripts/install-macos.sh
This builds the binary, creates a .env file, and installs a launchd service that auto-starts on login.
Manual control:
# Status
launchctl list | grep com.agent-memory-mcp
# Start
launchctl load ~/Library/LaunchAgents/com.agent-memory-mcp.plist
# Stop
launchctl unload ~/Library/LaunchAgents/com.agent-memory-mcp.plist
The server tries Jina → OpenAI → Ollama in auto mode and stops at the first available one. If none is reachable, embeddings (and therefore semantic recall) are disabled.
JINA_API_KEY, OPENAI_API_KEY, or run Ollama with bge-m3 pulled (ollama pull bge-m3)MCP_EMBEDDING_MODE=local-only only Ollama is consulted; verify OLLAMA_BASE_URL (default http://localhost:11434) respondsCLI agent-memory-mcp store … without an embedder still saves the memory but skips the vector — the record will only be retrievable via text/keyword search until you run agent-memory-mcp reembed.
The RAG index and stored memories are tagged with the embedding model that produced them. If you switch provider or model, retrieval refuses to mix vector spaces:
agent-memory-mcp index # rebuild RAG index for the new model
agent-memory-mcp reembed # re-embed stored memories
agent-memory-mcp stats -json # check how many memories still belong to older models
18080 takenAnother agent-memory-mcp (or unrelated service) holds the port:
lsof -nP -iTCP:18080 -sTCP:LISTEN
brew services list | grep agent-memory-mcp
If two instances were started, stop one (brew services stop agent-memory-mcp or kill <pid>) or change MCP_HTTP_PORT.
brew services start agent-memory-mcp does not start the daemonMost common causes:
brew uninstall --cask agent-memory-mcp && brew install ipiton/tap/agent-memory-mcpcat $(brew --prefix)/etc/agent-memory-mcp/config.envtail -f $(brew --prefix)/var/log/agent-memory-mcp/mcp-diagnostics.logAfter agent-memory-mcp setup, restart Claude Code (hooks load at process start). Verify the merge:
agent-memory-mcp setup --dry-run # show what would be written
jq '.hooks' ~/.claude/settings.json # inspect actual config
If you upgraded via brew upgrade, re-run agent-memory-mcp setup --force so the hook command points to the new binary path. See docs/HOOKS.md.
In HTTP mode the server refuses non-loopback binds without MCP_HTTP_AUTH_TOKEN. Either:
MCP_HTTP_AUTH_TOKEN=$(openssl rand -hex 32)) — recommendedMCP_HTTP_INSECURE_ALLOW_UNAUTHENTICATED=trueagent-memory-mcp project-bank canonical_overview and … review_queue to spot raw session summaries that should be promoted or marked outdatedMCP_STEWARD_MODE=scheduled triggers periodic dedup/stale scansMCP_CHECKPOINT_DEDUP_THRESHOLD, MCP_CHECKPOINT_DEDUP_WINDOW)agent-memory-mcp export > backup.json (see docs/BACKUP_RESTORE.md)recall_multihop returns emptyThe multi-hop graph walks the (subj, rel, obj) triple corpus. It's empty until you either:
MCP_TRIPLE_EXTRACTOR_ENABLED=true and write new memories (extraction is async on every store)agent-memory-mcp index-triples (idempotent, supports --resume)Both paths require MCP_TRIPLE_EXTRACTOR_* (see Key variables) — extraction calls an OpenAI-compatible /chat/completions endpoint.
Changes are picked up within ~30s. Force an immediate reload:
kill -HUP $(pgrep agent-memory-mcp)
Note: HTTP host/port require a full restart (brew services restart agent-memory-mcp). Only RAG-related settings hot-reload.
# Build
make build
# Run
make run
# Test
make test
# Full quality gate (lint + tests + smoke)
make quality-gates
For repo layout, code style, and PR conventions see docs/CONTRIBUTING.md.
MIT
MCP server that gives AI agents persistent memory with semantic search
工具
暂无工具列表。远程服务器在首次健康检查后会获得工具列表。
常见问题
在本页复制适用于 Cursor、Claude Desktop、Claude Code 或 VS Code 的 stdio 配置。它使用发布者的安装方式，而不是 PlugMCP 代理。
此记录未列出必需的环境变量。
Agent Memory 通过 stdio 在本地运行。
上次检查时间：2026-10-28。 MCP server that gives AI agents persistent memory with semantic search
