Quickstart

Four steps to get MemoryOS working with your AI:

1. Install the SDK
2. Store a memory
3. Retrieve memories
4. Use context in a model call

For the cross-agent Memory Passport flow, see Cross-agent memory sharing. For domain-specific products, the same calls below still apply - enable your domain first, then use:

• EdTech tutor cookbook
• Support agent cookbook

Step 1: Install

# Python
pip install memoryos openai

# TypeScript
npm install @memoryos/sdk openai

For solo builders: start without source metadata

Use this path for MVPs, single-agent products, and small SaaS apps. It is the recommended first integration.

Step 2: Store a memory

Python

import os
from memoryos import Memory

client = Memory(api_key=os.environ["MEMORYOS_API_KEY"])

result = client.add(
    messages=[
        {
            "role": "user",
            "content": "Please remember that I prefer concise technical explanations and Python examples.",
        }
    ],
    external_user_id="customer-123",
)

print(result.status)   # "queued"
client.close()

Step 3: Retrieve memories

Python

import os
from memoryos import Memory

client = Memory(api_key=os.environ["MEMORYOS_API_KEY"])

memories = client.get(
    query="How should I answer this user?",
    external_user_id="customer-123",
    limit=5,
)

if memories.has_context:
    print(memories.system_prompt_addition)

client.close()

Step 4: Use context in an AI call

Retrieve before the model call. Prepend system_prompt_addition when available. Always call the LLM - even if memory is empty or in passthrough.

Python

import os
from memoryos import Memory
from openai import OpenAI

memory = Memory(api_key=os.environ["MEMORYOS_API_KEY"])
openai_client = OpenAI(api_key=os.environ["OPENAI_API_KEY"])

external_user_id = "customer-123"
user_message = "What kind of answer format do I like?"

memories = memory.get(query=user_message, external_user_id=external_user_id, limit=5)

system_prompt = "You are a helpful assistant."
if memories.has_context:
    system_prompt = f"{system_prompt}\n\n{memories.system_prompt_addition}"

response = openai_client.responses.create(
    model="gpt-4.1-mini",
    input=[
        {"role": "system", "content": system_prompt},
        {"role": "user", "content": user_message},
    ],
)

print(response.output_text)
memory.close()

For multi-service companies: add source metadata later

Use this only when multiple backend services write memory for the same user, such as Billing, Support, CRM, and Product. This enables provenance, deduplication, conflict handling, and source-of-truth routing.

Python

import os
from memoryos import Memory

client = Memory(api_key=os.environ["MEMORYOS_API_KEY"])

client.add(
    external_user_id="customer-123",
    messages=[{"role": "assistant", "content": "Customer is on the Growth plan."}],
    source=Memory.source(
        "billing-service",
        event_id="invoice_evt_8842",
        scope={"workspace_id": "ws_123"},
        evidence=[{"source_type": "billing_record", "reference": "invoice_evt_8842"}],
    ),
)

client.close()

For production multi-service traffic, register service writers in the Tenant Dashboard and bind dedicated API keys. You can still start by passing source.service with one tenant API key while testing.

What to expect

• add() returns queued, passthrough, or a quality gate block - not an error
• get() always returns a typed result, even with zero memories
• is_passthrough / isPassthrough being true means skip memory context but still call the LLM
• system_prompt_addition is safe to prepend as-is
• if your tenant has a domain schema enabled, system_prompt_addition includes domain-aware context automatically

Next steps

• Authentication - key format, permissions, and identity model
• Python SDK reference
• TypeScript SDK reference
• Domain schemas