# XMemo (npm · @xmemo/client)

Shared, governed long-term memory for AI agents across tools and sessions via MCP and REST.

- Trust score: 77/100 (medium)
- Registry status: active
- Liveness: live
- Owner verified: no
- Last scored: 2026-08-13

## Components

- remote · `xmemo.dev`: 39/100, [markdown](https://verifymcp.io/servers/yonro-xmemo/xmemo.md), [page](https://verifymcp.io/servers/yonro-xmemo/xmemo)
- npm · `@xmemo/client`: 77/100 (this document), [markdown](https://verifymcp.io/servers/yonro-xmemo/xmemo-client.md), [page](https://verifymcp.io/servers/yonro-xmemo/xmemo-client)

## Channel facts

- Registry: `npm`
- Package: `@xmemo/client`
- Version: `0.4.181`
- Transport: `stdio`

## Trust breakdown

How this component scores in each security and reliability category. Every signal is checked automatically from public evidence about the published package, including repeated runs of it in an isolated sandbox, and we only credit what we can confirm. Scores are 0–100 per category. Scoring method: https://verifymcp.io/docs/scoring (what has changed: https://verifymcp.io/docs/scoring/changelog)

Scored 2026-08-13.

- **Supply Chain Security**: 100/100
  - No malware found by supply-chain analysis.
  - No known CVEs affecting this package version or its production dependencies.
  - No install/post-install scripts declared.
  - No production dependencies, so there is no dependency health to assess.
- **Provenance & Transparency**: 100/100
  - Source repository is publicly reachable at the declared URL.
  - Cryptographically verified build provenance (signed, bound to yonro/memory-os-cli).
  - Clear OSI-approved license (MIT).
  - Actively maintained (last published 2 days ago).
  - Publishes a security disclosure policy (SECURITY.md).
- **Schema Quality & AI Usability**: 81/100
  - 100% of prompts and resources have a non-trivial description (not blank, and not just the item's name).
  - AI-judged instruction clarity (good).
  - Tool/resource definitions use about 1998 tokens (~90/item across 22 items; 20 tools + 2 resources), lean.
  - Usage-examples check failed: none of the tools include examples.
- **Stability & Change Management**: 0/100
  - Stability not yet verified: not enough scan history yet (needs a 30-day window).
- **Tool Coverage**: 100/100
  - 100% of tools have a non-trivial description (not blank, and not just the tool's name).
  - 100% of tool parameters carry a description.
  - Structured output schemas are declared (100% of tools); any adoption earns full credit.
- **Capabilities**: 20/100
  - Spec-recency check failed: implements MCP spec 2024-11-05; the latest is 2026-07-28.

**Unverified: 1 category.** A category scored 0 because we could not verify it: a data source with nothing on this package, evidence we could not reach, or a check we could not run. We only credit what we can confirm.

## Install

### Claude

```bash
claude mcp add yonro-xmemo -- npx -y @xmemo/client
```

### Codex

```bash
codex mcp add yonro-xmemo -- npx -y @xmemo/client
```

### opencode

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "yonro-xmemo": {
      "type": "local",
      "command": [
        "npx",
        "-y",
        "@xmemo/client"
      ],
      "enabled": true
    }
  }
}
```

### OpenClaw

```bash
openclaw mcp add yonro-xmemo --command npx --arg -y --arg @xmemo/client
```

### Hermes

```yaml
mcp_servers:
  yonro-xmemo:
    command: "npx"
    args: ["-y", "@xmemo/client"]
```

### Other

```json
{
  "mcpServers": {
    "yonro-xmemo": {
      "command": "npx",
      "args": [
        "-y",
        "@xmemo/client"
      ]
    }
  }
}
```

## Changelog

Every change recorded for this component, newest first. Days that predate change tracking, or that we cannot explain, say so: "we were watching and nothing happened" and "we were not watching" are different claims.

### 2026-08-13 (score 77)

First indexed and scored.

## MCP tools (20)

### `get_mcp_identity` (~22 tokens)

Check XMemo connection status and the connected account/agent.

Output parameters:

- `result` (string): Human-readable text or JSON requested by output_json.

### `remember` (~48 tokens)

Save a memory so it can be recalled in future conversations.

Input parameters:

- `content` (string, required): Text body to save.
- `path` (string, required): Category path, e.g. preferences, projects/xmemo.

Output parameters:

- `result` (string): Human-readable text or JSON requested by output_json.

### `recall` (~29 tokens)

Recall the most relevant saved memories before answering.

Input parameters:

- `query` (string, required): Natural-language question or search text.

Output parameters:

- `result` (string): Human-readable text or JSON requested by output_json.

### `recall_context` (~282 tokens)

Read a multi-memory context pack. Requires memory:read and does not change content. Use when many memories need explicit budgets; use recall for lightweight answer or get_project_context for project snapshot. max_items/max_tokens bound rendered output.

Input parameters:

- `agent_id` (string): Optional client-supplied agent label for memory attribution.
- `agent_instance_id` (string): Optional stable, non-secret agent instance ID for per-client attribution.
- `bucket` (string): Accessible bucket filter; % includes all accessible buckets.
- `limit` (integer): Candidate-result limit; 0 derives it from the item/token budgets.
- `max_items` (integer): Maximum memories rendered in the context pack.
- `max_tokens` (integer): Approximate token budget for the rendered context pack.
- `memory_type` (string): Memory type filter; auto searches the normal mixed set.
- `output_json` (boolean): True returns the full structured pack; false returns rendered context text.
- `path_filter` (string): Case-insensitive memory-path pattern; % matches all paths.
- `prefer_working` (boolean): True prioritizes active working/session-state signals.
- `query` (string, required): Natural-language query used to rank memories for the context pack.
- `scope` (string): Optional authorized scope; blank uses the token default.
- `team_id` (string): Optional exact authorized team filter.

Output parameters:

- `result` (string): Human-readable text or JSON requested by output_json.

### `memory_stats` (~16 tokens)

Show aggregate statistics for XMemo memories.

Output parameters:

- `result` (string): Human-readable text or JSON requested by output_json.

### `update_memory` (~51 tokens)

Update the content or metadata of an existing memory.

Input parameters:

- `content` (string): Replacement memory content.
- `memory_id` (string, required): Exact XMemo memory reference.
- `path` (string): Replacement memory path.

Output parameters:

- `result` (string): Human-readable text or JSON requested by output_json.

### `explain_memory` (~41 tokens)

Explain why a memory exists or matched a query.

Input parameters:

- `memory_id` (string, required): Exact XMemo memory reference.
- `query` (string): Optional explanation query.

Output parameters:

- `result` (string): Human-readable text or JSON requested by output_json.

### `restore_memory` (~37 tokens)

Restore a previously deleted memory.

Input parameters:

- `memory_id` (string, required): Exact XMemo memory reference.
- `reason` (string): Optional restore reason.

Output parameters:

- `result` (string): Human-readable text or JSON requested by output_json.

### `add_expense` (~421 tokens)

Create one XMemo Ledger transaction and backing memory. Requires memory:write; it records a new transaction or reuses a semantic duplicate, and never deletes Ledger records. Use it for a purchase, income, refund, or transfer; use list_ledger_transactions or get_monthly_ledger_summary for reads. amount must be positive; transaction_type defaults to expense; blank transaction_date uses today's UTC date.

Input parameters:

- `agent_id` (string): Optional client-supplied agent label for memory attribution.
- `agent_instance_id` (string): Optional stable, non-secret agent instance ID for per-client attribution.
- `amount` (number, required): Positive transaction amount; zero and negative values are rejected.
- `bucket` (string): Bucket for the backing memory; defaults to private.
- `category` (string): Optional Ledger category, such as food, transport, or electronics.
- `currency` (string): Currency code or label; labels such as yen or RMB are normalized to codes.
- `device_id` (string): Optional client-supplied device identifier for attribution.
- `device_label` (string): Optional human-readable device label for attribution.
- `item` (string, required): Purchased item, income source, refund, or transfer label.
- `merchant` (string): Optional merchant, payer, payee, or store name.
- `note` (string): Optional note stored with the transaction.
- `path` (string): Memory path; the default follows transaction_type for non-expenses.
- `payment_method` (string): Optional payment method, such as card, cash, Alipay, or WeChat Pay.
- `project_id` (string): Optional exact authorized project ID; stores the transaction in its private scope.
- `scope` (string): Optional authorized scope; must match project_id when both are set.
- `team_id` (string): Optional team attribution within the authorized scope.
- `transaction_date` (string): YYYY-MM-DD transaction date; blank uses today's UTC date.
- `transaction_type` (string): Transaction to create: expense, income, refund, or transfer.

Output parameters:

- `result` (string): Human-readable text or JSON requested by output_json.

### `list_ledger_transactions` (~38 tokens)

Show XMemo Ledger records.

Input parameters:

- `limit` (integer): Maximum number of records.
- `query` (string): Optional ledger search text.

Output parameters:

- `result` (string): Human-readable text or JSON requested by output_json.

### `get_monthly_ledger_summary` (~35 tokens)

Summarize Ledger totals by month and currency.

Input parameters:

- `months` (integer): Number of recent months to summarize.

Output parameters:

- `result` (string): Human-readable text or JSON requested by output_json.

### `forget` (~43 tokens)

Permanently delete a memory by target.

Input parameters:

- `reason` (string): Optional deletion reason.
- `target` (string): The memory to forget: current or an exact memory ID.

Output parameters:

- `result` (string): Human-readable text or JSON requested by output_json.

### `create_memory_todo` (~45 tokens)

Create a TODO/action item with an optional due time.

Input parameters:

- `content` (string, required): Text body of the TODO item.
- `due_at` (string): Optional due time.

Output parameters:

- `result` (string): Human-readable text or JSON requested by output_json.

### `list_memory_todos` (~42 tokens)

List open or completed TODO/action items.

Input parameters:

- `item_status` (string): Optional TODO status filter.
- `limit` (integer): Maximum number of TODOs.

Output parameters:

- `result` (string): Human-readable text or JSON requested by output_json.

### `complete_memory_todo` (~33 tokens)

Mark a TODO/action item completed.

Input parameters:

- `todo_id` (string, required): The memory TODO/action-item ID to complete.

Output parameters:

- `result` (string): Human-readable text or JSON requested by output_json.

### `list_memory_versions` (~29 tokens)

List available versions for a memory.

Input parameters:

- `memory_id` (string, required): Exact XMemo memory reference.

Output parameters:

- `result` (string): Human-readable text or JSON requested by output_json.

### `get_timeline` (~145 tokens)

Read authorized timeline events newest first. Requires memory:read and makes no memory changes. Use it for recent history or session resumption; use recall_context for semantic multi-memory context. limit is clamped to 1-500; session_id and event_type are exact filters.

Input parameters:

- `bucket` (string): Accessible bucket filter; % includes all accessible buckets.
- `event_type` (string): Optional exact event type after lowercase normalization.
- `limit` (integer): Maximum events to return; values are clamped to 1-500.
- `scope` (string): Optional authorized scope; blank uses the token default.
- `session_id` (string): Optional exact session ID filter.

Output parameters:

- `result` (string): Human-readable text or JSON requested by output_json.

### `record_event` (~31 tokens)

Record a significant session event, milestone, or decision.

Input parameters:

- `content` (string, required): Text body of the event.

Output parameters:

- `result` (string): Human-readable text or JSON requested by output_json.

### `update_state` (~262 tokens)

Create or replace one scoped working-state record for resuming a task, next action, or blocker. Requires memory:write; it versions that state slot and refreshes its expiry without deleting other memories. Use remember for durable facts or record_event for history. Provide content or a structured state field; ttl_seconds=0 means no expiry.

Input parameters:

- `blocked_reason` (string): Blocker; used to build the state body when content is blank.
- `bucket` (string): Bucket containing the working-state slot; defaults to work.
- `content` (string): Free-form state body; otherwise provide at least one structured state field.
- `current_task` (string): Current task; used to build the state body when content is blank.
- `metadata_json` (string): JSON object merged into the working-state metadata.
- `next_action` (string): Next action; used to build the state body when content is blank.
- `scope` (string): Scope containing the working-state slot; blank uses the token default.
- `state_key` (string): Normalized state slot; the same owner, bucket, scope, and key updates that slot.
- `ttl_seconds` (integer): Expiry in seconds from 0 to 2592000; 0 means no expiry.

Output parameters:

- `result` (string): Human-readable text or JSON requested by output_json.

### `get_project_context` (~309 tokens)

Read one authorized project's bounded context pack: state, TODOs, decisions, timeline, recent memories, and optional durable recall. Requires memory:read; it does not mutate project memories, and access is audit-logged. Use an exact project_id for a whole-project snapshot; otherwise use recall_context. max_items/max_tokens bound the whole pack; recent_hours affects only timeline; durable_query requires include_durable_context.

Input parameters:

- `agent_id` (string): Optional client-supplied agent label for memory attribution.
- `agent_instance_id` (string): Optional stable, non-secret agent instance ID for per-client attribution.
- `bucket` (string): Accessible bucket filter; % includes all accessible buckets.
- `durable_query` (string): Query only for durable recall; ignored when include_durable_context is false.
- `include_durable_context` (boolean): Include semantic durable recall; false omits that section.
- `max_items` (integer): Whole-pack item budget from 1 to 1000.
- `max_tokens` (integer): Whole-pack approximate token budget from 1 to 50000.
- `output_json` (boolean): True returns the full structured pack; false returns a text summary.
- `project_id` (string, required): Exact authorized project ID; project names are not accepted.
- `recent_hours` (integer): Timeline lookback from 1 to 8760 hours; other sections are unaffected.
- `team_id` (string): Optional exact authorized team focus; other team rows are excluded.

Output parameters:

- `result` (string): Human-readable text or JSON requested by output_json.

## Diagnostics

Captured diagnostic sections: Provenance, Dependencies. The full working is on the page: https://verifymcp.io/servers/yonro-xmemo/xmemo-client#diagnostics

## Score history

- 2026-08-13: 77

## Links

- npm package: https://www.npmjs.com/package/@xmemo/client
- Socket report: https://socket.dev/npm/package/@xmemo/client
- Repository: https://github.com/yonro/memory-os-cli
- Website: https://xmemo.dev/product/mcp
- Changelog RSS feed: https://verifymcp.io/servers/yonro-xmemo/xmemo-client.xml
- Changelog JSON feed: https://verifymcp.io/servers/yonro-xmemo/xmemo-client.json
- HTML version of this page: https://verifymcp.io/servers/yonro-xmemo/xmemo-client