Store and recall memory

Step 1

Write to private memory

Store durable facts that an agent can use across runs, such as preferences, decisions, verified fixes, and reusable procedures. Every write is tied to the authenticated user and organization.

Use active for normal memory and draft for incomplete material. Use canonical for stable facts that automatic reconciliation must protect.

Lifecycle status and review status are separate. New memory starts unreviewed, including canonical memory. Use the REST review operation after explicit review. The model-facing MCP tools cannot mark their own memories as reviewed.

import { serenMemoryRemember } from "@serendb/sdk";

const { data, error } = await serenMemoryRemember({
  body: {
    content: "The release approval owner is the on-call lead.",
    memory_type: "semantic",
    lifecycle_status: "active",
    importance: 4,
  },
});
if (error) throw error;

Step 2

Recall it for a task

Recall retrieves the memories most relevant to a query across semantic, keyword, ranking, and connection signals. Optional time bounds narrow the search to a period.

Convert phrases such as "last week" into explicit UTC created_after and created_before values before recall. If semantic search is unavailable, hybrid recall uses keyword retrieval. Inspect the returned signals to explain this condition.

import { serenMemoryRecall } from "@serendb/sdk";

const { data, error } = await serenMemoryRecall({
  body: {
    query: "release approval process",
    limit: 5,
    created_after: "2026-06-01T00:00:00Z",
  },
});
if (error) throw error;

console.log(data.data.memories);
console.log(data.data.signals.semantic_available);

Step 3

Retain a completed conversation

Process a completed turn with a stable source ID when an application needs durable provenance. Repeating the same source ID and content is idempotent. A changed revision replaces the earlier derived memories for that source.

Seren stores the raw transcript separately and links it to extracted facts. As a result, private source text does not become recall content. This retained-source workflow is separate from automatic lifecycle hooks. Automatic hooks do not retain the raw transcript payload.

import { serenMemoryProcessConversation } from "@serendb/sdk";

const { data, error } = await serenMemoryProcessConversation({
  body: {
    transcript: "User: Keep releases reversible.

Assistant: I will add rollback steps.",
    project_context: "release automation",
    retain_source: true,
    source_external_id: "desktop:message:018f-example",
    source_revision: "1",
    source_uri: "seren://desktop/conversations/release/messages/018f-example",
  },
});
if (error) throw error;

console.log(data.data.conversation_source_id);
console.log(data.data.stored_memory_ids);

Step 4

Ingest source-managed notes

Use the document ingestion operation for notes that remain owned by another source. Seren Notes uses ProseMirror and can provide its document directly.

For Notion, convert page blocks to ProseMirror. Keep connector credentials and synchronization state outside Memory content. Use the Notion page ID as the stable external source ID.

A newer source revision updates the same memory and preserves earlier revisions. To change a managed note, ingest the source again. Direct updates and appends are rejected.

import { serenMemoryIngestDocument } from "@serendb/sdk";

const { data, error } = await serenMemoryIngestDocument({
  body: {
    memory_type: "semantic",
    source_kind: "notion",
    source_external_id: "page_abc123",
    source_revision: "2026-07-13T14:30:00Z",
    source_uri: "https://www.notion.so/page_abc123",
    document: {
      type: "doc",
      content: [
        {
          type: "paragraph",
          content: [{ type: "text", text: "Release approval belongs to the on-call lead." }],
        },
      ],
    },
  },
});
if (error) throw error;

console.log(data.data.action);

Step 5

Read governed knowledge

Organizational knowledge is the separate, read-only surface for curated facts. Start by listing the knowledge domains available to the current user and agent. Then pass the selected domain_id to search, entity, and operation requests. If you omit the identifier, Seren selects the default organization-visible domain. Agents can follow connections only inside the selected domain.

Restricted domains use direct grants rather than keywords. A human request needs a user grant. An agent request needs both a grant for the authenticated user and a reader grant for the authenticated agent. For example, granting an engineering user access to engineering knowledge does not grant that user or their agent access to a restricted financial domain. Domain classification is descriptive metadata and is never used as an authorization shortcut.

Organization owners and administrators create domains. Each domain's owner then controls direct grants, and every domain or grant change is recorded for audit. Seren uses TLS and encrypted database storage for Memory data. Organization isolation and grants determine who can query published knowledge.