Memories API

Store and retrieve structured knowledge objects in your Neuroloom workspace. Every memory has a title, narrative, tags, concepts, source files, and importance and confidence scores. After creation, the API enqueues background jobs to generate embeddings and discover relationships to other memories.

See Memory Concepts for data model details, or Coding Agent Memory cookbook for a worked integration example.

Base URL and Authentication

https://api.neuroloom.dev

All endpoints require an API key in the Authorization header:

Authorization: Token $MEMORIES_API_TOKEN

Set these environment variables to match what the Neuroloom MCP server reads:

export MEMORIES_API_TOKEN="your-api-key"
export MEMORIES_WORKSPACE_ID="your-workspace-id"

Memory IDs

Every memory is identified by a single UUID id field (e.g. a1b2c3d4-e5f6-7890-abcd-ef1234567890). Use this UUID in all API paths and when referencing a memory from another object.

GET /memories/{id} also accepts a hex prefix of the UUID — at least 8 characters, dashes optional (e.g. a1b2c3d4 or a1b2c3d4-e5f6). This is the only memory endpoint with prefix support; every other {id} path (PATCH, DELETE, /access, /retrieval, /related, /supersession-trail) still requires the full UUID.

Prefix resolution is workspace-scoped and returns one of three outcomes:

• Unique match — returns that memory, same as a full-UUID lookup.
• Zero matches — 404 Not Found.
• Two or more matches — 409 Conflict with code memory_prefix_ambiguous and up to 10 candidate_ids. See the error catalog.

Store a Memory

POST /api/v1/memories/store

Persist a pre-structured memory directly, bypassing LLM extraction. Use this when you have already synthesised a well-formed insight and want to store it immediately.

memory_store(
  title="Prefer async SQLAlchemy for all DB calls",
  memory_type="pattern",
  content="All database operations must use async/await. Sync calls block the event loop and cause latency spikes under load. Use AsyncSession from sqlalchemy.ext.asyncio and await all queries.",
  tags=["sqlalchemy", "async", "backend"],
  concepts=["async", "database", "performance"],
  files=["api/neuroloom_api/database.py"],
  importance=0.9,
  confidence=0.95
)

import httpx, os

response = httpx.post(
    "https://api.neuroloom.dev/api/v1/memories/store",
    headers={"Authorization": f"Token {os.environ['MEMORIES_API_TOKEN']}"},
    json={
        "title": "Prefer async SQLAlchemy for all DB calls",
        "narrative": "All database operations must use async/await. Sync calls block the event loop and cause latency spikes under load.",
        "memory_type": "pattern",
        "tags": ["sqlalchemy", "async", "backend"],
        "concepts": ["async", "database", "performance"],
        "source_files": ["api/neuroloom_api/database.py"],
        "importance_score": 0.9,
        "confidence_score": 0.95,
    },
)
memory = response.json()
print(memory["id"])  # a1b2c3d4-e5f6-7890-abcd-ef1234567890

curl -X POST "https://api.neuroloom.dev/api/v1/memories/store" \
  -H "Authorization: Token $MEMORIES_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Prefer async SQLAlchemy for all DB calls",
    "narrative": "All database operations must use async/await. Sync calls block the event loop and cause latency spikes under load.",
    "memory_type": "pattern",
    "tags": ["sqlalchemy", "async", "backend"],
    "concepts": ["async", "database", "performance"],
    "source_files": ["api/neuroloom_api/database.py"],
    "importance_score": 0.9,
    "confidence_score": 0.95
  }'

Request body

Response — 201 Created, memory object.

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "workspace_id": "ws-xyz789",
  "title": "Prefer async SQLAlchemy for all DB calls",
  "narrative": "All database operations must use async/await. Sync calls block the event loop and cause latency spikes under load.",
  "memory_type": "pattern",
  "tags": ["sqlalchemy", "async", "backend"],
  "concepts": ["async", "database", "performance"],
  "source_files": ["api/neuroloom_api/database.py"],
  "importance_score": 0.9,
  "confidence_score": 0.95,
  "content_hash": null,
  "pagerank_score": null,
  "community_label": null,
  "access_count": 0,
  "retrieval_count": 0,
  "last_accessed_at": null,
  "source_session_id": null,
  "is_consolidated": false,
  "consolidated_from": null,
  "created_at": "2026-03-20T09:00:00Z",
  "updated_at": null
}

Batch Store Memories

POST /api/v1/memories/batch

Store up to 100 pre-structured memories in a single request. Each item is attempted independently — one item's failure (duplicate content, validation error, a leaked-markup rejection) does not abort the rest. Always returns 207 Multi-Status; check success on each item in results to determine outcome.

