> ## 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.
# Quickstart
> Add long-term memory to your AI agent in under 5 minutes.
## 1. Install the SDK
```bash pip theme={null}
pip install atlas-mem
```
```bash pip (async) theme={null}
pip install "atlas-mem[async]"
```
```bash uv theme={null}
uv add atlas-mem
```
***
## 2. Get your API key
Sign up at [atlas.bsyncs.com](https://atlas.bsyncs.com), create an organisation, and generate an API key from the **Dashboard → API Keys** tab.
Your key will look like: `atlas_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx`
Store your API key in an environment variable — never hardcode it in source files.
```bash theme={null}
export ATLAS_API_KEY="atlas_your_key_here"
```
***
## 3. Your first memory operations
```python theme={null}
import os
from atlas_mem import AtlasMem
brain = AtlasMem(
api_key=os.environ["ATLAS_API_KEY"],
base_url="https://api.bsyncs.com", # or your self-hosted URL
user_id="user-123", # isolate memories per user
session_id="session-abc", # optional: enables working memory
)
# Store a fact
brain.add("Sarah Jenkins is the Lead Software Engineer at Acme Corp.")
brain.add("Acme Corp recently migrated their primary database to PostgreSQL.")
brain.add("Sarah prefers async Python and has 8 years of backend experience.")
# Search for relevant context
results = brain.search("Who manages engineering at Acme?")
# Inject into your LLM system prompt
print(results.format())
```
**Expected output:**
```text theme={null}
[Memory Context]
- Sarah Jenkins is the Lead Software Engineer at Acme Corp. (high confidence, via episodic)
- sarah_jenkins WORKS_AT acme_corp (high confidence, via semantic)
- Sarah prefers async Python and has 8 years of backend experience. (medium confidence, via episodic)
```
***
## 4. Add memory to an OpenAI call
Here is the pattern used in production — retrieve context, inject into the system prompt, then call the LLM.
```python theme={null}
import os
from openai import OpenAI
from atlas_mem import AtlasMem
openai_client = OpenAI(api_key=os.environ["OPENAI_API_KEY"])
brain = AtlasMem(
api_key=os.environ["ATLAS_API_KEY"],
base_url="https://api.bsyncs.com",
user_id="user-123",
session_id="session-abc",
)
def chat(user_message: str) -> str:
# 1. Retrieve relevant memory
memory = brain.search(user_message, k=5)
memory_context = memory.format()
# 2. Build system prompt with memory
system_prompt = f"""You are a helpful assistant with long-term memory.
MEMORY CONTEXT (use this to personalise your response):
{memory_context}
Always reference specific facts from memory when relevant."""
# 3. Call the LLM
response = openai_client.chat.completions.create(
model="gpt-4o",
messages=[
{"role": "system", "content": system_prompt},
{"role": "user", "content": user_message},
]
)
assistant_reply = response.choices[0].message.content
# 4. Store both turns in memory
brain.add(user_message, source="user")
brain.add(assistant_reply, source="assistant")
return assistant_reply
# Example usage
print(chat("What database does Acme Corp use?"))
# → "Based on my memory, Acme Corp recently migrated their primary database to PostgreSQL."
```
***
## 5. Async usage (FastAPI / LangGraph)
```python theme={null}
import asyncio
import os
from atlas_mem import AsyncAtlasMem
async def main():
async with AsyncAtlasMem(
api_key=os.environ["ATLAS_API_KEY"],
base_url="https://api.bsyncs.com",
user_id="user-123",
session_id="session-abc",
) as brain:
# Batch ingest historical context
await brain.add_batch([
"The project uses a microservices architecture.",
"Services communicate via gRPC internally.",
"The team follows trunk-based development.",
])
# Retrieve with graph traversal
results = await brain.search(
"How are services connected?",
k=5,
max_hops=2, # traverse up to 2 hops in the knowledge graph
)
for fact in results:
print(f"[{fact['source_type']}] {fact['fact']} (score: {fact['score']:.2f})")
asyncio.run(main())
```
***
## 6. Verify the service is running
```python theme={null}
health = brain.health()
print(health)
# {
# "ready": true,
# "models_loaded": true,
# "neo4j": "connected",
# "redis": "connected",
# "qdrant": "connected",
# "version": "1.0.0"
# }
```
***
## What's next?
Configure scoring weights, memory decay, and pruning thresholds.
Detailed schema for ingesting text, including LLM extraction options.
Query your knowledge graph in natural language.
Wire Atlas into Cursor, Claude Code, or Windsurf.