> ## Documentation Index
> Fetch the complete documentation index at: https://docs.maximem.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# FAQ
> Common questions about Synap, organized by topic. If your question is not answered here, check the [Support](/resources/support) page for additional help channels.
## General
Synap is a managed memory platform for AI agents. It provides a complete pipeline for ingesting conversations and documents, extracting structured knowledge (facts, preferences, episodes, emotions, temporal events), resolving entities across conversations, and retrieving relevant context when your agent needs it.
Instead of building and maintaining your own vector database, retrieval pipeline, and entity resolution system, you integrate the Synap SDK into your application and let the platform handle the rest. Your agent gets long-term, structured memory with a few lines of code.
Traditional RAG systems retrieve raw document chunks based on similarity search. Synap goes several steps further:
* **Structured extraction**: Synap does not just store chunks. It extracts typed knowledge (facts, preferences, episodes, emotions, and temporal events) with confidence scores.
* **Entity resolution**: Mentions of the same entity across conversations (e.g., "John", "my manager", "John Smith") are linked to a single canonical entity.
* **Scoped retrieval**: Memories are scoped to users, customers, and organizations. Each user gets their own memory without manual isolation logic.
* **Context compaction**: Long conversation histories are automatically summarized while preserving key information, reducing token usage.
* **Managed pipeline**: No vector databases to deploy, no embedding models to tune, no retrieval pipelines to build.
All of these are memory layers for AI agents, and at a 30,000-ft view they overlap. The differences that matter in practice:
| Capability | Synap | Mem0 | Zep | Letta | SuperMemory |
| --------------------------------------------------------------------- | -------------------------------------------- | -------------------- | ----------------- | -------------------- | -------------------- |
| Typed memories (facts / preferences / episodes / emotions / temporal) | Native, per-type retrieval | Single "memory" type | Facts + episodes | Single "memory" type | Single "memory" type |
| Entity resolution across conversations | Yes (graph store, automatic) | Limited | Yes (graph store) | No | No |
| Multi-scope (user / customer / client / world) | Native scope chain | User only | User only | User only | User only |
| Customized Memory Architecture (MACA) | Yes, generated from a Use-Case Markdown spec | Manual prompt tuning | Manual config | Manual schema | Manual config |
| Context compaction (auto-summarize long history) | Built-in (`context.compact`) | No | Limited | No | No |
| Self-host option | Self-host + cloud (Enterprise) | Self-host + cloud | Self-host + cloud | Self-host | Cloud only |
| Anticipation cache (background prefetch of likely-needed memories) | Yes | No | No | No | No |
| B2B-native (customer/org isolation, MACA-per-instance) | Yes | No (user-only) | No (user-only) | No (user-only) | No (user-only) |
**When Synap is the right choice**: you're building a B2B agent product where each customer org has shared context (policies, runbooks, product data) on top of per-user memory; you want typed extraction so the LLM can reason over preferences vs. facts vs. temporal events distinctly; you don't want to run a vector DB.
**When another tool is a better fit**: you only have a single-user consumer app and don't need the scope chain or entity graph (Mem0 / SuperMemory are simpler); you want agent state + memory bundled in one SDK (Letta).
Build your own if **any** of these apply:
* You have strict data residency or air-gap requirements that managed cloud can't meet, and your prospective scale doesn't justify Synap's self-hosted licensing.
* Your memory model is highly domain-specific (e.g., medical records with regulated taxonomies) and you'd end up reimplementing extraction anyway.
* You're at single-digit MAU and a `pgvector` table + a few prompt-engineered extraction calls is genuinely cheaper than the integration overhead.
Don't build your own if you're just worried about "lock-in" or "wanting control." The honest cost of running a production memory pipeline (embeddings, vector store, graph store, entity resolution, compaction, eviction, observability) is a multi-engineer-quarter project that no agent team has gotten right on a side budget.
Yes. Synap is designed with a zero-trust security model:
* **Encryption in transit**: All connections use TLS 1.3.
* **Encryption at rest**: All stored data is encrypted at rest using AES-256.
* **Instance isolation**: Each instance has its own storage namespace. Memories from one instance are never accessible from another.
* **Scope isolation**: Within an instance, memories are scoped to users and customers. A user can only access memories in their scope chain.
* **Credential management**: API keys are hashed (SHA-256) before storage. Plaintext keys are never stored on the server.
See [Authentication](/setup/authentication) for details on the credential lifecycle.
Synap Cloud is currently available in **US East** and **EU Central**. Additional regions are planned based on demand. Contact [sales@maximem.ai](mailto:sales@maximem.ai) for region-specific requirements or data residency needs.
## SDK
The official Synap SDK is available for **Python 3.11+**. It is fully async, built on `asyncio`, and available via pip:
```bash theme={null}
pip install maximem-synap
```
A JavaScript/TypeScript SDK is available (`@maximem/synap-js-sdk`). Note it requires a Python 3.11+ runtime on the host since it wraps the Python SDK as a subprocess. Native TypeScript and Go SDKs are on the roadmap. Check the [Changelog](/resources/changelog) for updates on new language support.
Yes. All SDK methods are `async` and must be called with `await` inside an async context. This design ensures your application never blocks on network I/O.
If you need to call the SDK from synchronous code, use `asyncio.run()`:
```python theme={null}
import asyncio
from maximem_synap import MaximemSynapSDK
async def ingest():
sdk = MaximemSynapSDK(api_key="synap_your_key_here")
await sdk.initialize()
return await sdk.memories.create(
document="User prefers dark mode.",
document_type="ai-chat-conversation",
user_id="user_123",
customer_id="acme_corp",
mode="fast",
)
# From synchronous code
result = asyncio.run(ingest())
```
The SDK raises typed exceptions. Catch specific exceptions for fine-grained error handling:
```python theme={null}
import uuid
from maximem_synap import (
AuthenticationError, # raised when the API key is missing, malformed, or revoked
ContextNotFoundError, # raised when the conversation is unknown
RateLimitError, # raised after the SDK exhausts its automatic retries on rate-limited calls
ServiceUnavailableError, # raised when Synap is temporarily unavailable
InvalidInputError, # raised when the arguments to an SDK call are invalid
)
try:
context = await sdk.conversation.context.fetch(
conversation_id=str(uuid.uuid4()),
search_query=["user preferences"],
)
except RateLimitError as e:
# Automatic retry with backoff is built into the SDK.
# This exception is raised only after all retries are exhausted.
print(f"Retry after {e.retry_after}s")
except ContextNotFoundError:
print("Conversation not found")
```
The SDK automatically retries transient errors (rate limits, service-unavailable) with exponential backoff. See [Error Handling](/sdk/configuration) for the full reference.
Yes. Synap is framework-agnostic. The SDK operates independently of your LLM orchestration layer. Common integration patterns:
* **LangChain**: Use `sdk.conversation.context.fetch()` in a custom retriever, then pass the context to your chain.
* **LlamaIndex**: Use `await sdk.conversation.context.get_compacted(conversation_id=..., format='structured')` and inject it into your query engine.
* **Direct**: Call the SDK from your application code and pass context to any LLM API.
See the [First Integration](/setup/first-integration) guide for detailed examples.
## Memory
Retention is configurable per use-case via [MACA](/concepts/memory-architecture), which Synap generates automatically from your [use-case file](/concepts/memory-architecture#the-use-case-file). Compliance-sensitive agents get longer retention; consumer agents get shorter retention.
You can also delete individual memories at any time via [`sdk.memories.delete()`](/sdk-reference/memories/delete), regardless of the retention policy.
Yes. Use `sdk.memories.delete(memory_id)` to permanently delete a specific memory. Deletion removes the memory from both the vector store and graph store. Entity references are updated but the entities themselves are not deleted, as they may be referenced by other memories.
```python theme={null}
await sdk.memories.delete("mem_a1b2c3d4e5f67890")
```
Deletion is permanent and cannot be undone. See the [Memory API](/sdk-reference/memories/delete) for details.
The `mode` parameter controls a speed-quality tradeoff. Ingestion and retrieval use distinct mode value sets:
**Ingestion (`sdk.memories.create()`)** values: `"fast"` or `"long-range"` (default).
| Mode | Speed | Quality | Best For |
| ------------ | -------- | ------- | -------------------------------------------------------------- |
| `fast` | Highest | Good | Real-time chat ingestion, high-volume streams |
| `long-range` | Moderate | Highest | Important documents, support tickets, onboarding conversations |
**Retrieval (`sdk.conversation.context.fetch()`)** values: `"fast"` (default) or `"accurate"`.
| Mode | Latency | Method | Best For |
| ---------- | ------- | --------------------------- | ------------------------------------------------ |
| `fast` | Lower | Vector similarity only | Real-time chat, single-topic queries |
| `accurate` | Higher | Vector + graph + re-ranking | Relationship-aware queries, multi-entity context |
Actual latency depends on your Instance and workload. See **Dashboard → Usage** for real numbers.
The two value spaces are not interchangeable. Passing `"accurate"` to `memories.create()` or `"long-range"` to `context.fetch()` will be rejected.
Context fetch calls accept an optional `precision_level` parameter: `"high"` (default) or `"medium"`. With `high`, results go through an additional relevance-refinement pass before being returned; `"medium"` skips the refinement pass for faster responses. Recall isn't impacted — the same candidate memories are searched — but outputs are less precisely filtered.
Independent of `mode`; combine with either `fast` or `accurate`. For real latency on your instance, see **Dashboard → Usage**.
If you provide a `document_id` in the create memory request, Synap checks for duplicates. If a document with the same ID has already been ingested, the request is rejected as a duplicate (`InvalidInputError`).
If you do not provide a `document_id`, the document is ingested as a new record. The extraction pipeline may produce duplicate memories if the content overlaps with previously ingested documents. Entity resolution helps by linking entities across documents, but the memories themselves are stored independently.
For production use, we recommend always providing a `document_id` for deduplication.
## Configuration
Synap auto-generates each Instance's memory configuration from the [Use-Case Markdown file](/concepts/memory-architecture#the-use-case-file) you upload. To change behavior (enable different memory categories, shift the primary scope, update retention guidance), re-upload an updated use-case file in the Dashboard. Synap re-evaluates and applies the new configuration. The previous version is retained so you can roll back if needed.
No. Configuration updates are zero-downtime: in-flight requests complete on the previous configuration and new requests pick up the new one. There is no traffic interruption.
Existing memories keep their original scope and category assignments. The updated configuration governs **new** memories ingested after it takes effect, and it tunes retrieval/ranking behavior going forward. Memory data is not retroactively rewritten.
## Billing and Usage
Synap usage is measured across three dimensions:
* **API calls**: Each HTTP request to the API counts as one API call. Batch endpoints count as a single call regardless of batch size.
* **Token usage**: LLM tokens consumed during ingestion (extraction, categorization) and retrieval (re-ranking, compaction). Input and output tokens are tracked separately.
* **Storage**: Total memories stored across all instances. Measured as a monthly peak.
Use the [Dashboard Analytics](/dashboard/monitoring-and-analytics) to monitor your usage in real time.
Each HTTP request to any Synap API endpoint counts as one API call, including:
* Memory ingestion (single and batch)
* Context fetch and compaction
* Configuration operations
* Dashboard queries
* Analytics queries
* Status checks
Webhook deliveries do **not** count as API calls.
## Troubleshooting
Common causes and solutions:
1. **Missing or malformed API key**: Verify the API key string starts with `synap_` and is current in the Dashboard.
2. **Revoked key**: Check the Dashboard to verify the key is still active.
3. **Wrong instance**: The API key may not have access to the instance you are targeting.
See [Error Codes](/sdk-reference/errors#authentication-errors) for the full list of auth-related errors.
If context fetch returns empty results when you expect matches:
1. **Check ingestion status**: Verify using `sdk.memories.status(ingestion_id)`. Memories are not retrievable until ingestion completes.
2. **Check scope**: Memories are scoped to the user/customer that was specified during ingestion. Context fetch only returns memories within the conversation's scope chain.
3. **Check confidence threshold**: Memories with confidence below the MACA threshold (default 0.7) are discarded during ingestion.
4. **Check memory types**: If you are filtering by `types` in the fetch request, ensure the desired types are included.
5. **Check context budget**: If the budget is very small, only the highest-ranked memories may fit.
Use the Dashboard monitoring tools to inspect the ingestion pipeline and stored memories for debugging.
Steps for diagnosing retrieval problems:
1. **Get the correlation ID**: Capture the correlation ID returned by the SDK on the fetch response (or on the raised exception).
2. **Check analytics**: In the Dashboard, open **Analytics** to see if `context_fetch` latency is abnormal for your Instance.
3. **Try different modes**: Switch from `fast` to `accurate` mode to see if subquery decomposition and reranking surface additional results.
4. **Broaden the query**: Try more general search queries or remove type filters.
5. **Check compaction**: If the context was recently compacted, some memories may have been summarized away. Re-fetch with `format='narrative'` and `format='structured'` to compare what's available.
If the issue persists, [contact support](/resources/support) with the correlation ID and instance ID.