Quickstart

Five minutes to your first memory. This page walks you through dashboard → install → ingest → search end-to-end. Code blocks below are tabbed for Python, Node, and cURL — pick your stack.

Get your API key

Open app.memsy.io, create an account, and create an org (or pick an existing one).

Then in Settings → API Keys:

Click Create key and give it a label (local-dev works).
Copy the key — it's shown once and looks like memsy_live_xxxxxxxxxxxx.
While you're there, copy your API base URL (e.g. https://api.memsy.io/v1).

Info

Screenshots coming soon. For the detailed walkthrough (verification, teammates, rotation) see Sign Up.

Install the SDK

pip install memsy

Python 3.10, 3.11, 3.12, or 3.13 required.

npm install @memsy-io/memsy

Node 18+ required (uses the global fetch).

Nothing to install — curl is preinstalled on macOS and most Linux distros.

See Installation for uv, poetry, pnpm, yarn, and dev extras.

Set your credentials

export MEMSY_BASE_URL="https://api.memsy.io/v1"
export MEMSY_API_KEY="memsy_live_xxxxxxxxxxxx"

Tip

Put these in a .env file for local dev — and keep .env in .gitignore.

Remember something

Send a batch of events. The call returns immediately; processing happens server-side.

import os
from memsy import MemsyClient, EventPayload

client = MemsyClient(
    base_url=os.environ["MEMSY_BASE_URL"],
    api_key=os.environ["MEMSY_API_KEY"],
)

result = client.ingest([
    EventPayload(
        actor_id="user_42",
        session_id="session_1",
        kind="user_message",
        content="I prefer dark mode in all apps.",
    ),
    EventPayload(
        actor_id="user_42",
        session_id="session_1",
        kind="assistant_message",
        content="Got it — I'll use dark mode by default.",
    ),
])

print(result.event_ids)
# ['01JK...', '01JK...']

For an async variant (AsyncMemsyClient) see Async Client.

import { MemsyClient } from '@memsy-io/memsy';

const client = new MemsyClient({
  baseUrl: process.env.MEMSY_BASE_URL!,
  apiKey: process.env.MEMSY_API_KEY!,
});

const result = await client.ingest([
  {
    actorId: 'user_42',
    sessionId: 'session_1',
    kind: 'user_message',
    content: 'I prefer dark mode in all apps.',
  },
  {
    actorId: 'user_42',
    sessionId: 'session_1',
    kind: 'assistant_message',
    content: "Got it — I'll use dark mode by default.",
  },
]);

console.log(result.eventIds);
// ['01JK...', '01JK...']

The Node SDK is async-only — every method returns a Promise<T>.

curl -X POST "$MEMSY_BASE_URL/ingest" \
  -H "Authorization: Bearer $MEMSY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      {
        "actor_id": "user_42",
        "session_id": "session_1",
        "kind": "user_message",
        "content": "I prefer dark mode in all apps."
      },
      {
        "actor_id": "user_42",
        "session_id": "session_1",
        "kind": "assistant_message",
        "content": "Got it — I'\''ll use dark mode by default."
      }
    ]
  }'

Note the wire format uses snake_case (actor_id, session_id). The SDKs accept camelCase / snake_case ergonomically and serialize for you.

Recall it

Ask in plain English. The SDK returns ranked memories.

results = client.search("user preferences", actor_id="user_42")

for r in results.results:
    print(f"{r.score:.2f}  {r.content}")
# 0.84  User prefers dark mode across apps.

const results = await client.search('user preferences', {
  actorId: 'user_42',
});

for (const r of results.results) {
  console.log(`${r.score.toFixed(2)}  ${r.content}`);
}
// 0.84  User prefers dark mode across apps.

curl -X POST "$MEMSY_BASE_URL/search" \
  -H "Authorization: Bearer $MEMSY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "user preferences",
    "actor_id": "user_42",
    "limit": 10,
    "threshold": 0.0
  }'

What just happened?

In three calls you:

Ingested raw events over HTTPS with Bearer-token auth.
Memsy queued them and ran extraction → embeddings → indexing on its worker pool.
Searched a semantic index and got back ranked results.

And as a bonus:

Every authenticated response has usage (X-Usage-*) and rateLimit / rate_limit (X-RateLimit-Limit/-Remaining/-Reset) populated — you already know how much of your plan you've used and how many calls remain.
Rate-limited calls (HTTP 429) are retried automatically with exponential backoff. No code to write.
HTTP errors come back as typed exceptions in both SDKs (AuthenticationError/MemsyAuthError, UsageLimitExceeded, MemsyRateLimitError, …).

What's next

Events vs. memories

The mental model: what you send vs. what Memsy stores.

Searching memory

Thresholds, limits, actor scoping, reading scores.

Error handling

Catch the right exception for auth, quota, and rate-limit failures.

API reference

Python and Node — every class, method, and model.