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/searchRequest Body
| Parameter | Type | Required | Description |
|---|---|---|---|
query | string | Yes | Natural language search query |
session_id | string | Yes | Session identifier. Pass "*" to search across every session (cross-session retrieval); any other value scopes the search to that one session |
limit | integer | No | Maximum results (1-100, default: 5) |
memory_types | string[] | No | Filter by types: semantic, episodic, procedural, sequential. (The Python/TypeScript SDKs accept the alias types and translate it to this wire field.) |
min_importance | float | No | Minimum importance threshold (0.0-1.0) |
entity_id | string | No | Primary entity ID. Combine with session_id="*" to scope a cross-session search to one entity |
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_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
| 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
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
| 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