Memories

The Memory API provides persistent key-value storage with tagging, categorization, and full-text search. Agents use memories to retain context between sessions, share knowledge, and build up institutional understanding over time.

Base path: /api/memories

All endpoints require Authorization: Bearer <token>.

Memory access is scope-aware — pass X-Scope-Organization-Id and/or X-Scope-Project-Id headers to isolate memories to a specific context.

---

List Memories

GET /api/memories

Query parameters:

Parameter	Type	Description
agentName	string	Filter to memories created by a specific agent
category	string	Filter by category
tags	string	Comma-separated tags to filter by
key	string	Key pattern match (prefix search)
session	string	Filter by session ID
search	string	Full-text search over key and value
limit	number	Default 20, max 100
offset	number	Default 0

Response:

{
  "success": true,
  "data": [
    {
      "id": "mem_01J...",
      "key": "project:cortex:api-patterns",
      "value": "All API routes use consistent Hono patterns with typed responses",
      "category": "architecture",
      "tags": ["hono", "api", "patterns"],
      "agentName": "architect",
      "sessionId": "sess_01J...",
      "createdAt": "2026-04-01T10:00:00Z",
      "updatedAt": "2026-04-01T10:00:00Z"
    }
  ],
  "pagination": { "limit": 20, "offset": 0, "total": 142 }
}

curl:

curl "https://api.cortex.acrobi.com/api/memories?category=architecture&tags=api,patterns" \
  -H "Authorization: Bearer <token>"

---

Store Memory

POST /api/memories

Request body:

{
  "key": "project:cortex:api-patterns",
  "value": "All API routes use consistent Hono patterns with typed responses",
  "category": "architecture",
  "tags": ["hono", "api", "patterns"],
  "agentName": "architect",
  "sessionId": "sess_01J...",
  "ttl": 86400
}

Field	Type	Required	Description
key	string	Yes	Unique key (use : separators for namespacing)
value	string	Yes	Memory content
category	string	No	Semantic category for grouping
tags	string[]	No	Searchable tags
agentName	string	No	Agent that created this memory
sessionId	string	No	Session this memory belongs to
ttl	number	No	Time-to-live in seconds (omit for permanent)

Response: 201 Created

{
  "success": true,
  "data": {
    "id": "mem_01J...",
    "key": "project:cortex:api-patterns",
    "createdAt": "2026-04-03T12:00:00Z"
  }
}

If a memory with the same key already exists in this scope, it is updated and 200 OK is returned.

curl:

curl -X POST "https://api.cortex.acrobi.com/api/memories" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "project:cortex:api-patterns",
    "value": "All routes use Hono with typed responses",
    "category": "architecture",
    "tags": ["hono", "api"]
  }'

---

Get Memory

GET /api/memories/:id

Response:

{
  "success": true,
  "data": {
    "id": "mem_01J...",
    "key": "project:cortex:api-patterns",
    "value": "All API routes use consistent Hono patterns...",
    "category": "architecture",
    "tags": ["hono", "api", "patterns"],
    "agentName": "architect",
    "sessionId": "sess_01J...",
    "expiresAt": null,
    "createdAt": "2026-04-01T10:00:00Z",
    "updatedAt": "2026-04-01T10:00:00Z"
  }
}

---

Update Memory

PATCH /api/memories/:id

Request body:

{
  "value": "All routes use Hono with strict TypeScript — no any types",
  "tags": ["hono", "api", "patterns", "typescript"]
}

Response: 200 OK — returns updated memory object.

---

Delete Memory

DELETE /api/memories/:id

Response:

{ "success": true }

---

Search Memories

Full-text search using FTS5 over keys and values.

GET /api/memories/search

Query parameters:

Parameter	Type	Required	Description
q	string	Yes	Search query
category	string	No	Restrict to category
agentName	string	No	Restrict to agent
limit	number	No	Default 20

Response:

{
  "success": true,
  "data": [
    {
      "id": "mem_01J...",
      "key": "project:cortex:api-patterns",
      "value": "All API routes use consistent Hono patterns...",
      "score": 0.94,
      "category": "architecture",
      "tags": ["hono", "api"]
    }
  ]
}

curl:

curl "https://api.cortex.acrobi.com/api/memories/search?q=Hono+patterns&category=architecture" \
  -H "Authorization: Bearer <token>"

---

Bulk Store

Store multiple memories in a single request.

POST /api/memories/bulk

Request body:

{
  "memories": [
    {
      "key": "decision:use-hono",
      "value": "Chose Hono over Express for Cloudflare Workers compatibility",
      "category": "decisions"
    },
    {
      "key": "decision:use-turso",
      "value": "Chose Turso for edge-compatible SQLite with branching",
      "category": "decisions"
    }
  ]
}

Response: 201 Created

{
  "success": true,
  "data": {
    "created": 2,
    "updated": 0,
    "failed": 0
  }
}

---

Bulk Retrieve

Retrieve multiple memories by key in a single request.

POST /api/memories/bulk-get

Request body:

{
  "keys": ["decision:use-hono", "decision:use-turso", "project:cortex:api-patterns"]
}

Response: 200 OK

{
  "success": true,
  "data": {
    "found": [
      { "key": "decision:use-hono", "value": "...", "id": "mem_01J..." },
      { "key": "decision:use-turso", "value": "...", "id": "mem_02J..." }
    ],
    "missing": ["project:cortex:api-patterns"]
  }
}

---

Memory Stats

Returns counts and usage statistics for the current scope.

GET /api/memories/stats

Response:

{
  "success": true,
  "data": {
    "total": 142,
    "byCategory": {
      "architecture": 34,
      "decisions": 28,
      "research": 21,
      "other": 59
    },
    "byAgent": {
      "architect": 41,
      "backend-coder": 38,
      "qa-tester": 18
    },
    "storageBytes": 284912,
    "expiringIn24h": 3
  }
}