> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bsyncs.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Retrieve
> Hybrid search across episodic, semantic, and working memory with multi-hop graph traversal.
**Cost:** 2 operations per call
## `POST /brain/retrieve`
Runs the full query-adaptive retrieval pipeline:
1. **Session context** — loads rolling topic vector from Redis (if `session_id` provided)
2. **Episodic search** — similarity search in Qdrant (text chunks)
3. **Semantic search** — vector lookup in Neo4j entity graph
4. **Graph traversal** — multi-hop BFS from seed entities (if `max_hops` > 1)
5. **Working memory injection** — appends hot-cached facts from the current session
6. **Hybrid scoring** — across all candidates
7. **Conflict resolution** — deduplicates facts by slot, preferring user-sourced and newer
8. **LongContextReorder** — reorders results for optimal LLM prompt position
***
## Request body
```json theme={null}
{
"query": "What database does Acme Corp use and who chose it?",
"k": 5,
"persona": "shared",
"session_id": "session-abc",
"include_episodic": true,
"include_semantic": true,
"include_working": true,
"max_hops": 2,
"min_score": 0.2,
"use_compression": false
}
```
| Field | Type | Required | Default | Description |
| ------------------ | -------- | -------- | ------- | -------------------------------------------------------------------- |
| `query` | `string` | ✓ | — | Natural language query. |
| `k` | `int` | | `5` | Number of results to return (1–20). |
| `persona` | `string` | | `null` | Filter results to a specific persona (+ always includes `"shared"`). |
| `session_id` | `string` | | `null` | Enables working memory context blending. |
| `include_episodic` | `bool` | | `true` | Search Qdrant vector store. |
| `include_semantic` | `bool` | | `true` | Search Neo4j entity graph. |
| `include_working` | `bool` | | `true` | Inject hot-cached session facts. |
| `max_hops` | `int` | | `null` | Graph traversal depth (1–5). Set `null` to skip traversal. |
| `min_score` | `float` | | `null` | Minimum hybrid score threshold (0.0–1.0). |
| `use_compression` | `bool` | | `false` | LLM-based contextual compression (requires OpenAI). |
***
## Response
```json theme={null}
{
"context": "- Sarah Jenkins is the Lead Software Engineer at Acme Corp. (score: 0.84, via: episodic)\n- acme_corp USE postgres (score: 0.79, via: semantic)\n- Sarah Jenkins joined in 2019 and proposed the Postgres migration. (score: 0.71, via: episodic)",
"facts": [
{
"fact": "Sarah Jenkins is the Lead Software Engineer at Acme Corp.",
"score": 0.84,
"source_type": "episodic",
"created_at": 1719859200.0,
"access_count": 4,
"confidence": 1.0,
"metadata": {}
},
{
"fact": "acme_corp USE postgres",
"score": 0.79,
"source_type": "semantic",
"created_at": 1719859200.0,
"access_count": 1,
"confidence": 0.9,
"metadata": null
}
],
"episodic_count": 2,
"semantic_count": 1,
"working_count": 0,
"reasoning_chain": null,
"latency_ms": 187.3
}
```
| Field | Type | Description |
| --------------------- | ------------- | ------------------------------------------------------------------------------ |
| `context` | `string` | Pre-formatted memory context string ready to inject into an LLM system prompt. |
| `facts` | `array` | Ranked list of memory facts. |
| `facts[].fact` | `string` | Human-readable fact text. |
| `facts[].score` | `float` | Hybrid score (0.0–1.0). Higher is more relevant. |
| `facts[].source_type` | `string` | `"episodic"`, `"semantic"`, or `"working"`. |
| `facts[].created_at` | `float` | Unix timestamp when this memory was created. |
| `facts[].confidence` | `float` | Extraction confidence (1.0 for user-sourced). |
| `episodic_count` | `int` | Facts from Qdrant vector store. |
| `semantic_count` | `int` | Facts from Neo4j graph. |
| `reasoning_chain` | `array\|null` | Traversal steps when `max_hops` > 1. |
| `latency_ms` | `float` | Total retrieval time in milliseconds. |
***
## Code examples
```python Python SDK theme={null}
from atlas_mem import AtlasMem
brain = AtlasMem(api_key="atlas_...", base_url="https://api.bsyncs.com", user_id="user-123")
# Basic search
results = brain.search("Who is the lead engineer at Acme?", k=5)
# Inject into system prompt
print(results.format(max_facts=5))
# Iterate over individual facts
for fact in results:
print(f"[{fact['source_type']}] {fact['fact']} ({fact['score']:.2f})")
# With multi-hop graph traversal
results = brain.search(
"What infrastructure choices did the engineering team make?",
k=10,
max_hops=3,
)
print(results.reasoning_chain)
```
```python Python (requests) theme={null}
import requests
response = requests.post(
"https://api.bsyncs.com/brain/retrieve",
headers={
"x-api-key": "atlas_your_key_here",
"Content-Type": "application/json",
},
json={
"query": "Who is the lead engineer at Acme?",
"k": 5,
"max_hops": 2,
"include_episodic": True,
"include_semantic": True,
"session_id": "session-abc",
}
)
data = response.json()
print(data["context"])
```
```bash cURL theme={null}
curl -X POST https://api.bsyncs.com/brain/retrieve \
-H "x-api-key: atlas_your_key_here" \
-H "Content-Type: application/json" \
-d '{
"query": "Who is the lead engineer at Acme?",
"k": 5,
"max_hops": 2
}'
```
```typescript TypeScript (fetch) theme={null}
const response = await fetch("https://api.bsyncs.com/brain/retrieve", {
method: "POST",
headers: {
"x-api-key": "atlas_your_key_here",
"Content-Type": "application/json",
},
body: JSON.stringify({
query: "Who is the lead engineer at Acme?",
k: 5,
max_hops: 2,
}),
});
const { context, facts } = await response.json();
// Inject `context` directly into your LLM system prompt
console.log(context);
```
***
## Using `context` in your LLM prompt
The `context` field is a pre-formatted string designed to drop directly into an LLM system prompt:
```python theme={null}
import openai
from atlas_mem import AtlasMem
brain = AtlasMem(api_key="atlas_...", base_url="https://api.bsyncs.com", user_id="user-123")
def answer(user_question: str) -> str:
memory = brain.search(user_question, k=5)
messages = [
{
"role": "system",
"content": f"""You are a helpful assistant. Use the memory context below to personalise your answer.
MEMORY:
{memory.context}
If memory is not relevant, answer from general knowledge.""",
},
{"role": "user", "content": user_question},
]
resp = openai.chat.completions.create(model="gpt-4o", messages=messages)
return resp.choices[0].message.content
```
***
## Score interpretation
| Score range | Meaning |
| ----------- | --------------------------------------------------- |
| `0.7 – 1.0` | High confidence — directly relevant |
| `0.4 – 0.7` | Medium confidence — probably relevant |
| `0.2 – 0.4` | Low confidence — tangentially related |
| `< 0.2` | Filtered out by `v_floor` (not returned by default) |