Summary
Gives Claude and other AI agents a persistent, user-owned memory layer over remote MCP. The CLI handles OAuth login via xmemo.dev, writes config for Codex, Cursor, Copilot, Gemini, and Antigravity without embedding tokens, and optionally installs behavior profiles that nudge agents to search memory before starting work and save context after decisions. Uses streamable HTTP transport with stable agent instance IDs and zero telemetry. Reach for this when you want conversation history and project context to survive across sessions and tools without scattering state into each editor's isolated storage. The token flow supports both device login and manual credential injection.
Keep your Mac awake while Claude Code and 40+ AI agents run. Sleeps when they're idle.
One time payment $9 →
Integrate web data into your AI product. One API to scrape website & brand data.
Get API Key Now →
Agent, run crypto. Access onchain data & trade routes via 1inch.
Install now →
On Capafy, your Skill runs online 24/7 as an agent product, and you get paid every time someone uses it.
Start earning →
Tools
Public tool metadata for what this MCP can expose to an agent.
49 tools
get_mcp_identityCheck XMemo connection status and the connected account/agent. Call this when the user asks whether XMemo is connected.
Check XMemo connection status and the connected account/agent. Call this when the user asks whether XMemo is connected.
No parameter schema in public metadata yet.
store_memoryLow-level memory write with full field control. Use only when a caller needs explicit field-level control; for normal conversational capture use remember.17 params
Low-level memory write with full field control. Use only when a caller needs explicit field-level control; for normal conversational capture use remember.
Parameters* required
pathstringA simple user-facing category or path for this memory, such as preferences, projects/xmemo, or personal/travel.
scopestringOptional scope that narrows memory access; leave blank for the token default.default:
bucketstringMemory bucket or namespace to read from or write to; use % only for tools that support wildcard reads.default: public
contentstringText body to save, such as a memory, TODO/action item, event note, or state summary.
team_idstringOptional team/workspace identifier for team-scoped memory access.default:
agent_idstringOptional client-supplied agent label for memory attribution.default:
device_idstringOptional client-supplied device identifier for attribution.default:
confidencenumberConfidence score for the saved or updated memory, from 0.0 to 1.0.default: 1
expires_atstringOptional ISO 8601 expiration timestamp for the memory.default:
importancenumberImportance score for the saved or updated memory, from 0.0 to 1.0.default: 0.5
memory_typestringMemory type/category filter or value, such as episodic, identity, procedural, semantic, working, auto, or %.default: semantic
device_labelstringOptional human-readable device label for attribution.default:
semantic_keystringOptional stable semantic key used to identify or upsert a memory concept.default:
metadata_jsonstringOptional JSON object string with extra metadata for the operation.default: {}
embedding_jsonstringOptional JSON array or object containing a precomputed embedding; leave blank for normal use.default:
provenance_jsonstringOptional JSON object string describing memory source, evidence, or attribution.default: {}
agent_instance_idstringOptional stable, non-secret agent instance ID for per-client attribution.default:
rememberSave a memory so it can be recalled in future conversations. Call this whenever the user states a durable fact, preference, instruction, identity or profile detail, project detail, or recurring workflow likely useful later — you do not need an explicit 'remember this'. Skip tr...19 params
Save a memory so it can be recalled in future conversations. Call this whenever the user states a durable fact, preference, instruction, identity or profile detail, project detail, or recurring workflow likely useful later — you do not need an explicit 'remember this'. Skip tr...
Parameters* required
pathstringA simple user-facing category or path for this memory, such as preferences, projects/xmemo, or personal/travel.
scopestringOptional scope that narrows memory access; leave blank for the token default.default:
bucketstringMemory bucket or namespace to read from or write to; use % only for tools that support wildcard reads.default: public
dedupebooleanWhether to check for and merge likely duplicate memories before saving.default: true
contentstringText body to save, such as a memory, TODO/action item, event note, or state summary.
team_idstringOptional team/workspace identifier for team-scoped memory access.default:
agent_idstringOptional client-supplied agent label for memory attribution.default:
device_idstringOptional client-supplied device identifier for attribution.default:
memory_idstringExact XMemo memory reference shown by search or recall.default:
confidencevalueConfidence score for the saved or updated memory, from 0.0 to 1.0.
expires_atstringOptional ISO 8601 expiration timestamp for the memory.default:
importancevalueImportance score for the saved or updated memory, from 0.0 to 1.0.
memory_typestringMemory type/category filter or value, such as episodic, identity, procedural, semantic, working, auto, or %.default: auto
device_labelstringOptional human-readable device label for attribution.default:
semantic_keystringOptional stable semantic key used to identify or upsert a memory concept.default:
metadata_jsonstringOptional JSON object string with extra metadata for the operation.default: {}
embedding_jsonstringOptional JSON array or object containing a precomputed embedding; leave blank for normal use.default:
provenance_jsonstringOptional JSON object string describing memory source, evidence, or attribution.default: {}
agent_instance_idstringOptional stable, non-secret agent instance ID for per-client attribution.default:
add_expenseRecord one expense in the XMemo Ledger. Call this whenever the user states a concrete expense, purchase, income, or refund — for example, 'I spent 25 on lunch' or 'log this expense' — not only on an explicit 'record this'. Capture date, amount, currency, item, and merchant/cat...16 params
Record one expense in the XMemo Ledger. Call this whenever the user states a concrete expense, purchase, income, or refund — for example, 'I spent 25 on lunch' or 'log this expense' — not only on an explicit 'record this'. Capture date, amount, currency, item, and merchant/cat...
Parameters* required
itemstringThe purchased item or service, for example 2 watermelons or Nintendo Switch 2.
notestringOptional completion note.default:
pathstringA simple user-facing category or path for this memory, such as preferences, projects/xmemo, or personal/travel.default: finance/ledger/expenses
scopestringOptional scope that narrows memory access; leave blank for the token default.default:
amountnumberPositive transaction amount as a number.
bucketstringMemory bucket or namespace to read from or write to; use % only for tools that support wildcard reads.default: private
team_idstringOptional team/workspace identifier for team-scoped memory access.default:
agent_idstringOptional client-supplied agent label for memory attribution.default:
categorystringOptional spending category, such as food, transport, or electronics.default:
currencystringCurrency code or label, such as CNY, RMB, JPY, yen, or USD. For ledger search/list tools, leave blank unless the user explicitly requested one currency; labels are normalized to codes.default: CNY
merchantstringOptional merchant or store name.default:
device_idstringOptional client-supplied device identifier for attribution.default:
device_labelstringOptional human-readable device label for attribution.default:
payment_methodstringOptional payment method, such as card, cash, Alipay, or WeChat Pay.default:
transaction_datestringTransaction date in YYYY-MM-DD. Leave blank to use today's UTC date.default:
agent_instance_idstringOptional stable, non-secret agent instance ID for per-client attribution.default:
update_stateSave the current working state during long-running work — active task, next action, or blocker — so future turns/sessions can resume. For durable user facts use remember.9 params
Save the current working state during long-running work — active task, next action, or blocker — so future turns/sessions can resume. For durable user facts use remember.
Parameters* required
scopestringOptional scope that narrows memory access; leave blank for the token default.default:
bucketstringMemory bucket or namespace to read from or write to; use % only for tools that support wildcard reads.default: work
contentstringText body to save, such as a memory, TODO/action item, event note, or state summary.default:
state_keystringWorking-state key to save, snapshot, or restore, such as active_task.default: active_task
next_actionstringNext action to persist so future turns can resume the work.default:
ttl_secondsintegerTime-to-live in seconds for working state or restart snapshot records.default: 86400
current_taskstringCurrent task or work item to persist for later resume.default:
metadata_jsonstringOptional JSON object string with extra metadata for the operation.default: {}
blocked_reasonstringShort explanation of why the current work is blocked.default:
search_memorySearch XMemo memories by natural-language query. Call this when the user asks about saved or past information, AND proactively before answering any question where prior preferences, facts, projects, decisions, or history could change the answer. To delete a memory, use forget.10 params
Search XMemo memories by natural-language query. Call this when the user asks about saved or past information, AND proactively before answering any question where prior preferences, facts, projects, decisions, or history could change the answer. To delete a memory, use forget.
Parameters* required
limitintegerMaximum number of results to return.default: 5
querystringNatural-language question or search text.
scopestringOptional scope that narrows memory access; leave blank for the token default.default:
explainbooleanWhether to include retrieval explanation details with search or recall results.default: false
team_idstringOptional team/workspace identifier for team-scoped memory access.default:
agent_idstringOptional client-supplied agent label for memory attribution.default:
memory_typestringMemory type/category filter or value, such as episodic, identity, procedural, semantic, working, auto, or %.default: %
path_filterstringMemory path filter; % matches all paths.default: %
prefer_workingbooleanWhether to prioritize working/session-state memories in retrieval.default: false
agent_instance_idstringOptional stable, non-secret agent instance ID for per-client attribution.default:
recall_planPlan which memory searches to run before retrieval. Use only for complex tasks; for ordinary answers call recall_context or recall directly.8 params
Plan which memory searches to run before retrieval. Use only for complex tasks; for ordinary answers call recall_context or recall directly.
Parameters* required
querystringNatural-language question or search text.
scopestringOptional scope that narrows memory access; leave blank for the token default.default:
bucketstringMemory bucket or namespace to read from or write to; use % only for tools that support wildcard reads.default: %
team_idstringOptional team/workspace identifier for team-scoped memory access.default:
memory_typestringMemory type/category filter or value, such as episodic, identity, procedural, semantic, working, auto, or %.default: %
output_jsonbooleanReturn a machine-readable JSON response instead of a human-readable summary.default: false
path_filterstringMemory path filter; % matches all paths.default: %
prefer_workingbooleanWhether to prioritize working/session-state memories in retrieval.default: false
recall_contextBuild a context pack from XMemo memories. Call this before answering or planning when the task could benefit from multiple saved memories — preferences, prior conversations, projects, decisions, TODOs, or long-running work.13 params
Build a context pack from XMemo memories. Call this before answering or planning when the task could benefit from multiple saved memories — preferences, prior conversations, projects, decisions, TODOs, or long-running work.
Parameters* required
limitintegerMaximum number of results to return.default: 0
querystringNatural-language question or search text.
scopestringOptional scope that narrows memory access; leave blank for the token default.default:
bucketstringMemory bucket or namespace to read from or write to; use % only for tools that support wildcard reads.default: %
team_idstringOptional team/workspace identifier for team-scoped memory access.default:
agent_idstringOptional client-supplied agent label for memory attribution.default:
max_itemsintegerMaximum number of memory items to include.default: 8
max_tokensintegerApproximate maximum response size.default: 1500
memory_typestringMemory type/category filter or value, such as episodic, identity, procedural, semantic, working, auto, or %.default: auto
output_jsonbooleanReturn a machine-readable JSON response instead of a human-readable summary.default: false
path_filterstringMemory path filter; % matches all paths.default: %
prefer_workingbooleanWhether to prioritize working/session-state memories in retrieval.default: true
agent_instance_idstringOptional stable, non-secret agent instance ID for per-client attribution.default:
list_ledger_transactionsShow XMemo Ledger records. Call this when the user asks about past expenses, purchases, or spending history, or before answering a finance question that depends on recorded transactions. For item searches use query and leave currency blank unless a currency was requested.13 params
Show XMemo Ledger records. Call this when the user asks about past expenses, purchases, or spending history, or before answering a finance question that depends on recorded transactions. For item searches use query and leave currency blank unless a currency was requested.
Parameters* required
limitintegerMaximum number of results to return.default: 20
querystringNatural-language question or search text.default:
scopestringOptional scope that narrows memory access; leave blank for the token default.default:
bucketstringMemory bucket or namespace to read from or write to; use % only for tools that support wildcard reads.default: %
offsetintegerNumber of matching records to skip for pagination.default: 0
date_tostringOnly include ledger transactions on or before this YYYY-MM-DD date.default:
categorystringOptional spending category, such as food, transport, or electronics.default:
currencystringCurrency code or label, such as CNY, RMB, JPY, yen, or USD. For ledger search/list tools, leave blank unless the user explicitly requested one currency; labels are normalized to codes.default:
date_fromstringOnly include ledger transactions on or after this YYYY-MM-DD date.default:
max_amountvalueOnly include ledger transactions with amount less than or equal to this value.
min_amountvalueOnly include ledger transactions with amount greater than or equal to this value.
output_jsonbooleanReturn a machine-readable JSON response instead of a human-readable summary.default: false
transaction_typestringOptional ledger type filter: expense, income, refund, or transfer.default:
get_monthly_ledger_summarySummarize Ledger totals by month and currency. Call this when the user asks for monthly spending, income, refunds, net balance, budget review, or spending trends.6 params
Summarize Ledger totals by month and currency. Call this when the user asks for monthly spending, income, refunds, net balance, budget review, or spending trends.
Parameters* required
scopestringOptional scope that narrows memory access; leave blank for the token default.default:
bucketstringMemory bucket or namespace to read from or write to; use % only for tools that support wildcard reads.default: %
monthsintegerNumber of recent ledger months to summarize.default: 6
currencystringCurrency code or label, such as CNY, RMB, JPY, yen, or USD. For ledger search/list tools, leave blank unless the user explicitly requested one currency; labels are normalized to codes.default:
output_jsonbooleanReturn a machine-readable JSON response instead of a human-readable summary.default: false
transaction_typestringOptional ledger type filter: expense, income, refund, or transfer.default:
mark_memory_usedRecord that a recalled memory was used in the answer. Call this after a retrieved memory actually influenced your response (not for ignored results).5 params
Record that a recalled memory was used in the answer. Call this after a retrieved memory actually influenced your response (not for ignored results).
Parameters* required
actionstringUsage action or audit-event action filter, depending on the tool.default: used
contextstringShort context explaining a memory usage event or pending decision.default:
memory_idstringExact XMemo memory reference shown by search or recall.
metadata_jsonstringOptional JSON object string with extra metadata for the operation.default: {}
usage_tracking_idstringOptional tracking ID that links a recalled memory to later usage feedback.default:
record_recall_eval_judgmentEvaluation only — record whether a returned memory was relevant for a query. Do not use in normal conversation.7 params
Evaluation only — record whether a returned memory was relevant for a query. Do not use in normal conversation.
Parameters* required
querystringNatural-language question or search text.
reasonstringOptional user-facing reason for the deletion.default:
positionintegerOne-based rank position of the memory in the recall results, or 0 if not returned.default: 0
relevantbooleanWhether the memory was relevant to the recall-evaluation query.
memory_idstringExact XMemo memory reference shown by search or recall.
metadata_jsonstringOptional JSON object string with extra metadata for the operation.default: {}
expected_relevant_totalintegerExpected number of relevant memories for this recall-evaluation query.default: 0
run_recall_evalAdmin/evaluation only — aggregate stored recall judgments and optionally tune retrieval. Not for normal conversation.3 params
Admin/evaluation only — aggregate stored recall judgments and optionally tune retrieval. Not for normal conversation.
Parameters* required
sincestringOnly include memories or activity on or after this ISO 8601 timestamp.default:
untilstringOnly include memories or activity on or before this ISO 8601 timestamp.default:
auto_tunebooleanWhether recall evaluation may tune retrieval settings from recorded judgments.default: true
record_recall_feedbackRecord recall corrections. Call this when the user says relevant context was missing or wrong, or supplies memories that should have been found.7 params
Record recall corrections. Call this when the user says relevant context was missing or wrong, or supplies memories that should have been found.
Parameters* required
notesstringFreeform notes explaining recall feedback or corrections.default:
querystringNatural-language question or search text.
metadata_jsonstringOptional JSON object string with extra metadata for the operation.default: {}
missing_ids_jsonstringJSON array of relevant memory IDs that were missing from recall results.default: []
returned_ids_jsonstringJSON array of memory IDs returned by the recall query.default: []
corrected_ids_jsonstringJSON array of memory IDs that should have been returned for the recall query.default: []
missing_memories_jsonstringJSON array of memory snippets or objects that should exist but were missing.default: []
get_recall_policyInspect XMemo retrieval policy (debug/admin). For actual recall use recall_context/recall/search_memory.
Inspect XMemo retrieval policy (debug/admin). For actual recall use recall_context/recall/search_memory.
No parameter schema in public metadata yet.
get_safety_policyShow the account safety policy. Useful before custom memory-writing that may include sensitive content; normal writes are already sanitized server-side.
Show the account safety policy. Useful before custom memory-writing that may include sensitive content; normal writes are already sanitized server-side.
No parameter schema in public metadata yet.
query_audit_eventsAdvanced audit query by action/time/target. For normal users prefer memory_activity.8 params
Advanced audit query by action/time/target. For normal users prefer memory_activity.
Parameters* required
limitintegerMaximum number of results to return.default: 100
scopestringOptional scope that narrows memory access; leave blank for the token default.default:
sincestringOnly include memories or activity on or after this ISO 8601 timestamp.default:
untilstringOnly include memories or activity on or before this ISO 8601 timestamp.default:
actionstringUsage action or audit-event action filter, depending on the tool.default:
bucketstringMemory bucket or namespace to read from or write to; use % only for tools that support wildcard reads.default:
offsetintegerNumber of matching records to skip for pagination.default: 0
target_idstringOptional audit target ID to filter audit events.default:
query_consolidation_auditInspect consolidation/lifecycle/reflection audit records (admin). Not for normal recall/save.7 params
Inspect consolidation/lifecycle/reflection audit records (admin). Not for normal recall/save.
Parameters* required
limitintegerMaximum number of results to return.default: 100
scopestringOptional scope that narrows memory access; leave blank for the token default.default:
sincestringOnly include memories or activity on or after this ISO 8601 timestamp.default:
untilstringOnly include memories or activity on or before this ISO 8601 timestamp.default:
bucketstringMemory bucket or namespace to read from or write to; use % only for tools that support wildcard reads.default:
offsetintegerNumber of matching records to skip for pagination.default: 0
action_typestringConsolidation, lifecycle, or reflection audit action type to filter by.default:
record_eventRecord a significant session event, milestone, decision, or handoff note useful for reconstructing recent work. Not for durable facts/preferences (use remember).6 params
Record a significant session event, milestone, decision, or handoff note useful for reconstructing recent work. Not for durable facts/preferences (use remember).
Parameters* required
scopestringOptional scope that narrows memory access; leave blank for the token default.default:
bucketstringMemory bucket or namespace to read from or write to; use % only for tools that support wildcard reads.default: work
contentstringText body to save, such as a memory, TODO/action item, event note, or state summary.
event_typestringTimeline event type, such as event, milestone, decision, or handoff.default: event
session_idstringOptional session identifier associated with the event, timeline query, or snapshot.default:
metadata_jsonstringOptional JSON object string with extra metadata for the operation.default: {}
get_timelineShow recent events. Call this when the user asks what happened recently or when resuming work that may depend on recent events.5 params
Show recent events. Call this when the user asks what happened recently or when resuming work that may depend on recent events.
Parameters* required
limitintegerMaximum number of results to return.default: 20
scopestringOptional scope that narrows memory access; leave blank for the token default.default:
bucketstringMemory bucket or namespace to read from or write to; use % only for tools that support wildcard reads.default: %
event_typestringTimeline event type, such as event, milestone, decision, or handoff.default:
session_idstringOptional session identifier associated with the event, timeline query, or snapshot.default:
create_reminderCreate a TODO item. Alias for create_memory_todo.5 params
Create a TODO item. Alias for create_memory_todo.
Parameters* required
scopestringOptional scope that narrows memory access; leave blank for the token default.default:
bucketstringMemory bucket or namespace to read from or write to; use % only for tools that support wildcard reads.default: work
due_atstringOptional due time for a memory TODO/action item, preferably ISO 8601.default:
contentstringText body to save, such as a memory, TODO/action item, event note, or state summary.
metadata_jsonstringOptional JSON object string with extra metadata for the operation.default: {}
list_remindersList TODO items. Alias for list_memory_todos.5 params
List TODO items. Alias for list_memory_todos.
Parameters* required
limitintegerMaximum number of results to return.default: 20
scopestringOptional scope that narrows memory access; leave blank for the token default.default:
bucketstringMemory bucket or namespace to read from or write to; use % only for tools that support wildcard reads.default: %
due_beforestringOnly show memory TODO/action items due before this time.default:
item_statusstringOptional memory TODO/action-item status filter.default: open
complete_reminderComplete a TODO item. Alias for complete_memory_todo.2 params
Complete a TODO item. Alias for complete_memory_todo.
Parameters* required
notestringOptional completion note.default:
reminder_idstringThe memory TODO/action-item ID to complete.
create_memory_todoCreate a TODO/action item in XMemo with an optional due time. Call this when the user asks to save a task, follow-up, action item, or reminder-style item to revisit later.5 params
Create a TODO/action item in XMemo with an optional due time. Call this when the user asks to save a task, follow-up, action item, or reminder-style item to revisit later.
Parameters* required
scopestringOptional scope that narrows memory access; leave blank for the token default.default:
bucketstringMemory bucket or namespace to read from or write to; use % only for tools that support wildcard reads.default: work
due_atstringOptional due time for a memory TODO/action item, preferably ISO 8601.default:
contentstringText body to save, such as a memory, TODO/action item, event note, or state summary.
metadata_jsonstringOptional JSON object string with extra metadata for the operation.default: {}
list_memory_todosList open or completed TODO/action items. Call this when the user asks what tasks, follow-ups, or saved action items are pending or done.5 params
List open or completed TODO/action items. Call this when the user asks what tasks, follow-ups, or saved action items are pending or done.
Parameters* required
limitintegerMaximum number of results to return.default: 20
scopestringOptional scope that narrows memory access; leave blank for the token default.default:
bucketstringMemory bucket or namespace to read from or write to; use % only for tools that support wildcard reads.default: %
due_beforestringOnly show memory TODO/action items due before this time.default:
item_statusstringOptional memory TODO/action-item status filter.default: open
complete_memory_todoMark a TODO/action item completed. Call this when the user says a saved task is done, resolved, or no longer needed; use the exact reference from list_memory_todos.2 params
Mark a TODO/action item completed. Call this when the user says a saved task is done, resolved, or no longer needed; use the exact reference from list_memory_todos.
Parameters* required
notestringOptional completion note.default:
todo_idstringThe memory TODO/action-item ID to complete.
create_pending_decisionRecord an unresolved decision with its options to revisit later. Use for open choices, not ordinary TODOs.6 params
Record an unresolved decision with its options to revisit later. Use for open choices, not ordinary TODOs.
Parameters* required
scopestringOptional scope that narrows memory access; leave blank for the token default.default:
bucketstringMemory bucket or namespace to read from or write to; use % only for tools that support wildcard reads.default: work
due_atstringOptional due time for a memory TODO/action item, preferably ISO 8601.default:
contextstringShort context explaining a memory usage event or pending decision.
options_jsonstringJSON array of candidate options for a pending decision.default: []
metadata_jsonstringOptional JSON object string with extra metadata for the operation.default: {}
list_pending_decisionsList open/unresolved decisions. Call this when the user asks what decisions are pending, or before planning work that depends on unresolved choices.5 params
List open/unresolved decisions. Call this when the user asks what decisions are pending, or before planning work that depends on unresolved choices.
Parameters* required
limitintegerMaximum number of results to return.default: 20
scopestringOptional scope that narrows memory access; leave blank for the token default.default:
bucketstringMemory bucket or namespace to read from or write to; use % only for tools that support wildcard reads.default: %
due_beforestringOnly show memory TODO/action items due before this time.default:
item_statusstringOptional memory TODO/action-item status filter.default: open
resolve_decisionRecord the chosen option for a previously saved pending decision. Call this when the user states their decision.2 params
Record the chosen option for a previously saved pending decision. Call this when the user states their decision.
Parameters* required
resolutionstringChosen resolution text for a pending decision.
decision_idstringExact pending-decision ID returned by list_pending_decisions.
create_restart_snapshotSave active state, recent events, TODOs, and pending decisions for restart. Call this before handoff or when context may be lost.9 params
Save active state, recent events, TODOs, and pending decisions for restart. Call this before handoff or when context may be lost.
Parameters* required
scopestringOptional scope that narrows memory access; leave blank for the token default.default:
bucketstringMemory bucket or namespace to read from or write to; use % only for tools that support wildcard reads.default: work
state_keystringWorking-state key to save, snapshot, or restore, such as active_task.default: active_task
session_idstringOptional session identifier associated with the event, timeline query, or snapshot.default:
ttl_secondsintegerTime-to-live in seconds for working state or restart snapshot records.default: 604800
metadata_jsonstringOptional JSON object string with extra metadata for the operation.default: {}
decision_limitintegerMaximum number of pending decisions to include in a restart snapshot.default: 20
reminder_limitintegerMaximum number of TODO/reminder items to include in a restart snapshot.default: 20
timeline_limitintegerMaximum number of recent timeline events to include in a restart snapshot.default: 20
restore_restart_snapshotResume previous work from a saved snapshot. Call this when the user asks to resume/restart or after context loss.9 params
Resume previous work from a saved snapshot. Call this when the user asks to resume/restart or after context loss.
Parameters* required
scopestringOptional scope that narrows memory access; leave blank for the token default.default:
bucketstringMemory bucket or namespace to read from or write to; use % only for tools that support wildcard reads.default: work
state_keystringWorking-state key to save, snapshot, or restore, such as active_task.default:
snapshot_idstringExact restart snapshot memory ID to restore.default:
ttl_secondsintegerTime-to-live in seconds for working state or restart snapshot records.default: -1
restore_statebooleanWhether restore_restart_snapshot should restore the saved working-state record.default: true
source_session_idstringSession ID whose saved restart snapshot should be restored.default:
target_session_idstringSession ID to associate with restored state and restore events.default:
record_restore_eventbooleanWhether to write a timeline event after restoring a restart snapshot.default: true
recallRecall the few most relevant saved memories before answering, when prior preferences, known facts, past decisions, or project context may directly affect the response. Use recall_context when many memories are needed.8 params
Recall the few most relevant saved memories before answering, when prior preferences, known facts, past decisions, or project context may directly affect the response. Use recall_context when many memories are needed.
Parameters* required
limitintegerMaximum number of results to return.default: 5
querystringNatural-language question or search text.
explainbooleanWhether to include retrieval explanation details with search or recall results.default: false
agent_idstringOptional client-supplied agent label for memory attribution.default:
memory_typestringMemory type/category filter or value, such as episodic, identity, procedural, semantic, working, auto, or %.default: %
path_filterstringMemory path filter; % matches all paths.default: %
prefer_workingbooleanWhether to prioritize working/session-state memories in retrieval.default: false
agent_instance_idstringOptional stable, non-secret agent instance ID for per-client attribution.default:
update_memoryUpdate the content, location, or type of an existing memory. Call this only when the user explicitly asks to correct, revise, move, or reclassify a specific saved memory.18 params
Update the content, location, or type of an existing memory. Call this only when the user explicitly asks to correct, revise, move, or reclassify a specific saved memory.
Parameters* required
pathstringA simple user-facing category or path for this memory, such as preferences, projects/xmemo, or personal/travel.default:
scopestringOptional scope that narrows memory access; leave blank for the token default.default:
bucketstringMemory bucket or namespace to read from or write to; use % only for tools that support wildcard reads.default:
statusstringMemory status filter or update value, such as active, archived, deleted, or %.default:
contentstringText body to save, such as a memory, TODO/action item, event note, or state summary.default:
team_idstringOptional team/workspace identifier for team-scoped memory access.default:
memory_idstringExact XMemo memory reference shown by search or recall.
confidencevalueConfidence score for the saved or updated memory, from 0.0 to 1.0.
expires_atstringOptional ISO 8601 expiration timestamp for the memory.default:
importancevalueImportance score for the saved or updated memory, from 0.0 to 1.0.
memory_typestringMemory type/category filter or value, such as episodic, identity, procedural, semantic, working, auto, or %.default:
semantic_keystringOptional stable semantic key used to identify or upsert a memory concept.default:
metadata_jsonstringOptional JSON object string with extra metadata for the operation.default: {}
merge_metadatabooleanWhether to merge new metadata with existing metadata instead of replacing it.default: true
provenance_jsonstringOptional JSON object string describing memory source, evidence, or attribution.default: {}
detect_conflictsbooleanWhether to detect possible conflicts with existing memories during an update.default: true
merge_provenancebooleanWhether to merge new provenance with existing provenance instead of replacing it.default: true
supersession_reasonstringReason the updated memory supersedes older content.default:
forget_memoryDelete a memory (recoverable) by exact reference, when the user explicitly asks to remove or hide it. Use forget or delete_current_memory for permanent deletion.5 params
Delete a memory (recoverable) by exact reference, when the user explicitly asks to remove or hide it. Use forget or delete_current_memory for permanent deletion.
Parameters* required
modestringDeletion mode for forget_memory, such as soft_delete, hard_delete, or redact when supported.default: soft_delete
reasonstringOptional user-facing reason for the deletion.default:
memory_idstringExact XMemo memory reference shown by search or recall.
metadata_jsonstringOptional JSON object string with extra metadata for the operation.default: {}
replacement_contentstringReplacement text to store when redacting or replacing deleted memory content.default:
forgetPermanently delete one memory by natural target ('latest', 'current', or an exact ID). Call this only when the user explicitly asks to forget/delete a specific memory; search or check activity first if the target is ambiguous.2 params
Permanently delete one memory by natural target ('latest', 'current', or an exact ID). Call this only when the user explicitly asks to forget/delete a specific memory; search or check activity first if the target is ambiguous.
Parameters* required
reasonstringOptional user-facing reason for the deletion.default:
targetstringThe memory to forget: current or an exact memory ID shown by search.default: current
delete_current_memoryPermanently delete the single active memory (no ID needed). Call this only when exactly one memory exists and the user explicitly asks to delete it; refused if zero or multiple match.1 params
Permanently delete the single active memory (no ID needed). Call this only when exactly one memory exists and the user explicitly asks to delete it; refused if zero or multiple match.
Parameters* required
reasonstringOptional user-facing reason for the deletion.default:
memory_overviewShow a summary of XMemo memories and recent activity. Call this when the user asks what XMemo remembers without a specific query.
Show a summary of XMemo memories and recent activity. Call this when the user asks what XMemo remembers without a specific query.
No parameter schema in public metadata yet.
memory_statsShow aggregate statistics for XMemo memories — counts by type, source, location, and optional time range. Call this when the user asks for counts, breakdowns, or distributions.8 params
Show aggregate statistics for XMemo memories — counts by type, source, location, and optional time range. Call this when the user asks for counts, breakdowns, or distributions.
Parameters* required
scopestringOptional scope that narrows memory access; leave blank for the token default.default:
sincestringOnly include memories or activity on or after this ISO 8601 timestamp.default:
top_nintegerMaximum number of aggregate groups to return.default: 10
untilstringOnly include memories or activity on or before this ISO 8601 timestamp.default:
group_bystringOptional grouping: none, month, agent, location, memory_type, type, source, path, bucket, day, or comma-separated advanced fields.default:
memory_typestringMemory type/category filter or value, such as episodic, identity, procedural, semantic, working, auto, or %.default: %
output_jsonbooleanReturn a machine-readable JSON response instead of a human-readable summary.default: false
path_filterstringMemory path filter; % matches all paths.default: %
memory_activityShow recent memory activity — writes, deletions, TODO changes, ledger changes, and timeline events. Call this when the user asks what changed recently, or before deleting 'latest/recent' memory so the user can confirm the preview.6 params
Show recent memory activity — writes, deletions, TODO changes, ledger changes, and timeline events. Call this when the user asks what changed recently, or before deleting 'latest/recent' memory so the user can confirm the preview.
Parameters* required
limitintegerMaximum number of results to return.default: 10
sincestringOnly include memories or activity on or after this ISO 8601 timestamp.default:
untilstringOnly include memories or activity on or before this ISO 8601 timestamp.default:
output_jsonbooleanReturn a machine-readable JSON response instead of a human-readable summary.default: false
activity_typestringActivity filter: all, writes, deletions, reads, reminders, ledger, or timeline.default: all
include_timelinebooleanWhether to include timeline events in recent memory activity.default: true
analyze_memory_textCount a word or phrase across XMemo memories, optionally grouped by month, agent, location, or type. Call this when the user asks how often a word/topic appears.12 params
Count a word or phrase across XMemo memories, optionally grouped by month, agent, location, or type. Call this when the user asks how often a word/topic appears.
Parameters* required
scopestringOptional scope that narrows memory access; leave blank for the token default.default:
sincestringOnly include memories or activity on or after this ISO 8601 timestamp.default:
untilstringOnly include memories or activity on or before this ISO 8601 timestamp.default:
phrasestringExact word or phrase to count across visible XMemo memories.
group_bystringOptional grouping: none, month, agent, location, memory_type, type, source, path, bucket, day, or comma-separated advanced fields.default: none
match_modestringHow to match phrase: exact, case_insensitive, or regex_lite.default: exact
memory_typestringMemory type/category filter or value, such as episodic, identity, procedural, semantic, working, auto, or %.default: %
output_jsonbooleanReturn a machine-readable JSON response instead of a human-readable summary.default: false
path_filterstringMemory path filter; % matches all paths.default: %
max_examplesintegerMaximum number of short snippets to include.default: 3
max_memoriesintegerMaximum number of memories to inspect while analyzing text.default: 1000
include_examplesbooleanWhether to include a few short matching memory snippets.default: false
restore_memoryRestore a previously deleted memory. Call this only when the user explicitly asks to restore or undo a deletion.3 params
Restore a previously deleted memory. Call this only when the user explicitly asks to restore or undo a deletion.
Parameters* required
reasonstringOptional user-facing reason for the deletion.default:
memory_idstringExact XMemo memory reference shown by search or recall.
metadata_jsonstringOptional JSON object string with extra metadata for the operation.default: {}
redact_memoryRedact sensitive content from a memory while keeping an audit trail. Call this only when the user explicitly asks to redact.4 params
Redact sensitive content from a memory while keeping an audit trail. Call this only when the user explicitly asks to redact.
Parameters* required
reasonstringOptional user-facing reason for the deletion.default:
memory_idstringExact XMemo memory reference shown by search or recall.
metadata_jsonstringOptional JSON object string with extra metadata for the operation.default: {}
replacement_contentstringReplacement text to store when redacting or replacing deleted memory content.default: [REDACTED]
explain_memoryExplain why a memory exists or matched a query. Call this when the user asks why something was saved or why it was retrieved.4 params
Explain why a memory exists or matched a query. Call this when the user asks why something was saved or why it was retrieved.
Parameters* required
querystringNatural-language question or search text.default:
memory_idstringExact XMemo memory reference shown by search or recall.
output_jsonbooleanReturn a machine-readable JSON response instead of a human-readable summary.default: false
include_embeddingbooleanWhether to include embedding/vector metadata in the returned explanation.default: false
list_memory_versionsShow version history for a memory. Call this when the user asks for previous content or changes over time.2 params
Show version history for a memory. Call this when the user asks for previous content or changes over time.
Parameters* required
memory_idstringExact XMemo memory reference shown by search or recall.
output_jsonbooleanReturn a machine-readable JSON response instead of a human-readable summary.default: false
list_memory_conflictsList conflicting/inconsistent memories. Call this when the user/admin asks to review unresolved conflicts.3 params
List conflicting/inconsistent memories. Call this when the user/admin asks to review unresolved conflicts.
Parameters* required
limitintegerMaximum number of results to return.default: 50
output_jsonbooleanReturn a machine-readable JSON response instead of a human-readable summary.default: false
unresolved_onlybooleanWhether to show only unresolved memory conflicts.default: true
resolve_memory_conflictResolve a listed memory conflict. Call this only when the user/admin explicitly chooses a resolution strategy.5 params
Resolve a listed memory conflict. Call this only when the user/admin explicitly chooses a resolution strategy.
Parameters* required
conflict_idstringExact memory-conflict ID returned by list_memory_conflicts.
merge_contentstringMerged memory content to apply when resolving a conflict with a merge strategy.default:
metadata_jsonstringOptional JSON object string with extra metadata for the operation.default: {}
winning_memory_idstringMemory ID that should win when resolving a conflict.default:
resolution_strategystringConflict resolution strategy, such as mark_conflict, keep_existing, replace, or merge.default: mark_conflict
run_lifecycleMaintenance tool. Use only when the user/admin explicitly asks to expire, archive, decay, or dry-run lifecycle processing.8 params
Maintenance tool. Use only when the user/admin explicitly asks to expire, archive, decay, or dry-run lifecycle processing.
Parameters* required
decaybooleanWhether lifecycle maintenance should decay low-value memories.default: true
limitintegerMaximum number of results to return.default: 500
scopestringOptional scope that narrows memory access; leave blank for the token default.default:
bucketstringMemory bucket or namespace to read from or write to; use % only for tools that support wildcard reads.default: %
expirebooleanWhether lifecycle maintenance should expire memories that reached their expiration policy.default: true
archivebooleanWhether lifecycle maintenance should archive stale memories.default: true
dry_runbooleanPreview the maintenance action without applying changes.default: false
team_idstringOptional team/workspace identifier for team-scoped memory access.default:
reflectMaintenance tool. Use only when the user/admin asks to summarize, promote, expire, decay, or archive via reflection. Prefer dry_run unless changes are explicitly requested.11 params
Maintenance tool. Use only when the user/admin asks to summarize, promote, expire, decay, or archive via reflection. Prefer dry_run unless changes are explicitly requested.
Parameters* required
limitintegerMaximum number of results to return.default: 500
scopevalueOptional scope that narrows memory access; leave blank for the token default.
sincevalueOnly include memories or activity on or after this ISO 8601 timestamp.
untilvalueOnly include memories or activity on or before this ISO 8601 timestamp.
bucketstringMemory bucket or namespace to read from or write to; use % only for tools that support wildcard reads.default: %
dry_runbooleanPreview the maintenance action without applying changes.default: false
team_idstringOptional team/workspace identifier for team-scoped memory access.default:
actions_csvstringComma-separated maintenance actions to run, such as summarize, promote, expire, decay, or archive.default: summarize,promote,expire,decay,archive
path_filterstringMemory path filter; % matches all paths.default: %
owner_filtervalueOptional owner/user filter for administrative maintenance tools.
time_window_hoursnumberNumber of recent hours to inspect during reflection maintenance.default: 24
get_system_statsDetailed memory stats with filters and grouping. For a quick summary use memory_overview or memory_stats.11 params
Detailed memory stats with filters and grouping. For a quick summary use memory_overview or memory_stats.
Parameters* required
scopestringOptional scope that narrows memory access; leave blank for the token default.default:
sincestringOnly include memories or activity on or after this ISO 8601 timestamp.default:
top_nintegerMaximum number of aggregate groups to return.default: 20
untilstringOnly include memories or activity on or before this ISO 8601 timestamp.default:
sourcestringOptional source filter for system statistics.default:
statusstringMemory status filter or update value, such as active, archived, deleted, or %.default: %
team_idstringOptional team/workspace identifier for team-scoped memory access.default:
group_bystringOptional grouping: none, month, agent, location, memory_type, type, source, path, bucket, day, or comma-separated advanced fields.default:
memory_typestringMemory type/category filter or value, such as episodic, identity, procedural, semantic, working, auto, or %.default: %
output_jsonbooleanReturn a machine-readable JSON response instead of a human-readable summary.default: false
path_filterstringMemory path filter; % matches all paths.default: %
XMemo CLI
@xmemo/client is the privacy-first command line entry point for XMemo client
setup. It is intentionally small: the npm package contains only the CLI and
setup helper code needed on a user's machine.
@yonro/xmemo-client is reserved as a Yonro fallback package. The CLI exposes
xmemo as the primary command and keeps memory-os as a compatibility alias.
The XMemo server, database, token registry, deployment files, logs, and internal scripts are not part of this npm package.
🧠 XMemo is also an MCP Server — give your AI agents persistent memory across sessions. See MCP Setup below.
MCP Server Overview
XMemo is a user-owned, hosted MCP memory service that lets AI agents persistently store, search, recall, update, and manage notes and memory fragments across sessions, projects, and tools.
- MCP Endpoint:
https://xmemo.dev/mcp(Streamable HTTP) - Auth: Bearer Token (
XMEMO_KEY) or MCP OAuth - Tools:
remember,recall,search_memory,update_memory,forget,redact_memory,explain_memory,create_memory_todo,list_memory_todos,complete_memory_todo,record_event,get_timeline,add_expense - Clients: Kimi, Claude, Cursor, Copilot, Gemini, Grok, Windsurf, Cline, Trae, Zed, Qwen, and more
{
"mcpServers": {
"XMemo": {
"type": "streamable-http",
"url": "https://xmemo.dev/mcp",
"headers": {
"Authorization": "Bearer ${XMEMO_KEY}"
}
}
}
}
See MCP Setup for detailed client configuration.
Install
npm install -g @xmemo/client
Upgrade an existing global install:
xmemo update
This runs npm install -g @xmemo/client@latest. Use xmemo update --dry-run
to print the exact command without changing anything.
Commands
xmemo update
xmemo setup codex
xmemo setup codex --dry-run
xmemo setup cursor
xmemo setup cursor --dry-run
xmemo setup copilot
xmemo setup copilot --dry-run
xmemo setup gemini
xmemo setup gemini --dry-run
xmemo setup antigravity
xmemo setup antigravity --dry-run
xmemo setup kiro
xmemo setup kiro --dry-run
xmemo setup grok
xmemo setup grok --dry-run
xmemo mcp add antigravity2
xmemo mcp add antigravity2 --write
xmemo doctor
xmemo discovery show
xmemo setup
xmemo login
xmemo auth status
xmemo status
xmemo token status
xmemo token add --from-stdin
xmemo env example --shell bash
xmemo mcp list
xmemo mcp config --client generic
xmemo mcp config --client antigravity
xmemo mcp add antigravity --write
xmemo profile status codex
xmemo profile install gemini
xmemo profile install antigravity
xmemo smoke --client codex
xmemo privacy
Enterprise privacy and security defaults
- No telemetry or analytics.
xmemo doctor,xmemo discovery show, andxmemo statusdo not send tokens.- MCP config generated by the CLI references
XMEMO_KEYor uses the client's MCP OAuth flow; it does not write token values into project files. - The CLI generates one stable non-secret
XMEMO_AGENT_INSTANCE_IDper device and stores it in user-scoped config outside git. All agents on the same device share this instance ID. xmemo setup <client>can install a marker-scoped XMemo memory behavior profile for the selected agent. The profile contains instructions only; it never embeds token values.xmemo loginstores the issued credential in the user-scoped XMemo CLI config directory, shows the approved account when the server provides it, and does not require extra token configuration afterward.xmemo token addremains available for existing tokens and still avoids project files, shell history, and printed token values.- Legacy
xmemo token setrefuses plaintext credential storage unless--allow-plaintextis explicitly provided. - The npm package uses a
fileswhitelist so onlybin,src,README.md, andLICENSEare published.
Token flow
Recommended personal-user flow:
xmemo login
xmemo auth status
xmemo token status --verify
xmemo login uses the hosted device-login flow when the service advertises it:
the CLI shows a browser URL and one-time code, the user authorizes in XMemo, and
the CLI stores the issued MCP token in the user-scoped credential file. When the
service returns approved account metadata, the CLI prints the account label so
users can confirm which XMemo account was connected. No manual token setup is
needed after a successful xmemo login; xmemo token status --verify is only
an optional connectivity check. The CLI waits for the full browser authorization
window by default; use --timeout-ms only to shorten or extend that approval
window, and --http-timeout-ms only for individual service requests.
Users who already have a token can configure it directly without shell profiles:
printf '%s\n' 'your-token' | xmemo token add --from-stdin
xmemo token status --verify
This is the preferred fallback while a hosted service is rolling out device login. It still avoids project files, MCP config files, logs, and chat transcripts.
Tokens should be created by the XMemo website or enterprise console, then
stored with xmemo login, xmemo token add, a user environment variable, or an
enterprise secret manager:
export XMEMO_KEY="your-token"
PowerShell:
[Environment]::SetEnvironmentVariable("XMEMO_KEY", "your-token", "User")
Do not commit tokens to source control, MCP config files, .env files, logs, or
chat transcripts.
Hosted discovery setup
Hosted setup uses the XMemo public discovery contracts. The CLI reads secret-free discovery and onboarding status documents, then tells the user where the API, MCP endpoint, docs, and any server-advertised onboarding links are.
xmemo doctor
xmemo discovery show
xmemo setup
Discovery requests do not send XMEMO_KEY or any Authorization
header. Token creation still happens in the website or enterprise console; the
public service discovery document does not return token values.
The hosted default service/base URL is https://xmemo.dev, so normal users do
not need to type a service address. The MCP endpoint is discovered from that
base URL and written as https://xmemo.dev/mcp; https://mcp.xmemo.dev is not
the current canonical setup URL. Use --url <service-url> or XMEMO_URL only
for private, enterprise, or self-hosted deployments. MEMORY_OS_URL remains
accepted as a compatibility alias.
Generate and write a client config from discovery:
xmemo setup codex
xmemo setup codex --url "https://your-private-service.example"
xmemo setup cursor
xmemo setup copilot
xmemo setup gemini
xmemo setup antigravity
xmemo setup <client> is the unified setup entry point. For write-capable
clients, it applies the user-scoped config directly; use --dry-run to preview
without writing. Codex/Cursor configs reference XMEMO_KEY; OAuth-native
clients such as Gemini CLI and Antigravity use the client's MCP OAuth flow
instead. No generated config embeds a token value. Write-capable client configs
also include stable non-secret agent identity headers where the client format
supports them. --yes remains accepted for Codex and Cursor as a compatibility
no-op.
After writing MCP config, xmemo setup <client> prompts:
Write XMemo memory behavior profile to <path>? [Y/n]
The default is Y, so pressing Enter writes a marker-scoped profile that nudges
the agent to recall/search XMemo at the start of non-trivial work and remember
high-signal decisions after meaningful changes. Use n or --no-profile to
configure MCP only. Use --dry-run to preview without writing config or profile
files, and --profile-target <path> to choose a different behavior profile
target.
Uninstall
Remove the XMemo MCP server entry from one or all detected client configs:
xmemo uninstall --all --dry-run
xmemo uninstall --all --yes
xmemo uninstall cursor --yes
xmemo uninstall --all --yes --profiles
xmemo uninstall --all scans the same clients as setup --all and removes only
the XMemo entry (and legacy names such as memory_os) from each detected
config file. Other MCP servers are preserved. By default it shows a summary and
asks for confirmation; pass --yes (or -y) to skip the prompt, or --dry-run
to preview without modifying files.
Pass --profiles to also remove installed behavior profiles (Codex AGENTS.md,
Cursor memory profile, etc.). Identity files and credentials are not removed, so
a later xmemo setup --all can re-enable XMemo with the same agent instance ID.
Default behavior profile targets:
codex ./AGENTS.md
cursor ~/.cursor/memory-profile.md
gemini ~/.gemini/GEMINI.md
antigravity ~/.gemini/antigravity/MEMORY.md
Antigravity 2.0 currently uses the lower-level MCP writer because its stable user config path is separate from the original Antigravity profile. Preview the generated OAuth-first config with:
xmemo mcp add antigravity2 --url https://xmemo.dev
Write it to the default Antigravity 2.0 config path with:
xmemo mcp add antigravity2 --url https://xmemo.dev --write
The generated config uses https://xmemo.dev/mcp, contains no bearer token, and
expects Antigravity 2.0 to complete MCP OAuth in the browser on first use.
XMEMO_AGENT_INSTANCE_ID is a device-level identifier shared by all agents on
the same machine, generated and stored when --write is used.
MCP setup
List supported client generators:
xmemo mcp list
Current write-capable clients:
codex ~/.codex/config.toml
cursor ~/.cursor/mcp.json
copilot ~/.copilot/mcp-config.json
gemini ~/.gemini/settings.json
antigravity ~/.gemini/antigravity/mcp_config.json
antigravity2 ~/.antigravity2/mcp.json
kiro ~/.kiro/settings/mcp.json
For clients without a verified user-scoped write path, generate a read-only template and apply it manually after review:
xmemo mcp config --client generic --base-url "https://your-private-service.example" --json
Codex, Cursor, Copilot CLI, Gemini CLI, Antigravity, and Kiro have write-capable setup
helpers. Antigravity 2.0 is write-capable through xmemo mcp add antigravity2 --write.
Other client writes should only be added after their official user-scoped config
format is verified.
Copilot CLI
Copilot CLI has /mcp management and reads user MCP configuration from
~/.copilot/mcp-config.json (or $COPILOT_HOME/mcp-config.json). XMemo writes
a local proxy server entry there:
xmemo login
xmemo setup copilot
xmemo mcp proxy
xmemo setup copilot writes XMemo to Copilot CLI's user MCP config and
does not include token or identity headers. Use xmemo setup copilot --dry-run
to preview without writing. xmemo mcp proxy reads the token saved by
xmemo login or xmemo token add --from-stdin, adds the XMemo bearer token and
local agent identity, then forwards requests to https://xmemo.dev/mcp. If
Copilot CLI is already open, reload MCP config or restart Copilot CLI after
setup.
If you specifically want the older environment-variable template, run:
xmemo mcp config --client copilot-cli --remote-env
Codex
Recommended Codex setup:
xmemo setup codex
xmemo smoke --client codex
setup codex writes the MCP config to user-scoped Codex config and, by default,
installs the XMemo Codex behavior profile into the current project's AGENTS.md
between these markers. Use xmemo setup codex --dry-run to preview without
writing or xmemo setup codex --no-profile to skip the behavior profile.
<!-- memory-os:codex-profile:start -->
<!-- memory-os:codex-profile:end -->
Repeat installs update only that marker block. Remove it with:
xmemo profile uninstall codex
Advanced: generate a Codex MCP config snippet without touching files:
xmemo mcp add codex --url "$XMEMO_URL"
Write it to the default Codex config path:
xmemo mcp add codex --url "$XMEMO_URL" --write
The generated config references XMEMO_KEY, includes the non-secret
X-Memory-OS-Agent-ID / X-Memory-OS-Agent-Instance-ID attribution headers,
and does not include the token value.
Codex MCP-depth checks:
xmemo mcp profile codex
xmemo profile install codex --dry-run
xmemo profile install codex
xmemo profile status codex
xmemo smoke --client codex
xmemo mcp profile codex prints the recommended memory behavior profile:
recall/search at the start of non-trivial tasks, write back high-signal
decisions and fixes, and never store secrets. xmemo smoke --client codex
checks the local Codex TOML config for the XMemo MCP server,
bearer_token_env_var = "XMEMO_KEY", token presence in the environment, and
absence of embedded token values.
Cursor
Cursor marketplace plugin assets live in .cursor-plugin/marketplace.json and
plugins/xmemo/. The marketplace plugin is OAuth-first and its mcp.json stores
only https://xmemo.dev/mcp; it must not contain Authorization, Bearer, or
XMEMO_KEY.
Recommended Cursor setup:
xmemo setup cursor
setup cursor merges the Cursor MCP config into the default Cursor user config
path. Use xmemo setup cursor --dry-run to preview without writing. The
lower-level equivalent remains:
xmemo mcp add cursor --url "$XMEMO_URL" --write
The CLI refuses to overwrite an existing XMemo, memory_os, or memory-os
MCP server entry. Edit the config manually if you need to rotate the endpoint.
Cursor configs include
X-Memory-OS-Agent-ID and X-Memory-OS-Agent-Instance-ID; the instance ID is
non-secret and stored under the user's XMemo CLI config directory. By default,
the setup prompt also installs a Cursor behavior profile at
~/.cursor/memory-profile.md; answer n or pass --no-profile to skip it.
Use this direct-key setup only for local/manual installs where Cursor OAuth is
unavailable; public plugin submission should use the OAuth-first plugin config.
Gemini CLI
Recommended Gemini CLI setup:
xmemo setup gemini
setup gemini merges an XMemo MCP server into Gemini CLI's user settings at
~/.gemini/settings.json. It writes a remote HTTP server using Gemini's
httpUrl key plus X-Memory-OS-Agent-ID and X-Memory-OS-Agent-Instance-ID
headers. Use xmemo setup gemini --dry-run to preview without writing.
Unlike Codex/Cursor, the Gemini config carries no token: authentication uses
Gemini CLI's built-in MCP OAuth flow (a one-time browser login on first use).
This is deliberate — Gemini redacts environment variables matching
*KEY*/*TOKEN*/*AUTH* during header expansion, so an ${XMEMO_KEY}
reference would not survive. OAuth avoids storing any secret in the config and
still grants the full XMemo tool profile. After setup, restart Gemini CLI and
run /mcp (or the first XMemo tool call) to complete the OAuth login. By
default, the setup prompt also installs a Gemini behavior profile at
~/.gemini/GEMINI.md; answer n or pass --no-profile to skip it.
The CLI refuses to overwrite an existing XMemo, memory_os, or memory-os
MCP server entry. Edit the config manually if you need to rotate the endpoint.
Antigravity
Recommended Antigravity setup:
xmemo setup antigravity
setup antigravity merges an XMemo MCP server into Antigravity's user MCP config
at ~/.gemini/antigravity/mcp_config.json. It writes Antigravity's
serverUrl shape plus X-Memory-OS-Agent-ID and
X-Memory-OS-Agent-Instance-ID headers. Like Gemini CLI, the config carries
no token: restart Antigravity and complete the MCP OAuth flow on first use.
By default, the setup prompt also installs an Antigravity behavior profile at
~/.gemini/antigravity/MEMORY.md; answer n or pass --no-profile to skip it.
The lower-level equivalent is:
xmemo mcp add antigravity --write
Use xmemo setup antigravity for normal installs because it performs discovery
and chooses the recommended Antigravity path automatically. Use
xmemo mcp add antigravity --write when you want the generic MCP writer
directly, for example with --url or --config in advanced/multi-client setup.
The CLI refuses to overwrite an existing XMemo, memory_os, or memory-os
MCP server entry. Edit the config manually if you need to rotate the endpoint.
Kiro
Recommended Kiro setup:
xmemo setup kiro
setup kiro merges an XMemo MCP server into Kiro's user MCP config at
~/.kiro/settings/mcp.json. It writes a remote HTTP server using Kiro's
standard url key plus X-Memory-OS-Agent-ID and X-Memory-OS-Agent-Instance-ID
headers. Use xmemo setup kiro --dry-run to preview without writing.
The Kiro config includes Authorization: Bearer ${env:XMEMO_KEY} so
authentication uses the environment variable approach. Set your XMemo token with:
xmemo login
# or
printf '%s\n' 'your-token' | xmemo token add --from-stdin
After setup, restart Kiro or reload MCP servers for the changes to take effect.
The CLI refuses to overwrite an existing XMemo, memory_os, or memory-os
MCP server entry. Edit the config manually if you need to rotate the endpoint.
Grok (xAI)
Recommended Grok setup:
xmemo setup grok
setup grok appends an XMemo MCP server to Grok's user config at
~/.grok/config.toml using Grok's TOML [mcp_servers.XMemo] format with url,
bearer_token_env_var = "XMEMO_KEY", and an [mcp_servers.XMemo.http_headers]
table carrying X-Memory-OS-Agent-ID. Use xmemo setup grok --dry-run to
preview without writing.
Set your XMemo token with:
xmemo login
# or
printf '%s\n' 'your-token' | xmemo token add --from-stdin
Grok is also fully compatible with Claude Code: it automatically reads Claude
Code marketplaces, plugins, skills, and MCP servers. So xmemo setup claude-code
plus the repo's .claude-plugin/, .mcp.json, and skills/ are discovered by
Grok with zero extra configuration. Use xmemo setup grok when you want the
server written directly into Grok's own ~/.grok/config.toml.
After setup, restart Grok or run /mcps to reload MCP servers. The CLI refuses
to overwrite an existing XMemo MCP server entry; edit the config manually if
you need to rotate the endpoint.
Antigravity 2.0
Recommended Antigravity 2.0 setup:
xmemo mcp add antigravity2 --write
Use a dry preview first if you want to inspect the exact JSON before writing:
xmemo mcp add antigravity2
Antigravity 2.0 uses a separate config path from the original Antigravity
profile. The default write target is ~/.antigravity2/mcp.json; on Windows the
server-side config contract also documents %APPDATA%\\Antigravity 2.0\\mcp.json
as the Antigravity 2.0 user config location. Pass --config <path> when you
want to write to a specific file.
The generated XMemo entry uses hosted HTTP MCP:
{
"mcpServers": {
"XMemo": {
"type": "http",
"url": "https://xmemo.dev/mcp"
}
}
}
No token value is written. Restart Antigravity 2.0 after setup and complete the
MCP OAuth browser flow on first use. If you use --write, the CLI also prepares
a device-level XMEMO_AGENT_INSTANCE_ID shared by all agents on the same
machine so XMemo can attribute activity consistently without embedding secrets.
Release model
This repository is the source for the @xmemo/client npm package. Releases
should be published from GitHub Actions on tags or GitHub Releases, not from a
developer workstation.
Recommended flow:
develop -> test -> tag/release -> GitHub Actions -> npm publish --provenance
Package boundary
Included in npm:
bin/
src/
README.md
LICENSE
Excluded from npm:
.github/
test/
coverage/
server code
database migrations
deployment files
logs
local state
secrets
Featured
Keep your Mac awake while Claude Code and 40+ AI agents run. Sleeps when they're idle.
One time payment $9 →Integrate web data into your AI product. One API to scrape website & brand data.
Get API Key Now →Agent, run crypto. Access onchain data & trade routes via 1inch.
Install now →On Capafy, your Skill runs online 24/7 as an agent product, and you get paid every time someone uses it.
Start earning →Categories
Registryactive
TransportHTTP
AuthRequired
UpdatedMay 30, 2026
