Skip to main content

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.

You don’t always need an entity graph and typed extractions. Sometimes you just want “given a query, return the most relevant chunks of this user’s past conversations.” Synap does this too — its ContextResponse is queryable like a vector store, with the bonus that retrieval is automatically scoped to the user.
from maximem_synap import MaximemSynapSDK, ContextType

sdk = MaximemSynapSDK()
await sdk.initialize()

async def search_user_history(user_id: str, customer_id: str, query: str, top_k: int = 8):
    """Pure RAG: return raw memory chunks ranked by relevance to `query`."""
    ctx = await sdk.user.context.fetch(
        user_id=user_id,
        customer_id=customer_id,
        search_query=[query],
        max_results=top_k,
        types=[ContextType.FACTS, ContextType.EPISODES],
        mode="accurate",                # graph-aware ranking
    )

    # Sort facts and episodes by relevance using their respective scores
    hits = (
        [(f.confidence, "fact", f.content) for f in ctx.facts] +
        [(e.significance, "episode", e.summary) for e in ctx.episodes]
    )
    hits.sort(key=lambda h: h[0], reverse=True)
    return hits[:top_k]


async def rag_chat(user_id: str, customer_id: str, user_message: str) -> str:
    hits = await search_user_history(user_id, customer_id, user_message)

    citations = "\n".join(f"[{i+1}] ({kind}) {text}" for i, (score, kind, text) in enumerate(hits))
    system_prompt = (
        "Answer the user's question using ONLY the citations below. "
        "Cite by number. If the answer isn't in the citations, say you don't know.\n\n"
        f"Citations:\n{citations}"
    )

    completion = await openai.chat.completions.create(
        model="gpt-4o",
        messages=[
            {"role": "system", "content": system_prompt},
            {"role": "user", "content": user_message},
        ],
    )
    return completion.choices[0].message.content
Why this works without your own vector DB
  • Synap embeds every ingested document at ingest time and stores the vectors in its vector engine.
  • mode="accurate" combines vector similarity with graph traversal — so a query about “the project Bob is leading” pulls memories about Bob even if Bob isn’t named in the query verbatim.
  • All retrievals are scoped — you cannot accidentally fetch another user’s data.
When this isn’t enough If you have non-conversational sources (PDFs, knowledge base articles, web pages) that you want to retrieve over, you have two options:
  1. Ingest them into Synap with document_type="document" at the CUSTOMER or CLIENT scope. They become part of the same retrieval surface as user history.
  2. Keep a separate vector DB for the document corpus and merge results at the application layer. Use Synap for memory only.
Option 1 is simpler and gets you scope-aware retrieval for free. Option 2 makes sense if you already have a doc corpus indexed and don’t want to re-ingest. Comparing to a raw vector DB
Pure pgvector / PineconeSynap
SetupDB + embed model + retrieval pipelinepip install maximem-synap
Per-user isolationYou build itNative (user_id scope)
Multi-source merge (chat + docs)ManualNative
Re-ranking by recency / significanceManualBuilt in
CostPay for compute + storage + embedding APIPer-call pricing
If “I just want a vector DB” is genuinely all you want, pgvector is cheaper. If you’re going to end up building scope isolation, multi-source merge, and reranking on top of pgvector, you’re rebuilding Synap.