Use stable, non-secret agent and instance labels so later recalls retain source context.
Identity labels are attribution, not authentication
X-Memory-OS-Agent-ID and XMEMO_AGENT_INSTANCE_ID identify which client or runner wrote a memory. They never authorize access — the bearer token or OAuth grant does that. Sending them lets the Memory Console show provenance for every entry.
- Keep XMEMO_AGENT_INSTANCE_ID stable for the same local install or runner.
- Generate a different value for a different local agent profile.
- Keep the value out of git; it is not a secret but it is per-install state.
- XMemo hashes the instance id server-side for stable attribution.
Identity headers sit next to Authorization in the MCP client configuration. The token stays in the environment; the labels are plain values.
{
"mcpServers": {
"XMemo": {
"type": "http",
"url": "https://xmemo.dev/mcp",
"headers": {
"Authorization": "Bearer ${env:XMEMO_KEY}",
"X-Memory-OS-Agent-ID": "codex",
"X-Memory-OS-Agent-Instance-ID": "${env:XMEMO_AGENT_INSTANCE_ID}"
}
}
}
}
Generate a stable instance id
The SDK ships helpers so a setup script can create the value once per local profile and reuse it on later runs.
import {
XMEMO_AGENT_ID_ENV_VAR,
XMEMO_AGENT_INSTANCE_ID_ENV_VAR,
buildMcpIdentityHeaders,
createAgentInstanceId,
} from '@xmemo/client';
const agentId = 'gemini-cli';
const agentInstanceId = existingStoredValue ?? createAgentInstanceId('gemini-cli');
const headers = buildMcpIdentityHeaders({ agentId, agentInstanceId });
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.