Separate the non-secret installation label used for attribution from the credential that authorizes requests.
An instance id is not a credential
XMEMO_AGENT_INSTANCE_ID identifies a local client or runner instance; it does not authorize a request. The API key or OAuth grant is the access credential. The server derives an agent_instance_id_hash from the instance value and reports the boundary authority as attribution_only.
- Credential: X-API-Key or the accepted OAuth bearer grant controls access.
- Instance label: X-Memory-OS-Agent-Instance-ID lets the server compare the writing runner with a later caller.
- Agent label: X-Memory-OS-Agent-ID identifies the logical agent separately from one installation.
Normalize, then hash
The runtime trims an instance id, rejects an empty value, and accepts at most 256 characters before hashing it with SHA-256. A stored hash is normalized as sha256:<64 hexadecimal characters>; malformed pre-hashed values are ignored rather than treated as credentials.
from memory_manager.auth.agent_identity import agent_instance_id_hash
instance_hash = agent_instance_id_hash("codex-local-install")
# sha256:<64 hexadecimal characters>
Keep one value per local installation
Persist one non-secret instance value outside the repository and send it with the access credential. Reuse it after a restart for the same install; choose a different value for a different local profile.
X-API-Key: <your-assigned-api-key>
X-Memory-OS-Agent-ID: codex
X-Memory-OS-Agent-Instance-ID: <stable-local-instance-id>
Boundary semantics are explicit
memory_agent_boundary compares the caller's agent_id and instance hash with the row's values. Matching both is self; a matching agent_id with another hash is same_agent_other_instance; missing comparable identity is reported as unverified or unknown. These labels explain attribution and do not replace token authorization.
{
"relation": "self",
"ownership": "current_agent",
"boundary_authority": "attribution_only",
"current_agent_trust": "client_asserted"
}
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.