Guides

Personalization

Build per-user persistent context by tagging memories with the user’s id and using X-End-User-ID on writes/reads. Persona facts live alongside event memories; recall reranks them naturally because the persona is recent and high-importance.

Model

Persona memories — durable preferences (UI, language, tone, allergens).
Event memories — what the user did or said, time-bounded.
Decision memories — outcomes you want to honor (subscriptions, opt-outs).

Capture preferences

TYPESCRIPT

await ms.memory.add({
  text: "User Alice prefers concise replies and uses dark mode.",
  source: "preferences",
  tags: ["persona", "ui"],
  importance: 0.85,
  metadata: { user_id: "alice@acme.com" },
})

// Use header to keep multi-tenant separation if you're a B2B platform:
await fetch("/memory/add", {
  headers: {
    Authorization: `Bearer ${MS_KEY}`,
    "X-End-User-ID": "alice@acme.com",
    "X-Project-ID": "prj_chatbot",
  },
  body: JSON.stringify({ text: "...", tags: ["persona"], importance: 0.85 })
})

Retrieve at the right time

Don’t fetch persona on every turn — fetch it on session start and cache it in your prompt builder. Re-fetch when the user signals a new preference.

TYPESCRIPT

const persona = await ms.memory.query({
  query: "preferences and persona facts",
  k: 8,
  filters: { tags: ["persona"] },
  weights: { semantic: 0.3, importance: 0.5, recency: 0.2 },
  sessionId: "alice@acme.com",
})

Resolving conflicts

If the user says “actually use light mode now,” the new memory is added but the older one still exists. The intelligence pipeline detects conflict via entity-level contradiction during clustering and exposes it on GET /memory/decisions. Resolve programmatically with POST /memory/decision/resolve to pick a winner.

Privacy

Tag PII memories with tags: ["pii"] — they require reason on forget and follow stricter retention.
For B2B, use X-End-User-ID; per-end-user data isolation is enforced server-side.
Use POST /v1/users/{external_id}/erase for GDPR-style erasure of all memories tied to an end user.