Memories API

The Memories API is the core of Neuroloom. It stores text content as vector embeddings and exposes semantic search over them.

Base URL

https://api.neuroloom.dev/v1

All endpoints require the Authorization: Bearer <api_key> header.

Create a Memory

POST /memories

curl -X POST https://api.neuroloom.dev/v1/memories \
  -H "Authorization: Bearer nlk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "content": "The user prefers concise technical answers with code examples.",
    "metadata": {
      "category": "preferences",
      "agentId": "assistant-v1"
    }
  }'

Response:

{
  "id": "mem_01abc123",
  "content": "The user prefers concise technical answers with code examples.",
  "metadata": { "category": "preferences", "agentId": "assistant-v1" },
  "createdAt": "2026-03-23T10:00:00Z",
  "workspaceId": "ws_xyz"
}

SDK

const memory = await client.memories.create({
  content: "The user prefers concise technical answers with code examples.",
  metadata: { category: "preferences", agentId: "assistant-v1" },
});

Search Memories

Semantic search uses cosine similarity over the stored embeddings. Results are ranked by relevance.

POST /memories/search

curl -X POST https://api.neuroloom.dev/v1/memories/search \
  -H "Authorization: Bearer nlk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "query": "How does the user like to receive answers?",
    "topK": 5,
    "filters": { "category": "preferences" }
  }'

Response:

{
  "results": [
    {
      "id": "mem_01abc123",
      "content": "The user prefers concise technical answers with code examples.",
      "score": 0.94,
      "metadata": { "category": "preferences" }
    }
  ]
}

SDK

const results = await client.memories.search({
  query: "How does the user like to receive answers?",
  topK: 5,
  filters: { category: "preferences" },
});

Get a Memory

GET /memories/:id

curl https://api.neuroloom.dev/v1/memories/mem_01abc123 \
  -H "Authorization: Bearer nlk_live_..."

Update a Memory

Partial updates only — supply the fields you want to change.

PATCH /memories/:id

curl -X PATCH https://api.neuroloom.dev/v1/memories/mem_01abc123 \
  -H "Authorization: Bearer nlk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "content": "Updated content text." }'

Updating content automatically re-embeds the text.

SDK

await client.memories.update("mem_01abc123", {
  content: "Updated content text.",
});

Delete a Memory

DELETE /memories/:id

curl -X DELETE https://api.neuroloom.dev/v1/memories/mem_01abc123 \
  -H "Authorization: Bearer nlk_live_..."

Returns 204 No Content on success.

SDK

await client.memories.delete("mem_01abc123");

List Memories

GET /memories?limit=20&cursor=<cursor>

Responses use cursor-based pagination.

{
  "data": [ /* memory objects */ ],
  "nextCursor": "cur_...",
  "hasMore": true
}

Metadata Filtering

The filters field on search accepts key-value pairs matched against metadata. All filters are AND-ed together.

const results = await client.memories.search({
  query: "deployment instructions",
  topK: 10,
  filters: {
    agentId: "deploy-bot",
    environment: "production",
  },
});

Next Steps

• MCP Integration — Expose the Memories API as MCP tools to Claude and other agents
• Authentication — Key scopes and workspace isolation details