REST API

The Agent Brain brain-engine exposes a REST API on port 9090.

Base URL: http://localhost:9090

All request and response bodies are JSON. All write endpoints require Content-Type: application/json.

Memory operations

POST /api/v1/remember

Store a memory. The content is embedded and indexed for semantic recall.

Request body

Example

curl -X POST http://localhost:9090/api/v1/remember \
  -H "Content-Type: application/json" \
  -d '{
    "content": "PostgreSQL is canonical. Qdrant stores vector indexes only.",
    "type": "decision",
    "importance": 0.9,
    "project": "agent-brain",
    "tags": ["database", "architecture"]
  }'

POST /api/v1/recall

Retrieve the most semantically relevant memories for a query.

Request body

Example

curl -X POST http://localhost:9090/api/v1/recall \
  -H "Content-Type: application/json" \
  -d '{
    "query": "how does the vector index stay in sync with postgres",
    "limit": 5,
    "filter": {
      "project_id": "agent-brain",
      "memory_type": "decision",
      "min_importance": 0.6
    }
  }'

POST /api/v1/search

Paginated search across all memories.

Request body

Example

curl -X POST http://localhost:9090/api/v1/search \
  -H "Content-Type: application/json" \
  -d '{
    "query": "redis caching",
    "filter": { "tags": ["redis"] },
    "page": 1,
    "page_size": 10
  }'

POST /api/v1/forget

Archive a memory. Archived memories are excluded from default recall and search.

Request body

Example

curl -X POST http://localhost:9090/api/v1/forget \
  -H "Content-Type: application/json" \
  -d '{ "memory_id": "3f2a1b4c-0e9d-4f7a-8c3e-1a2b3c4d5e6f" }'

POST /api/v1/get

Fetch a single memory by UUID.

Request body

Example

curl -X POST http://localhost:9090/api/v1/get \
  -H "Content-Type: application/json" \
  -d '{
    "memory_id": "3f2a1b4c-0e9d-4f7a-8c3e-1a2b3c4d5e6f",
    "include_archived": true
  }'

GET /api/v1/memories

Browse memories for a project. All parameters are query string values.

Query parameters

Example

curl "http://localhost:9090/api/v1/memories?project_id=agent-brain&page=1&page_size=20"

POST /api/v1/share

Share a memory with one or more agents. Omit target_agents to share globally.

Request body

Example

curl -X POST http://localhost:9090/api/v1/share \
  -H "Content-Type: application/json" \
  -d '{
    "memory_id": "3f2a1b4c-0e9d-4f7a-8c3e-1a2b3c4d5e6f",
    "target_agents": ["cursor-agent", "claude-code-agent"]
  }'

Cache

POST /api/v1/cache/check

Check whether a semantically similar LLM response is cached for a given query and model.

Request body

Example

curl -X POST http://localhost:9090/api/v1/cache/check \
  -H "Content-Type: application/json" \
  -d '{
    "query": "explain the Qdrant hydration flow",
    "model": "claude-sonnet-4-6",
    "context_depth": 3
  }'

GET /api/v1/cache/stats

Return cache hit/miss statistics and storage usage. No request body.

Example

curl http://localhost:9090/api/v1/cache/stats

Status and health

GET /api/v1/status

Return full service health: PostgreSQL, Qdrant, Redis, NATS, Ollama, memory counts, and connected agents. No request body.

Example

curl http://localhost:9090/api/v1/status

GET /health

Lightweight liveness check. Returns 200 OK with a minimal JSON body when the process is running. Suitable for Docker health checks and load balancer probes.

Example

curl http://localhost:9090/health

Audit

POST /api/v1/memories/audit

Run a governance audit to detect duplicate memories, conflicting decisions, stale context, and unused skills.

Request body

Example

curl -X POST http://localhost:9090/api/v1/memories/audit \
  -H "Content-Type: application/json" \
  -d '{
    "scope": "project",
    "project_id": "agent-brain",
    "skills_dir": "/home/josh/.claude/skills"
  }'

