Connecting Agents

Agent Brain supports MCP clients and REST clients. MCP is the easiest path for coding agents that support tool servers. REST is useful for scripts, custom agents, and integrations.

MCP endpoint

http://localhost:3001/mcp

REST endpoint

http://localhost:9090/api/v1

Store a memory:

curl -X POST http://localhost:9090/api/v1/remember \
  -H 'Content-Type: application/json' \
  -d '{
    "content": "Auth uses JWT with 24h expiry. Refresh tokens are stored in Redis.",
    "type": "decision",
    "importance": 0.8,
    "tags": ["auth", "jwt", "redis"]
  }'

Recall context:

curl -X POST http://localhost:9090/api/v1/recall \
  -H 'Content-Type: application/json' \
  -d '{"query": "how does authentication work?"}'

Agent-specific MCP configuration

Claude Code

Add to claude_desktop_config.json, or to the mcpServers block in your project CLAUDE.md:

{
  "mcpServers": {
    "agent-brain": {
      "type": "http",
      "url": "http://localhost:3001/mcp"
    }
  }
}

Cursor

Create or edit .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "agent-brain": {
      "type": "http",
      "url": "http://localhost:3001/mcp"
    }
  }
}

Codex

Add to your project AGENTS.md:

# MCP Servers
agent-brain: http://localhost:3001/mcp

Gemini CLI

Add to your Gemini CLI config:

{
  "mcpServers": {
    "agent-brain": {
      "serverUrl": "http://localhost:3001/mcp"
    }
  }
}

REST client examples

Python (requests)

import requests

BASE = "http://localhost:9090/api/v1"

def remember(content, type, importance=0.7, tags=None, project=None):
    return requests.post(f"{BASE}/remember", json={
        "content": content,
        "type": type,
        "importance": importance,
        "tags": tags or [],
        "project": project,
    }).json()

def recall(query, limit=5, project=None):
    payload = {"query": query, "limit": limit}
    if project:
        payload["filter"] = {"project_id": project}
    return requests.post(f"{BASE}/recall", json=payload).json()

Node.js (fetch)

const BASE = "http://localhost:9090/api/v1";

async function remember(content, type, opts = {}) {
  const res = await fetch(`${BASE}/remember`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ content, type, ...opts }),
  });
  return res.json();
}

async function recall(query, limit = 5) {
  const res = await fetch(`${BASE}/recall`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ query, limit }),
  });
  return res.json();
}

Verification

Check that the stack is healthy:

curl http://localhost:9090/health
curl -X POST http://localhost:9090/api/v1/status

Then ask a connected agent:

Use the `brain` MCP tool with command `status` to check if Agent Brain is healthy.

A healthy response confirms the MCP connection is working end-to-end. Store a small test memory and verify it appears in the desktop Knowledge Explorer to confirm write access.

Agent Terminal context loop

Agent Terminal is the local context and session-history layer for Claude Code, Codex, and Agent Harness. Run Terminal on http://127.0.0.1:4302, then set:

export BRAIN_BASE_URL=http://127.0.0.1:9090

For the complete provider setup, run this from an Agent Terminal checkout:

AGENT_TERMINAL_URL=http://127.0.0.1:4302 \
BRAIN_BASE_URL=http://127.0.0.1:9090 \
HARNESS_BASE_URL=http://127.0.0.1:5001 \
node scripts/setup-agent-integration.mjs

This preserves existing Claude settings, installs the Claude lifecycle hooks, and creates the codex-terminal launcher. Native Windows users should run the same command from PowerShell; the installer creates a .cmd launcher under %LOCALAPPDATA%\AgentTerminal\bin.

Terminal sends session observations and compact checkpoints to Brain. Claude Code receives them through Terminal hooks; Codex receives them through the codex-terminal JSONL wrapper or a reviewed Terminal handoff. Harness runs launched from Terminal receive the selected context pack and Brain hints.

Keep Brain's project path and Terminal's projectId aligned. Use the full workspace path rather than a short directory name so similarly named repos do not share context accidentally.