Search and retrieve memories using semantic similarity, hybrid retrieval, and graph context.

Search Memories

Search across stored memories using semantic similarity. Cerebe fuses results from vector search (Qdrant), graph traversal (Neo4j/Graphiti), and BM25 keyword matching to return the most relevant memories.

Endpoint

POST /api/v1/memory/search

Request Body

Parameter	Type	Required	Description
`query`	`string`	Yes	Natural language search query
`session_id`	`string`	Yes	Session identifier
`limit`	`integer`	No	Maximum results (1-100, default: 5)
`types`	`string[]`	No	Filter by types: `semantic`, `episodic`, `procedural`, `sequential`
`min_importance`	`float`	No	Minimum importance threshold (0.0-1.0)
`entity_id`	`string`	No	Primary entity ID for cross-session retrieval
`linked_entity_ids`	`string[]`	No	Secondary entity IDs to include in search
`retrieval_mode`	`string`	No	`vector` (default) or `hybrid` (BM25 + vector + graph)
`include_graph_context`	`boolean`	No	Include graph neighbour context in results (default: false)
`include_embeddings`	`boolean`	No	Include embedding vectors in response (default: false)
`temporal_scope`	`string`	No	ISO-8601 date for point-in-time retrieval

Examples

from cerebe import AsyncCerebe

client = AsyncCerebe(api_key="ck_live_...")

results = await client.memory.search(
    query="What kind of explanations does the user prefer?",
    session_id="session_xyz",
    user_id="user_123",
    limit=5,
    types=["semantic", "episodic"],
)

for memory in results.memories:
    print(f"[{memory.memory_type}] {memory.content}")
    print(f"  Score: {memory.similarity_score}")

import Cerebe from '@cerebe/sdk'

const client = new Cerebe({ apiKey: 'ck_live_...' })

const results = await client.memory.search({
  query: 'What kind of explanations does the user prefer?',
  sessionId: 'session_xyz',
  userId: 'user_123',
  limit: 5,
  types: ['semantic', 'episodic'],
})

for (const memory of results.memories) {
  console.log(`[${memory.memoryType}] ${memory.content}`)
  console.log(`  Score: ${memory.similarityScore}`)
}

curl -X POST https://api.cerebe.ai/api/v1/memory/search \
  -H "X-API-Key: ck_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What kind of explanations does the user prefer?",
    "session_id": "session_xyz",
    "entity_id": "user_123",
    "limit": 5,
    "memory_types": ["semantic", "episodic"]
  }'

Response

{
  "memories": [
    {
      "id": "mem_a1b2c3d4",
      "session_id": "session_abc",
      "content": "User prefers visual explanations over text",
      "memory_type": "semantic",
      "timestamp": "2025-03-07T14:30:00Z",
      "importance": 0.8,
      "access_count": 3,
      "last_accessed": "2025-03-07T16:00:00Z",
      "similarity_score": 0.92,
      "relationships": [],
      "metadata": {"source": "onboarding"}
    }
  ],
  "total": 1,
  "session_id": "session_xyz"
}

Retrieval Modes

Mode	Description
`vector`	Semantic similarity search only (fastest, default)
`hybrid`	Combines BM25 keyword search, vector similarity, and graph traversal for best recall

Hybrid mode is recommended when precision matters more than latency. It fuses results from all three retrieval strategies and re-ranks them.

Cross-Session Search

To search memories across sessions for the same user, pass the entity_id parameter:

results = await client.memory.search(
    query="learning preferences",
    session_id="current_session",
    entity_id="user_123",  # searches across all sessions for this user
)

Error Responses

Status	Description
`401`	Missing or invalid API key
`503`	Vector store unavailable

Next Steps

Store Memory — Add new memories to the fabric
Harvest Memories — Auto-extract memories from conversations
Memory Overview — Full guide to the Memory Fabric

Search Memories

On this page