Memory Endpoints — bRRAIn Docs

API reference for memory store and retrieve endpoints with request and response examples.

Memory Endpoints

The Memory endpoints are the core of the bRRAIn API. They allow you to store knowledge and retrieve it using semantic search. All memory endpoints require authentication and are scoped to the vault and workspace associated with your API key.

POST /v1/memory/store

Store a new memory object in bRRAIn.

Request

POST https://api.brrain.io/v1/memory/store
Authorization: Bearer brr_live_YOUR_API_KEY
Content-Type: application/json

Request Body

| Field | Type | Required | Description | |-------|------|----------|-------------| | content | string | Yes | The text content to store. Maximum 1 MB. | | metadata | object | No | Arbitrary key-value pairs for categorization. | | metadata.category | string | No | A primary category label. | | metadata.department | string | No | The originating department. | | metadata.tags | string[] | No | An array of tag strings for filtering. | | metadata.source | string | No | The system or user that produced this content. | | workspace_id | string | No | Target workspace. Defaults to the API key's default workspace. | | ttl_seconds | integer | No | Time-to-live in seconds. The object is auto-archived after this period. | | idempotency_key | string | No | A unique string to prevent duplicate storage. Valid for 24 hours. |

Example Request

curl -X POST https://api.brrain.io/v1/memory/store \
  -H "Authorization: Bearer brr_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Our SLA guarantees 99.95% uptime for enterprise customers. Downtime is calculated monthly, excluding scheduled maintenance windows announced 72 hours in advance.",
    "metadata": {
      "category": "policy",
      "department": "legal",
      "tags": ["sla", "uptime", "enterprise"],
      "source": "legal-team"
    },
    "ttl_seconds": 31536000
  }'

Response

{
  "id": "mem_8a2f4b6c9d1e3g5h",
  "status": "stored",
  "vault_id": "vlt_default",
  "workspace_id": "ws_engineering",
  "created_at": "2026-04-15T14:22:00Z",
  "content_hash": "sha256:a3f2b8c1d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0",
  "byte_size": 184,
  "metadata": {
    "category": "policy",
    "department": "legal",
    "tags": ["sla", "uptime", "enterprise"],
    "source": "legal-team"
  },
  "processing": {
    "embedding_status": "pending",
    "entity_extraction_status": "pending"
  }
}

Status Codes

| Code | Description | |------|-------------| | 201 | Memory object created successfully | | 400 | Invalid request body (missing content, exceeds size limit) | | 401 | Authentication failed | | 403 | API key does not have write permission | | 409 | Duplicate content detected (same idempotency key or content hash) | | 429 | Rate limit exceeded |

POST /v1/memory/batch

Store multiple memory objects in a single request. Maximum 100 objects per batch.

Request Body

{
  "memories": [
    {
      "content": "First memory content",
      "metadata": {"category": "notes"}
    },
    {
      "content": "Second memory content",
      "metadata": {"category": "procedures"}
    }
  ]
}

Response

{
  "stored": 2,
  "failed": 0,
  "results": [
    {"id": "mem_abc123", "status": "stored"},
    {"id": "mem_def456", "status": "stored"}
  ]
}

GET /v1/memory/retrieve

Retrieve memory objects using semantic search, keyword search, or filters.

Request

GET https://api.brrain.io/v1/memory/retrieve
Authorization: Bearer brr_live_YOUR_API_KEY

Query Parameters

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | q | string | Yes* | Natural language query for semantic search. | | keyword | string | No | Keyword-based search (exact and fuzzy matching). | | limit | integer | No | Maximum results to return (1-100, default 10). | | cursor | string | No | Pagination cursor from a previous response. | | category | string | No | Filter by metadata category. | | tags | string | No | Comma-separated tags to filter by (AND logic). | | department | string | No | Filter by department metadata. | | created_after | string | No | ISO 8601 datetime; return objects created after this time. | | created_before | string | No | ISO 8601 datetime; return objects created before this time. | | workspace_id | string | No | Override the default workspace scope. | | min_relevance | float | No | Minimum relevance score (0.0-1.0, default 0.0). | | mode | string | No | Search mode: semantic (default), keyword, or hybrid. |

*Either q or keyword is required.

Example Request

curl -G "https://api.brrain.io/v1/memory/retrieve" \
  -H "Authorization: Bearer brr_live_YOUR_API_KEY" \
  --data-urlencode "q=what is our uptime SLA for enterprise customers" \
  --data-urlencode "limit=5" \
  --data-urlencode "min_relevance=0.5"

Response

{
  "query": "what is our uptime SLA for enterprise customers",
  "mode": "semantic",
  "results": [
    {
      "id": "mem_8a2f4b6c9d1e3g5h",
      "content": "Our SLA guarantees 99.95% uptime for enterprise customers. Downtime is calculated monthly, excluding scheduled maintenance windows announced 72 hours in advance.",
      "relevance_score": 0.96,
      "metadata": {
        "category": "policy",
        "department": "legal",
        "tags": ["sla", "uptime", "enterprise"],
        "source": "legal-team"
      },
      "created_at": "2026-04-15T14:22:00Z",
      "highlights": [
        "Our <em>SLA</em> guarantees 99.95% <em>uptime</em> for <em>enterprise</em> customers."
      ]
    }
  ],
  "total": 1,
  "has_more": false,
  "next_cursor": null,
  "took_ms": 18
}

Status Codes

| Code | Description | |------|-------------| | 200 | Results returned successfully | | 400 | Invalid query parameters | | 401 | Authentication failed | | 403 | API key does not have read permission | | 429 | Rate limit exceeded |

GET /v1/memory/{id}

Retrieve a specific memory object by its ID.

Example Request

curl https://api.brrain.io/v1/memory/mem_8a2f4b6c9d1e3g5h \
  -H "Authorization: Bearer brr_live_YOUR_API_KEY"

Response

{
  "id": "mem_8a2f4b6c9d1e3g5h",
  "content": "Our SLA guarantees 99.95% uptime for enterprise customers...",
  "vault_id": "vlt_default",
  "workspace_id": "ws_engineering",
  "created_at": "2026-04-15T14:22:00Z",
  "updated_at": null,
  "metadata": {
    "category": "policy",
    "department": "legal",
    "tags": ["sla", "uptime", "enterprise"]
  },
  "processing": {
    "embedding_status": "completed",
    "entity_extraction_status": "completed",
    "entities": ["enterprise customers", "SLA", "99.95%", "72 hours"]
  }
}

DELETE /v1/memory/{id}

Soft-delete a memory object. The object is marked as deleted and excluded from search results. It remains in storage for the vault's retention period before permanent deletion.

curl -X DELETE https://api.brrain.io/v1/memory/mem_8a2f4b6c9d1e3g5h \
  -H "Authorization: Bearer brr_live_YOUR_API_KEY"

Response

{
  "id": "mem_8a2f4b6c9d1e3g5h",
  "status": "deleted",
  "deleted_at": "2026-04-15T16:00:00Z"
}

Next Steps