Claude | Coding assistants

The official SurrealDB plugin marketplace for Claude ships an agent-memory plugin with two parts: an MCP server connection and a set of memory hooks. It supports Claude Code, Cowork, and Claude Desktop; the hooks run in Claude Code and Cowork only.

MCP server. The plugin connects to SurrealDB's managed MCP server at https://mcp.surrealdb.com over OAuth. There is nothing to configure: on the first tool call, a browser opens so you can sign in with your Surreal ID.
Memory hooks. Three lifecycle hooks recall memories into context and store each exchange, without the model choosing to call a tool. The hooks call your Agent Memory instance's /mcp endpoint directly with a bearer token, so they need their own configuration.

Claude Code and Cowork

Install the plugin

Add the marketplace, then install the agent-memory plugin:

/plugin marketplace add surrealdb/ai-claude-plugin
/plugin install agent-memory@surrealdb

Claude Code reads the plugin directly - the MCP server, the hooks and the usage skill load automatically. The plugin's MCP entry has no URL or token to set:

{
  "mcpServers": {
    "agent-memory": {
      "type": "http",
      "url": "https://mcp.surrealdb.com"
    }
  }
}

The URL is the bare root, with no /mcp path.

Configure the memory hooks

The hooks are separate processes and cannot use the OAuth sign-in, so they take a token-authenticated endpoint from environment variables:

Hook event	Tool called	What it does
`SessionStart`	`recall`	Recalls general memories about the user and project and adds them to the context
`UserPromptSubmit`	`recall`	Recalls memories relevant to the current prompt and adds them to the context
`Stop`	`remember`	Stores the latest user and assistant exchange with `infer: "full"`

Set your instance's /mcp endpoint and a context API key before launching Claude Code, then restart:

export AGENT_MEMORY_MCP_URL="https://<your-agent-memory-instance>/mcp"
export AGENT_MEMORY_MCP_TOKEN="<your-api-key>"

Variable	Description
`AGENT_MEMORY_MCP_URL`	Your instance's `/mcp` endpoint. Required for the hooks
`AGENT_MEMORY_MCP_TOKEN`	Bearer token for that endpoint, a context API key. Required for the hooks
`AGENT_MEMORY_HOOKS`	Set to `off`, `0` or `false` to disable the hooks. The MCP server stays connected
`AGENT_MEMORY_HOOK_TIMEOUT`	Network timeout per hook call, in seconds. Default `8`

The hooks fail open. If either required variable is unset, or the instance returns an error or times out, the hook exits without output and does not block the prompt. Without these variables the MCP server still works, and memory is on-demand through the tools rather than automatic. The hooks never send context_id; the server uses the Context bound to the key.

Note

With the hooks configured, the Stop hook sends the latest exchange, which is conversation content, to the configured endpoint, and the recall hooks send the current prompt.

Verify the installation

claude mcp list

You should see agent-memory listed. The first tool call opens a browser to sign in with your Surreal ID. In a session, ask "What MCP tools do you have access to?" and Claude should list the SurrealDB and Agent Memory tools that the managed server provides.

Usage examples

Remember architectural decisions as you code:

claude "Remember that we have decided to use event sourcing for the orders service and that the aggregate root is OrderAggregate."

Claude Code stores the decision in Agent Memory. With the hooks configured, the next session in this project recalls it before Claude answers questions about the orders service.

Recall context before a coding task:

claude "What do you remember about our database schema decisions?"

Claude Desktop

Claude Desktop has no plugin or marketplace format, so set it up manually. Claude Desktop does not run plugin hooks, so memory there is on-demand through the MCP tools, and the AGENT_MEMORY_* variables have no effect.

Option A - Connectors UI (recommended)

Open Settings → Connectors → Add custom connector and add:

Name	URL	Auth
`agent-memory`	`https://mcp.surrealdb.com`	OAuth - sign in with your Surreal ID when prompted

The managed server carries the SurrealDB tools and the Agent Memory tools, so one connector is enough for both.

Option B - Manual config

Merge the following into claude_desktop_config.json, then restart Claude Desktop:

Platform	Path
macOS	`~/Library/Application Support/Claude/claude_desktop_config.json`
Windows	`%APPDATA%\Claude\claude_desktop_config.json`

{
  "mcpServers": {
    "agent-memory": {
      "type": "http",
      "url": "https://mcp.surrealdb.com"
    }
  }
}

You can validate the file with cat ~/Library/Application\ Support/Claude/claude_desktop_config.json | python3 -m json.tool.

Skill (optional)

Claude Desktop cannot load plugins, but you can add the SurrealDB Agent Memory usage skill by hand: open Settings → Skills → Upload skill and upload the plugins/agent-memory/skills/agent-memory/ folder from the plugin repo. Its sections about hooks do not apply on Claude Desktop.

Verify the installation

Restart Claude Desktop completely (quit and reopen)
Start a new conversation and sign in with your Surreal ID when prompted
Click the tools icon (the hammer symbol) in the composer - the SurrealDB Agent Memory tools should appear
Ask "What MCP tools do you have?" and Claude should describe the SurrealDB Agent Memory tools

Scope on tool calls

Narrow writes with the per-tool scope argument and reads with lens (slash paths, for example ["org/acme/user/alice"] or ["org/acme/project/orders-service"]). Register paths with agent-memory scopes create before first use. Use separate contexts or distinct scope paths to keep memory isolated per repository.

Removing SurrealDB Agent Memory

Claude Code / Cowork: remove the agent-memory plugin from the /plugin menu, or run claude mcp remove agent-memory.

Claude Desktop: remove the agent-memory connector, or delete the "agent-memory" key from claude_desktop_config.json, then restart Claude Desktop.