Give your agent memory over MCP

Your agent already speaks MCP. Claude Code, Cursor, Codex, 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 hosts one. There is nothing to install.

One command

claude mcp add --transport http illumina https://api.illumina.sh/mcp/demo \
  --header "Authorization: Bearer sub_live_..."

Or the equivalent entry in .mcp.json:

{
  "mcpServers": {
    "illumina": {
      "type": "http",
      "url": "https://api.illumina.sh/mcp/demo",
      "headers": {
        "Authorization": "Bearer sub_live_..."
      }
    }
  }
}

Restart the client and the tools appear. Ask it to remember something and it calls commit. Ask what it knows and it calls search or illuminate. A coding agent configured this way can pull up last month's schema-migration discussion before proposing a new one, and commit the decision it just helped you make.

What the agent gets

The core four are the memory operations themselves: commit for writing, sync_commit when the caller needs extraction to finish before the response returns, search for retrieval, and illuminate for reasoning over what the namespace knows.

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

Single-namespace mode

Mount one namespace at /mcp/{namespace_id} and the namespace-discovery tools disappear from the listing. The agent sees memory operations scoped to that namespace and nothing else. It cannot enumerate other namespaces, because the tool to do so was never exposed to it.

To work across several namespaces from one connection, use the bare /mcp endpoint with an X-Namespace-Id header for the default. Every tool then accepts an optional namespace_id so one session can commit into one namespace and search from another, as long as the key is scoped to both.

Scoping what an agent can do

Two mechanisms control blast radius, and they compose.

Per-namespace configuration filters which tools are exposed. Set mcp_enabled_tools and a read-only research agent gets search and illuminate with every write tool hidden. A note-taking agent gets commit 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. The field is managed through the REST config API; the MCP update_namespace tool cannot change it.

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 and TypeScript SDKs, all generated from one OpenAPI spec. A memory committed through an MCP tool call is the same row, the same extraction pipeline, and the same audit log entry as one committed from the SDK. Your agents and your services share one memory, reached from whichever surface fits.