How-to

Pull the memory brief.

The memory brief is the fastest way to personalize your app: a single call returns a short, plain-language portrait of the user — synthesized from their cross-app memory — that you can drop straight into a model's system prompt or render in your UI. It is the cheapest first step before you reach for richer reads. Your app brings the persona; PAMbase brings the person.

Prerequisites

You hold a connection token (see Connect an app) and that token includes the identity:read scope. A scope is one permission; this one lets you read the user's display name and the brief. Examples below use Margin, a reading companion built on PAMbase.

The one-call portrait (drop into any LLM)

systemPrompt() returns a ready-made system string — already framed as instructions for a model. Use it when you host your own model and just want grounding with zero assembly.

typescript

const system = await pambase.systemPrompt();
// → a 200–700 char portrait, written as system instructions.
// Drop it straight into the "system" field of any LLM call.

The structured response

getIdentityBrief() returns the same portrait plus metadata, so you can decide whether to refresh, show a timestamp, or skip personalization for a brand-new user. Here is a realistic response for a Margin user:

typescript

const r = await pambase.getIdentityBrief();
// {
//   brief: "Reads widely on distributed systems and infrastructure; enjoys " +
//          "long-form essays over quick takes. Recently saving highlights on " +
//          "rate limiting and consensus. Working toward reading 24 books this year.",
//   ai_name: "My memory",
//   generated_at: "2026-05-22T20:14:09.412Z",
//   source_memory_count: 14,
//   cached: false
// }

What each field means

Field	Type	What it tells you
`brief`	string	The synthesized portrait — high-signal facts, themes, goals, and any tone preference the user set. This is the part you feed a model or surface in your UI.
`ai_name`	string	The user's label for their memory (e.g. “My memory”). Display it; never assume a persona or character from it.
`generated_at`	ISO string	When this brief was synthesized. Useful to show “last updated” or to decide on a manual refresh.
`source_memory_count`	number	How many memories fed the synthesis. `0` means a new or empty store — skip personalization and show a neutral first-run experience.
`cached`	boolean	`true` means this came from the server-side cache (a near-instant, no-cost hit); `false` means it was freshly synthesized.

Why caching matters — call it freely

The brief is cached server-side for ~5 minutes per (user, scope-set). Synthesis is the expensive part; the cache makes repeat calls near-instant and cheap. So call it on every new conversation (it almost always hits cache, cached: true), on a user-triggered “refresh,” or daily via cron — you don't need to store or reuse the result yourself.

Margin in practice

When a Margin user opens the app, Margin fetches the brief and uses it to greet them and seed its recommendation chat. It checks source_memory_count first so new users get a clean welcome instead of an empty-sounding one:

margin/home.ts

const r = await pambase.getIdentityBrief();

if (r.source_memory_count === 0) {
  // New or empty store — don't fake familiarity.
  renderWelcome("Save your first highlight to start personalizing Margin.");
} else {
  renderWelcome(`Welcome back. ${r.brief}`);
  // Reuse the same portrait to ground Margin's own model:
  const system = await pambase.systemPrompt();
  myReadingModel.setSystem(system);
}

Expected result: a returning reader sees a greeting grounded in their actual interests (“…essays on distributed systems…”), while a first-time user sees a neutral prompt — all from one call.

The raw endpoint

If you are not using the SDK, the brief is a single authenticated GET:

bash

curl https://api.pambase.io/v1/identity/brief \
  -H "Authorization: Bearer $PAMBASE_CONNECTION_TOKEN"

Required scope & what stays private

The connection token must include identity:read. The brief is automatically filtered to the memory scopes your token can read — you can never surface memories your token wasn't granted, and identity:read itself exposes only a display name and the optional tone note, nothing more. See Permissions.

Audit & usage

Every fetch is logged in the user's audit trail as brief.fetch and counts toward your app's usage. Users see your app under Connected apps with a per-scope explanation and can revoke at any time.

What to expect next

The brief is a summary. When you need the underlying memories — to drive UI logic or feed your own model — move to context. When you want PAMbase to host the conversation, use chat.

Request context — the structured memories behind the brief.
Identity — exactly what is and isn't exposed about a person.
Host the AI — let PAMbase ground and run the model for you.