Agent identity

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.

Send identity headers alongside the token

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 });