> ## Documentation Index
> Fetch the complete documentation index at: https://docs.memoryo.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/guides/cross-agent-sharing).
For domain-specific products, the same calls below still apply - enable your domain first, then use:

* [EdTech tutor cookbook](/cookbooks/edtech-tutor)
* [Support agent cookbook](/cookbooks/support-agent)

## Step 1: Install

```bash theme={null}
# 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

<CodeGroup>
  ```python Python theme={null}
  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()
  ```

  ```ts TypeScript theme={null}
  import { MemoryOS } from "@memoryos/sdk";

  const client = new MemoryOS(process.env.MEMORYOS_API_KEY!);

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

  console.log(result.status); // "queued"
  ```
</CodeGroup>

## Step 3: Retrieve memories

<CodeGroup>
  ```python Python theme={null}
  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()
  ```

  ```ts TypeScript theme={null}
  import { MemoryOS } from "@memoryos/sdk";

  const client = new MemoryOS(process.env.MEMORYOS_API_KEY!);

  const memories = await client.get("How should I answer this user?", "customer-123", 5);

  if (memories.hasContext) {
    console.log(memories.systemPromptAddition);
  }
  ```
</CodeGroup>

## 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.

<CodeGroup>
  ```python Python theme={null}
  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()
  ```

  ```ts TypeScript theme={null}
  import OpenAI from "openai";
  import { MemoryOS } from "@memoryos/sdk";

  const memory = new MemoryOS(process.env.MEMORYOS_API_KEY!);
  const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY! });

  const externalUserId = "customer-123";
  const userMessage = "What kind of answer format do I like?";

  const memories = await memory.get(userMessage, externalUserId, 5);

  let systemPrompt = "You are a helpful assistant.";
  if (memories.hasContext) {
    systemPrompt = `${systemPrompt}\n\n${memories.systemPromptAddition}`;
  }

  const response = await openai.responses.create({
    model: "gpt-4.1-mini",
    input: [
      { role: "system", content: systemPrompt },
      { role: "user", content: userMessage },
    ],
  });

  console.log(response.output_text);
  ```
</CodeGroup>

## For multi-service companies: add source metadata later

<Warning>
  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.
</Warning>

<CodeGroup>
  ```python Python theme={null}
  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()
  ```

  ```ts TypeScript theme={null}
  import { MemoryOS } from "@memoryos/sdk";

  const client = new MemoryOS(process.env.MEMORYOS_API_KEY!);

  await client.add(
    [{ role: "assistant", content: "Customer is on the Growth plan." }],
    "customer-123",
    undefined,
    undefined,
    MemoryOS.source("billing-service", {
      eventId: "invoice_evt_8842",
      scope: { workspaceId: "ws_123" },
      evidence: [{ sourceType: "billing_record", reference: "invoice_evt_8842" }],
    }),
  );
  ```
</CodeGroup>

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](/authentication) - key format, permissions, and identity model
* [Python SDK reference](/sdk/python)
* [TypeScript SDK reference](/sdk/typescript)
* [Domain schemas](/concepts/domain-schemas)