Skip to content
DimpleDimple

MCP server

dimple mcp exposes your memory system to any MCP-capable agent (Claude Code, Codex, Cursor, your own client). Modern clients negotiate the 2026-07-28 protocol revision; 2025-era clients (codex and other harnesses that open with initialize) are served from the same factory, so nothing has to be pinned.

Start the server

Section titled “Start the server”
Terminal window
# stdio (client-launched — the default for Claude Desktop / VS Code / Codex)
dimple mcp


# print the client config block (command + args + cwd) for your client
dimple mcp --print


# loopback daemon with a lifecycle
dimple mcp start
dimple mcp status
dimple mcp reload        # blue-green config reload (SIGUSR1)
dimple mcp stop

The daemon serves Streamable HTTP on 127.0.0.1:8787 with DNS-rebinding guards; state lives in .dimple/mcp.pid and .dimple/mcp.log.

The tool surface

Section titled “The tool surface”

Every capability is a transparent MCP tool — no code execution, no lazy loading: the whole surface is advertised in tools/list, so clients can gate and display tools normally. (CodeMode is a harness concern; agents that want it can compose this server with their own.)

Every tool carries the four MCP annotations — readOnlyHint, destructiveHint, idempotentHint, openWorldHint — so a client can gate, sort, or pre-approve on real metadata instead of guessing from the name. openWorldHint is false for every tool: dimple is a local store, a local job queue, and a committed docs index, so no tool reaches an external world.

If you want fewer tools in a given client’s context, the HTTP daemon takes opt-in query parameters — nothing is filtered by default, and stdio is never filtered:

Parameter Effect
?readonly=1 keep only tools whose readOnlyHint is true (every read, no mutation)
?tools=memory_get,graph_explain keep exactly those tools
both union of the two

An unknown tool name is a 400 that lists the valid names, so a typo teaches the spelling instead of silently serving an empty surface.

Memory — memory_write, memory_write_many, memory_get, memory_search, memory_forget, memory_update_embedding, memory_embed, memory_index. memory_search is hybrid vector + FTS5 retrieval with an optional fusion profile, topic/content-type scoping, and a context budget. Deletes are part of the surface: memory_forget marks the unit forgotten and decrements it out of the topic tree.

Graph — graph_add_edge, graph_candidates, graph_confirm, graph_reject, graph_expire, graph_coverage, graph_explain. graph_candidates is the review set; graph_confirm / graph_reject / graph_expire are the review actions.

Maintenance — maintenance_dream (LLM consolidation), maintenance_repair (deletes edges whose endpoint memory is gone, plus stale concept annotations; the soft-delete purge of expired edges is off by default), maintenance_health (invariant report). Long-running jobs block in this build and return their result directly — durable task handles re-enable with the SDK’s era-gate fix (#2599).

System — system_reload applies a config change blue-green.

Failures come back as isError: true tool results with a stable code in structuredContent.error.code (invalid_params, resource_not_found, duplicate, internal_error) and a human-readable message.

Section titled “Docs search and deep links”

docs_search finds the documentation page for a concept or capability (keywords or intent) and returns ranked pages with URLs and snippets — the whole docs site is indexed locally, no network.

open_in_dimple resolves a capability (a tool name) to its documentation URL. Mutating and destructive tool results also carry a link field pointing at the page that explains what changed, so a human can open the exact documentation from the agent’s transcript.

Resources & prompts

Section titled “Resources & prompts”
  • dimple://memory/{id} (+ /neighbors template), dimple://config (API keys masked), dimple://health
  • dimple.context — session-start injection: warmup search + the pending edge review set
  • dimple.review — pending supersede/contradict edges as confirm/reject decisions

Client wiring

Section titled “Client wiring”
// .codex/config.toml (Codex)
[mcp_servers.dimple]
command = "dimple"
args = ["mcp"]
// claude_desktop_config.json (Claude Desktop)
{
  "mcpServers": {
    "dimple": { "command": "dimple", "args": ["mcp"] },
  },
}