Request body

Response — 207 Multi-Status

{
  "created_count": 2,
  "error_count": 1,
  "results": [
    { "index": 0, "success": true, "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "error": null, "code": null },
    { "index": 1, "success": false, "id": null, "error": "Field 'narrative' contains tool-call markup at offset 190 (a '</content>' token followed by '<summary>').", "code": "narrative_tool_markup_leak" },
    { "index": 2, "success": true, "id": "b9987766-5544-aabb-ccdd-eeff00112233", "error": null, "code": null }
  ]
}

List Memories

GET /api/v1/memories/

Return memories for the authenticated workspace, ordered by importance_score descending then created_at descending by default.

memory_get_index(limit=50)

import httpx, os

response = httpx.get(
    "https://api.neuroloom.dev/api/v1/memories/",
    headers={"Authorization": f"Token {os.environ['MEMORIES_API_TOKEN']}"},
    params={"memory_type": "pattern", "limit": 10, "ordering": "-importance_score"},
)
memories = response.json()

curl "https://api.neuroloom.dev/api/v1/memories/?memory_type=pattern&limit=10&ordering=-importance_score" \
  -H "Authorization: Token $MEMORIES_API_TOKEN"

Query parameters

Response — 200 OK, array of memory objects.

Get a Memory

GET /api/v1/memories/{id}

Fetch a single memory with its full relationship graph, including outgoing (what this memory relates to) and incoming (what relates to this memory) edges.

memory_get_detail(
  id="a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  include_related=true
)

import httpx, os

response = httpx.get(
    "https://api.neuroloom.dev/api/v1/memories/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    headers={"Authorization": f"Token {os.environ['MEMORIES_API_TOKEN']}"},
)
memory = response.json()
print(memory["outgoing_relationships"])

curl "https://api.neuroloom.dev/api/v1/memories/a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "Authorization: Token $MEMORIES_API_TOKEN"

Path parameters

Error responses

Response — 200 OK, extends the base memory object with relationship arrays.

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "title": "Prefer async SQLAlchemy for all DB calls",
  "narrative": "...",
  "pagerank_score": 0.42,
  "community_label": "database-patterns",
  "feedback_positive_count": 5,
  "feedback_negative_count": 1,
  "outgoing_relationships": [
    {
      "id": "...",
      "source_memory_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "target_memory_id": "b9987766-5544-aabb-ccdd-eeff00112233",
      "relationship_type": "similar_to",
      "discovery_method": "embedding_similarity",
      "confidence": 0.87,
      "is_bidirectional": false,
      "context": null,
      "created_at": "2026-03-20T09:00:00Z"
    }
  ],
  "incoming_relationships": []
}

feedback_positive_count and feedback_negative_count are 0 until feedback is recorded via the Feedback API.

Update a Memory

PATCH /api/v1/memories/{id}

Partial update — supply only the fields you want to change. id and workspace_id are immutable.

Request body — all fields optional

Response — 200 OK, updated memory object.

curl -X PATCH "https://api.neuroloom.dev/api/v1/memories/a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "Authorization: Token $MEMORIES_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "importance_score": 0.95,
    "tags": ["sqlalchemy", "async", "critical"]
  }'

Delete a Memory

DELETE /api/v1/memories/{id}

Permanently deletes a memory and all its relationship edges. This cannot be undone.

Response — 204 No Content.

curl -X DELETE "https://api.neuroloom.dev/api/v1/memories/a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "Authorization: Token $MEMORIES_API_TOKEN"

Batch Delete Memories

POST /api/v1/memories/batch-delete

Delete up to 100 memories in a single request. Only deletes memories belonging to the authenticated workspace. Returns the count of actually deleted memories — this may be less than the number of IDs supplied if some were not found.

Request body

Response — 200 OK

{ "deleted_count": 3 }

Supplying more than 100 IDs returns 422 Unprocessable Entity.

curl -X POST "https://api.neuroloom.dev/api/v1/memories/batch-delete" \
  -H "Authorization: Token $MEMORIES_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "memory_ids": ["a1b2c3d4-e5f6-7890-abcd-ef1234567890", "b9987766-5544-aabb-ccdd-eeff00112233", "c3344556-6677-ccdd-eeff-001122334455"]
  }'

Get Related Memories

GET /api/v1/memories/{id}/related

Find memories semantically similar to the given memory using pgvector cosine similarity on stored embeddings. The source memory must have a generated embedding; if not yet computed, no results are returned.

memory_get_related(
  id="a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  limit=5
)

import httpx, os

