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.
Keeps your Mac awake while Claude Code, Codex or Cursor works. Lets it sleep when they are done.
Try free for 7 days →
Block distracting apps from your iPhone permanently without a 3rd party app. Free and open source.
Block now (100% free) →
Notes, actions and memory. Without a meeting bot. First month 100% off.
Download for free →
belt cli automatically finds the best tools and skills for your agent. image, video, music, tts...
one prompt install →
Free an open-source skills that make AI coding agents easier to understand, verify, and control.
Download for free →
Connect your Claude agent to live crypto prices and trading routes via 1inch
Get the MCP →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
agent_idstringOptional client-supplied agent label for memory attribution.default:
agent_instance_idstringOptional stable, non-secret agent instance ID for per-client attribution.default:
bucketstringMemory bucket or namespace to read from or write to; use % only for tools that support wildcard reads.default: public
confidencenumberConfidence score for the saved or updated memory, from 0.0 to 1.0.default: 1
contentstringText body to save, such as a memory, TODO/action item, event note, or state summary.
device_idstringOptional client-supplied device identifier for attribution.default:
device_labelstringOptional human-readable device label for attribution.default:
embedding_jsonstringOptional JSON array or object containing a precomputed embedding; leave blank for normal use.default:
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
metadata_jsonstringOptional JSON object string with extra metadata for the operation.default: {}
pathstringA simple user-facing category or path for this memory, such as preferences, projects/xmemo, or personal/travel.
provenance_jsonstringOptional JSON object string describing memory source, evidence, or attribution.default: {}
scopestringOptional scope that narrows memory access; leave blank for the token default.default:
semantic_keystringOptional stable semantic key used to identify or upsert a memory concept.default:
team_idstringOptional team/workspace identifier for team-scoped memory access.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
agent_idstringOptional client-supplied agent label for memory attribution.default:
agent_instance_idstringOptional stable, non-secret agent instance ID for per-client attribution.default:
bucketstringMemory bucket or namespace to read from or write to; use % only for tools that support wildcard reads.default: public
confidencevalueConfidence score for the saved or updated memory, from 0.0 to 1.0.
contentstringText body to save, such as a memory, TODO/action item, event note, or state summary.
dedupebooleanWhether to check for and merge likely duplicate memories before saving.default: true
device_idstringOptional client-supplied device identifier for attribution.default:
device_labelstringOptional human-readable device label for attribution.default:
embedding_jsonstringOptional JSON array or object containing a precomputed embedding; leave blank for normal use.default:
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_idstringExact XMemo memory reference shown by search or recall.default:
memory_typestringMemory type/category filter or value, such as episodic, identity, procedural, semantic, working, auto, or %.default: auto
metadata_jsonstringOptional JSON object string with extra metadata for the operation.default: {}
pathstringA simple user-facing category or path for this memory, such as preferences, projects/xmemo, or personal/travel.
provenance_jsonstringOptional JSON object string describing memory source, evidence, or attribution.default: {}
scopestringOptional scope that narrows memory access; leave blank for the token default.default:
semantic_keystringOptional stable semantic key used to identify or upsert a memory concept.default:
team_idstringOptional team/workspace identifier for team-scoped memory access.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
agent_idstringOptional client-supplied agent label for memory attribution.default:
agent_instance_idstringOptional stable, non-secret agent instance ID for per-client attribution.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
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
device_idstringOptional client-supplied device identifier for attribution.default:
device_labelstringOptional human-readable device label for attribution.default:
itemstringThe purchased item or service, for example 2 watermelons or Nintendo Switch 2.
merchantstringOptional merchant or store name.default:
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
payment_methodstringOptional payment method, such as card, cash, Alipay, or WeChat Pay.default:
scopestringOptional scope that narrows memory access; leave blank for the token default.default:
team_idstringOptional team/workspace identifier for team-scoped memory access.default:
transaction_datestringTransaction date in YYYY-MM-DD. Leave blank to use today's UTC date.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
blocked_reasonstringShort explanation of why the current work is blocked.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:
current_taskstringCurrent task or work item to persist for later resume.default:
metadata_jsonstringOptional JSON object string with extra metadata for the operation.default: {}
next_actionstringNext action to persist so future turns can resume the work.default:
scopestringOptional scope that narrows memory access; leave blank for the token default.default:
state_keystringWorking-state key to save, snapshot, or restore, such as active_task.default: active_task
ttl_secondsintegerTime-to-live in seconds for working state or restart snapshot records.default: 86400
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
agent_idstringOptional client-supplied agent label for memory attribution.default:
agent_instance_idstringOptional stable, non-secret agent instance ID for per-client attribution.default:
explainbooleanWhether to include retrieval explanation details with search or recall results.default: false
limitintegerMaximum number of results to return.default: 5
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
querystringNatural-language question or search text.
scopestringOptional scope that narrows memory access; leave blank for the token default.default:
team_idstringOptional team/workspace identifier for team-scoped memory access.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
bucketstringMemory bucket or namespace to read from or write to; use % only for tools that support wildcard reads.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
querystringNatural-language question or search text.
scopestringOptional scope that narrows memory access; leave blank for the token default.default:
team_idstringOptional team/workspace identifier for team-scoped memory access.default:
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
agent_idstringOptional client-supplied agent label for memory attribution.default:
agent_instance_idstringOptional stable, non-secret agent instance ID for per-client attribution.default:
bucketstringMemory bucket or namespace to read from or write to; use % only for tools that support wildcard reads.default: %
limitintegerMaximum number of results to return.default: 0
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
querystringNatural-language question or search text.
scopestringOptional scope that narrows memory access; leave blank for the token default.default:
team_idstringOptional team/workspace identifier for team-scoped memory access.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
bucketstringMemory bucket or namespace to read from or write to; use % only for tools that support wildcard reads.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:
date_tostringOnly include ledger transactions on or before this YYYY-MM-DD date.default:
limitintegerMaximum number of results to return.default: 20
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.
offsetintegerNumber of matching records to skip for pagination.default: 0
output_jsonbooleanReturn a machine-readable JSON response instead of a human-readable summary.default: false
querystringNatural-language question or search text.default:
scopestringOptional scope that narrows memory access; leave blank for the token default.default:
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
bucketstringMemory bucket or namespace to read from or write to; use % only for tools that support wildcard reads.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:
monthsintegerNumber of recent ledger months to summarize.default: 6
output_jsonbooleanReturn a machine-readable JSON response instead of a human-readable summary.default: false
scopestringOptional scope that narrows memory access; leave blank for the token default.default:
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
expected_relevant_totalintegerExpected number of relevant memories for this recall-evaluation query.default: 0
memory_idstringExact XMemo memory reference shown by search or recall.
metadata_jsonstringOptional JSON object string with extra metadata for the operation.default: {}
positionintegerOne-based rank position of the memory in the recall results, or 0 if not returned.default: 0
querystringNatural-language question or search text.
reasonstringOptional user-facing reason for the deletion.default:
relevantbooleanWhether the memory was relevant to the recall-evaluation query.
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
auto_tunebooleanWhether recall evaluation may tune retrieval settings from recorded judgments.default: true
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:
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
corrected_ids_jsonstringJSON array of memory IDs that should have been returned for the recall query.default: []
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: []
missing_memories_jsonstringJSON array of memory snippets or objects that should exist but were missing.default: []
notesstringFreeform notes explaining recall feedback or corrections.default:
querystringNatural-language question or search text.
returned_ids_jsonstringJSON array of memory IDs returned by the recall query.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
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:
limitintegerMaximum number of results to return.default: 100
offsetintegerNumber of matching records to skip for pagination.default: 0
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:
target_idstringOptional audit target ID to filter audit events.default:
untilstringOnly include memories or activity on or before this ISO 8601 timestamp.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
action_typestringConsolidation, lifecycle, or reflection audit action type to filter by.default:
bucketstringMemory bucket or namespace to read from or write to; use % only for tools that support wildcard reads.default:
limitintegerMaximum number of results to return.default: 100
offsetintegerNumber of matching records to skip for pagination.default: 0
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:
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
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
metadata_jsonstringOptional JSON object string with extra metadata for the operation.default: {}
scopestringOptional scope that narrows memory access; leave blank for the token default.default:
session_idstringOptional session identifier associated with the event, timeline query, or snapshot.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
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:
limitintegerMaximum number of results to return.default: 20
scopestringOptional scope that narrows memory access; leave blank for the token default.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
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.
due_atstringOptional due time for a memory TODO/action item, preferably ISO 8601.default:
metadata_jsonstringOptional JSON object string with extra metadata for the operation.default: {}
scopestringOptional scope that narrows memory access; leave blank for the token default.default:
list_remindersList TODO items. Alias for list_memory_todos.5 params
List TODO items. Alias for list_memory_todos.
Parameters* required
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
limitintegerMaximum number of results to return.default: 20
scopestringOptional scope that narrows memory access; leave blank for the token default.default:
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
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.
due_atstringOptional due time for a memory TODO/action item, preferably ISO 8601.default:
metadata_jsonstringOptional JSON object string with extra metadata for the operation.default: {}
scopestringOptional scope that narrows memory access; leave blank for the token default.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
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
limitintegerMaximum number of results to return.default: 20
scopestringOptional scope that narrows memory access; leave blank for the token default.default:
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
bucketstringMemory bucket or namespace to read from or write to; use % only for tools that support wildcard reads.default: work
contextstringShort context explaining a memory usage event or pending decision.
due_atstringOptional due time for a memory TODO/action item, preferably ISO 8601.default:
metadata_jsonstringOptional JSON object string with extra metadata for the operation.default: {}
options_jsonstringJSON array of candidate options for a pending decision.default: []
scopestringOptional scope that narrows memory access; leave blank for the token default.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
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
limitintegerMaximum number of results to return.default: 20
scopestringOptional scope that narrows memory access; leave blank for the token default.default:
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
decision_idstringExact pending-decision ID returned by list_pending_decisions.
resolutionstringChosen resolution text for a pending decision.
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
bucketstringMemory bucket or namespace to read from or write to; use % only for tools that support wildcard reads.default: work
decision_limitintegerMaximum number of pending decisions to include in a restart snapshot.default: 20
metadata_jsonstringOptional JSON object string with extra metadata for the operation.default: {}
reminder_limitintegerMaximum number of TODO/reminder items to include in a restart snapshot.default: 20
scopestringOptional scope that narrows memory access; leave blank for the token default.default:
session_idstringOptional session identifier associated with the event, timeline query, or snapshot.default:
state_keystringWorking-state key to save, snapshot, or restore, such as active_task.default: active_task
timeline_limitintegerMaximum number of recent timeline events to include in a restart snapshot.default: 20
ttl_secondsintegerTime-to-live in seconds for working state or restart snapshot records.default: 604800
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
bucketstringMemory bucket or namespace to read from or write to; use % only for tools that support wildcard reads.default: work
record_restore_eventbooleanWhether to write a timeline event after restoring a restart snapshot.default: true
restore_statebooleanWhether restore_restart_snapshot should restore the saved working-state record.default: true
scopestringOptional scope that narrows memory access; leave blank for the token default.default:
snapshot_idstringExact restart snapshot memory ID to restore.default:
source_session_idstringSession ID whose saved restart snapshot should be restored.default:
state_keystringWorking-state key to save, snapshot, or restore, such as active_task.default:
target_session_idstringSession ID to associate with restored state and restore events.default:
ttl_secondsintegerTime-to-live in seconds for working state or restart snapshot records.default: -1
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
agent_idstringOptional client-supplied agent label for memory attribution.default:
agent_instance_idstringOptional stable, non-secret agent instance ID for per-client attribution.default:
explainbooleanWhether to include retrieval explanation details with search or recall results.default: false
limitintegerMaximum number of results to return.default: 5
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
querystringNatural-language question or search text.
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
bucketstringMemory bucket or namespace to read from or write to; use % only for tools that support wildcard reads.default:
confidencevalueConfidence score for the saved or updated memory, from 0.0 to 1.0.
contentstringText body to save, such as a memory, TODO/action item, event note, or state summary.default:
detect_conflictsbooleanWhether to detect possible conflicts with existing memories during an update.default: true
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_idstringExact XMemo memory reference shown by search or recall.
memory_typestringMemory type/category filter or value, such as episodic, identity, procedural, semantic, working, auto, or %.default:
merge_metadatabooleanWhether to merge new metadata with existing metadata instead of replacing it.default: true
merge_provenancebooleanWhether to merge new provenance with existing provenance instead of replacing it.default: true
metadata_jsonstringOptional JSON object string with extra metadata for the operation.default: {}
pathstringA simple user-facing category or path for this memory, such as preferences, projects/xmemo, or personal/travel.default:
provenance_jsonstringOptional JSON object string describing memory source, evidence, or attribution.default: {}
scopestringOptional scope that narrows memory access; leave blank for the token default.default:
semantic_keystringOptional stable semantic key used to identify or upsert a memory concept.default:
statusstringMemory status filter or update value, such as active, archived, deleted, or %.default:
supersession_reasonstringReason the updated memory supersedes older content.default:
team_idstringOptional team/workspace identifier for team-scoped memory access.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
memory_idstringExact XMemo memory reference shown by search or recall.
metadata_jsonstringOptional JSON object string with extra metadata for the operation.default: {}
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:
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
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: %
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:
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
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
limitintegerMaximum number of results to return.default: 10
output_jsonbooleanReturn a machine-readable JSON response instead of a human-readable summary.default: false
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:
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
group_bystringOptional grouping: none, month, agent, location, memory_type, type, source, path, bucket, day, or comma-separated advanced fields.default: none
include_examplesbooleanWhether to include a few short matching memory snippets.default: false
match_modestringHow to match phrase: exact, case_insensitive, or regex_lite.default: exact
max_examplesintegerMaximum number of short snippets to include.default: 3
max_memoriesintegerMaximum number of memories to inspect while analyzing text.default: 1000
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: %
phrasestringExact word or phrase to count across visible XMemo memories.
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:
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
memory_idstringExact XMemo memory reference shown by search or recall.
metadata_jsonstringOptional JSON object string with extra metadata for the operation.default: {}
reasonstringOptional user-facing reason for the deletion.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
memory_idstringExact XMemo memory reference shown by search or recall.
metadata_jsonstringOptional JSON object string with extra metadata for the operation.default: {}
reasonstringOptional user-facing reason for the deletion.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
include_embeddingbooleanWhether to include embedding/vector metadata in the returned explanation.default: false
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
querystringNatural-language question or search text.default:
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: {}
resolution_strategystringConflict resolution strategy, such as mark_conflict, keep_existing, replace, or merge.default: mark_conflict
winning_memory_idstringMemory ID that should win when resolving a conflict.default:
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
archivebooleanWhether lifecycle maintenance should archive stale memories.default: true
bucketstringMemory bucket or namespace to read from or write to; use % only for tools that support wildcard reads.default: %
decaybooleanWhether lifecycle maintenance should decay low-value memories.default: true
dry_runbooleanPreview the maintenance action without applying changes.default: false
expirebooleanWhether lifecycle maintenance should expire memories that reached their expiration policy.default: true
limitintegerMaximum number of results to return.default: 500
scopestringOptional scope that narrows memory access; leave blank for the token default.default:
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
actions_csvstringComma-separated maintenance actions to run, such as summarize, promote, expire, decay, or archive.default: summarize,promote,expire,decay,archive
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
limitintegerMaximum number of results to return.default: 500
owner_filtervalueOptional owner/user filter for administrative maintenance tools.
path_filterstringMemory path filter; % matches all paths.default: %
scopevalueOptional scope that narrows memory access; leave blank for the token default.
sincevalueOnly include memories or activity on or after this ISO 8601 timestamp.
team_idstringOptional team/workspace identifier for team-scoped memory access.default:
time_window_hoursnumberNumber of recent hours to inspect during reflection maintenance.default: 24
untilvalueOnly include memories or activity on or before this ISO 8601 timestamp.
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
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: %
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:
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:
top_nintegerMaximum number of aggregate groups to return.default: 20
untilstringOnly include memories or activity on or before this ISO 8601 timestamp.default:
XMemo: Memory OS for AI Agents
XMemo is a user-owned Memory OS for AI agents: persistent memory, project context and session continuity with agent identity, provenance and governed access, shared across AI clients through MCP, the CLI and a public REST API surface.
English · 简体中文 | Documentation · Hosted MCP
Quick start · What this repo contains · Beyond MCP · Integrations · Connection modes · Plugins · Commands · Versioning · Security
What this repository contains
@xmemo/client: the officialxmemoCLI for setup, diagnostics, behavior profiles, and memory commands.- MCP distribution: hosted Streamable HTTP configuration (
https://xmemo.dev/mcp) and the localxmemo-mcpstdio server. - XMemo Skill & native integrations:
skills/xmemofor agent platforms and the native plugin index (src/plugins/index.json). - Marketplace and registry metadata: canonical descriptors for MCP Registry (
server.json), LobeHub (lhm.plugin.json), and AI agents (context7.json).
The hosted service implementation is private.
Beyond MCP
MCP is one access surface of XMemo, not the product boundary. XMemo provides a persistent, governed memory operating layer across AI tools and agents:
- Persistent Memory: store, search, list, and soft-delete durable facts, preferences, and operational knowledge across sessions.
- Context Recall: retrieve focused, relevant context on demand with token-budget controls and document expansions.
- Session Continuity & Working State: restart snapshots and state save/restore so agents resume context across process restarts.
- Project Context & Decisions: track project-scoped facts, TODOs, and durable decisions across agent workflows.
- Agent Identity & Provenance: track authorship and origin per memory record via agent instance attribution without conflating credentials.
- Governed Access: scoped tokens, OAuth where the client supports it, soft/hard deletion and sensitive-memory handling (governance details).
- Native Integrations & Skill: dedicated integration for OpenClaw, Hermes, XMemo Skill (ClawHub), and DeepSeek DSH (available, released and pilot-tested; integration maturity Preview).
- Access Surfaces: unified via Model Context Protocol, the local CLI (
xmemo), and the public REST API.
Preview: Cloud Skills; Dream (off by default); Teams (Business plan not yet available). Knowledge Bases are available where enabled for the account.
XMemo CLI
@xmemo/client is the official control plane for connecting AI tools to XMemo. It makes setup repeatable, keeps credentials out of project files, and gives every supported client a consistent path to durable, user-owned memory.
The package is deliberately small: the CLI runtime, safe client configuration, behavior profiles, XMemo skills, and marketplace metadata. Server code, databases, deployment files, logs, and internal operations remain outside the npm distribution.
Architecture
| Package | @xmemo/client |
| Primary command | xmemo (alias: client) |
| Local MCP command | xmemo-mcp |
| Hosted MCP | https://xmemo.dev/mcp |
| Runtime | Node.js 20 or later |
| License | MIT |
Why XMemo CLI
- One control plane — login, diagnostics, configuration, profiles, updates, and smoke checks share one predictable interface.
- Private by design — generated project configuration references a credential; it never embeds the credential value.
- Native where it matters — OpenClaw and Hermes use dedicated memory integrations instead of duplicating the same capability through MCP.
- Portable everywhere else — hosted Streamable HTTP MCP and local stdio cover modern editors, terminals, and agent runtimes.
- Safe automation — supported setup and removal paths offer preview, dry-run, or explicit confirmation before making changes.
- Small supply-chain surface — the npm package is governed by an explicit file allowlist and release provenance.
Quick start
Guided onboarding (xmemo init)
For an interactive first-run experience across account authentication, detected clients, agent behavior instructions, MCP server setup, skills, and plugins, run:
npm install -g @xmemo/client
xmemo init
Flags and options:
xmemo init --dry-run: View the full onboarding plan without performing network calls or disk writes.xmemo init --yes: Automatically accept and apply all onboarding steps without interactive prompts.xmemo init --json: Emit structured JSON for the plan or result envelope.xmemo init --client <id>...: Restrict onboarding to specific clients (e.g.,cursor,codex,claude-code).xmemo start: Alias forxmemo initwith quick-start walkthrough steps.
Global installation exposes xmemo as the primary command, and also provides client and memory-os as aliases.
Manual step-by-step setup
xmemo account login
xmemo doctor
xmemo setup codex
xmemo status
Replace codex with your client. Preview a configuration before writing it:
xmemo setup cursor --dry-run
Running with npx
You can also run any CLI command directly without a global install via npx @xmemo/client <command>:
# Check version or health
npx @xmemo/client --version
npx @xmemo/client doctor
# Guided onboarding without global install
npx @xmemo/client init
# Install skill or run MCP stdio server
npx @xmemo/client skill install
npx @xmemo/client mcp serve
[!TIP] Start with
xmemo init(orxmemo account login,xmemo doctor, andxmemo setup <client>). Hand-edit MCP configuration only when a client has no verified setup path.
How the commands fit together
The XMemo CLI architecture is built on four core design principles:
1. Unified Resource Grammar (xmemo <resource> <action>)
Every integration component is a first-class resource with predictable lifecycle actions:
| Resource | Scope | Actions | Examples |
|---|---|---|---|
mcp | MCP server connection configuration | install, remove, status | xmemo mcp install codex, xmemo mcp status |
plugin | Host-native extension packages | install, remove, status, list, info | xmemo plugin install gemini-cli, xmemo plugin list |
skill | Agent skill scripts & documentation | install, remove, status, update | xmemo skill install --client openclaw |
profile | Markdown behavior steering instructions | install, remove, status, show | xmemo profile install cursor |
- Composite commands:
xmemo setup [<client>...],xmemo uninstall [<client>...], andxmemo status [<client>]orchestrate these resources in a single step according to the client's declarative profile. - Backward-compatible aliases: Familiar commands such as
xmemo mcp add(alias formcp install),xmemo profile uninstall(alias forprofile remove), andxmemo skill uninstall(alias forskill remove) remain fully functional and print a helpful one-line hint in interactive terminals.
2. Unified Target Resolver
When no client is explicitly passed, the CLI uses a deterministic three-tier precedence resolution model:
- Explicit flag or argument:
--client <id>, positional client argument, or--all. - Calling agent environment: Automatically identifies the calling agent runtime when running inside an agent session (e.g.,
CLAUDECODE/CLAUDE_CODE_ENTRYPOINTmaps toclaude-code, andCODEX_THREAD_ID/CODEX_SESSION_IDmaps tocodex). - Detected installed clients: Inspects local configuration paths and markers. If exactly one matching client is found, it is automatically selected; if multiple clients are found in interactive mode, an interactive picker is presented. The CLI never silently writes configuration to arbitrary unverified paths.
3. Plan, Confirm Once, Apply (PlanRunner)
Mutating commands follow a strict, atomic execution pattern:
- Build Plan: Assemble an ordered sequence of actions across resources (e.g. plugin install followed by skill configuration).
- Preview: Print the entire plan (including modified paths, commands, and unified diffs) to the terminal.
- Confirm Once: Prompt
[y/N]exactly once for the entire sequence. Re-running with--yesor-ybypasses the prompt;--dry-rundisplays the preview without mutation. - Apply Sequentially: Steps run in dependency order, stopping immediately upon first failure. Re-running an already configured client detects that all components are up to date and reports
Nothing to do.
4. Declarative Client Registry
All client configurations, recipes, and capabilities are declared centrally in src/clients/registry.js. Command implementations are purely generic orchestrators with zero hardcoded client ID strings. Platforms can also be added dynamically at runtime via registerClient().
Supported integrations
| Client | Recommended command | Connection |
|---|---|---|
| Codex | xmemo setup codex | Hosted MCP + behavior profile |
| Cursor | xmemo setup cursor | Hosted MCP + Bearer Token + behavior profile |
| Copilot CLI | xmemo setup copilot | Local authenticated proxy |
| Gemini CLI | xmemo setup gemini | Hosted MCP + OAuth |
| Antigravity | xmemo setup antigravity | Hosted MCP + OAuth |
| OpenClaw | xmemo setup openclaw | Native memory plugin + Skill |
| Hermes | xmemo setup hermes | Native memory provider |
| Kiro | xmemo setup kiro | Native HTTP OAuth; --auth key for API Key |
| Grok | xmemo setup grok | Hosted MCP |
| Other MCP clients | xmemo mcp config --client generic | Generated template |
The client registry also covers Devin Desktop (formerly Windsurf), Cline, Continue, Claude Desktop,
Claude Code, Kimi Code, Zed, JetBrains, OpenCode, Qwen, Trae, and compatible
MCP hosts. Run xmemo mcp list for the current machine-readable catalog.
For VS Code users looking for the dedicated editor extension, see the yonro/xmemo-vscode repository. For Cursor users looking for the dedicated plugin, see the yonro/xmemo-cursor-plugin repository. For Claude users looking for the dedicated plugin, see the yonro/xmemo-claude-plugin repository.
Connection modes
Hosted MCP
The recommended universal path is the XMemo Streamable HTTP endpoint:
https://xmemo.dev/mcp
OAuth-capable clients complete authentication in the browser. Other clients
reference XMEMO_KEY without copying its value into repository files.
Generic configuration shape:
{
"mcpServers": {
"XMemo": {
"type": "streamable-http",
"url": "https://xmemo.dev/mcp",
"headers": {
"Authorization": "Bearer ${XMEMO_KEY}"
}
}
}
}
Client configuration keys differ; prefer xmemo setup <client> over copying
this generic example directly.
Local stdio MCP
xmemo-mcp is the dedicated stdio entry point for marketplaces and clients
that launch a local process. Safe discovery exposes 20 tools, three prompts,
and two documentation resources without a token. Tool execution still requires
authentication.
After a global installation:
xmemo-mcp
Install-free MCP configuration:
{
"mcpServers": {
"XMemo": {
"command": "npx",
"args": [
"-y",
"--package",
"@xmemo/client@latest",
"xmemo-mcp"
]
}
}
}
xmemo mcp serve is equivalent when the CLI is already installed.
Native integrations
OpenClaw and Hermes have dedicated memory providers. Their default setup avoids installing a second, duplicate XMemo tool surface:
- OpenClaw: installs the pinned plugin
clawhub:@xmemo/openclaw-memory@1.0.18without--forceby default. Re-running setup gracefully detects existing installations; use--forceto reinstall or overwrite. - Hermes: installs the pinned provider package
hermes-xmemo==1.1.3viapip installwithout-U. - Every install command prints the exact command before executing. Use
--dry-runto preview actions without installing.
# Native OpenClaw plugin (clawhub:@xmemo/openclaw-memory@1.0.18) + XMemo Skill
xmemo setup openclaw
# Native Hermes memory provider (hermes-xmemo==1.1.3)
xmemo setup hermes
Add hosted MCP only when an explicit fallback is desired:
xmemo setup openclaw --with-mcp
xmemo setup hermes --with-mcp
Use --mcp-only to skip the native integration and install only the hosted MCP
fallback.
XMemo Skill install
The CLI installs the verified XMemo Skill locally into agent skill folders or a target directory:
- Installs into client skill directories:
- Claude Code:
~/.claude/skills/xmemo-memory(global) or.claude/skills/xmemo-memory(project with--project) - Codex:
~/.codex/skills/xmemo-memory - OpenClaw:
~/.openclaw/skills/xmemo-memory - All other 21 clients remain
nulluntil officially documented.
- Claude Code:
- Defaults to the pinned
@xmemo/skill@1.1.35release from npm and verifies tarball integrity (sha512 SRI) before extraction. - Override version with
--version <semver>or explicitly opt into the latest release via--version latest. - For air-gapped or offline installations, install from a local directory or packed tarball with
--from <dir|tgz>(optional--integrity <sha512>). - Manage client skills with
skill status,skill update, andskill remove. - Preview actions without writing files using
--dry-run. - Safety & Consent:
- Interactive install prompts
[y/N]before writing (Enter, EOF, or empty input cancels) unless--yesis specified. - Existing installs refuse overwrite without
--force; when--forceis used, a backup is created in~/.xmemo/backups/skills/<client>/(outside the agent skills directory). skill removeonly removes verified XMemo skill directories, refusing foreign folders, and reports the preserved backup location.
- Interactive install prompts
# Install to agent skill folder (Claude Code global, Codex, or OpenClaw)
xmemo skill install --client claude-code
xmemo skill install --client codex
xmemo skill install --client openclaw
# Install OpenClaw skill globally (shared ~/.openclaw/skills)
xmemo skill install --client openclaw --global
# Install to project-level skill folder (Claude Code project: .claude/skills/xmemo-memory)
xmemo skill install --client claude-code --project
# Install for all detected supported clients
xmemo skill install --all
# Automatically resolve detected client(s) (or specify --client <id>)
xmemo skill install
# Install into a custom directory path
xmemo skill install --dir ./custom-skill-dir
# Non-interactive install (skips [y/N] prompt)
xmemo skill install --client codex --yes
# Replace existing installation (creates backup in ~/.xmemo/backups/skills/<client>/)
xmemo skill install --client codex --force --yes
# Update alias (equivalent to skill install --force)
xmemo skill update --client codex --yes
# Inspect installation status across clients
xmemo skill status
xmemo skill status --client codex
xmemo skill status --all --json
# Remove installed skill from an agent folder (refuses non-XMemo folders)
xmemo skill remove --client codex --yes
xmemo skill remove --client claude-code --project --yes
# Dry run preview
xmemo skill install --client codex --dry-run
Standalone curl & PowerShell installers
For environments without Node.js or @xmemo/client, XMemo provides standalone HTTPS installers at https://xmemo.dev/skill/install (POSIX sh) and https://xmemo.dev/skill/install.ps1 (PowerShell).
The installer is agent-aware and automatically resolves the correct target directory for your active agent:
# Claude Code: installs to ~/.claude/skills/xmemo-memory
curl -fsSL https://xmemo.dev/skill/install | XMEMO_SKILL_AGENT=claude-code sh
# Codex: installs to ${CODEX_HOME:-$HOME/.codex}/skills/xmemo-memory
curl -fsSL https://xmemo.dev/skill/install | XMEMO_SKILL_AGENT=codex sh
# OpenClaw: install via OpenClaw CLI
openclaw skills install @xmemo/xmemo --version 1.1.35
# Windows (PowerShell):
# $env:XMEMO_SKILL_AGENT="claude-code"; irm https://xmemo.dev/skill/install.ps1 | iex
# $env:XMEMO_SKILL_AGENT="codex"; irm https://xmemo.dev/skill/install.ps1 | iex
[!TIP] Prompt for your AI Agent (copy and paste directly into Claude Code, Codex, or another agent):
Install the standalone XMemo Skill into your skills directory: run the installer from https://xmemo.dev/skill/install (on Windows, https://xmemo.dev/skill/install.ps1) with XMEMO_SKILL_DIR set to your skills directory plus /xmemo-memory. Run the doctor command it prints to verify the installation, then reload your skills and follow the Skill's first-run steps. Follow your normal safety checks and do not use elevated privileges.
Target resolution precedence (first match wins):
XMEMO_SKILL_DIR: Installs to the specified directory.XMEMO_SKILL_AGENT=claude-code|codex: Installs to the explicit agent's skills directory (openclawredirects toopenclaw skills install xmemo).- Auto-detection: Automatically detects Claude Code (
CLAUDECODE=1) or Codex (CODEX_THREAD_ID,CODEX_SESSION_ID, orCODEX_HOME). - Home directory discovery: If only
~/.claudeor only~/.codexexists in HOME, selects that agent. - Fallback: Installs to
./xmemo-skillwith a warning on stderr explaining that AI agents will not automatically load the skill from this directory.
Safety & Replacement:
- Refuses to overwrite existing installations unless
XMEMO_SKILL_FORCE=1is provided. - When replacing, moves the previous installation to
~/.xmemo/backups/skills/<agent>/<name>-<timestamp>(safely outside agent skill search paths). - After installation, prints the absolute install path, the verification doctor command (
node <path>/scripts/xmemo-skill.mjs doctor --anonymous), and a prompt to reload your agent.
Agent plugins
The CLI provides a curated, static index of verified agent plugins shipped directly in @xmemo/client. Each entry contains a pinned version, release tag, and exact Git commit SHA resolved at release time.
ℹ️ Strict Separation Rule:
xmemo plugininstalls agent plugins only (e.g.@xmemo/openclaw-memory). Skills are installed exclusively viaxmemo skill install(e.g.@xmemo/xmemo).
| Plugin ID | Platform / Agent | Kind | Status | Integration |
|---|---|---|---|---|
openclaw | OpenClaw | native-cli | Stable | openclaw plugins install clawhub:@xmemo/openclaw-memory@1.0.18 (auto-prompts update if already installed) |
hermes | Hermes Agent | native-cli | Stable | hermes plugins install xmemo (fallback: python -m pip install hermes-xmemo==1.1.3) |
claude-code | Claude Code | git-dir | Preview | Pinned Git clone verified against commit 5d0d280 (defaults to ~/.xmemo/plugins/claude-code) |
cursor | Cursor | marketplace | Preview | Cursor Marketplace plugin |
gemini-cli | Gemini CLI | native-cli | Preview | gemini extensions install https://github.com/yonro/xmemo-gemini-cli --ref 39e25b185b5157490d1683e4ca8c5c5fb1312a88 |
kiro | Kiro | manual | Preview | Steering rules & Power integration |
vscode | VS Code | manual | Preview | VS Code extension manual steps (pending marketplace publication) |
deepseek-dsh | DeepSeek DSH | native-cli | Preview | dsh plugin --profile <name> add dsh-xmemo (requires --profile) |
chatgpt-codex | ChatGPT / Codex | marketplace | Preview | ChatGPT & Codex extension |
cindy | Cindy | manual | Preview | Native agent memory integration |
codex | Codex | mcp | Preview | Dedicated MCP configuration (xmemo setup codex) |
Commands:
# List available plugins (excluding legacy entries)
xmemo plugin list
# Include legacy plugins
xmemo plugin list --all
# View plugin details and verification metadata
xmemo plugin info <id>
# Preview install plan without executing
xmemo plugin install <id> --dry-run
# Install with explicit confirmation (prompts [y/N] by default)
xmemo plugin install <id>
# Non-interactive install
xmemo plugin install <id> --yes
# Specify profile for deepseek-dsh
xmemo plugin install deepseek-dsh --profile default --yes
# Specify custom target directory for git-dir plugins
xmemo plugin install claude-code --yes --dir ~/.custom-plugins/claude-code
# Open plugin documentation or marketplace in browser
xmemo plugin install <id> --open
# Check installation status
xmemo plugin status [<id>]
Security & Consent:
- Only verified plugin IDs from the static index are accepted; arbitrary URLs and unknown IDs are rejected with exit code 2.
- Interactive install always displays the execution plan and requires explicit consent (
[y/N], defaulting to Cancel on empty input or EOF). --dry-runguarantees zero disk writes and zero spawned processes.- Marketplace and manual plugins display exact step-by-step instructions from the plugin repository during
plugin install <id>(pass--opento open docs in browser). - Git directory plugins (
claude-code) clone into a stable per-user location (~/.xmemo/plugins/<id>), support--dir <path>override, verify the checked-outHEADcommit byte-for-byte, and output the exact load command (claude --plugin-dir <dir>). On commit mismatch, the directory is immediately removed. - Plugin child processes run in an isolated environment with authentication tokens (
XMEMO_KEY,MEMORY_OS_MCP_TOKEN,XMEMO_TOKEN) scrubbed from argv and env.
Account and authentication
Account commands
Manage local authentication, stored credentials, and tokens through the account command family:
# Browser device login
xmemo account login
# Check active authentication state
xmemo account status
# Optional remote verification
xmemo account status --verify
# Check or store token credentials
xmemo account token status
printf '%s\n' 'your-token' | xmemo account token add --from-stdin --allow-plaintext
# Logout: remove locally stored XMemo credentials owned by the CLI
xmemo account logout
# Non-interactive logout
xmemo account logout --yes
Safe account logout (xmemo account logout)
- Target removal: Removes only the user-scoped credential file owned by the CLI (
~/.config/xmemo/credentials.jsonor OS config root). - Explicit confirmation: Displays the target credential path and prompts
Proceed with logout? [y/N](defaulting to No) unless--yesis specified. - Client & Agent Isolation: Preserves all client MCP configuration files (Cursor, Claude, VS Code, etc.) and agent-managed OAuth sessions.
- Privacy: Never displays or leaks token values in stdout, stderr, or JSON envelopes.
- Scripting: Requires
--yeswhen--jsonis specified to prevent accidental headless logout.
Legacy authentication aliases
The legacy commands remain fully supported as backward-compatible aliases:
xmemo login(alias forxmemo account login)xmemo auth status(alias forxmemo account status)xmemo auth-status(alias forxmemo account status)xmemo token <status|add|set>(alias forxmemo account token <status|add|set>)
In interactive human mode, legacy aliases emit a one-line deprecation hint to stderr. When run with --json or --help, the deprecation hint is suppressed.
Existing token import
Pipe an existing token through stdin so it does not appear in command history:
printf '%s\n' 'your-token' | xmemo account token add --from-stdin --allow-plaintext
xmemo account token status --verify
PowerShell:
$xmemoToken = Read-Host "XMemo token"
$xmemoToken | xmemo account token add --from-stdin --allow-plaintext
Remove-Variable xmemoToken
For CI and managed workstations, expose XMEMO_KEY through the platform's
secret manager. Do not commit it to .env, MCP configuration, logs, issue
reports, or chat transcripts.
Universal --json output
Every command and subcommand supports --json for predictable scripting:
- On success: Outputs valid JSON on
stdoutwith exit code0. - On error: Outputs a structured JSON error envelope
{ schemaVersion, ok: false, command, data: null, error: { code, message, ... } }onstdoutwith a non-zero exit code (e.g. exit code2for usage/input errors,1for internal/network errors).
Command reference
1. Get started
xmemo init [--client <id>...] [--yes] [--dry-run] [--json]
# Backward-compatible alias
xmemo start [--json]
2. Connect agents
# High-level client configuration
xmemo setup <client> [--url <url>] [--no-profile] [--json] [--force]
xmemo setup <client> --dry-run
xmemo setup --all [--write] [--profile] [--force]
# Direct MCP server configuration
xmemo mcp serve
xmemo mcp list
xmemo mcp config --client <client-id> [--base-url <url>] [--json]
xmemo mcp add <client-id> [--write] [--config <path>]
xmemo mcp proxy [--port 8765] [--base-url <url>]
# Workspace behavior profiles
xmemo profile install <client-id> [--target <path>] [--dry-run]
xmemo profile show <client-id> [--target <path>] [--json]
xmemo profile status <client-id> [--target <path>] [--json]
xmemo profile uninstall <client-id> [--target <path>] [--yes]
3. Skill
# Install verified pinned skill into agent skill folders
xmemo skill install [--client <id>|--all] [--project] [--dir <path>] [--dry-run] [--yes] [--force] [--json]
# Inspect installation status across clients
xmemo skill status [--client <id>|--all] [--json]
# Remove installed skill from an agent folder (refuses non-XMemo folders)
xmemo skill remove --client <id> [--project] [--yes] [--json]
# Update skill installation (creates backup in ~/.xmemo/backups/skills/<client>/)
xmemo skill update [--client <id>|--all] [--yes] [--json]
4. Plugins
xmemo plugin list [--all] [--json]
xmemo plugin info <id> [--json]
xmemo plugin install <id> [--dry-run] [--yes] [--open] [--dir <path>] [--json]
xmemo plugin status [<id>] [--all] [--json]
5. Memory
xmemo memory add --content "Remember this" --path notes/example --json
xmemo memory search "example" --json
xmemo memory read <id> --json
xmemo memory list [--path-prefix <prefix>] [--project <name>] [--query <text>] [--type <type>] [--all] [--limit <n>] [--offset <n>] --json
xmemo memory delete <id> [--reason <text>] [--yes] --json
xmemo memory restore <id> [--yes] --json
xmemo memory import --file memories.jsonl [--dry-run] [--idempotency-key <key>] [--yes] --json
xmemo memory ledger-delete --id <transaction-uuid> --yes --json
xmemo context recall "resume this task" --include-knowledge --json
xmemo state save --current-task "ship the client" --next-action "run tests" --json
xmemo state restore --json
xmemo restart snapshot --json
xmemo restart restore --snapshot-id <snapshot-id> --json
xmemo knowledge add --base <base-id> --file ./guide.pdf --title "Guide" --json
xmemo knowledge search "setup" --base <base-id> --json
xmemo knowledge read <item-id> --json > knowledge-view.json
xmemo knowledge update <item-id> --text "Updated" --from knowledge-view.json --publish --yes --json
xmemo dream preview --wait --json
xmemo dream show <run-id> --json > dream-view.json
xmemo dream apply <run-id> --item <candidate-id> --from dream-view.json --yes --json
xmemo cloud-skill list --json
xmemo cloud-skill add --file ./SKILL.md --json
xmemo cloud-skill show <skill-id> --json > skill-view.json
xmemo cloud-skill update <skill-id> --from skill-view.json --file ./SKILL.md --json
xmemo cloud-skill run <skill-id> --input ./args.json --from skill-view.json --yes --json
All direct service commands support a single machine-readable JSON envelope.
Knowledge update, Dream apply, and Cloud Skill run use the readReceipt from a
saved read/show result so the CLI never silently substitutes a newer revision.
Set XMEMO_KNOWLEDGE_BASE_ID for a non-interactive default knowledge base.
For a long knowledge item, continue the same fixed revision with
xmemo knowledge read <item-id> --from knowledge-view.json --offset <n>.
Run xmemo doctor --services --json for read-only Knowledge, Dream, and Cloud
Skill diagnostics; it deliberately does not claim write or production readiness.
Cloud Skill add/update already target the safe create-only and content-CAS
contracts. They fail with SERVER_CONTRACT_REQUIRED on older services and do
not fall back to legacy upsert routes. Binary Knowledge item updates similarly
require a new version of the same server Document; use --document and
--document-version after that version has been uploaded.
The normal login scopes remain unchanged. Request additional service scopes explicitly when needed, for example:
xmemo login --scopes memory:read,memory:write,memory:restore,knowledge:read,knowledge:write
6. Account
xmemo account login [--base-url <url>] [--allow-plaintext] [--json]
xmemo account logout [--yes] [--json]
xmemo account status [--verify] [--base-url <url>] [--json]
xmemo account token status [--verify] [--json]
xmemo account token add --from-stdin --allow-plaintext [--json]
xmemo account token set --from-stdin [--allow-plaintext] [--json]
# Backward-compatible aliases (emit one-line deprecation note on stderr in human mode)
xmemo login
xmemo auth status
xmemo auth-status
xmemo token status
xmemo token add --from-stdin --allow-plaintext
7. Maintenance
# Diagnostics and environment validation
xmemo doctor [--services [memory,dream,knowledge,cloud-skill]] [--base-url <url>] [--json]
xmemo doctor --discovery [--base-url <url>] [--json]
xmemo doctor --client <client-id> [--config <path>] [--smoke] [--auth oauth|key] [--fix] [--json]
# Probes, updates, and environment
xmemo status [--url <url>] [--json]
xmemo update [--dry-run] [--json]
xmemo env [--example] [--shell bash|powershell|cmd] [--json]
xmemo privacy [--json]
xmemo --version [--json]
# Safe removal (only XMemo-owned entries and profiles are removed)
xmemo uninstall <client> --dry-run
xmemo uninstall <client> --yes
xmemo uninstall --all --dry-run
xmemo uninstall --all --yes --profiles
# Backward-compatible aliases (emit one-line deprecation note on stderr in human mode)
xmemo smoke --client codex
xmemo discovery show
Run xmemo help or xmemo <command> --help for complete, version-matched
options.
Client notes
Codex and Cursor
xmemo setup codex
xmemo doctor --client codex --smoke
xmemo setup cursor
Both setup paths write a user-scoped MCP entry and can install a marker-scoped
memory behavior profile. Use --no-profile to configure MCP only. Cursor's
public marketplace plugin remains OAuth-first and contains no bearer-token
configuration.
Gemini CLI and Antigravity
xmemo setup gemini
xmemo setup antigravity
These clients use hosted MCP OAuth. Their generated configuration carries no token value; restart the client and complete the browser login on first use.
OpenClaw
xmemo login
xmemo setup openclaw
openclaw xmemo status
The setup command installs or updates @xmemo/openclaw-memory, installs the
XMemo Skill, reuses the shared XMemo credential, and checks plugin status.
Hermes
xmemo login
xmemo setup hermes
The setup command installs or updates hermes-xmemo, configures the native
provider, and synchronizes the user-scoped XMemo credential with Hermes.
Copilot CLI
xmemo login
xmemo setup copilot
xmemo mcp proxy
Copilot CLI receives a local proxy entry. The proxy reads the credential from user-scoped storage, adds identity metadata, and forwards requests to hosted MCP without writing secrets into Copilot configuration.
Security by default
| Control | Default behavior |
|---|---|
| Telemetry | No CLI analytics or usage telemetry |
| Credential output | Token values are never printed |
| Project files | Generated configuration references secrets; it does not embed them |
| Discovery | doctor, discovery show, and public capability discovery send no token |
| Identity | One stable, non-secret agent-instance ID is stored outside git |
| Writes | Setup supports preview/dry-run; broad removal requires confirmation |
| Local credential storage | Interactive login asks first; non-interactive writes require --allow-plaintext; stored tokens are unencrypted |
| Package contents | An npm files allowlist excludes tests, operations, logs, and server code |
Credential precedence and compatibility aliases are documented by:
xmemo env example --shell bash
xmemo privacy
For private or self-hosted deployments, set XMEMO_URL or pass
--url <service-url>. MEMORY_OS_URL remains a compatibility alias.
Package boundary
Published to npm:
bin/
docs/assets/
src/
README.md
LICENSE
Not published:
.github/
docs/analysis/
docs/architecture/
docs/design/
test/
coverage/
server code
database migrations
deployment files
logs and local state
Development
npm install
npm run release:check
npm run lint
npm test
npm run pack:dry-run
Before proposing a release, run the complete package gate:
npm run prepublishOnly
The local stdio server can be inspected directly:
node bin/mcp-stdio.js
Versioning
This repository distributes two independent products with decoupled version tracks:
- CLI (
@xmemo/client): Published to npm.- Version source:
package.json. - Tag convention:
cli-v*(legacy tags through version 0.4.181 usedv0.4.xxx). - View versions on npm (@xmemo/client).
- Version source:
- Skill (
xmemo): Published to ClawHub and distributed via xmemo.dev.- Version source:
skills/xmemo/scripts/xmemo-skill.mjs(SKILL_VERSION). - Tag convention:
skill-v*. - View versions on ClawHub (xmemo). GitHub Releases for skill releases explicitly carry the
Latestrelease badge to support automated installer and server fallback downloads.
- Version source:
Release model
Normal releases are produced by GitHub Actions from the exact tagged commit, not from a mutable branch checkout or a developer workstation:
develop → CLI version sync → test → cli-v tag → GitHub Actions → npm publish --provenance
The CLI package and hosted MCP service intentionally have separate version streams:
- CLI/npm version:
package.json,package-lock.json, and the npm package entry inserver.json. - Hosted MCP/Registry version: the top-level
server.json.versionandlhm.plugin.json. This version follows the deployed XMemo service.
node scripts/check-release-version.mjs verifies both contracts. A
cli-vX.Y.Z tag must equal the CLI/npm version and publishes only npm. The
MCP Registry is published separately with the Publish MCP Registry metadata
workflow using mcp-vX.Y.Z, which must equal the hosted MCP/Registry version.
The separate npm publish workflow is manual recovery only, so creating a
GitHub Release cannot publish twice. CLI npm publishing uses OIDC trusted
publishing (environment: npm, id-token: write); static NPM_TOKEN is no
longer used. Manual recovery via .github/workflows/publish.yml requires its
own trusted publisher entry on npmjs.com.
Documentation and support
Canonical service documentation lives at docs.xmemo.dev. This repository documents the client; the pages below document the hosted service it connects to.
| Quickstart | docs.xmemo.dev/docs/quickstart |
| MCP overview and per-client setup | docs.xmemo.dev/docs/mcp/overview |
Tool reference (remember, recall, search, …) | docs.xmemo.dev/docs/tools/remember |
| REST API | docs.xmemo.dev/docs/api/authentication |
| Troubleshooting | docs.xmemo.dev/docs/troubleshooting |
| Machine-readable index | xmemo.dev/llms.txt |
License
MIT © 2025–2026 Yonro
Featured
Keeps your Mac awake while Claude Code, Codex or Cursor works. Lets it sleep when they are done.
Try free for 7 days →Block distracting apps from your iPhone permanently without a 3rd party app. Free and open source.
Block now (100% free) →Notes, actions and memory. Without a meeting bot. First month 100% off.
Download for free →belt cli automatically finds the best tools and skills for your agent. image, video, music, tts...
one prompt install →Free an open-source skills that make AI coding agents easier to understand, verify, and control.
Download for free →Connect your Claude agent to live crypto prices and trading routes via 1inch
Get the MCP →Categories
Registryactive
TransportHTTP
AuthRequired
UpdatedMay 30, 2026
