Events and Memories

Memsy splits your data into two distinct things: events (raw input) and memories (extracted, searchable output).

Events: the raw input

An event is an immutable record of something that happened in your application. You send events to Memsy; you never edit them after the fact.

In the SDKs an event is an EventPayload:

from memsy import EventPayload

EventPayload(
    actor_id="user_42",
    session_id="session_1",
    kind="user_message",
    content="I prefer dark mode in all apps.",
    ts=None,            # optional ISO-8601 timestamp; defaults to "now" server-side
    metadata=None,      # optional JSON-serialised string
)

import type { EventPayload } from '@memsy-io/memsy';

const event: EventPayload = {
  actorId: 'user_42',
  sessionId: 'session_1',
  kind: 'user_message',
  content: 'I prefer dark mode in all apps.',
  // ts: '2026-03-15T14:22:10Z',  // optional
  // metadata: JSON.stringify({...}),  // optional, JSON string
};

{
  "actor_id": "user_42",
  "session_id": "session_1",
  "kind": "user_message",
  "content": "I prefer dark mode in all apps."
}

Event kinds

Kind	When to use it
`user_message`	A message authored by the end user.
`assistant_message`	A reply generated by your AI.
`tool_result`	Output from a tool/function call your assistant made.
`app_event`	Anything else — domain events, lifecycle events, custom signals.

When do events show up in search?

Never, directly. Search always returns memories, not events. If you want the original source events alongside results, pass include_source_events=True (Python) / includeSourceEvents: true (Node) to search().

Memories: the extracted output

A memory is something Memsy has distilled from one or more events — a stable fact about an actor or session, written in natural language, embedded into a vector space, and indexed for semantic retrieval. You don't create memories directly; Memsy creates them from your events.

In the SDKs a memory surfaces as a SearchResult:

from memsy import SearchResult  # returned from client.search()

SearchResult(
    id="mem_01JK...",
    content="User prefers dark mode across apps.",
    score=0.84,
    metadata={"actor_id": "user_42"},
)

import type { SearchResult } from '@memsy-io/memsy';

const result: SearchResult = {
  id: 'mem_01JK...',
  content: 'User prefers dark mode across apps.',
  score: 0.84,
  metadata: { actor_id: 'user_42' },
};

{
  "id": "mem_01JK...",
  "content": "User prefers dark mode across apps.",
  "score": 0.84,
  "metadata": { "actor_id": "user_42" }
}

Typical flow

  your app                    Memsy
  ────────                    ─────
  build EventPayload
          │
          ▼
    ingest(events) ─────────► queue + extract + embed + index
                                            │
                                            ▼
                                       memory store
                                            ▲
                                            │
    search("...")  ◄───── rank + return ───┘

Events are cheap to produce; memories are created lazily. That's why ingest() returns immediately while search() reads from the processed index.

How actors and sessions scope your data → Actors and Sessions.
Why ingest is async → Async Processing.

Events: the raw input

Event kinds

When do events show up in search?

Memories: the extracted output

Typical flow

Next