response = httpx.get(
    "https://api.neuroloom.dev/api/v1/memories/a1b2c3d4-e5f6-7890-abcd-ef1234567890/related",
    headers={"Authorization": f"Token {os.environ['MEMORIES_API_TOKEN']}"},
    params={"limit": 5, "similarity_threshold": 0.8},
)
related = response.json()

curl "https://api.neuroloom.dev/api/v1/memories/a1b2c3d4-e5f6-7890-abcd-ef1234567890/related?limit=5&similarity_threshold=0.8" \
  -H "Authorization: Token $MEMORIES_API_TOKEN"

Query parameters

Response — 200 OK, array of SearchResult objects (same shape as search results).

Explore a Memory Subgraph

POST /api/v1/memories/explore

Expand a topic or query into a subgraph of related memories using graph traversal from seed nodes. Returns a bounded set of nodes and edges for visualisation or context injection.

memory_explore(
  query="database connection pooling",
  max_nodes=30,
  relationship_types=["similar_to", "references"],
  min_edge_confidence=0.7
)

import httpx, os

response = httpx.post(
    "https://api.neuroloom.dev/api/v1/memories/explore",
    headers={"Authorization": f"Token {os.environ['MEMORIES_API_TOKEN']}"},
    json={
        "query": "database connection pooling",
        "max_nodes": 30,
        "relationship_types": ["similar_to", "references"],
        "min_edge_confidence": 0.7,
        "seed_limit": 5,
    },
)
subgraph = response.json()

curl -X POST "https://api.neuroloom.dev/api/v1/memories/explore" \
  -H "Authorization: Token $MEMORIES_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "database connection pooling",
    "max_nodes": 30,
    "relationship_types": ["similar_to", "references"],
    "min_edge_confidence": 0.7,
    "seed_limit": 5
  }'

Request body

Response — 200 OK

{
  "nodes": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "title": "Use connection pooling for all DB connections",
      "memory_type": "pattern",
      "importance_score": 0.88,
      "pagerank_score": 0.51,
      "community_label": "database-patterns"
    }
  ],
  "edges": [
    {
      "source_memory_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "target_memory_id": "b9987766-5544-aabb-ccdd-eeff00112233",
      "relationship_type": "similar_to",
      "confidence": 0.82
    }
  ],
  "seed_memories": ["a1b2c3d4-e5f6-7890-abcd-ef1234567890"]
}

Find Shortest Path

POST /api/v1/memories/path

Find the shortest relationship path between two memories using BFS graph traversal. Useful for understanding how two concepts connect through the workspace's relationship graph.

Request body

Response — 200 OK

{
  "path": [
    "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "c3344556-6677-ccdd-eeff-001122334455",
    "b9987766-5544-aabb-ccdd-eeff00112233"
  ],
  "edges": [
    {
      "source_memory_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "target_memory_id": "c3344556-6677-ccdd-eeff-001122334455",
      "relationship_type": "references",
      "confidence": 0.91
    },
    {
      "source_memory_id": "c3344556-6677-ccdd-eeff-001122334455",
      "target_memory_id": "b9987766-5544-aabb-ccdd-eeff00112233",
      "relationship_type": "related_to",
      "confidence": 0.78
    }
  ],
  "depth": 2
}

If no path exists within max_depth, returns {"path": [], "edges": [], "depth": 0}.

curl -X POST "https://api.neuroloom.dev/api/v1/memories/path" \
  -H "Authorization: Token $MEMORIES_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "source_memory_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "target_memory_id": "b9987766-5544-aabb-ccdd-eeff00112233",
    "max_depth": 5,
    "relationship_types": ["references", "related_to", "similar_to"]
  }'

Record an Access Event

POST /api/v1/memories/{id}/access

Record that a memory was viewed or read. Increments access_count and updates last_accessed_at. Used by the MCP memory_get_detail tool automatically; call this endpoint directly only if you are building a custom client.

Response — 200 OK, updated memory object.

Record a Retrieval Event

POST /api/v1/memories/{id}/retrieval

Record that a memory appeared in search results. Increments retrieval_count. Distinct from access — retrieval means the memory surfaced in a search response; access means it was directly opened. Both signals feed into importance score recalculation.

Response — 200 OK, updated memory object.

Memory Types

Valid values for the memory_type field (9 canonical types):

LLM-assignable

System-only (never submit these from the LLM extraction path)

Error Responses

{ "detail": "Memory 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' not found." }

Pagination

All list endpoints use limit + offset pagination:

To fetch the second page of 20 results: ?limit=20&offset=20.

Related

• What is a Memory — memory types, fields, and data model
• Memory Lifecycle — how memories move from observation to searchable record
• Coding Agent Memory — worked integration example