GET /api/v1/memories/audit/history

List past audit runs.

Query parameters

Example

curl "http://localhost:9090/api/v1/memories/audit/history?project_id=agent-brain&limit=10"

GET /api/v1/memories/audit/

Fetch a single audit run by ID.

Path parameter: run_id — UUID of the audit run.

Example

curl http://localhost:9090/api/v1/memories/audit/7a3c9f01-12ab-4d56-8e90-fedcba987654

POST /api/v1/memories/audit/suppress

Suppress a specific finding from an audit run so it no longer appears in future reports.

Request body

Example

curl -X POST http://localhost:9090/api/v1/memories/audit/suppress \
  -H "Content-Type: application/json" \
  -d '{
    "run_id": "7a3c9f01-12ab-4d56-8e90-fedcba987654",
    "finding_id": "b1c2d3e4-f5a6-7890-abcd-ef1234567890"
  }'

POST /api/v1/memories/audit/merge

Merge multiple duplicate memories into a single canonical memory.

Request body

Example

curl -X POST http://localhost:9090/api/v1/memories/audit/merge \
  -H "Content-Type: application/json" \
  -d '{
    "memory_ids": [
      "aaaa0000-0000-0000-0000-000000000001",
      "bbbb0000-0000-0000-0000-000000000002"
    ]
  }'

Project

GET /api/v1/project//context

Return stored context and active agent information for a project.

Path parameter: project_id — project UUID or name.

Example

curl http://localhost:9090/api/v1/project/agent-brain/context

Export and import

POST /api/v1/export

Export memories and metadata to a JSON archive file on the server filesystem. Pass a passphrase to encrypt the output with AES-256-GCM.

Request body

Example

curl -X POST http://localhost:9090/api/v1/export \
  -H "Content-Type: application/json" \
  -d '{
    "output_path": "/home/josh/backups/brain-2026-04-30.json",
    "memories": true,
    "projects": true,
    "since": "2026-01-01",
    "passphrase": "correct-horse-battery-staple"
  }'

POST /api/v1/import

Import a previously exported Agent Brain archive. Use dry_run: true to preview without writing.

Request body

Example

curl -X POST http://localhost:9090/api/v1/import \
  -H "Content-Type: application/json" \
  -d '{
    "source_path": "/home/josh/backups/brain-2026-04-30.json",
    "dry_run": true,
    "passphrase": "correct-horse-battery-staple"
  }'

POST /api/v1/import/foreign

Import memory files from other AI tools. Supports CLAUDE.md, OpenAI Codex agents.md, Gemini memory files, and the Claude memory format.

Request body

Example

curl -X POST http://localhost:9090/api/v1/import/foreign \
  -H "Content-Type: application/json" \
  -d '{
    "source_path": "/home/josh/.claude/memory/MEMORY.md",
    "format": "claude-md",
    "project": "agent-brain",
    "dry_run": false
  }'

GET /api/v1/onboarding/scan

Scan the server filesystem for known memory file locations (CLAUDE.md, agents.md, Gemini memory files, etc.) and return the discovered paths. No request body.

Example

curl http://localhost:9090/api/v1/onboarding/scan

POST /api/v1/onboarding/import

Import a list of discovered memory files in one operation. Typically used after /api/v1/onboarding/scan.

Request body

Example

curl -X POST http://localhost:9090/api/v1/onboarding/import \
  -H "Content-Type: application/json" \
  -d '{
    "file_paths": [
      "/home/josh/.claude/memory/MEMORY.md",
      "/home/josh/dev/myproject/CLAUDE.md"
    ],
    "project": "agent-brain"
  }'

Agents

POST /api/v1/agents/heartbeat

Register or refresh a connected agent. Used by agent integrations to signal that an agent is active.

Request body

Example

curl -X POST http://localhost:9090/api/v1/agents/heartbeat \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "claude-code-agent",
    "project_id": "agent-brain"
  }'

Filter reference

The filter object accepted by /recall, /search, and related endpoints supports the following fields. All fields are optional and combine with AND logic.