Give your agent memory over MCP

Your agent already speaks MCP. Claude Code, desktop clients, most agent frameworks: they all discover and call MCP tools without custom integration code. So the shortest path to giving an agent durable memory is an MCP server, and Illumina ships one with 39 tools.

What the agent gets

The core four are the memory operations themselves: retain for writing, sync_retain when the caller needs extraction to finish before the response returns, recall for retrieval, and reflect for reasoning over what the namespace knows.

The remaining tools cover management: namespaces, mental models, directives, documents, graph communities, the namespace ontology, async operations, and tags. An agent with the full toolset can create a namespace for a new project, set a directive, retain a design discussion, build communities over the resulting graph, and check the status of the extraction operation, all through tool calls.

Local agents: stdio

For agents running on your machine, illumina-local-mcp speaks MCP over stdio. Client configuration is one entry:

{
  "mcpServers": {
    "illumina": {
      "command": "illumina-local-mcp",
      "env": {
        "ILLUMINA_API_KEY": "<your-key>"
      }
    }
  }
}

Restart the client and the tools appear. A coding agent configured this way can recall last month's schema-migration discussion before proposing a new one, and retain the decision it just helped you make.

Remote agents: HTTP

Agents running in your infrastructure connect over the HTTP transport instead. Same 39 tools, same semantics, no local process to babysit.

HTTP is also where single-namespace mode earns its keep. Mount one namespace at /mcp/:namespace_id and the management tools disappear from the listing. The agent sees memory operations scoped to that namespace and nothing else. It cannot enumerate other namespaces, cannot rewrite directives, cannot touch workspace configuration, because the tools to do so were never exposed to it.

Scoping what an agent can do

Two mechanisms control blast radius, and they compose.

Per-namespace configuration filters which tools are exposed. A read-only research agent gets recall and reflect with every write tool hidden. A note-taking agent gets retain and little else. The filter operates at the tool-listing level, so a hidden tool is not a denied call. The agent never learns the tool exists.

API keys are namespace-scoped. The key in your support agent's environment opens the support namespace and no other, so a prompt-injected or simply confused agent cannot wander into engineering's memory. Key scoping holds at the API layer regardless of what any client claims about itself.

One spec underneath

The MCP server fronts the same REST API as the Python, TypeScript, and Rust SDKs and the CLI, all generated from one OpenAPI spec. A memory retained through an MCP tool call is the same row, the same extraction pipeline, and the same audit log entry as one retained from the SDK. Your agents and your services share one memory, reached from whichever surface fits.