What XMemo stores
XMemo keeps durable context that stays useful after the current chat or task ends: project facts, decisions, preferences, corrections and handoff notes. Transient conversation noise, one-off answers and raw tool output do not belong in memory.
- semantic — durable facts and decisions that stay true across sessions.
- episodic — something that happened, tied to a moment in a task or session.
- procedural — how a task is performed in this project.
- working — active state for the task currently in progress.
- identity — stable information about the owner or the agent itself.
Write a durable memory
A durable write needs the content, a logical path that attaches it to a project or namespace, and the memory type. The path is what later recalls filter on.
remember({
content: "Use OAuth for hosted ChatGPT connections.",
path: "projects/memory-os/decisions"
})Memory types in the SDK
MemoryCandidate.memory_type accepts the same set through the TypeScript SDK, so a normalized agent event carries the type it should be stored under.
import { normalizeAgentEvent, toMemoryCandidate } from '@xmemo/client';
const event = normalizeAgentEvent(
{ type: 'command_completed', command: 'pytest', exit_code: 0, output: '12 passed' },
{ source: 'shell', defaultAgentId: 'codex' },
);
console.log(toMemoryCandidate(event).memory_type); // episodicInteractive Provenance and Lifecycle Walkthrough (Synthetic Demo)
A step-by-step verifiable lifecycle demonstration showing memory creation, cross-client retrieval, realtime user correction with version supersession (v1 -> v2), token budget protection, soft-deletion tombstoning, and isolated synthetic teardown. Every step is backed by disposable runtime evidence with zero exposure of real user memories:
- Step 1 [STATE_1_CREATED_ACTIVE_V1]: Agent A (Claude Desktop) writes initial preference with immutable author, instance hash, and device metadata via tools.py::remember — Receipt: Status 200 OK, demo_mem_lifecycle_001@v1, active — Status: [SOURCE_BACKED_PUBLIC_CONTRACT (VERIFIED)] — Boundary: [DEMO_DATA: SYNTHETIC].
- Step 2 [STATE_2_ACCESSED_ATTRIBUTED]: Agent B (Codex CLI) in the same authorized scope immediately retrieves the memory with citation receipt and zero cross-client drift via tools.py::recall — Receipt: Status 200 OK, cited demo_mem_lifecycle_001@v1 — Status: [SOURCE_BACKED_PUBLIC_CONTRACT (VERIFIED)] — Boundary: [DEMO_DATA: SYNTHETIC].
- Step 3 [STATE_3_CORRECTED_SUPERSEDED_V2]: User corrects the meeting room and time via tools.py::update_memory. VersionController creates an immutable snapshot of v1 with status='superseded' and bumps active record to v2 — Receipt: Status 200 OK, v2, parent v1, diff: Room Orion -> Room Polaris — Status: [SOURCE_BACKED_PUBLIC_CONTRACT (VERIFIED)] — Boundary: [DEMO_DATA: SYNTHETIC].
- Step 4 [STATE_4_RETRIEVAL_FILTERED]: Subsequent recall query selects only active v2 while obsolete v1 is strictly filtered out of LLM context window to prevent hallucinations and conserve token budget — Receipt: Status 200 OK, selected v2, superseded v1 excluded — Status: [SOURCE_BACKED_PUBLIC_CONTRACT (VERIFIED)] — Boundary: [DEMO_DATA: SYNTHETIC].
- Step 5 [STATE_5_TOMBSTONE_DELETED]: Owner marks fact as deleted via tools.py::forget. It is immediately excluded from recall candidate queries and moved to Trash view with Restore action — Receipt: Status 200 OK, status: deleted, candidate_count: 0 — Status: [SOURCE_BACKED_PUBLIC_CONTRACT (VERIFIED)] — Boundary: [DEMO_DATA: SYNTHETIC].
- Step 6 [STATE_6_RESET_PURGED]: Isolated disposable teardown (reset_synthetic_state) purges demo scope records to exactly 0 residual rows on disk. Personal account hard-reset (POST /api/v1/me/memories/reset) is strictly excluded — Receipt: teardown_status: SUCCESS_PURGED, residual_rows: 0, account_hard_reset_called: FALSE — Status: [SOURCE_BACKED_PUBLIC_CONTRACT (VERIFIED)] — Boundary: [DEMO_DATA: SYNTHETIC].
+------------------------------------------------------------------------------------------------------------------------+
| [PROVENANCE & LIFECYCLE 6-STATE STATE MACHINE: DISPOSABLE HARNESS WALKTHROUGH] |
| |
| Agent A (Claude Desktop) XMemo FastMCP & Engine Agent B (Codex CLI) Demo Owner (Supervising) |
| [04f9b8c2 / MacBook] [VersionController / Scope] [e81d7a31 / Workstation] [user:demo_owner] |
| | | | | |
| (1) remember(sync in Orion) | | | |
| -------------------------------------> | | | |
| | [STATE 1: Created Active v1] | | |
| <------------------------------------- | | | |
| Receipt: mem-001@v1 | | | |
| | | (2) recall(sync) | | |
| | | <--------------------------- | | |
| | | [STATE 2: Cited @v1] | | |
| | | ---------------------------> | | |
| | | Citation: mem-001@v1 | | |
| | | | (3) update_memory(Polaris) | |
| | | <---------------------------------------------------------- | |
| | | [STATE 3: Bump v2, Supersede v1] | |
| | | ----------------------------------------------------------> | |
| | | Receipt: mem-001@v2 (parent: v1) | |
| | | | | |
| | | (4) recall(Polaris) | | |
| | | <--------------------------- | | |
| | | [STATE 4: Select v2, | | |
| | | Filter superseded v1] | | |
| | | ---------------------------> | | |
| | | Citation: mem-001@v2 only | | |
| | | | (5) forget(mem-001) | |
| | | <---------------------------------------------------------- | |
| | | [STATE 5: Tombstone / Trash View] | |
| | | ----------------------------------------------------------> | |
| | | Receipt: status=deleted | |
| | | | | |
| | | (6) reset_synthetic_state() | |
| | | <---------------------------------------------------------- | |
| | | [STATE 6: Teardown Purge] | |
| | | Scope purged: 0 residual rows (account reset excluded) | |
| | | ----------------------------------------------------------> | |
| | | Teardown Status: SUCCESS_PURGED | |
+------------------------------------------------------------------------------------------------------------------------+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.
Source: Introduction