JetBrains Air is a standalone agentic development environment that runs Claude Agent, OpenAI Codex, Gemini CLI, Junie, or any ACP-compatible agent installed on your machine. Installing SurrealDB Agent Memory gives the agent you select persistent memory across sessions, so it can recall previous decisions and project context without you repeating them.
For integration rules your agent should follow (auth, scope, endpoints, common mistakes), see Agent guide (AGENTS.md). Air picks up instruction files that already exist in your project, including CLAUDE.md and the .claude folder for Claude Agent, and passes them to the selected agent.
This page covers JetBrains Air. For AI Assistant inside IntelliJ IDEA, PyCharm, WebStorm and the other IDEs, see the JetBrains guide.
Configure
The install-mcp helper does not cover JetBrains Air, so configure the server by hand.
Open Settings and go to AI | MCP Servers
Turn on Enable MCP support
Click Add Global MCP Server, or use the drop-down to choose Add Local MCP Server or Add Workspace MCP Server
Paste the configuration below and save it
{
"mcpServers": {
"spectron": {
"url": "https://<your-context-host>/mcp",
"headers": {
"Authorization": "Bearer <your-api-key>",
"X-Spectron-Context": "acme-prod"
}
}
}
}On SurrealDB Cloud, use your context host from SurrealDB Studio API keys (not a generic shared domain). Self-hosted: replace the URL with your SurrealDB Agent Memory server's base URL + /mcp.
Air connects on save, because SurrealDB Agent Memory authenticates with a static Bearer key rather than OAuth.
Choosing a scope
The three Add options write the same JSON to different places:
| Scope | Where it lives | Use it for |
|---|---|---|
| Global | Air's own settings on your machine | A personal key you want in every project |
| Local | .air/mcp.json in the project root | Project-specific configuration, stored with Air's other project settings |
| Workspace | .mcp.json in the project root | A repository that already carries MCP configuration |
Workspace servers start only when Launch workspace MCP servers is also enabled on the same settings page.
Air reads the bearer token from the configuration file itself, and tokens passed through environment variables are not supported. Both .air/mcp.json and .mcp.json sit in the project root, so add the file to .gitignore before you paste a key, or use the Global scope to keep the key out of the repository.
X-Spectron-Context is a client-side convenience for templating. Each API key is bound to one Context, so context_id is optional on every tool call; omit it to use the key's Context. An explicit value that does not match the key still returns 401.
Verify the installation
Reopen Settings → AI | MCP Servers and confirm spectron is in the Added list with a green status indicator and a tool count
Start a task and ask "What MCP tools do you have available?" The agent should report the SurrealDB Agent Memory tools
If the indicator is not green, check that the URL (your context host + /mcp) and API key are correct.
Usage examples
Store a project decision:
"Remember that this service uses hexagonal architecture and all adapters live under
internal/adapters."
The agent calls remember with a suitable scope.
Recall context before a change:
"What did we decide about where adapters live in this project?"
The agent calls recall before answering.
Air's permission mode, cycled with Shift+Tab, applies to the task as a whole rather than to individual tool calls. In Ask mode the agent requests approval before it changes files or runs commands.
Scope per tool call
Narrow reads and writes with the per-tool scope argument (slash paths, for example ["org/acme/project/platform"]). Register paths with spectron scopes create before first use. For project isolation, use separate contexts or distinct scope paths.
Removing SurrealDB Agent Memory
Open Settings → AI | MCP Servers, select the spectron entry, and remove it. For the Local and Workspace scopes you can instead delete the "spectron" key from .air/mcp.json or .mcp.json.