REST API

All requests go to the base URL below. Authenticate every request with your API key in the X-API-Key header.

Base URL

https://mem-brain-api-cutover-v4-production.up.railway.app

All endpoints require X-API-Key: mb_live_xxx unless noted otherwise. Keys are tenant-scoped — you only ever see your own memories.

Memories

Store a memory

POST /api/v1/memories

curl -X POST https://mem-brain-api-cutover-v4-production.up.railway.app/api/v1/memories \
  -H "X-API-Key: mb_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "User prefers dark mode and uses VSCode",
    "tags": ["type.preference", "domain.ui"],
    "category": "user-prefs"
  }'

This endpoint is asynchronous. It returns 202 Accepted with a job_id, not the final memory payload.

Field	Type	Required	Description
`content`	string	yes	The text of the memory
`tags`	string[]	no	Dot-separated tags like `type.preference` or `domain.ui`
`category`	string	no	Optional grouping label
`ingestion_scope`	string	no	Optional regex over tags — limits merge/link candidates during ingest only (not stored). Same pattern family as search `scope_regex` and `GET /graph/traverse`.

202 Accepted response

{
  "status": "accepted",
  "job_id": "0b8d1b72-...",
  "job_status": "queued",
  "status_url": "https://mem-brain-api-cutover-v4-production.up.railway.app/api/v1/memories/jobs/0b8d1b72-...",
  "created_at": "2026-03-19T16:43:06.562Z"
}

Check ingest job status

GET /api/v1/memories/jobs/{job_id}

curl https://mem-brain-api-cutover-v4-production.up.railway.app/api/v1/memories/jobs/0b8d1b72-... \
  -H "X-API-Key: mb_live_xxx"

Completed job response

{
  "job_id": "0b8d1b72-...",
  "status": "completed",
  "created_at": "2026-03-19T16:43:06.562Z",
  "started_at": "2026-03-19T16:43:06.901Z",
  "completed_at": "2026-03-19T16:43:18.266Z",
  "result": {
    "status": "success",
    "memory_id": "72f1e039-...",
    "action": "created",
    "memory": {
      "id": "72f1e039-...",
      "content": "User prefers dark mode and uses VSCode",
      "tags": ["type.preference", "domain.ui"]
    }
  },
  "error": null
}

Search memories

The most important endpoint. Pass a natural language query and get back the most relevant memories.

POST /api/v1/memories/search

curl -X POST https://mem-brain-api-cutover-v4-production.up.railway.app/api/v1/memories/search \
  -H "X-API-Key: mb_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What does the user prefer for their IDE?",
    "k": 5,
    "response_format": "interpreted"
  }'

Field	Type	Default	Description
`query`	string	—	Natural language search query
`k`	number	5	Number of memories to retrieve
`response_format`	string	`raw`	See response formats below
`keyword_filter`	string \| string[]	—	Regex (or AND list) on tags; mutually exclusive with `scope_regex`
`scope_regex`	string	—	Single tag regex for a shared subgraph with ingest/traverse; mutually exclusive with `keyword_filter`

Response formats

Format	What you get
`raw`	Memory nodes and graph edges — structured JSON you process yourself
`interpreted`	LLM-generated plain-language summary with key facts and supporting IDs
`both`	Raw results plus the interpreted summary side by side

Use interpreted when you want to inject the answer directly into a prompt. Use raw when you need the memory IDs or graph structure.

Get a memory

GET /api/v1/memories/{memory_id}

curl https://mem-brain-api-cutover-v4-production.up.railway.app/api/v1/memories/mem_abc123 \
  -H "X-API-Key: mb_live_xxx"

Update a memory

PUT /api/v1/memories/{memory_id}

curl -X PUT https://mem-brain-api-cutover-v4-production.up.railway.app/api/v1/memories/mem_abc123 \
  -H "X-API-Key: mb_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"content": "User prefers dark mode and uses Neovim now"}'

Delete a memory

DELETE /api/v1/memories/{memory_id}

curl -X DELETE https://mem-brain-api-cutover-v4-production.up.railway.app/api/v1/memories/mem_abc123 \
  -H "X-API-Key: mb_live_xxx"

Batch delete

Delete multiple memories by ID, tag, or category in one shot.

DELETE /api/v1/memories/bulk

curl -X DELETE https://mem-brain-api-cutover-v4-production.up.railway.app/api/v1/memories/bulk \
  -H "X-API-Key: mb_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"tags": ["domain.ui"]}'

Count memories

GET /api/v1/memories/count

curl https://mem-brain-api-cutover-v4-production.up.railway.app/api/v1/memories/count \
  -H "X-API-Key: mb_live_xxx"

Graph

Memories are automatically linked when they're related. The graph endpoints let you explore those connections.

Semantic traversal

Expand from a start memory along edges whose descriptions match a natural language query (embedding similarity), with optional tag scope_regex. See docs/MEMBRAIN_AGENTIC_API_GUIDE.md in the repo for full detail.

GET /api/v1/graph/traverse

curl -G "https://mem-brain-api-cutover-v4-production.up.railway.app/api/v1/graph/traverse" \
  -H "X-API-Key: mb_live_xxx" \
  --data-urlencode "start_memory_id=YOUR_MEMORY_ID" \
  --data-urlencode "query=authentication and access control" \
  --data-urlencode "max_hops=2" \
  --data-urlencode "edge_similarity_threshold=0.7"

Find path between two memories

GET /api/v1/graph/path

curl "https://mem-brain-api-cutover-v4-production.up.railway.app/api/v1/graph/path?from_id=mem_aaa&to_id=mem_bbb" \
  -H "X-API-Key: mb_live_xxx"

Get neighborhood

Returns all memories within N hops of a given memory.

GET /api/v1/graph/neighborhood

curl "https://mem-brain-api-cutover-v4-production.up.railway.app/api/v1/graph/neighborhood?memory_id=mem_abc123&hops=2" \
  -H "X-API-Key: mb_live_xxx"

Find hub memories

Returns the most connected memories — useful for understanding what your agent references most.

GET /api/v1/graph/hubs

curl "https://mem-brain-api-cutover-v4-production.up.railway.app/api/v1/graph/hubs?limit=10" \
  -H "X-API-Key: mb_live_xxx"

Stats & health

GET /api/v1/stats

curl https://mem-brain-api-cutover-v4-production.up.railway.app/api/v1/stats \
  -H "X-API-Key: mb_live_xxx"

GET /health

curl https://mem-brain-api-cutover-v4-production.up.railway.app/health

Try it live

Paste your API key and use the full interactive playground below to create, read, update, delete, search, and explore your own memory graph live.

Interactive Playground

CRUD, search, polling, and graph exploration in one place

Paste your API key once, then create memories, poll ingest jobs, run graph operations, and inspect your own graph live.

Base URL: https://mem-brain-api-cutover-v4-production.up.railway.app

API Key

The playground sends browser requests directly to the hosted API using your X-API-Key.

Content