Keep user-owned memory boundaries explicit as clients and agents move between projects and sessions.
Bucket and scope are different boundaries
Bucket is the storage namespace. Scope is the project, session or team boundary used for retrieval. Keeping them separate is what lets one account hold several projects without their memories bleeding into each other.
- bucket — storage namespace, commonly work for agent process memory.
- scope — explicit project/session/team grouping applied at retrieval time.
- path — logical location inside a scope, filtered with an ILIKE pattern.
- team_id — restricts retrieval to one team the caller can already access.
Retrieve inside one scope
Pass scope on a search to keep results inside one project boundary. Scope is validated against the authenticated token; it cannot widen access.
GET /v1/memories/search?query=MCP%20token%20context&scope=memory-os&memory_type=semantic&limit=5
X-API-Key: <your-assigned-api-key>
Scope from the SDK
The TypeScript client takes the same boundary arguments, so capture and recall stay inside the project the caller is authorized for.
const search = await client.search('MCP token context', {
scope: 'memory-os',
memoryType: 'semantic',
candidateCount: 20,
explain: true,
});
Persona flows
ChatGPT user
Give ChatGPT durable access to your XMemo preferences, project facts, decisions, and TODOs without pasting bearer tokens into a chat.
Save a synthetic preference or project note, start a new chat, then ask ChatGPT to recall it through XMemo before continuing work.
Copilot / Codex developer
Carry repo decisions, coding conventions, bug-fix notes, and task history between IDE and CLI agents.
Record a codebase decision or bug fix, then ask the next IDE or CLI agent to recall the relevant XMemo context before editing.
Team / enterprise pilot owner
Evaluate shared memory with account controls, source attribution, export/delete workflows, and reviewer-safe setup evidence.
Have a pilot member save a synthetic team memory, confirm source attribution in XMemo, then review delete/export and support paths.