Sync and search memories with an Obsidian vault, including importing/exporting markdown files with frontmatter and wikilinks, and bidirectional vault-memory operations for knowledge management.
A memory server for Claude Code and any other MCP client. It gives your AI assistant a permanent, searchable memory that lives in one SQLite file on your machine. Store a decision today, ask about it next month, and the answer comes back. Everything runs locally: the embedding model, the search index, the knowledge graph. No cloud account, no API key, no per-token cost.
License: source-available and free for noncommercial use (PolyForm Noncommercial 1.0.0): personal projects, hobby, study, research, charity, education, and government. Commercial use requires a paid license (COMMERCIAL.md).
Who it's for: developers who want Claude (or Cursor, Codex, any MCP client) to remember decisions across sessions. Solo builders and hobbyists use it free. Teams share a knowledge base over git. And anyone who wants to replace a cloud memory service (mem0, Zep, Letta, Supermemory) with something that runs entirely on their own machine.
Run npx mcp-memory-graph serve and you get a local web dashboard for browsing and searching your memory outside Claude.
Search works by meaning, not keywords. The query below ("how do we handle payments") finds the Stripe, GDPR, and Postgres notes even though none of them contains that phrase — each result carries a confidence score and a match-type badge:
Browse and sort the whole store in one table — scope, type, tags, quality score, and how often each memory has been read:
Related MCP server: CozoDB Memory MCP Server
mem0, Zep, Letta, and Supermemory are the usual names for AI memory, and several of them have open-source cores. This one is built around a different default: nothing leaves your machine and there's no infrastructure to run.
MCP Memory Graph | Typical hosted memory service | |
Where it runs | One SQLite file on your machine | A managed cloud service (some also self-host) |
Embeddings | Local model in Node (MiniLM), no API key | Usually a cloud embedding API |
Cost per token | $0 — nothing is metered | Usage-based, or a server you operate |
Extra infrastructure | None | Often Postgres/pgvector, Redis, or a Python service |
Claude Code integration | First-class: hooks auto-capture and recall | Manual wiring |
Benchmarks | Committed corpus + runner, reproducible locally | Mostly self-reported |
The trade-off is honest: a single-process SQLite server tops out in the low hundreds of thousands of vectors (see Limitations), and a hosted service will scale past that without you thinking about it. If you're a solo developer or a small team who wants memory that's private, free, and zero-ops, that ceiling is rarely the thing you hit first.
AI assistants forget everything between sessions. Your decisions, your patterns, the bug you fixed last Tuesday: all gone when the conversation ends. This server fixes that.
Knowledge stored today is searchable tomorrow, next week, next year.
Search works by meaning, not just keywords. "contract notice period" finds "90-day renewal clause".
It improves itself. It tracks what gets used, scores quality, extracts learnings from your sessions, and cleans itself up on a schedule.
It stays private. Local embeddings, no cloud APIs, no telemetry. The one exception is the optional Stop hook, which sends your session transcript to your own locally installed Claude Code (claude -p) for learning extraction. You can turn that off with review_on_stop: false.
It works for any kind of knowledge. Engineers store architecture decisions, lawyers store contract patterns, accountants store audit procedures.
You need Node.js 20 or newer and Claude Code installed.
1. Get the server. From npm (easiest):
npm install -g mcp-memory-graphOr from source:
git clone https://github.com/YonasValentin/mcp-memory-graph.git
cd mcp-memory-graph
npm install
npm run build2. Register the server with Claude Code (optional — init in step 3 does this for you at user scope):
# npm install:
claude mcp add memory-server -- npx -y mcp-memory-graph
# from source:
claude mcp add memory-server node /path/to/mcp-memory-graph/dist/index.js3. Install the hooks (recommended):
npx mcp-memory-graph initThis is the one command that wires everything up: it registers the MCP server (user scope), installs the auto-capture/recall hooks and the usage skill, writes config, and schedules a nightly cleanup. Answer the prompts, or pass --yes to accept the defaults. (Skip the auto-registration with --no-register if you manage claude mcp yourself.)
4. Try it. Open a Claude Code session and say:
Remember this: we use Postgres for the main app database. Decided 2026-06-01,
because we need JSONB and full-text search in one place.Then, in a later session:
What database did we decide to use, and why?Claude searches its memory and answers with the stored decision. That's the whole loop.
5. Verify the install. Ask Claude:
What memory tools do you have available?It should list all 51 tools (45 memory_*, 3 vault_*, 3 core_memory_*).
The first time a memory tool runs, the embedding model (about 30 MB) downloads from HuggingFace and is cached at ~/.cache/huggingface/. Every start after that is instant.
To undo everything: npx mcp-memory-graph uninstall.
npm install -g mcp-memory-graph@latest # or just let `npx -y mcp-memory-graph` pull it
npx mcp-memory-graph init # re-run to refresh on-disk hooks + the nightly scheduleUpgrading the package updates the code that runs each session (hooks, tools, the server), so server-side fixes apply the next time a tool runs — nothing else needed for those.
But files that init wrote earlier are not rewritten by a package upgrade: the Claude Code hook registrations in settings.json and the macOS launchd plist at ~/Library/LaunchAgents/com.mcp-memory.consolidate.plist. If you installed before 2.6.3, that plist used a bare node that launchd (whose minimal PATH excludes nvm) could not run — so the nightly consolidation silently never fired. Re-run npx mcp-memory-graph init once after upgrading to regenerate it with an absolute node path and an output log. Verify it then runs:
launchctl start com.mcp-memory.consolidate
cat ~/.mcp-memory/consolidation.log # should show a "Consolidation complete" reportTo clear conflict noise that accumulated while the job wasn't running: npx mcp-memory-graph consolidate.
When you store a memory, the server turns the text into a vector (a list of 384 numbers that captures its meaning) using a small model that runs inside Node.js. It also indexes the text for keyword search. Both live in one SQLite file, by default at ~/.mcp-memory/memory.db.
When you search, the server runs both kinds of search at once, merges the rankings, and returns the best matches with a confidence label. A second model can then re-sort the top results for better precision (this is the reranker, on by default for MCP clients, and it costs about 200 ms).
On top of that sits a knowledge graph: memories link to entities and to each other, so the server can answer questions that need more than one hop, like "what does the payment service depend on?". A nightly "dream cycle" deduplicates, re-scores, prunes, and reports gaps.
Every number below was produced locally: real embedding model, real production handlers, no network. You can rerun all of them on your own machine.
A quick primer if benchmarks are new to you. A gold set is a list of questions where the right answer is known in advance. Precision@1 asks: was the top result the right one? Recall@5 asks: was the right answer anywhere in the top 5? MRR (mean reciprocal rank) rewards putting the right answer near the top. The reranker is a second model that re-sorts the top 50 results; it is slower but noticeably more accurate.
precision@1 | precision@3 | MRR | search p95 | |
Hybrid (RRF) | 0.563 | 0.750 | 0.704 | ~4 ms |
+ cross-encoder rerank (MCP default) | 0.813 | 0.875 | 0.867 | ~230 ms |
Reproduce with npm run bench. Full methodology, the gold set itself, and every miss are printed and documented in docs/BENCHMARKS.md.
With the real embedder and a file-backed SQLite database, retrieval p95 is 9.1 ms at 10,000 vectors and 30 ms at 50,000. The rerank pass adds a roughly constant 200 ms on top. Most memory products publish self-reported, cloud-hosted numbers; these are measured locally and reproducible from a committed corpus and runner.
Four public memory benchmarks, run untuned (stock MiniLM embedder, production handlers, zero benchmark-specific tweaks), matching or beating MemPalace on all four:
Benchmark | Our result | Comparison |
R@5 = 97.8% | vs 96.6% published | |
R@10 = 93.5% | vs 92.9% | |
session R@10 = 82.2%, R@50 = 100% | vs 60.3% baseline | |
hit@5 = 78.7% | vs their 80.3% tuned |
Run them yourself: npm run bench:longmemeval, bench:locomo, bench:convomem, bench:membench. The honest notes (where the reranker helps and where it hurts, the dedup floor on MemBench, gold-set size caveats) are in docs/BENCHMARKS.md.
51 MCP tools: CRUD and retrieval, a confidence-tagged knowledge graph, a self-correcting write gate, signed provenance and verification, an event bus with SSRF-guarded webhooks, change propagation and advisor surfaces, resumable session state, expertise profiles, memory tiers, Obsidian vault round-tripping, and GDPR-grade forget and history. Full list below.
Hybrid search: vector similarity (meaning) plus keyword matching (exact terms), merged with Reciprocal Rank Fusion. rerank: true adds the cross-encoder pass. use_graph: true blends in HippoRAG Personalized PageRank multi-hop scores. as_of: <timestamp> searches the graph as it stood at a past moment.
Local embeddings: Transformers.js running all-MiniLM-L6-v2 (384 dimensions) inside Node.js. No Python, no cloud API, no GPU.
SQLite storage: one file, using better-sqlite3 with two extensions: sqlite-vec for vector nearest-neighbor search, FTS5 for keyword search with BM25 ranking.
Structure-aware chunking: text splits on paragraphs, markdown on headings (heading context preserved in each chunk), code on function and class boundaries, legal on sentences.
Scopes: organize memories into global, project, user, team, department.
Version history: every update saves the previous version. Full audit trail of who changed what, when.
Temporal decay: optional time-based scoring that favors recent memories (exponential or linear).
Confidence scoring: every result carries a 0 to 1 confidence and a plain label (high, medium, low).
Expiration: time-sensitive memories can carry an expiry date and drop out of search automatically.
Access tracking: every search, get, and related-memory call records which memories were touched.
Quality scoring: automatic importance_score and confidence_score on every memory, from access frequency, recency, and content signals.
Learning extraction: at session end, a headless claude -p reviews the transcript and stores zero to five curated learnings. (This replaces the older type: "agent" Stop hook, which is silently broken on macOS; see anthropics/claude-code#39184.)
Dream cycle: scheduled or on-demand deduplication, re-scoring, pruning, expiry enforcement, and knowledge-gap detection.
Gap detection: searches that return nothing are logged, so you can see what knowledge is missing.
Five opt-in hooks, installed by init:
Hook | When it fires | What it does |
SessionStart | session begins | Status check (memory count, expired, stale docs) and surfaces the top memories for the project |
UserPromptSubmit | each prompt that carries a task signal (a ticket/PR id or ≥2 keywords) | Keyword-searches the store and surfaces matching memories so you recall prior work before re-deriving it; stays silent on trivial prompts |
PostToolUse | after a memory search | Tracks hits and misses to |
PreCompact | before context compression | Optional learning extraction (off by default) |
Stop | session ends | Spawns headless |
The Stop hook detaches in about 30 ms and reviews in the background for 10 to 60 seconds. It needs the claude CLI on $PATH (or $CLAUDE_BIN), authenticated. Turn it off with review_on_stop: false in ~/.mcp-memory/config.json.
Field | Purpose | Examples |
| Isolation level | global, project, user, team, department |
| Sub-scope grouping | "my-project", "legal-team", "q4-audit" |
| Organizational unit | legal, engineering, hr, sales, finance |
| Content classification | contract, policy, code, incident, decision, report |
| Data sensitivity | public, internal, confidential, restricted |
| Flexible categorization | ["renewal", "notice-period", "compliance"] |
| Content language (ISO 639-1) | "en", "da", "de" |
| Origin | file path, URL, system name |
| Creator | person or system name |
| Domain-specific JSON |
|
| Auto-expiration date | ISO 8601 timestamp |
scope and namespace group content within one database. A shared-database MCP_API_NAMESPACE pin gives supported per-namespace multi-tenant isolation (schema v14); a separate database file per tenant is the strongest boundary. See docs/MULTI-TENANCY.md.
Bi-temporal validity: every memory carries valid-time (valid_from, valid_to) alongside transaction-time. Updates invalidate rather than delete: the prior fact gets a valid_to stamp instead of being overwritten, so history is never lost. Reads default to currently valid rows but accept as_of: <timestamp> for point-in-time recall. memory_history returns one memory's full timeline.
Confidence-tagged links: memories connect via wikilink, co-occurrence, and similarity edges, each with a confidence weight. memory_graph traverses entities and relationships up to 3 hops. memory_extract_entities stores LLM-extracted entities and relationships.
HippoRAG multi-hop: use_graph: true on search runs Personalized PageRank over the entity and link graph for associative retrieval.
Token-budgeted answers: memory_query answers a question with a tight subgraph. It seeds from hybrid search, walks the graph up to max_hops while avoiding hubs, and returns a token-budgeted context string instead of flooding the window.
Communities: memory_communities finds densely connected entity clusters, for "what are the main themes in here?" questions.
Write gate: stores route through an ADD, UPDATE, DELETE, or NOOP decision (on_conflict), so new facts reconcile with existing ones instead of piling up duplicates.
Contradiction detection: a cross-encoder NLI model flags when an incoming memory contradicts something already stored.
Forgetting curve: memories carry a stability signal, so rarely reinforced knowledge slowly sinks in ranking, the way human memory fades.
Core memory block: a small, bounded, always-in-context note per (scope, namespace) that the agent maintains itself (core_memory_get, core_memory_append, core_memory_replace). Appends that would overflow are refused, which forces deliberate compaction.
Tiers: memory_tiers reports a MemGPT-style hot / recall / archival distribution and lists the hot working set.
Reflection: memory_reflect gathers the most reflection-worthy memories and, in store mode, persists synthesized insights linked back to their sources.
Bidirectional sync: vault_sync reads a vault in. memory_export_vault writes memories out as .md files with YAML frontmatter that round-trips losslessly for every authored field (id, scope, namespace, tags, access_level, importance, timestamps). Two derived scores are not in the frontmatter and reset on re-import: confidence_score (to 0.6) and stability (to 1.0). Use memory_export (JSON) for a byte-perfect backup. One metadata key is reserved: metadata._vault holds internal sync bookkeeping and never appears in tool output or exported files.
JSON Canvas: memory_canvas exports the graph as a JSON Canvas 1.0 .canvas file that opens as a spatial board in Obsidian.
Read-only wiki: serve exposes /publish/:namespace (index, page, search, graph) as a read-only wiki. It is deliberately not behind bearer auth, but is hard-scoped to published access levels (MCP_PUBLISH_ACCESS_LEVELS, default public).
Session notes and templates: memory_session_note appends to one "daily note" per session. memory_template returns structured note scaffolds per document type.
memory init wizard: interactive setup (or --yes for defaults) that writes ~/.mcp-memory/config.json (or project-scoped config) plus the Claude Code wiring.
Committable graph artifact: memory export-graph writes a deterministic memory-graph.json you can commit and share. memory git-setup installs a .gitattributes entry and the memory-union merge driver so parallel commits merge instead of conflict.
Attribution: set MCP_AGENT_ID (or pass agent_id per store) and memory_attribution reports how many valid memories each agent wrote.
Questions to ask: memory_questions surfaces what the graph is well placed to find: ambiguous links to confirm, frequently mentioned but under-documented entities, orphaned and stale memories.
GDPR-grade forget: memory_forget soft-deletes by default (a tombstone via valid_to, recoverable, still visible via as_of). With hard: true it returns a portability export first, then permanently erases. memory_delete is unchanged.
Output sanitization: every tool result passes through one chokepoint that strips ANSI and VT escapes, control characters, and zero-width or BiDi Trojan-Source spoofing before it leaves the server. Stored content stays raw at rest.
Hot reload: config changes apply without a restart.
The server ships a browser dashboard for viewing and managing memories outside Claude. It runs on the same Express server as the MCP HTTP transport, so there is no separate process.
Six pages:
Dashboard: memory counts, content size, breakdowns by scope, department, and type, plus the 10 most recently updated memories.
Search: hybrid search with confidence and match-type badges, and instant fuzzy suggestions as you type.
Browse: sortable, paginated table of all memories with scope filtering and quality indicators.
Memory detail: full content, metadata, version history, related memories, inline edit and delete.
Knowledge graph: D3 force-directed view. Nodes sized by importance, colored by scope. Zoom, pan, drag, double-click to navigate.
Tools: a console for the full tool surface. It lists every tool the server advertises, renders a form from each schema, and runs it over the authenticated MCP endpoint. Destructive tools ask for confirmation first.
Tech: React 19, Vite, Tailwind CSS v4, shadcn/ui, Fuse.js, D3, Recharts.
Run it:
# Development (hot reload)
npm run build && npm run serve # Terminal 1: server on :3100
npm run dev:web # Terminal 2: Vite on :5173 (proxies /api to :3100)
# Production (single process)
npm run build:all # Builds server + frontend
npm run serve # http://localhost:3100 serves both API and UIDocker: the image includes the built frontend. After docker compose up, the dashboard is at http://<host>:3200 alongside the MCP endpoint. Team members can browse the shared store from any browser, no Claude Code required.
The REST surface is for reading and managing. Creating memories goes through MCP (memory_store over POST /mcp); there is deliberately no POST /api/memories.
Method | Path | Description |
|
| Memory counts and breakdowns |
|
| Hybrid search with filters |
|
| List with pagination and sorting |
|
| Single memory with metadata |
|
| Version history |
|
| Semantically related memories |
|
| Update content or metadata |
|
| Delete a memory |
|
| Nodes and edges for graph visualization |
|
| Integrity manifest (merkle root plus per-memory hashes) |
|
| Trends and themes summary |
|
| Knowledge-gap report (recurring zero-result searches) |
|
| List webhook targets (gated by |
|
| Register an SSRF-validated outbound target |
|
| Remove a webhook target |
|
| Drain the durable, HMAC-signed delivery queue |
The first nine are what the dashboard uses. All REST endpoints call the same handlers as the MCP tools; no business logic is duplicated.
The server tracks how knowledge is used, scores quality, learns from sessions, and consolidates itself over time.
┌──────────────────────────────────────────────────────────┐
│ SESSION │
│ Claude searches → access_count++ on matched memories │
│ Claude stores → new memory with initial scores │
│ Zero results → knowledge gap recorded │
└─────────────┬────────────────────────────────────────────┘
│
▼
┌──────────────────────────────────────────────────────────┐
│ SESSION END (Stop command hook) │
│ Hook spawns detached `claude -p` headless review │
│ --allowedTools restricts to memory_store only │
│ Claude judges → 0-5 curated entries via memory_store │
│ Deduplicates against existing memories │
└─────────────┬────────────────────────────────────────────┘
│
▼
┌──────────────────────────────────────────────────────────┐
│ DREAM CYCLE (nightly or manual) │
│ 1. Score : Recalculate importance from access data │
│ 2. Expire : Enforce expiration dates │
│ 3. Prune : Remove low-quality, never-accessed items │
│ 4. Dedup : Merge near-duplicate memories │
│ 5. Gaps : Surface zero-result search patterns │
└──────────────────────────────────────────────────────────┘Every memory gets an importance_score between 0 and 1:
importance = 0.3 * current_score + 0.4 * normalized_access_frequency + 0.3 * recency_factorRecency factor:
Age | Factor |
< 7 days | 1.0 |
< 30 days | 0.7 |
< 90 days | 0.4 |
> 90 days | 0.1 |
Memories that are never accessed gradually lose importance. Auto-extracted memories start lower and get pruned if they never prove useful.
Note on access reinforcement. The formula above is the periodic recompute run by the consolidate Score stage. Each read (
memory_get,memory_search,memory_related) also applies a small immediate boost (importance_score += 0.03, capped at 1.0), and search uses importance as a mild rank multiplier (1 + importance * 0.5). A memory read 20 or more times approaches the ceiling from reads alone, and consolidate re-baselines it on the next run. This popularity weighting is intentional. If you want a fixed value that reads don't drift, set an explicitimportance_scoreonmemory_storeormemory_update.
When a search returns nothing, the query is logged. The dream cycle's gap stage surfaces these, so you can see what's missing from the store.
Node.js 20+, for any client.
An MCP client. Claude Code is the first-class experience; the automatic capture and recall hooks are Claude-Code-only. Other MCP clients (Codex, Cursor, and the rest) get all 51 tools but drive them manually. See "Other MCP clients" below.
For the Stop hook only: the claude binary on $PATH (or $CLAUDE_BIN), authenticated without prompting. Optional; disable with review_on_stop: false.
init doesnpx mcp-memory-graph init # user scope: hooks apply to all projects
npx mcp-memory-graph init --scope project # this project onlyUser scope writes hooks to ~/.claude/settings.json, so they fire in every Claude Code session. Project scope writes hooks to .claude/settings.json in the current directory and creates .mcp.json for automatic server discovery; collaborators who clone the project get the memory server registered automatically.
Init does seven things:
Verifies the hook scripts exist in dist/hooks/.
Registers the five hooks in settings.json.
Creates the config file with sensible defaults: ~/.mcp-memory/config.json (user scope) or <project>/.mcp-memory/config.json (project scope; the generated .mcp.json pins it via MCP_MEMORY_CONFIG_PATH).
Writes memory usage instructions to .claude/CLAUDE.md (project scope) or prints a snippet (user scope).
Registers the MCP server with Claude Code — user scope runs claude mcp add -s user memory-server -- npx -y mcp-memory-graph for you (idempotent; best-effort — warns with the manual command if the claude CLI isn't on PATH; skip with --no-register). Project scope is registered via the committable .mcp.json instead. This makes step 2 of the Quick Start optional.
Installs the mcp-memory-graph usage skill into ~/.claude/skills/ so Claude Code has inline guidance for all 51 tools, gotchas, and workflows. Skip with --no-skill.
Sets up the nightly consolidation schedule (macOS: launchd, loaded immediately so it runs without a relogin; Linux: prints a cron suggestion; skipped for project scope).
Under a non-interactive shell (agent/CI) the wizard is bypassed: defaults are applied and a report is printed showing what was set and how to change each value. Passing --yes applies the defaults silently (no report).
Key flags: --scope user|project, --schedule HH:MM[,HH:MM] (nightly consolidation time, default 03:00), --vault <path> (enable Obsidian vault round-trip), --no-review-on-stop (disable the end-of-session learning review), --no-skill (skip skill install), --no-register (skip the user-scope claude mcp add), --remote <url> (team server mode).
npx mcp-memory-graph uninstall reverses everything init did: removes hooks, the nightly schedule, the CLAUDE.md block, and the installed skill.
Every step is scriptable. There is no interactive-only path:
git clone https://github.com/YonasValentin/mcp-memory-graph.git
cd mcp-memory-graph
npm install && npm run build
npx mcp-memory-graph init --scope project --yes # local: hooks + .mcp.json, no prompts
# or point at a shared self-hosted server instead:
# npx mcp-memory-graph init --remote https://memory.example.com --token-env MEMORY_MCP_TOKENClaude Code gets the hooks; everyone else gets the same 51 tools, driven manually. The server is a standard MCP server, so any client works. A line in the client's rules file makes usage near-automatic.
Register the server. Example for Codex, in ~/.codex/config.toml (global) or .codex/config.toml (project, trusted only):
[mcp_servers.memory-graph]
command = "node"
args = ["/abs/path/to/mcp-memory-graph/dist/index.js"]
tool_timeout_sec = 180 # the first call downloads the ~30 MB model once; the 60s default can be tight
[mcp_servers.memory-graph.env]
MCP_MEMORY_DB_PATH = "/abs/path/to/.mcp-memory/memory.db"
# or a shared self-hosted server over HTTP (see Self-hosting below):
# url = "https://memory.example.com/mcp"
# bearer_token_env_var = "MEMORY_MCP_TOKEN"Or codex mcp add memory-graph -- node /abs/path/to/mcp-memory-graph/dist/index.js. Cursor, Windsurf, and other clients use their own MCP config format, but the server command (node .../dist/index.js) and the HTTP option are the same.
Then nudge the agent in its instructions file (Codex: AGENTS.md; Cursor: project rules):
Before answering questions about architecture, decisions, patterns, or past fixes, call
memory_searchon the memory-graph server first; store new decisions, patterns, and fixes withmemory_store.
The server runs three ways, from a single-user cache to a knowledge base shared across many machines. All three are local-first: nothing leaves the machines you choose to run it on.
npx mcp-memory-graph init registers a local stdio server plus the hooks. Memory lives in one SQLite file on your machine. Nothing else to run. Right choice for solo use.
Run one server that many clients connect to over HTTP. Everyone shares the same memory base, live.
Start the server (pick one):
# From source: build the server (and the dashboard, if you want it) first
npm run build:all
MCP_AUTH_TOKEN=$(openssl rand -hex 32) MCP_BIND=0.0.0.0 npm run serve
# MCP at /mcp, REST at /api, dashboard at /, all on :3100
# Or with Docker (frontend included; publishes host port 3200 by default)
MCP_AUTH_TOKEN=$(openssl rand -hex 32) docker compose up -dSet MCP_AUTH_TOKEN whenever the server is reachable beyond loopback. It is a shared bearer token, one secret for all clients. The server refuses to start unauthenticated on a non-loopback bind unless you set MCP_AUTH_OPTIONAL=1. Terminate TLS at a reverse proxy or tunnel for anything off-host.
Connect a client, one command per machine:
npx mcp-memory-graph init --remote https://memory.example.com --token-env MEMORY_MCP_TOKEN
export MEMORY_MCP_TOKEN=<the server token> # in your shell or .envFor Claude Code this writes a project .mcp.json pointing at the shared server. The token is stored as an env-var reference ("Authorization": "Bearer ${MEMORY_MCP_TOKEN}"), so the committed .mcp.json never contains the secret. Non-Claude clients point at the same server through their own MCP config.
Flag | Effect |
| Reference this env var for the token (default |
| Inline a literal token instead (avoid committing it) |
| Omit the auth header (loopback or trusted network only) |
In remote mode the local capture and recall hooks are not installed. The memory lives on the server, not in a local file the hooks could read. The agent uses
memory_searchandmemory_storedirectly (the CLAUDE.md guidance is still written).
Prefer your knowledge base in git, reviewed through pull requests, with no server to run? Export memories to plain Markdown and share the folder as a git repo:
npx mcp-memory-graph vault-init # make the vault a git repo (union merge driver + rebuild hook)
git add -A && git commit -m "memory snapshot" && git push
# collaborators, once after cloning:
# npx mcp-memory-graph vault-init # registers the union merge driver + post-merge hook in THEIR clone
# collaborators, thereafter: git pull && npx mcp-memory-graph rebuildEach collaborator must run
vault-initonce in their own clone. The merge driver and post-merge rebuild hook live in local git config (.git/), not in the repo. A fresh clone withoutvault-initwill hit raw conflict markers in.memory/graph.jsonon its first concurrent pull. Re-runningvault-initis idempotent and does not clobber the committed sidecar.
Two recovery notes for team vaults:
After a merge you resolved by hand (the post-merge hook only fires on clean merges), memory rebuild can refuse with VaultIntegrityError because .memory/manifest.json is stale. Delete that file and re-run rebuild; it is derived state and regenerates.
Hand-edited a .md while your database has newer state? Import first (vault_sync or rebuild), then export (memory sync). A full export from a stale database overwrites vault files, including your hand edit.
MCP_AUTH_TOKEN is a single shared secret, fine for a trusted group; rotate it by restarting the server with a new value. For per-key RBAC (one server, N keys, each pinned to a namespace set and an access-level ceiling) use memory keys create|list|revoke (schema v16). The legacy shared token still works and is checked first. See docs/MULTI-TENANCY.md.
Never commit a token. The --remote default keeps it in an env var by design.
Bind to 127.0.0.1 (the default) unless you front the server with a proxy that terminates TLS; then set MCP_BIND=0.0.0.0.
Building an org-wide AI brain? One server, a key per employee, an org chart the AI can traverse (people, teams, SOPs, and tools as typed graph nodes), with enforced who-sees-what. The recipe, built on existing primitives, is in docs/ENTERPRISE-BRAIN.md.
Variable | Default | Description |
|
| Database file location. The directory is created automatically. |
|
| HuggingFace embedding model name. Must be an ONNX model compatible with Transformers.js. |
|
| Embedding vector dimensions. Must match the model's output. |
|
| Override location for the configuration file. |
The full env reference (auth, rate limits, webhooks, vault, publish) is in docs/ENV.md.
claude mcp add memory-server --env MCP_MEMORY_DB_PATH=/path/to/project/.memory.db node /path/to/dist/index.js# Swap the embedding model (same 384 dimensions; drop-in for the existing index
# AFTER a re-embed; see the warning below)
claude mcp add memory-server \
--env MCP_MEMORY_MODEL=Xenova/bge-small-en-v1.5 \
--env MCP_MEMORY_DIMENSIONS=384 \
node /path/to/dist/index.jsModel identity is recorded and enforced. The database remembers which embedding model built it (
schema_meta.embedding_model). Starting the server with a differentMCP_MEMORY_MODELfails loudly instead of silently degrading every search (same dimension does not mean same vector space). To switch models: set the new model and runmemory rebuild(re-embeds from the vault), or export and re-import.
The config file controls self-improvement behavior, hook settings, and per-project overrides. Resolution order: MCP_MEMORY_CONFIG_PATH env, then <cwd>/.mcp-memory/config.json (project-scope init writes this), then ~/.mcp-memory/config.json. Created by npx mcp-memory-graph init, or write it by hand:
{
"defaults": {
"scope": "project",
"namespace": "auto"
},
"projects": [
{
"path": "~/Documents/MyApp",
"namespace": "my-app",
"watch": ["README.md", "docs/**/*.md"]
}
],
"consolidation": {
"similarity_threshold": 0.85,
"prune_after_days": 30,
"min_importance_to_keep": 0.1,
"max_operations": 100,
"schedule": [
{ "hour": 11, "minute": 30 },
{ "hour": 16, "minute": 0 }
]
},
"hooks": {
"extract_on_compact": false,
"extract_on_session_end": false,
"track_searches": true,
"review_on_stop": true
},
"extraction": {
"categories": ["decision", "pattern", "error_fix", "convention"],
"min_confidence": 0.4
}
}Section | Key | Default | Description |
|
|
| Default scope for new memories |
|
|
| Default namespace ( |
|
| Project root directory | |
|
| Namespace override for this project | |
|
| Glob patterns for files to track for changes | |
|
|
| Cosine similarity threshold for deduplication (0.5-1.0) |
|
|
| Days before pruning low-quality memories |
|
|
| Minimum importance score to survive pruning |
|
|
| Max operations per consolidation run |
|
|
| One or more |
|
|
| Mine transcript before context compression (regex-based, off by default) |
|
|
| Extract learnings when session ends (regex-based, off by default) |
|
|
| Log search hits and misses to |
|
|
| Spawn headless |
|
|
| Learning categories to extract |
|
|
| Minimum confidence for extracted learnings |
|
| scope-dependent | SQLite file location ( |
|
| unset | Obsidian vault root used by |
|
|
| Mirror memory writes out to the vault as |
Command | Description |
| Start the MCP server on stdio (default) |
| Start the HTTP server: MCP transport, REST API, web dashboard |
| Interactive setup wizard: hooks, config, nightly schedule (user scope). Add |
| Setup for the current project only (creates |
| Reverse init: remove hooks and schedule |
| Run the dream cycle manually |
| Write a committable, deterministic |
| Install the |
| Git union merge driver for |
| Make the vault a git repo: union merge driver, |
| Export all valid memories plus the graph sidecar to the vault ( |
| Rebuild the SQLite index from the vault's |
| Upgrade the database to the current schema version |
| WAL-safe online snapshot (retention: |
| Per-key RBAC: mint, inspect, revoke API keys (namespace set plus access ceiling) |
memory_storeStore a new memory. The vector embedding is generated automatically.
Parameter | Type | Required | Default | Description |
| string | Yes | The text content to store | |
| string | No | Short title for the memory | |
| enum | No |
| global, project, user, team, department |
| string | No | ¹ | Sub-scope (e.g., project name) |
| number | No | computed | 0-1 manual importance override |
| string | No |
| Attribution for memory_attribution rollups |
| enum | No |
| add, supersede, skip: write-gate behavior on near-duplicates |
| string | No | contract, policy, code, incident, decision, etc. | |
| string | No | Where this content came from | |
| string | No | Who created it | |
| string | No | legal, engineering, hr, sales, finance | |
| string[] | No | Tags for categorization | |
| enum | No |
| public, internal, confidential, restricted |
| string | No |
| ISO 639-1 language code |
| object | No | Domain-specific key-value pairs | |
| string | No | ISO 8601 expiration date |
¹ When omitted, a loaded config file's defaults.scope and defaults.namespace ("auto" = project directory name) apply first; the hardcoded fallback is global with no namespace.
Example prompt:
Store this memory with department=legal and tags=["compliance","gdpr"]:
"All customer data processing agreements must include a GDPR Article 28 addendum effective January 2025."memory_searchHybrid vector plus keyword search across stored memories.
How it works:
Your query is embedded and compared against all stored vectors (semantic similarity).
Your keywords are matched against memory text via FTS5 (exact matching).
Both result lists merge using Reciprocal Rank Fusion.
Optional temporal decay favors recent memories.
Results get a confidence score and label.
The access is recorded for quality scoring.
Parameter | Type | Required | Default | Description |
| string | Yes | Natural language query or keywords | |
| enum | No | Filter by scope | |
| string | No | Filter by namespace | |
| string | No | Filter by department | |
| string | No | Filter by document type | |
| string[] | No | Filter: must contain ALL specified tags | |
| enum | No | Filter by access level | |
| string | No | Filter by language | |
| number | No |
| Max results (1-100) |
| number | No |
| Pagination offset |
| enum | No |
|
|
| object | No |
| |
| string | No | Only memories after this date | |
| string | No | Only memories before this date | |
| number | No | Minimum confidence threshold (0-1) |
Example prompts:
Search memories for "contract renewal notice requirements" in the legal department
Search memories for "authentication" with search_mode=keyword
Search memories for "deployment patterns" with temporal_decay={type:"exponential", half_life_days:60}Each result includes the memory content and metadata, the combined RRF score, a normalized confidence (0-1), a confidence_level label (high at 0.7 and above, medium at 0.4 and above, low below that), and a match_type (hybrid, vector, or keyword).
The default
detail_level: "summary"projection returnsconfidence_levelbut omits the numericconfidenceand the fullcontent, to save tokens. Passdetail_level: "full"when you need them.
memory_getRetrieve a specific memory by ID. For ingested documents, optionally include all child chunks.
Parameter | Type | Required | Default | Description |
| string | Yes | Memory UUID | |
| boolean | No |
| Include child chunks for ingested documents |
memory_updateUpdate an existing memory. If content changes, the embedding regenerates automatically. The previous version is saved to history.
Parameter | Type | Required | Default | Description |
| string | Yes | Memory ID to update | |
| string | No | New content (triggers re-embedding) | |
| string | No | New title | |
| object | No | Replacement metadata | |
| string[] | No | Replacement tags | |
| string/null | No | New expiry, or null to remove | |
| string | No | Who made this change |
memory_deleteDelete memories by ID or by filter. At least one of id or filter is required.
Parameter | Type | Required | Description |
| string | No | Delete a specific memory |
| enum | No | Delete all in scope |
| string | No | Delete all in namespace |
| string | No | Delete all in department |
| string | No | Delete older than date |
| boolean | No | Only delete expired memories |
memory_listBrowse memories with filtering, pagination, and sorting.
Parameter | Type | Default | Description |
| enum | Filter by scope | |
| string | Filter by namespace | |
| string | Filter by department | |
| string | Filter by type | |
| number |
| Max results (1-100) |
| number |
| Pagination offset |
| enum |
|
|
| enum |
|
|
memory_ingestIngest a full document: it is chunked by content type, each chunk is embedded, and everything is stored with parent-child relationships. Use this for large documents.
Parameter | Type | Default | Description |
| string | Full document text (required) | |
| string | Document title | |
| enum |
| Chunking strategy: |
| number |
| Target chunk size in characters (~4 chars per token) |
| number |
| Overlap between chunks for context |
| string | Origin file or URL | |
| string | Document classification | |
| string | Department | |
| string | Author | |
| string[] | Tags | |
| object | Domain-specific metadata |
Chunking by content type:
Type | Strategy | Splits on |
| Paragraph | Double newlines ( |
| Heading-aware |
|
| Function-aware |
|
| Sentence | Period, exclamation, question marks |
| Paragraph | Double newlines (same as text) |
memory_relatedFind memories semantically related to a given one. Uses vector similarity, so it finds connections keyword search misses.
Parameter | Type | Default | Description |
| string | Memory ID to find related for (required) | |
| number |
| Max results (1-50) |
| number | Minimum similarity threshold (0-1) |
memory_versionsView a memory's version history. Every update creates a version record.
Parameter | Type | Default | Description |
| string | Memory ID (required) | |
| number |
| Max versions (1-50) |
memory_statsUsage statistics about stored memories.
Parameter | Type | Description |
| enum | Filter stats by scope |
| string | Filter stats by namespace |
| string | Filter stats by department |
Returns totals for memories, documents, and chunks, breakdowns by scope, department, and type, storage size, and the expired count.
memory_exportExport current memory content as JSON for portability or migration. This is not a full backup: it serializes only currently live, top-level memories. It omits edit history, the knowledge graph, condense-undo originals, ingested child chunks, and soft-forgotten rows. For disaster recovery, copy the SQLite file (cp ~/.mcp-memory/memory.db ..., see the RUNBOOK); embeddings recompute deterministically on import.
Parameter | Type | Default | Description |
| enum | Filter export | |
| string | Filter export | |
| string | Filter export |
Max 1000 records per export.
memory_importImport memories from JSON. Each item is embedded and stored.
Parameter | Type | Default | Description |
| array | Array of memory objects (required) | |
| boolean |
| Overwrite existing IDs |
vault_syncScan an Obsidian vault, parse the markdown, embed and store. See Obsidian Vault Integration below.
vault_statusSync status for a vault: files synced, pending, changed, and the last sync time.
vault_searchHybrid search scoped to one vault's memories.
By default this searches the namespace named after the vault's folder name. Memories exported from another namespace keep their original namespace in frontmatter. If a search over a freshly synced vault returns nothing, pass an explicit
namespace(and/orscope) override.
memory_consolidateThe dream cycle: deduplicate, score, prune, expire, and detect knowledge gaps.
Parameter | Type | Required | Default | Description |
| enum | No | Limit consolidation to a scope | |
| string | No | Limit consolidation to a namespace | |
| number | No |
| Cosine similarity for dedup (0.5-1.0) |
| boolean | No |
| Remove expired memories |
| boolean | No |
| Remove memories below min importance |
| boolean | No |
| Preview changes without applying |
| number | No |
| Cap on total operations per run |
Five stages run in order: Score (recalculate importance), Expire (enforce expires_at), Prune (drop low-quality when enabled), Dedup (merge near-duplicates), Gaps (surface zero-result searches). Returns a report with counts per stage.
Example prompts:
Run a dream cycle consolidation with dry_run=true to preview what would change
Consolidate memories in namespace=my-project with similarity_threshold=0.9
Run consolidation with prune_low_quality=true to clean up unused memoriesmemory_extract_learningsMine a session transcript for decisions, patterns, error fixes, and conventions using heuristic pattern matching. No external LLM needed.
Parameter | Type | Required | Default | Description |
| string | Yes | Session transcript text to mine | |
| enum | No | Scope for extracted memories | |
| string | No | Namespace for extracted memories | |
| string | No | Department for extracted memories | |
| string[] | No | Additional tags | |
| string | No | Source attribution | |
| enum[] | No | all | Filter to |
| boolean | No |
| Automatically store extracted learnings |
Extraction looks for decision language ("we decided", "the fix was"), pattern language ("always use", "never do"), error fixes ("the problem was", "solved by"), and conventions ("our convention is", "standard practice"). Each hit is deduplicated against existing memories and stored with a lower initial confidence.
Parameters for the remaining tools are validated by Zod schemas in src/schemas/; each registration's full description lives in src/server.ts.
# | Tool | Purpose |
18 |
| MemGPT-style hot / recall / archival tier distribution plus the hot working set |
19 |
| Write memories out to an Obsidian vault as |
20 |
| Export the graph as a JSON Canvas 1.0 |
21 |
| Lightweight content-free index (titles, types, tags, scores) to discover what exists |
22 |
| Query the knowledge graph: entities, relationships, linked memories, multi-hop traversal (depth 1-3) |
23 |
| Store LLM-extracted entities and relationships for a memory |
24 |
| Apply agent-generated summaries to condense old memories (original preserved) |
25 |
| Restore a condensed memory to its original content and re-embed |
26 |
| Answer a question with a tight, token-budgeted subgraph instead of flooding context |
27 |
| Read the pinned, always-in-context core-memory block for a |
28 |
| Append to the core-memory block (refused if it would overflow |
29 |
| Replace text in the core-memory block (used to update or compact it) |
30 |
| Generative-Agents-style reflection: gather material, or store a synthesized insight |
31 |
| GraphRAG community detection over the entity graph for corpus-level themes |
32 |
| Fetch a structured note scaffold per document type |
33 |
| Per-session "daily note" (appends to one memory per |
34 |
| Roll up how many valid memories each |
35 |
| "Questions to ask" digest: ambiguous links, under-documented entities, orphans |
36 |
| GDPR-grade forget: soft-delete (recoverable) by default, or |
37 |
| Point-in-time bi-temporal timeline plus edit-version history for one memory |
38 |
| Entity names mentioned in memory text with no graph edge yet (suggested links) |
39 |
| Exact metadata filter query over top-level memories (no semantic ranking) |
40 |
| Line-level diff between two stored versions of a memory |
41 |
| Roll a memory back to a previous version (snapshots the current one first) |
42 |
| Verify the signed provenance envelope of memories (ed25519 over content_hash plus origin): per-memory |
# | Tool | Purpose |
43 |
| Manage the event bus (gated by |
44 |
| Advisor digest: unresolved conflicts, stale memories, most-contradicted facts, evidence-less decisions |
45 |
| Store health roll-up: live/retired/stale counts, aging buckets, unresolved conflicts, webhook delivery health |
46 |
| Change propagation: list stale memories, preview a change's blast radius (dry run), or confirm a memory is current |
47 |
| Resumable "where was I" session state, save and resume (versioned) |
48 |
| Per-user expertise profile: observe a topic, get the profile |
49 |
| Export learnings and reflections as JSONL training pairs (pairs/chatml/alpaca) for fine-tuning |
50 |
| Capture a structured lesson or incident in one call: fills the matching section template (incident → Symptom/Root Cause/Fix/Prevention; lesson → What/Why it matters/How to apply) from your field values and stores it through the normal deduped write path |
Claude Code ──stdio──> MCP Memory Graph
│
┌───────┴───────┐
│ │
Transformers.js SQLite DB
(embeddings) (~/.mcp-memory/memory.db)
│
┌────────────┼────────────┐
│ │ │
memories memories_fts memories_vec
(data + (FTS5 index) (vec0 index)
scores)
│
┌────────┼────────┐
│ │ │
memory_ memory_ ingest_
versions access_ source_
log tracking
Claude Code Hooks (opt-in)
│
├── SessionStart ──> memory_stats (status check)
├── PostToolUse ───> search-log.jsonl (hit/miss tracking)
├── PreCompact ────> learning extraction (disabled by default)
└── Stop ──────────> spawn detached `claude -p` headless review
│
└─> --allowedTools mcp__memory-server__memory_store
Claude reviews transcript → memory_store calls
Nightly Schedule (opt-in)
└── 3:00 AM ───────> memory_consolidate (dream cycle)Query: "contract renewal notice"
│
┌────┴────┐
│ │
Embed Tokenize
│ │
▼ ▼
sqlite-vec FTS5
(semantic) (keyword)
│ │
│ rank │ rank
│ 1: A │ 1: A
│ 2: C │ 2: B
│ 3: B │ 3: D
│ │
└────┬────┘
│
Reciprocal Rank Fusion
RRF(d) = Σ 1/(60 + rank)
│
▼
[A: 0.033, B: 0.026, C: 0.016, D: 0.016]
│
Temporal Decay (optional)
│
Confidence Scoring
│
Access Tracking (record hit)
│
▼
Final ranked resultsThe SQLite database is at schema version 18, with automatic forward migration from any earlier version. The core tables:
memories: all memory data, TEXT primary key (UUIDs), parent-child support for document chunks, plus access_count, last_accessed_at, importance_score, and confidence_score.
memories_fts: FTS5 virtual table for keyword search with BM25 ranking, synced with the memories table.
memories_vec: vec0 virtual table for vector search. 384-dimension float32 embeddings with scope and namespace metadata for pre-filtering.
memory_versions: version history for every change.
memory_access_log: every search, get, and related-memory access, with timestamps and query context.
ingest_source_tracking: ingested files, for change detection on re-ingestion.
Later schema versions add the knowledge-graph tables (entities, links, conflicts, communities), webhooks, session state, and the RBAC api_keys table. Every mutation keeps the three core tables in sync atomically inside a SQLite transaction; the repository.ts layer enforces this, and nothing else touches the tables directly.
src/
├── index.ts # Entry point (stdio transport)
├── server.ts # All 51 tool registrations
├── config/ # Config file loading + validation
├── db/ # Connection, schema, migrations, repository (three-table sync)
├── embeddings/ # Embedding providers (Transformers.js, registry, Ollama)
├── search/ # Hybrid search, reranker, temporal decay, scoring
├── chunking/ # Per-content-type chunking strategies
├── graph/ # Entities, links, PageRank, communities
├── vault/ # Obsidian round-trip, write-through, bookkeeping
├── tools/ # One handler per MCP tool
├── api/ # REST routes + security middleware
├── events/ # Webhook bus (SSRF guard, HMAC, retry)
├── cli/ # init, serve, vault, backup, keys, migrate, ...
├── hooks/ # Claude Code lifecycle hooks
└── schemas/ # Zod schemas for every tool inputEngineering:
Store memory: "We chose event sourcing over CRUD for the order service because
we need full audit trail and the ability to replay events for debugging.
ADR-042, decided 2026-03-15."
department=engineering, document_type=decision, tags=["architecture","event-sourcing"]Legal:
Ingest this contract template with content_type=legal, department=legal,
document_type=contract, tags=["template","nda","standard"]Finance:
Store memory: "Q4 2025 revenue recognition policy change: SaaS contracts
over 12 months now recognized ratably per ASC 606 guidance."
department=finance, document_type=policy, tags=["revenue-recognition","asc-606"]HR:
Ingest the employee handbook with department=hr, content_type=text,
document_type=policy, tags=["handbook","onboarding"]Sales:
Store memory: "When prospect objects on price vs CompetitorX, lead with
our 99.9% uptime SLA and dedicated support. This converted 3 deals in Q1."
department=sales, document_type=pattern, tags=["objection-handling","pricing","competitorx"]Point the server at a vault folder and every markdown file becomes a searchable memory, with frontmatter, tags, and wiki-links extracted. No Obsidian app needed; it reads the files straight from disk.
Tool | Description |
| Scan vault, parse files, embed and store. Incremental (mtime-based). |
| Sync status: files synced, pending, changed, last sync time. |
| Hybrid search scoped to a vault's memories. |
What gets extracted:
Obsidian feature | Memory field |
YAML frontmatter |
|
YAML frontmatter |
|
YAML frontmatter |
|
YAML frontmatter (all fields) |
|
Inline |
|
|
|
File path relative to vault |
|
Vault directory name |
|
Usage examples:
Sync my Obsidian vault at ~/Documents/my-vault
Check vault sync status for ~/Documents/my-vault
Search my vault for "meeting action items about hiring"
Sync vault but only the notes/ and projects/ folders:
vault_sync with include_patterns=["notes/**", "projects/**"]
Force re-sync everything (ignore modification times):
vault_sync with force=truevault_sync parameters:
Parameter | Type | Default | Description |
| string | Absolute path to vault directory (required) | |
| number |
| Target chunk size for large files |
| number |
| Overlap between chunks |
| boolean |
| Re-sync all files regardless of mtime |
| string[] | Only sync matching globs (e.g., | |
| string[] | Skip matching globs (e.g., |
How sync works: it scans the vault recursively for .md files (skipping .obsidian/, .trash/, .git/), compares modification times against the last sync, extracts frontmatter, wiki-links, and tags from new or changed files, embeds, and stores. Deleted files have their memories removed. Files larger than the chunk size are split with markdown-aware chunking. A second sync of an unchanged vault takes under a millisecond.
No network calls after the one-time model download (cached locally).
No telemetry, no analytics, no tracking.
Hooks are opt-in. They are only installed when you run npx mcp-memory-graph init.
The nightly schedule is opt-in too, and removed by npx mcp-memory-graph uninstall.
Everything is one SQLite file: easy to back up, move, or delete.
access_level metadata (public, internal, confidential, restricted) for organizational awareness.
Data never leaves your machine.
Backup:
# WAL-safe online snapshot with retention
npx mcp-memory-graph backup
# Or a simple file copy
cp ~/.mcp-memory/memory.db ~/.mcp-memory/memory.db.backupReset:
# Delete the database to start fresh
rm ~/.mcp-memory/memory.dbWhen installed via npx mcp-memory-graph init, a nightly job runs all five dream-cycle stages plus access-log rotation (entries older than 90 days are dropped).
On macOS, a launchd plist is created at ~/Library/LaunchAgents/com.mcp-memory.consolidate.plist, scheduled for 3:00 AM. On Linux, init prints a cron suggestion:
# Add to crontab -e
0 3 * * * /usr/local/bin/npx mcp-memory-graph consolidateRun it manually any time:
npx mcp-memory-graph consolidateScale ceiling. Vector search is an exact scan: 9.1 ms p95 at 10K vectors, about 30 ms at 50K, and it degrades linearly from there. Comfortable into the low hundreds of thousands; past that you want a dedicated ANN index, which this server does not have yet.
English-optimized. The default MiniLM model is English-only in practice; cross-language matching is weak. A multilingual model can be configured via MCP_MEMORY_MODEL (with a rebuild), but the shipped benchmarks only validate the default.
First-call cold start. Three to five seconds on first use while the embedding model loads. Cached after that.
Heuristic extraction. memory_extract_learnings uses pattern matching, not an LLM. It catches common phrasings and misses subtle ones. (The Stop hook's claude -p review is the LLM-quality path.)
One process. RBAC keys and revocation live in the server process. For horizontal scale you shard tenants across processes or give each tenant their own database file.
What's actually next, in rough order:
Multilingual embeddings, opt-in. Ship a multilingual ONNX model option (the embedder registry and the model-identity guard already exist, so a swap is safe and loud).
Office document ingestion. PDF, DOCX, XLSX, and friends as an ingest mode, with local extraction only.
Vault file watcher. Auto-rebuild on .md changes instead of manual rebuild.
as_of content reconstruction. Point-in-time queries currently reconstruct validity (which facts were live); reconstructing the content of edited memories at that instant is the remaining half.
ANN index for corpora past a few hundred thousand vectors.
Windows test suite port. The server runs on Windows, but the test suite carries POSIX path assumptions; the Windows CI leg is non-blocking until that's done.
Component | Package | Purpose |
MCP SDK |
| Model Context Protocol server framework |
Embeddings |
| Local ONNX model inference in Node.js |
Database |
| Synchronous SQLite with native bindings |
Vector search |
| vec0 virtual table for KNN search |
Validation |
| Schema validation for tool inputs |
TypeScript |
| Strict mode, ES2022 target |
Frontend | React 19, Vite, Tailwind CSS v4 | Web dashboard SPA |
UI components | shadcn/ui | Accessible component primitives |
Fuzzy search |
| Client-side autocomplete suggestions |
Graph viz |
| Knowledge graph layout |
Source-available, not open source. Licensed under the PolyForm Noncommercial License 1.0.0: free for any noncommercial purpose (personal projects, hobby, study, research, charitable, educational, public-research, and government use). Commercial use requires a paid license; see COMMERCIAL.md.
If you're unsure whether your use counts as commercial, check the safe harbors in the license or just ask: yonasmougaard@gmail.com.
MCP memory server · Model Context Protocol · Claude Code memory · persistent AI memory · LLM long-term memory · AI agent memory · local-first memory · $0/token memory · hybrid vector + keyword search · semantic search · knowledge graph · bi-temporal memory · HippoRAG / Personalized PageRank · cross-encoder reranking · RAG memory · SQLite vector database · sqlite-vec · FTS5 / BM25 · local embeddings (all-MiniLM-L6-v2, Transformers.js) · Obsidian vault sync · JSON Canvas · GDPR forget · signed provenance · self-hosted memory.
Also searched as: a self-hosted, privacy-first alternative to mem0, Zep, Letta, Cognee, and Supermemory · long-term memory for Claude / Cursor / Codex · an Obsidian-backed knowledge base for AI agents · a local knowledge-graph memory that never leaves your machine.
Append text to the pinned core-memory block (newline-separated when non-empty). If the result would exceed char_limit the write is refused (error: core_memory_full) so you compact via core_memory_replace instead of silently overflowing.
| Name | Required | Description | Default |
|---|---|---|---|
| scope | No | Memory scope for isolation | global |
| namespace | No | Namespace within scope (e.g., project name, team name) | |
| text | Yes | Text to append to the pinned core-memory block (newline-separated when the block is non-empty). Refused if it would exceed char_limit — compact via core_memory_replace instead. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses refusal behavior on exceeding char_limit and suggests alternative. Lacks explicit mention of mutation or state change, but 'append' implies it. Annotations are minimal (only openWorldHint=false), so description adds useful behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded purpose, no fluff. Every word contributes to understanding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Adequate for a simple append tool. Mentions error case but does not describe success return. No output schema, but for a tool with clear side effects, this is acceptable. Could mention success confirmation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%; description adds meaning beyond schema by explaining newline separation and the overflow condition. Enhances understanding of text parameter behavior.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clear verb 'Append' and resource 'pinned core-memory block', with specific detail 'newline-separated when non-empty'. Distinguishes from sibling core_memory_replace by mentioning the alternative for overflow.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use: append text, and when not: if exceeding char_limit, use core_memory_replace instead. Also provides error condition 'core_memory_full'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read the pinned "core memory" block for a (scope, namespace) — a small, bounded, always-in-context note the agent maintains about who it is and what matters now. Returns content, char_limit, and used (character count).
| Name | Required | Description | Default |
|---|---|---|---|
| scope | No | Memory scope for isolation | global |
| namespace | No | Namespace within scope (e.g., project name, team name) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true, and the description adds value by detailing return fields (content, char_limit, used count) and constraints (bounded, always-in-context). No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence that is efficient and front-loaded with the verb and object. Every word contributes to understanding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description adequately covers return values (content, char_limit, used) and explains the tool's role (pinned core memory). Sufficient for a read operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description does not add meaningful parameter-specific details beyond what the schema provides; it only contextualizes the overall tool purpose.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description specifies a clear verb ('Read'), resource ('pinned core memory block'), and scope ('for a (scope, namespace)'). It distinguishes from siblings by focusing on the 'pinned' and 'always-in-context' core memory, contrasting with other memory tools like memory_get.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives like memory_get or core_memory_append/replace. The description implies a read operation for core memory but does not specify when not to use it or suggest alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Replace the first occurrence of old_text with new_text in the pinned core-memory block. Returns error: not_found if old_text is absent, or core_memory_full if the result would exceed char_limit. Use this to update or compact the block.
| Name | Required | Description | Default |
|---|---|---|---|
| scope | No | Memory scope for isolation | global |
| namespace | No | Namespace within scope (e.g., project name, team name) | |
| old_text | Yes | Substring to find (first occurrence) in the core-memory block | |
| new_text | Yes | Replacement text for the first occurrence of old_text |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only provide openWorldHint=false, so the description carries the burden. It discloses replacing the first occurrence, possible errors (not_found, core_memory_full), and hints at persistence ('pinned core-memory block'). However, it does not specify if the operation is atomic or if any side effects occur beyond the replacement.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences: first explains the core operation, second adds error information and usage hint. Every word serves a purpose with no fluff. Front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Lacks output details for success (e.g., returns nothing or updated block?). No output schema exists. The description covers errors but leaves the agent guessing about success behavior. Adequate for a replace operation but not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has 100% description coverage, so every parameter's meaning is already documented. The tool description does not add further semantic value beyond what schema provides, meeting the baseline for high coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Replace the first occurrence of old_text with new_text in the pinned core-memory block', specifying verb and resource. It also mentions error conditions (not_found, core_memory_full) and a usage hint ('update or compact the block'), which distinguishes it from sibling tools like core_memory_append or core_memory_delete.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'Use this to update or compact the block' provides some guidance on when to use, but it does not explicitly contrast with alternatives like core_memory_append or core_memory_get. No when-not-to-use scenarios are mentioned, leaving room for ambiguity in tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Multi-agent / team attribution rollup. Returns how many currently-valid top-level memories each agent (agent_id, set at store time) wrote — { by_agent, by_author, total } — distinct from author (the human/source). Memories stored without an agent_id are bucketed under "unattributed". Optional scope/namespace filters scope the rollup.
| Name | Required | Description | Default |
|---|---|---|---|
| scope | No | Memory scope for isolation | |
| namespace | No | Namespace within scope (e.g., project name, team name) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=false. The description adds valuable behavioral context: it only counts 'currently-valid top-level memories', handles unattributed memories by bucketing them, and describes the return structure in detail, which goes beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loading key functionality and structure. Every sentence adds essential information with no redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has only two optional parameters and no output schema, the description fully explains the return structure and filtering. It covers all necessary aspects for an agent to correctly use the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with each parameter described (scope: 'Memory scope for isolation', namespace: 'Namespace within scope'). The description mentions optional filters but adds no new meaning beyond the schema, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns an attribution rollup of top-level memories by agent, with specific fields (by_agent, by_author, total). It distinguishes itself by noting the difference between agent and author, and mentions unattributed memories, which sets it apart from sibling tools like memory_stats.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for multi-agent/team attribution and includes optional filters, but does not explicitly state when to avoid this tool or mention alternatives. It provides clear context but lacks explicit guidance on when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Export the memory graph as a JSON Canvas 1.0 .canvas — opens as a spatial board in real Obsidian. Each currently-valid top-level memory becomes a text node on a deterministic grid; memory_links become labeled, arrow-tipped edges. Optionally filter by scope/namespace and cap with limit. When vault_path is given the canvas is written there (confined under the vault) and its path returned; otherwise only the canvas object.
| Name | Required | Description | Default |
|---|---|---|---|
| scope | No | Memory scope for isolation | |
| namespace | No | Namespace within scope (e.g., project name, team name) | |
| limit | No | Maximum memories to include as canvas nodes (default 50) | |
| vault_path | No | Absolute path to an Obsidian vault directory (created if missing). When given, the canvas is written there as a .canvas file (confined under the vault) and its path is returned; otherwise only the canvas object is returned. | |
| name | No | Filename stem for the written .canvas (default "memory-graph"). Sanitized — path separators and ".." can never escape the vault. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the minimal annotations (title, openWorldHint=false), the description adds key behavioral details: output is a deterministic grid with labeled arrow-tipped edges, vault_path confines writing, and filenames are sanitized. This provides good transparency for a read-only export operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is tightly written (~80 words), front-loads the purpose, and every sentence adds unique value. No redundant or extraneous content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 5 optional parameters, no output schema, and moderate complexity, the description covers core behavior (what becomes nodes/edges, filtering, file writing). The return value when vault_path is omitted is explained as 'canvas object,' which is somewhat vague but acceptable. Performance or size limitations are not mentioned.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds context on output structure ('memory_links become labeled, arrow-tipped edges') but does not enhance parameter meaning beyond what schema descriptions already provide.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool exports the memory graph as a JSON Canvas 1.0 .canvas file, which opens as a spatial board in Obsidian. This specific verb and resource distinguishes it from sibling tools like memory_export, memory_export_dataset, and memory_export_vault.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions optional filtering and two modes (return object or write file) but does not explicitly state when to use this tool versus alternative export tools. Usage context is implied but not contrasted with siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
GraphRAG global sensemaking (agent-driven, no LLM in the server). Detects communities (densely-connected entity clusters) over the entity graph on demand via weighted label propagation, and returns each community's top entities + linked memories. This is the corpus-level view that chunk-level search can't give — synthesize named themes from the communities to answer "what are the main themes?".
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum communities to return, largest first (default 20) | |
| min_size | No | Drop communities with fewer than this many entities (default 1) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true (safe read). The description adds that the process is agent-driven with no LLM in the server (deterministic algorithm), and that it runs on demand via weighted label propagation. This provides useful behavioral context beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences with no redundant words. The first sentence explains what it does and how, the second describes the output, and the third gives usage context. Information is front-loaded and every part adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of community detection and lack of output schema, the description explains the algorithm, output contents, and usage context well. It could mention potential computational cost or size limits, but overall it is complete enough for an agent to decide when to use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with both parameters (limit, min_size) clearly described. The description does not add any additional semantic information about parameter usage or defaults beyond what the schema provides, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool detects communities over the entity graph via weighted label propagation and returns top entities with linked memories. It distinguishes itself from chunk-level search by providing a corpus-level view, making its purpose specific and distinct from siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly contrasts with chunk-level search and advises using it to synthesize named themes for global questions like 'what are the main themes?'. However, it does not explicitly list when not to use or mention specific sibling alternatives beyond the implicit contrast.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Apply agent-generated summaries to condense old memories. Preserves original content for later restoration. Use after consolidation reports flag condensation candidates.
| Name | Required | Description | Default |
|---|---|---|---|
| memories | Yes | Batch of memories with agent-generated summaries | |
| target_level | No | Target condensation level | summary |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds important behavioral detail: 'Preserves original content for later restoration.' This goes beyond the minimal annotations (only title and openWorldHint=false) by clarifying the non-destructive nature of the operation. It also mentions that it is for old memories and after consolidation reports, providing context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no wasted words. The first sentence clearly states the primary action, and the second adds important context. It is front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 2 well-documented parameters and no output schema, the description covers the core purpose, usage trigger, and a key behavioral aspect (preservation). It is sufficiently complete for an agent to understand when and how to use it, though it omits potential return values or error states.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage, with detailed descriptions for all parameters including the batch structure and target_level enum. The tool description does not add significant new meaning beyond summarizing what the schema already states, so a baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly indicates the tool applies agent-generated summaries to condense old memories, with the specific verb 'condense' and resource 'old memories'. It also distinguishes itself by noting it preserves original content for later restoration, setting it apart from destructive operations like memory_delete.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance: 'Use after consolidation reports flag condensation candidates.' This clearly indicates when to use the tool. However, it does not explicitly list alternatives or when not to use it, though the context implies it is for condensing rather than other operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run the "dream cycle": find and merge near-duplicate memories, prune expired/low-quality entries, and update quality scores based on access patterns. Use dry_run=true to preview changes.
| Name | Required | Description | Default |
|---|---|---|---|
| scope | No | Memory scope for isolation | |
| namespace | No | Namespace within scope (e.g., project name, team name) | |
| similarity_threshold | No | Cosine similarity threshold for duplicate detection (0.5-1.0) | |
| prune_expired | No | Remove memories past their expires_at date | |
| prune_low_quality | No | Remove memories with both low importance and low confidence | |
| dry_run | No | If true, report what would be done without making changes | |
| max_operations | No | Maximum number of merge/prune operations per run | |
| forgetting_floor | No | Opt-in spaced-repetition prune. When set (0-1), remove weakly-held memories whose retention e^(-Δt/stability) has decayed below this floor. Omit to disable. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that the tool modifies memory by merging, pruning, and updating scores, implying destructive potential. However, it lacks detail on side effects like irreversible deletion or impact on related data. The dry_run hint partially compensates.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: two sentences that front-load the core purpose and end with a key usage tip. Every sentence is meaningful, with no redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description adequately explains what the tool does and hints at preview via dry_run, but it does not describe the output format (e.g., report structure, returned data). Given no output schema and 8 parameters, more detail on return values would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All 8 parameters are fully described in the schema (100% coverage), so the description adds limited value beyond a usage hint for dry_run. The description does not explain parameter interactions or complex constraints, meeting the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it runs a 'dream cycle' to merge near-duplicates, prune expired/low-quality entries, and update quality scores. The verb 'consolidate' matches the purpose, and it distinguishes from sibling tools like memory_condense or memory_forget that focus on single aspects.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description notes using dry_run=true to preview changes, which provides usage direction, but does not explicitly state when to use this tool over alternatives like memory_condense or memory_forget, nor does it specify when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete memories by ID or by filter criteria (scope, department, before_date, expired_only). Provide at least one of id or filter.
| Name | Required | Description | Default |
|---|---|---|---|
| id | No | Delete a specific memory by ID | |
| filter | No | Delete memories matching filter criteria |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint=true. The description adds that it deletes by ID or filter, which is minimal beyond what annotations convey. No additional behavioral traits like irreversibility or authorization needs are disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One sentence of 15 words, front-loaded with verb and object. Every word is necessary; no waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of the nested filter object and the destructive nature, the description is too minimal. Missing details on what happens when both id and filter are provided, behavior on no matches, or return value. Output schema is absent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents parameters. The description merely lists filter criteria already present in the schema, adding no extra meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Delete memories' and specifies two modes: by ID or by filter criteria. However, it does not differentiate from sibling tool 'memory_forget', which may also delete memories, reducing clarity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a constraint ('Provide at least one of id or filter') but lacks explicit guidance on when to use this tool versus alternatives like memory_forget, prerequisites, or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Adaptive per-user expertise profile. action=observe records demonstrated knowledge of a topic (level rises on a saturating curve, never collapses other topics); action=get returns the profile. The agent supplies the classified topic — the server just tracks evidence over time.
| Name | Required | Description | Default |
|---|---|---|---|
| action | No | observe demonstrated knowledge of a topic | get the profile | get |
| topic | No | The topic (required for observe; optional filter for get). | |
| scope | No | Scope (default 'user'). | |
| namespace | No | Namespace within scope (e.g., project name, team name) | |
| weight | No | Evidence increment for observe (default 1). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses key behavioral traits: a saturating curve for level increases, no collapsing of other topics, and the role of the agent in providing classified topics. This goes beyond the minimal annotations, which only set openWorldHint=false. It lacks details on auth or rate limits but is sufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the core purpose, and no superfluous text. Every sentence contributes to understanding the tool's function and behavior.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description explains the core mechanism and actions well, but it does not describe the output format of the profile (no output schema). With 5 parameters and no output schema, a brief mention of what 'get' returns would improve completeness. Still, it covers essential aspects.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already describes all parameters. The tool description adds some context for action semantics but does not provide meaning significantly beyond the schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool is an adaptive per-user expertise profile with two actions: observe (record demonstrated knowledge) and get (return profile). It uses specific verbs and resource, and the focus on per-user expertise distinguishes it from sibling memory tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not provide when to use this tool versus alternatives. It explains the actions but offers no guidance on when not to use or comparisons to other memory tools. The agent is left to infer usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Export memories as JSON for backup or migration. Supports filtering by scope, namespace, and department. Max 1000 records per export.
| Name | Required | Description | Default |
|---|---|---|---|
| scope | No | Memory scope for isolation | |
| namespace | No | Namespace within scope (e.g., project name, team name) | |
| department | No | Department (e.g., legal, engineering, hr, sales, finance) | |
| limit | No | Maximum memories to export in this page (live, top-level only) | |
| offset | No | Pagination offset; use with has_more to export a large corpus in pages |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description contradicts the explicit limit parameter definition in the input schema: the description states 'Max 1000 records per export' while the schema defines default=1000 and maximum=10000. This inaccuracy could mislead an agent about the tool's capacity. Annotations correctly mark it as read-only, but the description adds conflicting information.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence covering purpose, filtering, and a constraint. It wastes no words, though the limit inaccuracy detracts slightly from its effectiveness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the output format (JSON) and basic filtering, but fails to mention pagination (offset/has_more) which is available in the schema, and does not describe the response structure or differentiate from similar export siblings. Given no output schema, more detail on return values would be beneficial.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Since schema description coverage is 100%, the baseline is 3. The description adds little beyond restating the filter parameters (scope, namespace, department) and introduces a potentially misleading limit of 1000, which is already expressed more precisely in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it exports memories as JSON for backup or migration, specifying the output format and high-level use case. However, it does not distinguish itself from sibling tools like memory_export_dataset or memory_export_vault, missing an opportunity to clarify unique scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions filtering by scope, namespace, and department, giving context on when to use it. However, it fails to provide guidance on when not to use it or alternatives, and the mention of 'Max 1000 records per export' is an oversimplification given the schema allows up to 10000.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Export high-signal rows (auto-extracted learnings + agent reflections) as instruction→output training pairs (pairs/chatml/alpaca) for a project LoRA/distillation flywheel. Read-only, quality-filtered by importance/confidence. Training stays out of the repo — this only emits the JSONL.
| Name | Required | Description | Default |
|---|---|---|---|
| scope | No | Memory scope for isolation | |
| namespace | No | Namespace within scope (e.g., project name, team name) | |
| format | No | Output shape: {prompt,completion} | ChatML messages | Alpaca instruction/output. | pairs |
| min_importance | No | Quality floor on importance_score. | |
| min_confidence | No | Quality floor on confidence_score. | |
| limit | No | Max training pairs to emit. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide readOnlyHint=true and no destructive hint. Description adds that it is read-only, quality-filtered by importance/confidence, and emits JSONL without modifying state. This adds value beyond annotations, though could mention pagination or behavior on empty results.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no wasted words. First sentence states core purpose and output shape, second clarifies safety and output file format. Highly concise and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only export tool with 6 parameters and no output schema, the description covers purpose, filters, output format, and safety. It doesn't detail output field structure or edge cases, but is sufficient for an agent to invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with clear descriptions. The description reinforces the meaning of min_importance/min_confidence and format, but does not add new information beyond the schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('export'), resource ('high-signal rows...as instruction→output training pairs'), and differentiates from siblings by focusing on training data generation for LoRA/distillation. It clearly identifies the tool's intent.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use (generating training data) and contrasts with the generic 'memory_export' sibling, but lacks explicit when-not-to-use guidance or alternative recommendations. Usage context is clear but not exhaustive.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Write memories OUT to an Obsidian vault as .md files with YAML frontmatter — the reverse of vault_sync. Each currently-valid top-level memory becomes a plain markdown file a human can open and edit; namespaced memories land under //. Lossless: written files parse back via the vault parser. Optionally filter by scope/namespace.
| Name | Required | Description | Default |
|---|---|---|---|
| vault_path | Yes | Absolute path to the target Obsidian vault directory (created if missing). Memories are written as .md files with YAML frontmatter — the reverse of vault_sync. | |
| scope | No | Memory scope for isolation | |
| namespace | No | Namespace within scope (e.g., project name, team name) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explains the write behavior: it creates .md files per memory, handles namespaced memories under subdirectories, and claims losslessness. It also notes the vault_path directory is created if missing. It lacks explicit mention of overwrite behavior if files already exist, but overall provides good behavioral context beyond the minimal annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is only three sentences, front-loaded with the core purpose in the first sentence. Every sentence adds value: purpose, structural detail, and filtering option. No redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the parameter count and schema coverage, the description is adequate but lacks completeness in differentiating from similar export siblings (e.g., memory_export). It does not explain return behavior or error handling, and the absence of an output schema shifts burden to the description, which it partially meets.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage of parameter descriptions, so the description adds little extra meaning. The vault_path description reiterates the purpose, and scope/namespace are described for filtering. No additional semantic enrichment beyond the schema is provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'write', resource 'memories to Obsidian vault', and specifies the output format (.md with YAML frontmatter). It distinguishes itself from vault_sync by calling itself 'the reverse', providing clear purpose and differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions it's the reverse of vault_sync and optional filtering by scope/namespace, which hints at when to use it. However, it does not explicitly state when not to use it or compare it to other sibling export tools like memory_export or memory_export_dataset, leaving ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Store LLM-extracted entities and relationships for a memory. The calling agent should analyze memory content and provide structured entity/relationship data. This enables knowledge graph queries.
| Name | Required | Description | Default |
|---|---|---|---|
| memory_id | Yes | Memory ID to associate extracted entities with | |
| entities | Yes | Entities extracted from the memory content | |
| relationships | No | Relationships between entities |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations (only openWorldHint, not behavioral), the description carries full burden. It only says 'Store... for a memory,' which indicates a write operation but reveals no side effects (e.g., overwriting existing entities, permissions required, or any destructive behavior). For a mutation tool, this is insufficient transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: two sentences, front-loaded with the core action. Every word adds value, with no redundancy. The structure is clear and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has a complex nested input schema, many sibling tools, and no output schema, the description is too minimal. It lacks context on prerequisites (e.g., memory existence), return values, how the tool fits into the larger system of memory tools, and what happens if relationships are omitted. The sentence about knowledge graph queries hints at purpose but doesn't compensate for the missing completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so each parameter is well-described in the schema itself. The description adds no additional semantics beyond what the schema provides (e.g., no explanation of how memory_id must be valid, or behavior on duplicate entities). Baseline score of 3 is appropriate as the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'Store LLM-extracted entities and relationships for a memory.' It specifies what the tool does (store structured entity/relationship data) and its benefit (enables knowledge graph queries). However, it does not explicitly distinguish this from siblings like 'memory_extract_learnings' or 'memory_store', which also deal with extraction or storage, missing an opportunity for differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides some guidance: 'The calling agent should analyze memory content and provide structured entity/relationship data.' This implies the tool is for storing extracted data after analysis. However, it does not state when to use this tool versus alternatives (e.g., memory_store for raw text, or memory_extract_learnings for patterns), nor does it mention prerequisites like the memory needing to exist or not.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Extract decisions, patterns, error fixes, and conventions from a session transcript using heuristic analysis. Deduplicates against existing memories and optionally auto-stores.
| Name | Required | Description | Default |
|---|---|---|---|
| transcript | Yes | Session transcript or conversation text to extract learnings from | |
| scope | No | Memory scope for isolation | global |
| namespace | No | Namespace within scope (e.g., project name, team name) | |
| department | No | Department (e.g., legal, engineering, hr, sales, finance) | |
| tags | No | Tags for categorization | |
| source | No | Source identifier for the session (e.g., "session-2026-03-26") | |
| categories | No | Which categories of learnings to extract (default: all) | |
| auto_store | No | If true, automatically store extracted learnings as memories |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses key behaviors: heuristic analysis, deduplication against existing memories, and optional auto-store. Since annotations only provide openWorldHint, this adds significant behavioral context beyond what annotations offer.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that efficiently conveys the core functionality and key features, with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 8 parameters and no output schema, the description covers the main action but does not explain what is returned (e.g., whether extracted learnings are returned or only stored). It adequately describes the process but leaves some ambiguity about output.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema descriptions cover 100% of parameters with clear definitions. The tool description provides overall context but does not add additional meaning beyond the schema details, meeting the baseline for high coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool extracts decisions, patterns, error fixes, and conventions from a session transcript using heuristic analysis. It also mentions deduplication and optional auto-store, distinguishing it from siblings like memory_extract_entities or memory_ingest.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for extracting learnings from transcripts but does not explicitly state when to use this tool over alternatives, nor does it provide exclusionary guidance. It is adequate but lacks context for tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
GDPR-grade forget (additive — does NOT replace memory_delete). hard:false (default) soft-deletes/tombstones: stamps valid_to so the memory is excluded from default retrieval but stays queryable via as_of and is recoverable. hard:true erases for real: returns a portability "export" copy FIRST (data-subject access), THEN permanently deletes (irreversible, cascades). Returns { forgotten, mode, recoverable, export? }.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Memory ID to forget | |
| hard | No | Erasure mode. false (default): soft-delete/tombstone — stamps valid_to so the memory is excluded from default retrieval but remains queryable via as_of and is recoverable. true: hard erase — returns a portability export copy FIRST (data-subject access), THEN permanently deletes (irreversible, cascades). Additive — the existing memory_delete tool is unaffected. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint=true, but the description adds substantial behavioral details: for hard:true it returns a portability copy before permanent deletion, irreversible and cascading; for hard:false it is recoverable and stamps valid_to. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is moderately concise; each sentence contributes useful information. It is front-loaded with general purpose then explains modes. A slight reduction in length could improve conciseness, but overall it is well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has two modes (soft/hard), no output schema, and requires understanding of recovery and portability, the description covers all aspects: return object shape, behavior differences, and GDPR compliance. It is complete for an agent to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% so baseline is 3, but the description adds significant meaning beyond schema: it explains the effect of each mode in detail (e.g., soft-delete stamps valid_to, hard erases after export), which enhances agent understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it is a 'GDPR-grade forget' operation that is additive to memory_delete. It specifies verb 'forget' on resource 'memory', and distinguishes itself from memory_delete by noting it does NOT replace it.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly explains when to use soft vs hard delete modes and mentions GDPR context. It implies this tool is for data subject access/erasure, while memory_delete is for regular deletion. However, it does not explicitly state when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve a specific memory by its ID. Optionally include child chunks for ingested documents.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Memory ID to retrieve | |
| include_chunks | No | If true, also return child chunks for ingested documents |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so safety is known. Description adds the behavioral detail about including child chunks, but does not disclose other traits like return structure or pagination.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the core action, no wasted words. Efficient and clear.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of the tool (2 params, no output schema, full annotations), the description is mostly complete. However, it could mention what the return value is (the memory object) to be fully self-contained.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and both parameters have descriptions. The description adds minimal additional meaning beyond the schema field descriptions for 'id' and 'include_chunks'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description uses specific verb 'Retrieve' and identifies the resource ('specific memory by its ID'). Clearly distinguishes from sibling tools like memory_search, memory_delete, etc. Optional include_chunks adds further clarity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied: use when you need to fetch a memory by its exact ID. No explicit alternatives or exclusions provided, but the context of the tool name and siblings makes it reasonably clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Query the knowledge graph: find entities, their relationships, and linked memories. Use entity name to start traversal, or browse all entities by type. Supports multi-hop traversal (depth 1-3).
| Name | Required | Description | Default |
|---|---|---|---|
| entity | No | Entity name to start graph traversal from | |
| entity_type | No | Filter entities by type | |
| depth | No | Graph traversal depth (1-3 hops) | |
| include_memories | No | Include linked memories in the response | |
| limit | No | Maximum entities to return |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the description's addition of traversal depth and entity browsing provides useful context. However, it does not describe failure behavior (e.g., entity not found) or pagination beyond the limit parameter. With annotations carrying the read-only signal, the description adds modest behavioral detail.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise: two sentences, front-loaded with the primary purpose. No redundant phrases. Slightly more structure could help, but it is efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the essential functionality but lacks details about the response format (e.g., how relationships and memories are structured). With no output schema, additional context about return fields would improve completeness. Adequate for basic understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the description adds marginal value beyond schema descriptions. It clarifies the role of entity and entity_type (start traversal vs. browse by type) and restates depth range. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool queries the knowledge graph to find entities, relationships, and linked memories. It specifies starting with an entity name or browsing by type, and supports multi-hop traversal. This sets it apart from sibling tools that focus on CRUD or other specific operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for graph traversal queries but does not explicitly state when to use this tool versus alternatives like memory_search or memory_get. No when-not-to-use or exclusion criteria are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Store health report: live/retired/stale counts, aging buckets, unresolved conflicts, and webhook delivery health, rolled up to a single ok|attention status with reasons. Read-only; optionally scoped.
| Name | Required | Description | Default |
|---|---|---|---|
| scope | No | Memory scope for isolation | |
| namespace | No | Namespace within scope (e.g., project name, team name) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the read-only nature is clear. The description adds that the output is a rolled-up status with reasons, but does not disclose additional behavioral traits like authentication needs, rate limits, or side effects. Context is adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that front-loads the core purpose and lists key components clearly. No wasted words or redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no output schema, the description effectively conveys the return value (counts, buckets, conflicts, webhook health, status with reasons). It covers the essential aspects for a simple tool with two optional parameters. Minor gap: does not explain the 'reasons' in detail, but still sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 100% description coverage for both parameters (scope and namespace), so the description adds minimal new meaning: it hints at optional scoping but does not elaborate beyond schema. Baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it is a health report for memory, listing specific metrics (live/retired/stale counts, aging buckets, unresolved conflicts, webhook delivery health) and notes it rolls up to a status. This distinguishes it from sibling tools like memory_stats, which is more general.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives. With many sibling tools, such as memory_stats or memory_insights, the description does not provide context for when this tool is preferred or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Point-in-time history surface for one memory: its current bi-temporal timeline (created_at/updated_at/valid_from/valid_to/tx_expired/superseded_at/version) plus the full memory_versions edit history. Returns { memory_id, exists, timeline, versions } or { memory_id, exists:false }.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Memory ID to get the bi-temporal timeline + version history for |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, and the description adds transparency about the return format (two possible shapes) and lists the timeline fields. No contradictions; the description enriches the behavioral understanding beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that front-loads the tool's purpose and efficiently lists key details and return types without any fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter, no output schema), the description fully covers the needed context: what it does, what it returns, and how it differs from similar tools. No gaps are apparent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 100% description coverage for the single parameter, and the tool description reiterates the parameter's purpose. While clear, the description adds minimal new meaning beyond the schema's param description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns a bi-temporal timeline and version history for a memory, using specific verbs like 'returns' and listing the fields. It distinguishes from siblings like memory_get and memory_versions by focusing on the combined timeline and history.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage context is implied by the description (detailed history retrieval), but there is no explicit guidance on when to use this tool over alternatives like memory_get or memory_versions, nor when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Import memories from JSON. Each item is embedded and stored. Use overwrite=true to update existing memories by ID.
| Name | Required | Description | Default |
|---|---|---|---|
| data | Yes | Array of memory objects to import (max 500 per batch) | |
| overwrite | No | If true, overwrite existing memories with same ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate destructiveHint=true, which aligns with the overwrite behavior mentioned. However, the description does not explain behavior when overwrite=false and an ID already exists (likely error), nor does it mention the batch size limit of 500 max items noted in the schema. It also omits return value or error handling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences that front-load the primary action ('Import memories from JSON') and add key context about overwrite. No extraneous words or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has many optional fields in the data object, but the schema covers them. The description does not mention output, error scenarios, or the batch limit of 500 items. Given the complexity and number of siblings, more context would help, but the description is minimally adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% with all properties described. The description adds context about the overwrite parameter's purpose ('update existing memories by ID'), but otherwise does not significantly extend the meaning beyond what the schema already provides. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Import memories from JSON' and specifies the action of embedding and storing. It distinguishes from siblings like memory_export, memory_append, and memory_update by indicating batch import with optional overwrite.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides guidance on using overwrite=true for updating existing memories, but it does not explicitly differentiate when to use this tool versus alternatives like memory_store (single store) or memory_append (append to existing). No when-not-to-use advice is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Ingest a full document: automatically chunks it based on content type (text, markdown, code, legal), embeds each chunk, and stores with provenance. Use this for large documents.
| Name | Required | Description | Default |
|---|---|---|---|
| content | Yes | Full document content to ingest | |
| title | No | Document title | |
| source | No | Origin of the content (e.g., file path, URL, system name) | |
| document_type | No | Type of document (e.g., contract, policy, code, incident, decision) | |
| scope | No | Memory scope for isolation | global |
| namespace | No | Namespace within scope (e.g., project name, team name) | |
| department | No | Department (e.g., legal, engineering, hr, sales, finance) | |
| author | No | Who created this content | |
| access_level | No | Access classification level | |
| tags | No | Tags for categorization | |
| metadata | No | Domain-specific metadata (e.g., {contract_type: 'NDA', parties: ['A','B']}) | |
| content_type | No | Content type determines chunking strategy | text |
| chunk_size | No | Target chunk size in characters (~4 chars per token) | |
| chunk_overlap | No | Overlap between chunks in characters for context preservation |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide minimal behavioral hints (only openWorldHint=false). Description adds important details: automatic chunking by content type, embedding, and provenance storage. No contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two efficient sentences: first defines core behavior, second adds usage context. No redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers ingestion flow and usage context but omits what is returned (e.g., success confirmation, document IDs). Lacks expected output details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers all 14 parameters with descriptions (100% coverage). Description does not add parameter-specific meaning beyond what schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Specifically describes ingesting a full document with automatic chunking, embedding, and provenance storage. Clearly differentiates from sibling memory tools that handle smaller operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
States 'Use this for large documents' but does not explicitly exclude other scenarios or mention alternative tools for smaller documents. Lacks when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Active advisor digest: what in the store needs ATTENTION now — unresolved conflicts, memories flagged stale by change-propagation, most-contradicted facts, and decisions recorded with no supporting evidence. Complements memory_questions (what to capture next). Read-only; optionally scoped.
| Name | Required | Description | Default |
|---|---|---|---|
| scope | No | Memory scope for isolation | |
| namespace | No | Namespace within scope (e.g., project name, team name) | |
| limit | No | Maximum number of insights to return (default 20) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true. The description adds specific behavioral details about the types of insights returned (conflicts, stale memories, contradicted facts, unsupported decisions) and notes scoping is optional. This provides useful context beyond annotations, though it does not cover performance or rate limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with key information, and contains no fluff. Every phrase adds value: it specifies the content, notes the complementary tool, and declares read-only and scoping.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description explains the content of insights and complementarity, but does not mention the return format or structure, which is important since there is no output schema. Given the tool's complexity (read-only, optional scoping, three parameters), the description is adequate but leaves room for improvement regarding output details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage with descriptions for all parameters (scope, namespace, limit). The description only mentions 'optionally scoped,' which aligns with the scope parameter but adds no new detail about parameter usage or syntax. Baseline 3 is appropriate since the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool provides a digest of items needing attention: unresolved conflicts, stale memories, contradicted facts, and decisions without evidence. It differentiates from the sibling 'memory_questions' tool, which captures next actions, making the purpose distinct and specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly complements memory_questions, indicating when to use this tool over that alternative. It also notes that it is read-only and optionally scoped, but does not list exclusions or provide a full decision tree for when to use versus other tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Capture a structured lesson or incident in one call: fills the matching section template (incident → Symptom/Root Cause/Fix/Prevention; lesson → What/Why it matters/How to apply) from your field values and stores it through the normal write path (deduped — a repeat capture is a NOOP). Unknown document_types use a generic scaffold.
| Name | Required | Description | Default |
|---|---|---|---|
| document_type | No | Section template to fill: lesson | incident | decision | bug-fix | meeting | session. Unknown types use a generic Summary/Details/Notes scaffold. | lesson |
| fields | Yes | Section values keyed by section name (snake_case ok), e.g. {symptom, root_cause, fix, prevention} for an incident or {what, why_it_matters, how_to_apply} for a lesson. Omitted sections keep a placeholder. | |
| title | No | Optional title (auto-derived from the first field value when omitted) | |
| scope | No | Memory scope for isolation | global |
| namespace | No | Namespace within scope (e.g., project name, team name) | |
| department | No | Department (e.g., legal, engineering, hr, sales, finance) | |
| tags | No | Tags for categorization | |
| source | No | Origin of the content (e.g., file path, URL, system name) | |
| access_level | No | Access classification level | internal |
| importance_score | No | Manual importance 0–1 (higher surfaces first in reflection/recall) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses key behaviors: deduplication (repeat capture is a NOOP), template filling based on document_type, and a generic scaffold for unknown types. Annotations provide no destructiveHint or readOnlyHint, so the description carries the burden and meets it reasonably.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no wasted words. The first sentence packs purpose, template behavior, and dedup, while the second handles edge cases. Front-loaded with the most important information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 10 parameters (1 required) and no output schema, the description covers core behavior well. It explains template usage and dedup. However, it doesn't mention return values or error conditions, which could be helpful.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds value by explaining how fields map to sections and that omitted sections get a placeholder, which is beyond the parameter descriptions in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool captures a structured lesson or incident by filling a section template. It distinguishes from generic memory tools by specifying template mapping and dedup behavior, but doesn't explicitly differentiate from siblings like memory_append or memory_store.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage context is implied: use when capturing lessons or incidents with structured fields. The description notes that repeat captures are NOOP, which guides against redundant calls, but doesn't explicitly state when not to use or provide alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find BROKEN [[wikilinks]] — the inverse of memory_unlinked_mentions. Reports (1) unresolved: a [[Title]] in a memory's content that matches no LIVE memory title in the same scope/namespace; (2) dangling_edges: stored wikilink edges whose target memory was deleted or superseded. Resolution is by TITLE (memories have no slug) so write [[Exact Title]]. Pass an id to check one memory, or scope/namespace to sweep a partition. Read-only.
| Name | Required | Description | Default |
|---|---|---|---|
| id | No | Check one memory by ID. Omit to sweep a whole partition (scope/namespace). | |
| scope | No | Sweep scope (when no id is given) | |
| namespace | No | Sweep namespace (when no id is given) | |
| limit | No | Max source memories to inspect in a sweep |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description states 'Read-only' which matches the readOnlyHint=true annotation. It discloses the types of results (unresolved and dangling_edges), the resolution method by title, and the effect of scope/namespace sweeping. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (two sentences), front-loaded with the core purpose, and every sentence adds essential detail. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema, the description fully explains what the tool reports (two types of broken links) and how to use it with single or batch modes. It covers all necessary context for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with clear parameter descriptions. The description adds value by explaining usage context: 'Pass an id to check one memory, or scope/namespace to sweep a partition' and the title resolution rule, which is not in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it finds broken [[wikilinks]] and specifies two detailed types (unresolved, dangling_edges). It explicitly distinguishes itself from memory_unlinked_mentions as the 'inverse', making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit when-to-use: 'Find BROKEN [[wikilinks]]' and gives two usage patterns (by id or by scope/namespace). It also mentions the alternative 'memory_unlinked_mentions' for the inverse case, offering clear guidance on when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Browse memories with filtering and pagination. Supports sorting by creation date, update date, or title.
| Name | Required | Description | Default |
|---|---|---|---|
| scope | No | Memory scope for isolation | |
| namespace | No | Namespace within scope (e.g., project name, team name) | |
| department | No | Department (e.g., legal, engineering, hr, sales, finance) | |
| document_type | No | Type of document (e.g., contract, policy, code, incident, decision) | |
| limit | No | Maximum results to return | |
| offset | No | Skip this many results for pagination | |
| sort_by | No | Field to sort results by | created_at |
| sort_order | No | Sort direction | desc |
| as_of | No | ISO 8601 point-in-time: return memories that were valid at this instant (bi-temporal). Defaults to currently-valid memories when omitted. Must be a full ISO-8601 timestamp (date + time + zone); a date-only or non-padded value is rejected to avoid a silently-wrong lexicographic slice. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, indicating safe read-only behavior. The description's 'Browse' aligns with this. However, the description does not add further behavioral context beyond what annotations provide, such as potential performance implications or the bi-temporal nature of the 'as_of' parameter. The openWorldHint=false is not explained. Since the description does not contradict annotations, a score of 3 is appropriate (baseline, no added value).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded, and every word adds value. It efficiently conveys core functionality. However, it could be slightly expanded to mention the bi-temporal or pagination behavior without losing conciseness. Still, it is well-structured and avoids fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 9 parameters, no output schema, and the complexity of bi-temporal filtering, the description is incomplete. It does not explain the return format (e.g., list of memory objects with fields), nor the effect of 'as_of' on results. For a tool of this complexity, the description should provide more context to aid correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage with descriptions for all 9 parameters. The description's mention of 'filtering and pagination' adds no detail beyond the schema. For example, 'as_of' is a complex parameter but the schema already explains it. Baseline 3 is correct since the schema does the work.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Browse memories with filtering and pagination.' It specifies supported sorting fields and implies list retrieval, which distinguishes it from sibling tools like memory_get (single retrieval) and memory_search (likely full-text search). The verb 'browse' and resource 'memories' are specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for browsing and filtering memories but provides no explicit guidance on when to use this tool versus alternatives. It does not mention exclusions or when not to use it. Among 52 sibling tools, there are many memory listing/search tools, so explicit differentiation would be helpful. Without such guidance, the description is adequate but not exemplary.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a lightweight index of all memories — titles, types, tags, and scores without content. Use this to discover what knowledge exists before running expensive searches.
| Name | Required | Description | Default |
|---|---|---|---|
| scope | No | Memory scope for isolation | |
| namespace | No | Namespace within scope (e.g., project name, team name) | |
| department | No | Department (e.g., legal, engineering, hr, sales, finance) | |
| document_type | No | Type of document (e.g., contract, policy, code, incident, decision) | |
| limit | No | Maximum entries to return (default 500) | |
| offset | No | Skip this many entries for pagination |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true; description adds that no content is returned, reinforcing non-destructive behavior. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with purpose and usage guidance. No extraneous information, highly concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Description lacks details on return structure, pagination behavior, and how parameters like scope/namespace interact. Given 6 parameters and no output schema, more completeness is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so description adds little beyond schema. Baseline 3 is appropriate as it provides overall context but no parameter-level details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Get a lightweight index of all memories' with specifics (titles, types, tags, scores) and contrasts with expensive searches, distinguishing it from siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly recommends using this tool before expensive searches, providing clear context. However, it does not explicitly mention when not to use or list alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Answer a question with a TIGHT, relevant subgraph instead of flooding context. Seeds from hybrid search, walks the memory graph (hub-avoiding) up to max_hops, and returns a token-budgeted "context" string plus structured nodes — with an actionable hint when truncated.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | The question to answer. Seeds from hybrid search, then walks the memory graph to return a tight, relevant subgraph instead of flooding context. | |
| max_tokens | No | Approximate token budget for the rendered context (~4 chars per token). Nodes are rendered until the budget is hit, then truncated with a hint. | |
| max_hops | No | How many hops to walk out from the seed memories (1-4). | |
| seed_limit | No | Maximum seed memories from the initial search. A gap cutoff drops seeds scoring below 20% of the top seed to keep the traversal focused. | |
| scope | No | Memory scope for isolation | |
| namespace | No | Namespace within scope (e.g., project name, team name) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark the tool as read-only (readOnlyHint: true). The description adds substantial behavioral context: hybrid search seeding, hub-avoiding graph walk, token budget, truncation with actionable hint. No contradiction observed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, dense sentence that packs all key information: purpose, mechanism, and return format. No wasted words, front-loaded with the core verb. Every phrase earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (graph walk, token budget, truncation) and absence of output schema, the description covers the main aspects: seeds from hybrid search, hub avoidance, max_hops, token budget, and return of 'context string plus structured nodes' with truncation hint. Slightly vague on the exact structure of nodes, but overall sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already explains each parameter thoroughly. The description only briefly mentions max_hops and token-budgeted, adding little extra meaning beyond the schema's existing descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool answers a question with a tight, relevant subgraph from memory, explicitly distinguishing it from flood-fetch alternatives. It mentions hybrid search, graph walking, and token budgeting, which differentiates it from siblings like memory_query_structured or simple memory_search.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for concise memory queries but does not explicitly state when to use this tool over alternatives like memory_query_structured or when not to use it. No exclusions or comparisons to siblings are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Structured query over memory PROPERTIES (the agent's "Bases/Dataview"): filter currently-valid, top-level memories by scope/namespace/department/document_type/language/tags (AND)/min_importance/created_at range, sort by created_at|updated_at|importance_score|title, paginate, and project specific fields. Exact, deterministic retrieval that complements fuzzy memory_search — use it for "all decision memories in namespace=acme with importance>0.7, newest first".
| Name | Required | Description | Default |
|---|---|---|---|
| filter | No | ||
| sort | No | ||
| limit | No | ||
| offset | No | ||
| fields | No | Return only these fields (projection) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the bar is lower. The description adds useful behavioral context: it operates on 'currently-valid, top-level memories', is 'exact, deterministic', and lists filtering criteria. It does not contradict annotations and provides additional transparency about the tool's scope and nature.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no wasted words. The first sentence is comprehensive but well-structured, and the second provides usage guidance. It front-loads the purpose and uses clear, direct language.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (5 parameters, nested objects, no output schema), the description covers the main capabilities well. It explains filtering, sorting, pagination, and field projection. It does not describe the return format, but that is partially mitigated by the schema's lack of output schema. Overall, it is sufficiently complete for an agent to understand and use the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is low (20%), but the description compensates by listing the filter criteria (scope, namespace, department, document_type, language, tags with AND, min_importance, created_at range) and sort options (created_at, updated_at, importance_score, title). It also mentions pagination and projection. The description adds significant meaning beyond the schema's minimal descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it's a structured query over memory properties, listing specific operations (filter, sort, paginate, project) and distinguishing from fuzzy memory_search. It uses specific verbs and resources, and the distinction from siblings is explicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance: 'Exact, deterministic retrieval that complements fuzzy memory_search' and gives a concrete example ('all decision memories in namespace=acme with importance>0.7, newest first'). It clearly tells when to use this tool versus the sibling 'memory_search'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Active "questions to ask" digest. Surfaces open questions / gaps the graph is uniquely positioned to find so you know what to verify or learn next: AMBIGUOUS inferred links to confirm (verify), frequently-mentioned but barely-documented entities (gap), and disconnected memories that may be stale or mis-scoped (orphan). Returns { questions: [{ question, type, evidence }], count } over currently-valid top-level memories. Optional scope/namespace filters and limit (default 20).
| Name | Required | Description | Default |
|---|---|---|---|
| scope | No | Memory scope for isolation | |
| namespace | No | Namespace within scope (e.g., project name, team name) | |
| limit | No | Maximum number of questions to return (default 20) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=true, but the description adds behavioral context: it operates over 'currently-valid top-level memories', returns structured questions with evidence, and supports optional filters. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense and front-loaded with the core purpose. It earns each sentence by explaining what the tool returns and the types of questions. Could be slightly more structured, but it is efficient and clear.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no output schema, the description fully explains the return format ({ questions: [{ question, type, evidence }], count }) and mentions the optional scope/namespace filters and limit. It is complete for safe, effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so parameter descriptions already exist. The description restates the optional filters and default limit, which adds marginal value beyond the schema. No additional syntax or format details are provided beyond what the schema covers.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool surfaces open questions and gaps (ambiguous links, gaps, orphans) from the memory graph, using specific verbs like 'surfaces' and 'digest'. It distinguishes from sibling tools by its unique output format and purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for verification and learning ('so you know what to verify or learn next') but does not explicitly contrast with other analytical tools like memory_insights or memory_search. No when-not-to-use or alternative guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generative-Agents-style reflection (agent-driven, no LLM in the server). mode:"gather" (default) returns the most reflection-worthy memories (high importance × recent) as material plus an instruction to synthesize 1–3 higher-level insights. mode:"store" persists a synthesized insight (provenance="reflection") and "derived_from"-links it to its source memories.
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | "gather" (default): the server SELECTs the most reflection-worthy memories (high importance × recent) as material for you to synthesize. "store": persist a synthesized insight back, linked to its source memories. | gather |
| scope | No | Memory scope for isolation | |
| namespace | No | Namespace within scope (e.g., project name, team name) | |
| limit | No | gather: max reflection-material rows to return (default 10) | |
| insight | No | store: the higher-level insight you synthesized from the gathered material | |
| title | No | store: optional short title for the stored insight | |
| source_ids | No | store: ids of the source memories this insight was derived from (linked via "derived_from"; non-existent ids are skipped) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds significant behavioral context beyond the minimal annotations (only openWorldHint). It discloses the selection criteria (high importance × recent), the linking mechanism ('derived_from'), and the provenance marking, which are critical for understanding the tool's operation. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that front-loads the key concept and efficiently covers both modes. It is concise with no fluff, though the dense structure could be slightly improved for readability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the 7 parameters (0 required), full schema coverage, and no output schema, the description provides adequate context for the core functionality. It covers the selection algorithm, storage mechanics, and linking. It lacks details about error handling or edge cases, but for this complexity level, it is sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although schema coverage is 100%, the description enhances understanding by explaining the role of each mode and how parameters like 'mode', 'insight', and 'source_ids' interact. It clarifies the 'gather' output (material + instruction) and 'store' behavior (persist with provenance). This adds value beyond the basic schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly defines the tool as a 'Generative-Agents-style reflection' with two distinct modes ('gather' and 'store'). It specifies the resource (memories) and action (reflection), effectively distinguishing it from sibling tools like memory_condense or memory_insights by emphasizing its agent-driven, no-LLM-in-server approach.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use each mode: 'gather' for retrieving reflection-worthy material and 'store' for persisting synthesized insights. While it doesn't explicitly state when not to use this tool or mention alternatives, the context is clear and the dual-mode design provides direct usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Bring a memory back: un-tombstones a soft-forgotten memory (memory_forget {hard:false}) by clearing valid_to/tx_expired so it re-enters default recall, AND/OR restores a condensed memory to its original full content. Both are applied when both apply. Returns reinstated/uncondensed flags.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Memory ID to bring back — un-tombstones a soft-forgotten memory and/or restores condensed content to original full text |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description reveals that the tool clears valid_to/tx_expired and restores content, and returns flags. It does not mention any destructive side effects, reversibility, or authorization requirements. With no annotations beyond title, the description provides moderate behavioral context but lacks depth.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (three sentences), front-loaded with 'Bring a memory back', and structured to explain two operations clearly. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description explains the tool's behavior and return flags, compensating for the lack of output schema. It addresses the two main use cases but could clarify whether the id must belong to a currently soft-forgotten or condensed memory.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description restates the schema's parameter description without adding new meaning. The schema already covers the parameter purpose adequately, so the description offers no additional semantic value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool restores a memory, specifying two distinct actions: un-tombstoning a soft-forgotten memory and/or restoring condensed content. It uses specific verbs and distinguishes from siblings like memory_forget and memory_condense.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use the tool (on soft-forgotten or condensed memories) and implies it is the inverse of memory_forget with hard:false and memory_condense. However, it does not explicitly exclude other states or provide alternative tool names for different scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Change-propagation surface. action=list: memories flagged needs_revalidation (a source they were derived from changed). action=preview: the blast radius of a change to id (which dependents WOULD be flagged) without mutating anything. action=confirm: clear id's stale flag after re-verifying it.
| Name | Required | Description | Default |
|---|---|---|---|
| action | No | list stale memories | preview the blast radius of a change to `id` (dry-run) | confirm `id` is current | list |
| id | No | Memory id (required for preview/confirm). | |
| scope | No | Memory scope for isolation | |
| namespace | No | Namespace within scope (e.g., project name, team name) | |
| limit | No | Max stale memories to list. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no readOnlyHint or destructiveHint annotations, the description takes responsibility. It clearly states that preview is non-mutating and confirm clears the stale flag (mutation). However, it does not disclose potential side effects, permissions, or rate limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise (3 sentences), front-loaded with 'Change-propagation surface', and uses structured listings for each action. No superfluous words; every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (3 actions, 5 parameters, no output schema), the description covers core purpose and action behaviors. However, it lacks details on return format, scope/namespace effects, and fails to specify how results from 'list' are structured.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already describes each parameter well (e.g., action enum values). The tool description adds narrative context but does not significantly enhance parameter understanding beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly defines the tool as a change-propagation surface with three distinct actions (list, preview, confirm), each with a specific verb and resource. It differentiates from siblings like memory_list by focusing on flagged memories needing revalidation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage contexts (e.g., list to see stale memories, preview to check impact, confirm to clear), but lacks explicit guidance on when to use this tool vs alternatives like memory_list or memory_verify. No when-not-to-use advice.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search memories using hybrid vector+keyword search. Finds semantically similar content and exact keyword matches, with optional filters for scope, department, tags, date range, and temporal decay.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Search query — supports natural language for semantic search and keywords for exact matching | |
| scope | No | Memory scope for isolation | |
| namespace | No | Namespace within scope (e.g., project name, team name) | |
| department | No | Department (e.g., legal, engineering, hr, sales, finance) | |
| document_type | No | Type of document (e.g., contract, policy, code, incident, decision) | |
| access_level | No | Access classification level | |
| language | No | Content language (ISO 639-1 code) | |
| tags | No | Filter to memories containing ALL specified tags | |
| limit | No | Maximum results to return | |
| offset | No | Skip this many results for pagination | |
| search_mode | No | Search mode: hybrid (vector+keyword), vector only, or keyword only | hybrid |
| temporal_decay | No | Apply time-based decay to favor recent memories | |
| auto_decay | No | When true and no explicit temporal_decay is given, derive decay per result from its volatility class (volatile facts decay fast, stable facts not at all). Down-ranks stale volatile facts without hand-tuning a half-life. | |
| date_from | No | Filter: only memories created at/after this full ISO-8601 timestamp (e.g. 2026-03-01T00:00:00Z) | |
| date_to | No | Filter: only memories created at/before this full ISO-8601 timestamp (e.g. 2026-03-31T23:59:59Z) | |
| min_confidence | No | Minimum confidence score threshold (0-1) | |
| min_groundedness | No | Minimum TRUST threshold (0-1), distinct from min_confidence (relevance). Drops results whose groundedness — stored confidence_score + provenance tier + recency — is below this. Use to demand well-sourced memories. | |
| as_of | No | ISO 8601 point-in-time: return memories that were valid at this instant (bi-temporal). Defaults to currently-valid memories when omitted. Must be a full ISO-8601 timestamp (date + time + zone); a date-only or non-padded value is rejected to avoid a silently-wrong lexicographic slice. | |
| use_graph | No | Enable HippoRAG multi-hop recall: seed the entity graph from the query and fuse Personalized PageRank as a third ranker, surfacing memories connected through entities (associative recall) that pure vector+keyword search misses. Default false. | |
| rerank | No | Enable local cross-encoder reranking: reorder the top candidates by joint (query, document) relevance using a cross-encoder model — the biggest precision win over the bi-encoder base embedder. Slower (runs a model per candidate) and lazy-loads the model on first use. Defaults ON at the MCP server (precision matters more than latency for agent recall); pass false to skip. Left unset, programmatic callers do not rerank. | |
| rerank_top_n | No | How many top candidates to rerank when "rerank" is true (default 50). Higher = better recall coverage but slower. | |
| detail_level | No | Controls response detail: "summary" returns titles + snippets (default, saves tokens), "full" returns complete content, "ids_only" returns just IDs and titles for browsing | summary |
| max_tokens | No | Approximate maximum response size in tokens (~4 chars per token). Results are truncated to fit within budget. Applies after detail_level projection. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=true, which is respected. The description adds behavioral context beyond annotations by mentioning hybrid vector+keyword search, optional filters, and temporal decay. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (2 sentences, ~30 words), front-loaded with the core functionality, and avoids unnecessary details. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (23 parameters, nested objects) and rich schema coverage, the description provides a good high-level summary. It covers key features but could briefly mention reranking or auto_decay. However, schema handles most details, so completeness is adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema provides 100% description coverage for all 23 parameters. The description adds a high-level overview but does not significantly enhance understanding beyond what the schema already offers. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool searches memories using hybrid vector+keyword search and lists optional filters. It distinguishes the action and resource well, but does not explicitly differentiate from sibling tools like memory_query or memory_get.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. There is no mention of prerequisites, exclusions, or comparison to other search or retrieval tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Frictionless per-session capture ("daily note for agents"). Keyed by source "session:": the first call creates one session memory (document_type "session"); every later call for the same session_id appends to that same memory (newline-joined, re-embedded and versioned). Different session_ids stay isolated. Returns { memory_id, created, appended }.
| Name | Required | Description | Default |
|---|---|---|---|
| session_id | Yes | Session identifier. The note is keyed by source "session:<session_id>" — the first call creates the memory, later calls append to that same one. | |
| text | Yes | Text to capture (created as content, or appended newline-joined to the session note). | |
| scope | No | Memory scope for isolation | |
| namespace | No | Namespace within scope (e.g., project name, team name) | |
| title | No | Optional title used only on create (defaults to "Session <session_id>"). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide minimal (openWorldHint=false), but description adds key behavioral traits: first-call creation, appending, isolation by session_id, return fields, re-embedding, and versioning. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is two sentences, front-loaded with core purpose, no wasted words. Each sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, but description explains return values. It covers creation/append logic, isolation, versioning, and scope/namespace context. Complete for a tool with 5 parameters and no nested objects.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so schema already documents parameters. Description reinforces keying behavior and title usage but adds no new semantics beyond what schema provides. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool does 'per-session capture' with a specific keying mechanism and explains create vs append behavior, distinguishing it from general memory tools like memory_store. It uses specific verbs and resources.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context for when to use ('daily note for agents', session-specific notes) and implies when not to use (for non-session or overwriting needs). However, it doesn't explicitly name alternative sibling tools or state exclusion criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Save or resume a resumable session-state ("where was I"): structured summary/next_steps/open_questions/files_touched/branch keyed by session_key. save upserts (versioned, so you can diff sessions via memory_version_diff); resume returns the latest. Bypasses the dedup write-gate so an incremental save always persists.
| Name | Required | Description | Default |
|---|---|---|---|
| action | No | save the current session state | resume the latest | resume |
| session_key | No | Stable key for the work thread (defaults to branch, else "default"). | |
| scope | No | Memory scope for isolation | |
| namespace | No | Namespace within scope (e.g., project name, team name) | |
| summary | No | Where things stand right now. | |
| next_steps | No | Ordered list of what to do next. | |
| open_questions | No | Unresolved questions. | |
| files_touched | No | Files in flight. | |
| branch | No | Git branch this session is on. | |
| extra | No | Any additional caller-defined state fields. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses that save upserts are versioned and diffable, and that resume returns latest. Also notes bypassing dedup write-gate, which is beyond annotation's openWorldHint=false.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences: first states purpose and structure, second explains key behavioral traits. Front-loaded and no unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Provides sufficient context for a 10-parameter tool with no output schema: mentions versioning, diff capability, and bypassing dedup. Could optionally describe return format, but not required.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 100% description coverage for parameters; description adds meaning by explaining action enum values, session_key default, and the overall state structure.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'Save or resume a resumable session-state' with specific fields (summary, next_steps, etc.). Differentiates from siblings by mentioning versioning and bypassing dedup write-gate.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly describes when to save vs resume, and notes that it bypasses dedup for incremental saves. Does not provide explicit 'when not to use' or alternative tools, but context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get usage statistics: total memories, chunks, documents, breakdowns by scope/department/type, storage size, and expired count.
| Name | Required | Description | Default |
|---|---|---|---|
| scope | No | Memory scope for isolation | |
| namespace | No | Namespace within scope (e.g., project name, team name) | |
| department | No | Department (e.g., legal, engineering, hr, sales, finance) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, and the description adds valuable details about what statistics are returned (breakdowns, storage, expired count). No contradiction with annotations. Description enhances understanding of the tool's behavior beyond mere read-only nature.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single, well-structured sentence that front-loads the purpose ('Get usage statistics') and efficiently enumerates key outputs. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Although no output schema is provided, the description adequately lists the types of statistics returned. Parameters are well documented. For a read-only stats tool, the description is sufficiently complete for an agent to understand its function and outputs.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema covers all 3 parameters with descriptions (scope, namespace, department). Baseline 3 is appropriate. The description mentions breakdowns by scope/department/type, which adds some context about parameter usage, but does not significantly expand beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool retrieves usage statistics, listing specific metrics (total memories, chunks, documents, breakdowns, storage size, expired count). Distinguishes from numerous sibling tools that perform other operations like appending, getting, or replacing memories.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implied usage for obtaining summary statistics, but no explicit guidance on when to use vs. alternatives like memory_get or memory_insights. Context is clear enough for an agent to differentiate, but lacks direct exclusions or when-not recommendations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Store a new memory with content, metadata, and automatic vector embedding. Use this to save information, decisions, patterns, or knowledge for later semantic retrieval.
| Name | Required | Description | Default |
|---|---|---|---|
| content | Yes | The text content to store as a memory | |
| title | No | Short title for the memory | |
| scope | No | Memory scope for isolation | |
| namespace | No | Namespace within scope (e.g., project name, team name) | |
| document_type | No | Type of document (e.g., contract, policy, code, incident, decision) | |
| source | No | Origin of the content (e.g., file path, URL, system name) | |
| author | No | Who created this content | |
| department | No | Department (e.g., legal, engineering, hr, sales, finance) | |
| tags | No | Tags for categorization | |
| access_level | No | Access classification level | internal |
| language | No | Content language (ISO 639-1 code) | en |
| metadata | No | Domain-specific metadata (e.g., {contract_type: 'NDA', parties: ['A','B']}) | |
| agent_id | No | Identifier of the writing agent for multi-agent attribution | |
| expires_at | No | Full ISO-8601 expiration timestamp, e.g. 2026-03-01T00:00:00Z (memory auto-excluded from search after this) | |
| importance_score | No | Explicit importance 0-1 (governance/criticality). When omitted it is derived from content; min_importance filters operate on this value. | |
| on_conflict | No | Write policy when a near-match exists. "add" (default): insert as new, except an exact duplicate is skipped (NOOP) — identical to prior behaviour. "update": merge content into the existing match (append + re-embed + version bump). "supersede": retire (invalidate) the conflicting match and add this as the current one. | add |
| volatility | No | Override the auto-derived volatility class. Omit to auto-classify from content + document_type (volatile deploy/status facts warn sooner on recall). | |
| verification_tier | No | How well this fact is verified: source_verified > tool_verified > asserted > unverified. Lowers groundedness for unverified claims. Omit ⇒ neutral. | |
| verification_detail | No | Free text: how/when/by-what the fact was verified (e.g. "checked live UAT DB 2026-06-18"). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide only openWorldHint=false, so the description carries the burden. It adds 'automatic vector embedding' but omits details on side effects, write policies (on_conflict), or permissions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence that efficiently conveys purpose and usage without unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite 19 parameters and no output schema, the description is minimal. It omits crucial behavioral context like conflict resolution, expiration, volatility, and return value, leaving the agent to infer from the schema alone.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with detailed descriptions for each parameter. The tool description does not add extra meaning beyond summarizing 'content, metadata, and automatic vector embedding'. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Store' and the resource 'a new memory', and distinguishes from sibling tools like memory_search and memory_delete by emphasizing saving for later retrieval. It also mentions automatic vector embedding, a key feature.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description tells when to use the tool ('to save information, decisions, patterns, or knowledge for later semantic retrieval') but does not explicitly exclude scenarios or mention alternatives like core_memory_append or memory_update for handling conflicts.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch an Obsidian-style note scaffold for a document_type so stored memories stay structurally consistent. Returns a markdown template with ## Section headers (e.g., decision → Context/Decision/Consequences; incident → Symptom/Root Cause/Fix/Prevention; also learning, bug-fix, meeting, session). Unknown types get a generic Summary/Details/Notes scaffold (known:false). Read-only: fill the scaffold, then store it via memory_store.
| Name | Required | Description | Default |
|---|---|---|---|
| document_type | Yes | Document type to fetch a note scaffold for (e.g., decision, incident, learning, bug-fix, meeting, session). Unknown types get a generic Summary/Details/Notes scaffold (known:false). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explicitly states the tool is read-only, matching the readOnlyHint annotation. It adds behavioral context beyond annotations by detailing the return format (markdown with section headers for known types) and behavior for unknown types (generic scaffold with known:false). No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with purpose, and every sentence adds value. It avoids redundancy and is efficiently structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the single parameter, full schema coverage, and presence of annotations, the description covers all necessary context: what it does, output format, behavior for known/unknown types, and read-only nature. No gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the schema description covers the parameter. The description adds value by listing example types (decision, incident, etc.) and explaining the generic behavior for unknowns, enhancing semantic understanding beyond the schema alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool fetches an Obsidian-style note scaffold for a document_type to maintain structural consistency. It uses the specific verb 'fetch' and identifies the resource as a note scaffold, distinguishing it from sibling tools that store or retrieve actual memories.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear guidance: fetch the scaffold, then store it via memory_store. It implies when to use (prior to storing structured notes) but does not explicitly mention when not to use or list alternatives, though the sibling tools include memory_store and others.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Show the MemGPT-style tier distribution (hot / recall / archival) of currently-valid, top-level memories and list the hot working set. Tiers are derived from access recency + frequency — hot = frequently or recently accessed, archival = old and rarely touched, recall = everything in between. Read-only; optional scope/namespace filter.
| Name | Required | Description | Default |
|---|---|---|---|
| scope | No | Memory scope for isolation | |
| namespace | No | Namespace within scope (e.g., project name, team name) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, and the description reinforces this and explains how tiers are derived (access recency + frequency). It adds value beyond annotations with no contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the core action and output. No redundant words; each sentence adds essential information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the main output (tier distribution, hot working set) and scope filters. With no output schema, it provides enough context for an agent to understand the result. Could mention that it's a snapshot or list, but sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema documents both parameters fully. The description mentions 'optional scope/namespace filter' but adds no new semantic detail beyond what the enum and description in the schema provide.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool shows 'MemGPT-style tier distribution (hot / recall / archival)' and 'list the hot working set'. It specifies the resource (memories) and action (show/list), distinguishing it from sibling tools like memory_get or memory_stats.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions it's read-only and has optional scope/namespace filters, giving context on when to use. However, it does not explicitly exclude other tools or provide when-not guidance, which could be helpful given the many sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Surface "unlinked mentions" for a memory — other memories that are semantically related (vector-near + shared entities) but that you have NOT explicitly linked yet. This is Obsidian's killer feature, automated: instead of matching note titles as literal text, it uses embeddings + the entity graph to propose latent connections the agent never made. Auto "similar_to" suggestions are surfaced; existing wikilink/co-occurrence/typed links are excluded. Use it to discover and then confirm real connections (e.g. via memory_extract_entities or a stored link).
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Memory ID to surface unlinked mentions for | |
| limit | No | Maximum number of unlinked mentions to return | |
| min_similarity | No | Minimum cosine similarity for a mention (0-1) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=true, consistent with the read-only nature of surfacing mentions. The description adds behavioral details: uses embeddings + entity graph, excludes existing links, and proposes latent connections. It does not contradict annotations and provides useful algorithmic context, though it does not cover return format or pagination.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences long and front-loads the main purpose in the first sentence. It is well-structured and information-dense, though slightly verbose in the second sentence. Overall, it is concise and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no output schema, the description explains the output type (auto 'similar_to' suggestions) and excludes existing links. It also suggests next steps, making it complete for a discovery tool. No major gaps are apparent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers all three parameters with descriptions (100% coverage). The description does not add significant new parameter semantics; it mentions the algorithm but not parameter-specific details. With high schema coverage, the baseline is 3, and the description does not elevate it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool surfaces unlinked mentions for a memory, which are semantically related but not explicitly linked. It distinguishes itself from typical text matching by using embeddings and entity graph, and the resource (memory) and verb (surface) are specific. The description differentiates it from siblings like memory_related or memory_query.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear guidance on when to use the tool: to discover latent connections that the agent never made. It also suggests a workflow after discovery, such as using memory_extract_entities or storing a link, implying the tool is for discovery, not confirmation. It does not explicitly list when not to use it, but the context makes it clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an existing memory. If content changes, the vector embedding is automatically regenerated. Previous versions are preserved in history.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ID of the memory to update | |
| content | No | New content (will re-generate embedding) | |
| title | No | New title | |
| metadata | No | Updated metadata (replaces existing) | |
| tags | No | Updated tags (replaces existing) | |
| expires_at | No | New full ISO-8601 expiration timestamp (e.g. 2026-03-01T00:00:00Z), or null to remove | |
| changed_by | No | Who made this change (for version history) | |
| importance_score | No | Reassign importance 0-1 (governance/criticality) | |
| verification_tier | No | Set/upgrade the verification tier after the fact (the main post-hoc use case — you verify a stored claim against live state later). Raises/lowers groundedness. | |
| verification_detail | No | Free text accompanying a verification_tier change. | |
| volatility | No | Manual override of the auto-derived volatility class. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses key side effects: automatic embedding regeneration on content change and preservation of previous versions in history. Annotations do not contradict; 'openWorldHint: false' is compatible. This provides useful beyond-schema context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences that front-load the core purpose and then add behavioral details with no extraneous words. Every sentence serves a purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers the main behavioral aspects but lacks comparative guidance against a large set of sibling tools. Does not describe return value or error states, though no output schema exists. Adequate for a basic update tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with detailed parameter descriptions. The description adds minimal extra per-parameter info (only the embedding regeneration tied to 'content'). Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Update an existing memory' with a specific verb and resource. It adds behavioral details (embedding regeneration, versioning) that differentiate it from similar tools, but does not explicitly contrast with siblings like 'memory_replace' or 'memory_append'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives such as 'core_memory_replace' or 'core_memory_append'. The description omits prerequisites, context for choosing this tool, or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Verify the signed provenance envelope of memories: recomputes each content_hash and ed25519-checks the signature against THIS machine's trusted signing key (not the row's self-embedded key). Verify one by id, or a batch by scope/namespace. Returns per-memory status (verified / unsigned / tampered / untrusted) + a summary {verified, unsigned, tampered, untrusted}. "untrusted" = validly signed but by a non-trust-root key (e.g. a teammate on a synced vault) — distinct from "tampered". Read-only. Signing is enabled by MCP_SIGN_MEMORIES.
| Name | Required | Description | Default |
|---|---|---|---|
| id | No | Verify a single memory by id. Omit to verify a batch by scope/namespace. | |
| scope | No | Memory scope for isolation | |
| namespace | No | Namespace within scope (e.g., project name, team name) | |
| limit | No | Max memories to verify in batch mode (default 100) | |
| trusted_pubkeys | No | Additional trusted signer public keys (SPKI PEM) for multi-machine/team vaults — a memory signed by any of these (or by MCP_TRUSTED_PUBKEYS, or this machine's own key) verifies instead of reading 'untrusted'. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, and the description reinforces that it is 'Read-only'. It also discloses important behavioral details: the verification uses the machine's trusted signing key (not the embedded key), and explains the four possible statuses (verified, unsigned, tampered, untrusted) with a definition of 'untrusted'. This provides transparency beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is four sentences, front-loaded with the main action. Each sentence contributes unique information: the verification process, modes, return format, and read-only nature. No redundant or vague phrasing; it is efficient and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema, the description explains the return value (per-memory status + summary dict). All 5 parameters are covered in the schema, and the description adds context for batch mode and key trust. Given the tool's complexity, this is complete and leaves no ambiguity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds value by explaining that omitting 'id' triggers batch verification, and it clarifies the 'trusted_pubkeys' parameter as 'additional trusted signer public keys ... a memory signed by any of these ... verifies instead of reading untrusted'. This gives semantic meaning beyond the schema's brief descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description begins with 'Verify the signed provenance envelope of memories: recomputes each content_hash and ed25519-checks the signature against THIS machine's trusted signing key', which is a specific verb and resource. It clearly distinguishes from siblings by focusing on cryptographic verification, unlike other memory tools that perform different actions (e.g., query, update, delete).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states 'Verify one by id, or a batch by scope/namespace', providing clear usage modes. It explains the distinction between 'untrusted' and 'tampered' statuses, offering context for interpreting results. However, it does not explicitly state when not to use this tool or mention alternatives, but this is not critical given its unique purpose.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Show a line-by-line diff between two revisions of a memory (Obsidian-Sync-grade trust). to defaults to the current version. Use it to audit exactly what an edit changed — added/removed lines plus a summary count.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Memory ID | |
| from | Yes | Version number to diff from | |
| to | No | Version to diff to (defaults to current) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the description does not need to reiterate safety. It adds value by explaining the output format ('added/removed lines plus a summary count') and noting that 'to' defaults to the current version. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is only two sentences, with every word contributing. The first sentence states the core purpose with a trust metaphor, and the second gives usage guidance and output summary. No wasted text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no output schema, so the description must convey return format. It mentions 'added/removed lines plus a summary count', which is adequate but could be more precise (e.g., format of the diff). Still, the description suffices for an agent to understand the tool's behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All three parameters are documented in the schema (100% coverage). The description adds meaning by stating that 'to defaults to the current version', which is not in the schema. This provides clarity beyond the schema alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool shows a line-by-line diff between two revisions of a memory, using a specific verb ('Show') and resource ('diff'). It distinguishes itself from sibling tools like memory_history, memory_versions, and memory_version_restore by focusing on detailed comparison for auditing.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'Use it to audit exactly what an edit changed', providing clear usage context. However, it does not mention when not to use it or directly contrast with alternative tools (e.g., memory_versions for listing, memory_history for history).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Roll a memory back to a prior version's content. The restore is itself a versioned, re-embedded edit (the pre-restore state is snapshotted, the vault file re-mirrored) — never a destructive overwrite. Returns the restored memory.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Memory ID | |
| version | Yes | Version number to restore content from | |
| changed_by | No | Who performed the restore |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description contradicts the annotation destructiveHint=true by claiming 'never a destructive overwrite'. This is a serious inconsistency. Additionally, while the description adds context about versioned edits and snapshots, the contradiction undermines transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the purpose, and contains no unnecessary words. It efficiently communicates the key action and behavioral nuance.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the restore action, versioned nature, and return value, but the contradiction with annotations reduces completeness. Without output schema, it does not explain what the restored memory object contains, and it lacks any mention of prerequisite or side effects beyond the annotation conflict.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the description does not add any parameter-level meaning beyond what is already in the schema. The parameters are well-documented in the schema, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'roll back' and resource 'memory to a prior version', explicitly distinguishing from destructive actions and noting the versioned nature. It differentiates from sibling tools like 'memory_restore' by focusing on version restoration and non-destructive behavior.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for restoring a specific prior version, but it does not explicitly state when to use this tool versus alternatives like 'memory_restore'. No direct exclusions or when-not-to-use guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
View the version history of a memory, showing all past edits with timestamps and who made each change.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Memory ID to get version history for | |
| limit | No | Maximum number of versions to return |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds behavioral context beyond the readOnlyHint annotation by detailing that timestamps and author information are included. However, it does not disclose potential limitations like pagination behavior or what happens if the memory has no history.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence that is front-loaded with the core purpose, containing no extraneous words. Every word is necessary.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only tool with two parameters and no output schema, the description covers the main purpose but does not describe the return format or how to interpret the history data. It is adequate but lacks some completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for both parameters (id and limit). The description does not add additional meaning beyond what the schema already provides, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('View'), the resource ('version history of a memory'), and what is shown ('all past edits with timestamps and who made each change'). This distinguishes it from sibling tools like memory_version_diff and memory_version_restore.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives such as memory_version_diff or memory_version_restore. It does not specify prerequisites or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Manage the active-infrastructure event bus (gated on MCP_WEBHOOKS). register an outbound webhook target (URL is SSRF-validated — public http(s) only), list targets (secrets never returned), delete a target, or dispatch the durable delivery queue now. Mutations to memories (created/updated/superseded/deleted/forgotten) enqueue HMAC-signed deliveries that this tool drains with retry + circuit-breaker + dead-letter.
| Name | Required | Description | Default |
|---|---|---|---|
| action | No | register a target | list targets | delete a target | dispatch the queue now | list |
| url | No | Target URL (action=register). Validated against the SSRF guard: public http(s) only. | |
| secret | No | Optional HMAC-SHA256 signing secret; sent as X-Memory-Signature on each delivery. | |
| events | No | Comma-separated event types or '*' (default all): memory.created/updated/superseded/deleted/forgotten. | |
| scope | No | Only deliver events for memories in this scope. | |
| namespace | No | Only deliver events for memories in this namespace. | |
| id | No | Target id (action=delete). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses significant behavioral traits including SSRF validation, HMAC signing, enqueueing, retry, circuit-breaker, and dead-letter mechanisms. These go beyond the annotations (which only have openWorldHint) and provide critical safety and performance context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single dense paragraph that efficiently covers key behaviors and actions. While no fluff, it could be slightly improved with bullet points or more structured layout for better scannability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 7 parameters and 4 actions, the description covers functional behavior well. However, it lacks details on return values, error handling, and authentication requirements, leaving some gaps for complete understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds context about SSRF validation, HMAC secret signing, and event types, enhancing understanding beyond the parameter schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it manages an event bus for webhooks, listing actions (register, list, delete, dispatch) and the context of memory mutations. It distinguishes itself from sibling tools that focus on memory operations rather than webhook management.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions it is 'gated on MCP_WEBHOOKS' implying a feature flag, but does not explicitly state when to use this tool versus alternatives like those for direct memory operations. There is no guidance on preconditions or when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search memories via hybrid vector+keyword search, scoped to a namespace. Defaults the namespace to the vault folder name; pass an explicit namespace to search memories that live under a different namespace (e.g. after memory_export_vault).
| Name | Required | Description | Default |
|---|---|---|---|
| vault_path | Yes | Absolute path to the Obsidian vault directory | |
| query | Yes | Search query — supports natural language for semantic search and keywords for exact matching | |
| scope | No | Memory scope to search (default "project") | |
| namespace | No | Namespace to search. Defaults to the vault folder name — set this when your memories live in a namespace different from the vault directory name (e.g. after memory_export_vault wrote them under <vault>/<namespace>/). | |
| limit | No | Maximum results to return | |
| offset | No | Skip this many results for pagination | |
| search_mode | No | Search mode: hybrid (vector+keyword), vector only, or keyword only | hybrid |
| tags | No | Filter to memories containing ALL specified tags | |
| min_confidence | No | Minimum confidence score threshold (0-1) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=false, indicating a safe read operation. The description adds context about the hybrid search mode, default namespace behavior, and the ability to search memories under a different namespace (e.g., after export). This adds value beyond annotations without contradicting them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description consists of two sentences with no filler. The first sentence front-loads the main purpose (search method and scoping), and the second adds key nuance about namespace defaulting. Every sentence earns its place, and the length is appropriate for the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 9 parameters, 2 required, and no output schema, the description covers the main search action and namespace behavior. However, it lacks explanation of how 'scope', 'tags', 'min_confidence', and search modes interact, or what the result format looks like. With a richer schema already documenting these, the description falls short of fully preparing an agent for all use cases.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description provides additional meaning for the 'namespace' parameter, explaining its default behavior and use case. It also implicitly clarifies the 'search_mode' enum by mentioning hybrid vector+keyword. This adds meaningful context beyond the schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool performs hybrid vector+keyword search on memories scoped to a namespace. It specifies the search method and scoping, but does not explicitly differentiate from the similar sibling 'memory_search' (which likely lacks namespace scoping). The verb 'search' and resource 'memories' are specific enough for an agent to understand the core functionality.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides guidance on when to use the explicit namespace parameter vs the default (vault folder name), including an example scenario. However, it does not mention when not to use this tool in favor of alternatives like memory_search or memory_query, which would be helpful for an agent deciding between siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check the sync status of an Obsidian vault: total files, synced/pending/changed counts, last sync time, and memory count.
| Name | Required | Description | Default |
|---|---|---|---|
| vault_path | Yes | Absolute path to the Obsidian vault directory |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true, and the description confirms a read-only operation ('Check the sync status'). The description adds detail about the returned data (counts, times, memory count), providing useful context beyond what annotations convey. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that efficiently conveys purpose and output without any wasted words. It is front-loaded with the action and resource, making it easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With one parameter, no output schema, and readOnlyHint provided, the description adequately covers the tool's behavior and return values. It could mention potential errors or prerequisites (e.g., vault must exist), but for a simple status check it is sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a single parameter 'vault_path' described as 'Absolute path to the Obsidian vault directory'. The description does not add further meaning beyond the schema, so baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses specific verb 'Check' and resource 'sync status of an Obsidian vault', listing exact data returned (total files, synced/pending/changed counts, last sync time, memory count). This clearly distinguishes from siblings like vault_sync (which performs sync) and memory_stats (different scope).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for checking sync status, but provides no explicit guidance on when to use it versus alternatives (e.g., vault_sync for performing sync, or memory_stats for different stats). No when-not-to-use or context exclusions are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Sync an Obsidian vault to memory. Scans for markdown files, extracts frontmatter/tags/wiki-links, embeds content, and stores as searchable memories. Uses incremental sync based on file modification times.
| Name | Required | Description | Default |
|---|---|---|---|
| vault_path | Yes | Absolute path to the Obsidian vault directory | |
| chunk_size | No | Target chunk size in characters for large files (~4 chars per token) | |
| chunk_overlap | No | Overlap between chunks in characters for context preservation | |
| force | No | If true, re-sync all files regardless of modification time | |
| include_patterns | No | Only sync files matching these glob patterns (e.g., ["notes/**", "projects/**"]) | |
| exclude_patterns | No | Skip files matching these glob patterns (e.g., ["templates/**", "daily/**"]) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are sparse (only title and openWorldHint=false), so the description carries the burden. It explains the tool is incremental, scans, extracts, and stores, but does not disclose potential overwrite behaviors or idempotency. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with purpose, and concise. It covers the main aspects without unnecessary detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description explains the process but does not mention the return value or output, which is notable given no output schema. For a sync operation with 6 parameters, more completeness about outcomes would be beneficial.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description adds context about the sync process but does not provide additional meaning beyond the schema for individual parameters. No compensation needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool syncs an Obsidian vault to memory, specifying the verb 'sync' and the resource 'Obsidian vault to memory'. It details actions like scanning markdown files, extracting frontmatter/tags/wiki-links, and storing as searchable memories, distinguishing it from sibling tools like vault_search and vault_status.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions incremental sync based on file modification times and a force parameter, but does not explicitly state when to use this tool versus alternatives like memory_import or other memory ingestion tools. No when-not or alternative guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v2.9.1memory_link_checkmemory_search1 field changedInput schema / properties / auto_decayAdded value: +{
+ "description": "When true and no explicit temporal_decay is given, derive decay per result from its volatility class (volatile facts decay fast, stable facts not at all). Down-ranks stale volatile facts without hand-tuning a half-life.",
+ "type": "boolean"
+}memory_store3 fields changedInput schema / properties / verification_detailAdded value: +{
+ "description": "Free text: how/when/by-what the fact was verified (e.g. \"checked live UAT DB 2026-06-18\").",
+ "type": "string"
+}Input schema / properties / verification_tierAdded value: +{
+ "description": "How well this fact is verified: source_verified > tool_verified > asserted > unverified. Lowers groundedness for unverified claims. Omit ⇒ neutral.",
+ "enum": [
+ "source_verified",
+ "tool_verified",
+ "asserted",
+ "unverified"
+ ],
+ "type": "string"
+}Input schema / properties / volatilityAdded value: +{
+ "description": "Override the auto-derived volatility class. Omit to auto-classify from content + document_type (volatile deploy/status facts warn sooner on recall).",
+ "enum": [
+ "volatile",
+ "normal",
+ "stable"
+ ],
+ "type": "string"
+}memory_update3 fields changedInput schema / properties / verification_detailAdded value: +{
+ "description": "Free text accompanying a verification_tier change.",
+ "type": "string"
+}Input schema / properties / verification_tierAdded value: +{
+ "description": "Set/upgrade the verification tier after the fact (the main post-hoc use case — you verify a stored claim against live state later). Raises/lowers groundedness.",
+ "enum": [
+ "source_verified",
+ "tool_verified",
+ "asserted",
+ "unverified"
+ ],
+ "type": "string"
+}Input schema / properties / volatilityAdded value: +{
+ "description": "Manual override of the auto-derived volatility class.",
+ "enum": [
+ "volatile",
+ "normal",
+ "stable"
+ ],
+ "type": "string"
+}v2.6.4core_memory_appendcore_memory_getcore_memory_replacememory_attributionmemory_canvasmemory_communitiesmemory_condensememory_consolidatememory_deletememory_expertisememory_exportmemory_export_datasetmemory_export_vaultmemory_extract_entitiesmemory_extract_learningsmemory_forgetmemory_getmemory_graphmemory_healthmemory_historymemory_importmemory_ingestmemory_insightsmemory_lessonmemory_listmemory_manifestmemory_querymemory_query_structuredmemory_questionsmemory_reflectmemory_relatedmemory_restorememory_revalidatememory_searchmemory_session_notememory_session_statememory_statsmemory_storememory_templatememory_tiersmemory_unlinked_mentionsmemory_updatememory_verifymemory_version_diffmemory_version_restorememory_versionsmemory_webhookvault_searchvault_statusvault_syncMany tools have overlapping purposes, such as multiple search/query tools (memory_search, memory_query, memory_query_structured, vault_search) and multiple memory operations (core_memory_* vs memory_*). While descriptions help, the large number of similar-sounding tools can cause confusion for an agent.
All tools use snake_case and share a consistent prefix pattern (memory_, core_memory_, vault_). However, the naming mixes action verbs (memory_store, memory_delete) with nouns (memory_canvas, memory_insights), breaking the verb_noun pattern in several cases.
With 50 tools, the server is on the heavy side. The broad domain might justify some specialization, but many tools could be consolidated (e.g., three export tools, multiple analytical tools). The count feels slightly beyond optimal for agent usability.
The tool set is exceptionally thorough, covering CRUD operations, versioning, import/export, vault sync, knowledge graph queries, analytics, reflection, consolidation, and even GDPR compliance. No obvious dead ends or missing operations for the stated purpose of memory management.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Private persistent memory for Claude, ChatGPT & Gemini via MCP - semantic search, zero-code setup.
Persistent, outcome-grounded episodic memory for Claude. 14ms CPU retrieval, no GPU, no vector DB.
Persistent memory for AI agents across Claude, ChatGPT and any MCP client.
Portable memory for AI agents: capture once, recall across Claude, Cursor, and any MCP client.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/YonasValentin/mcp-memory-graph'
If you have feedback or need assistance with the MCP directory API, please join our Discord server