CerebeCerebe Docs
AI Infra

Search Memories

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

ParameterTypeRequiredDescription
querystringYesNatural language search query
session_idstringYesSession identifier. Pass "*" to search across every session (cross-session retrieval); any other value scopes the search to that one session
limitintegerNoMaximum results (1-100, default: 5)
memory_typesstring[]NoFilter by types: semantic, episodic, procedural, sequential. (The Python/TypeScript SDKs accept the alias types and translate it to this wire field.)
min_importancefloatNoMinimum importance threshold (0.0-1.0)
entity_idstringNoPrimary entity ID. Combine with session_id="*" to scope a cross-session search to one entity
linked_entity_idsstring[]NoSecondary entity IDs to include in search
retrieval_modestringNovector (default) or hybrid (BM25 + vector + graph)
include_graph_contextbooleanNoInclude graph neighbour context in results (default: false)
include_embeddingsbooleanNoInclude embedding vectors in response (default: false)
temporal_scopestringNoISO-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_abc",
    limit=5,
    types=["semantic", "episodic"],
)

# `search` returns an APIResponse; the payload is a plain dict on `.data`.
for memory in results.data["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_abc',
  limit: 5,
  types: ['semantic', 'episodic'],
})

// The payload is on `results.data` (typed `unknown`); narrow it before use.
const { memories } = results.data as {
  memories: Array<{ memory_type: string; content: string; similarity_score: number }>
}
for (const memory of memories) {
  console.log(`[${memory.memory_type}] ${memory.content}`)
  console.log(`  Score: ${memory.similarity_score}`)
}
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_abc",
    "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_abc"
}

Retrieval Modes

ModeDescription
vectorSemantic similarity search only (fastest, default)
hybridCombines 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.

By default a search is scoped to its session_id. To search across every session for the same entity, pass session_id="*" — which disables the per-session filter — and scope the results with entity_id:

results = await client.memory.search(
    query="learning preferences",
    session_id="*",          # "*" disables the per-session filter
    entity_id="user_123",    # scope the cross-session search to this entity
)

Error Responses

StatusDescription
401Missing or invalid API key
503Vector store unavailable

Next Steps

On this page