XMemo

https://docs.xmemo.dev/
Admin
XMemo serves as a shared memory home for AI assistants, allowing clients to save and recall useful...
Tokens:123,827
Snippets:1,025
Trust Score:7.5
Update:2 days ago
Show doc for...
Tokens:
Raw
================
LIBRARY RULES
================
- Use https://xmemo.dev/mcp as the canonical hosted XMemo MCP endpoint.
- Use the authentication mode documented for the specific MCP client; prefer OAuth only where that client profile explicitly supports it.
- Never hardcode XMEMO_KEY, bearer tokens, API keys, passwords, or other credentials in public configuration or source code.
- For token-based clients, read XMEMO_KEY from an environment variable or supported secret store.
- Treat X-Memory-OS-Agent-ID and XMEMO_AGENT_INSTANCE_ID as attribution identifiers, not authentication credentials.
- Keep XMEMO_AGENT_INSTANCE_ID stable for the same local installation or autonomous runner when the documented client profile requires it.
- Use only XMemo tools, SDK helpers, parameters, scopes, and endpoints that are explicitly documented. Never invent XMemo APIs or tool names.
- Store durable and reusable context in XMemo, such as project facts, decisions, preferences, corrections, and handoff information; avoid transient conversation noise.
- Preserve documented project, memory scope, provenance, and attribution semantics when saving or retrieving context.
- Prefer the current canonical XMemo developer documentation over old examples, marketing pages, third-party snippets, or deprecated configuration.

================
CODE SNIPPETS
================
### Install @xmemo/client CLI

Source: https://docs.xmemo.dev/docs/sdk/typescript

Install the official @xmemo/client CLI package globally and run setup with the xmemo.dev URL. This package is the CLI orchestrator for account setup, diagnostics, and local MCP server management.

```bash
npm install -g @xmemo/client
npx @xmemo/client setup --url https://xmemo.dev
```

--------------------------------

### Install Hermes XMemo plugin and setup memory

Source: https://docs.xmemo.dev/docs/connect/hermes

Install the XMemo provider using the Hermes plugin market command. For older Hermes versions that lack the plugin market command, use the pip fallback and then run the memory setup wizard.

```bash
hermes plugins install xmemo

# Fallback for older Hermes versions
pip install hermes-xmemo
hermes memory setup xmemo
```

--------------------------------

### Check status, update, and install skills

Source: https://docs.xmemo.dev/docs/skills/updates

These commands check installation status across all clients, update an installed skill with a dry-run preview and then apply it, and install to a specific client. The update command uses --dry-run to preview and --yes to confirm.

```bash
# Check status across all detected clients:
xmemo skill status --all

# Update an installed skill with preview:
xmemo skill update --client codex --dry-run
xmemo skill update --client codex --yes

# Install to a specific client:
xmemo skill install --client claude-code --yes
```

--------------------------------

### Agent installation instructions

Source: https://docs.xmemo.dev/docs/quickstart

Paste this text into an agent to install the standalone XMemo Skill. It instructs the agent to run the installer from the provided URLs, set XMEMO_SKILL_DIR, run the doctor command, reload skills, and follow first-run steps. Emphasizes normal safety checks and no elevated privileges.

```text
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.
```

--------------------------------

### Install and use Node.js 22.22.0 with nvm

Source: https://docs.xmemo.dev/docs/quickstart

Install and switch to Node.js 22.22.0 or higher using nvm. Required for the standalone Skill to operate.

```bash
nvm install 22.22.0 && nvm use 22.22.0
```

--------------------------------

### Deployment Guidelines content example

Source: https://docs.xmemo.dev/docs/guides/knowledge-bases

Example content for the Deployment Guidelines knowledge item. This content is edited and saved as a new immutable revision.

```markdown
## Deployment Guidelines

Production deployments require two peer approvals, clean migration dry-runs, verified canary health, and automated smoke verification.
```

--------------------------------

### Search memories HTTP request example

Source: https://docs.xmemo.dev/docs/api/memory

Example GET request to /v1/memories/search with query parameters and X-API-Key header. The response includes Cache-Control: no-store, private.

```http
GET /v1/memories/search?query=current%20MCP%20decision&limit=5&scope=memory-os&explain=true
X-API-Key: <your-assigned-api-key>
```

--------------------------------

### taskStart(content, options)

Source: https://docs.xmemo.dev/docs/sdk/typescript

Starts a task by capturing content with default status 'started' and memoryType 'working'. Accepts content string and optional AgentWorkflowOptions, returns Promise<CaptureResult>.

```APIDOC
## taskStart(content, options)

### Description
Starts a task by capturing the provided content. Supplies default status 'started' and memoryType 'working'.

### Method
async taskStart(content: string, options: AgentWorkflowOptions = {}): Promise<CaptureResult>

### Parameters
- **content** (string) - Required - The content to capture.
- **options** (AgentWorkflowOptions) - Optional - Additional workflow options (e.g., source, sessionId, taskId).

### Request Example
```ts
await client.taskStart('Implement MCP token repair', { source: 'codex', sessionId: 's1', taskId: 'p0' });
```

### Response
Returns a Promise<CaptureResult>.
```

--------------------------------

### Install XMemo Gemini CLI extension

Source: https://docs.xmemo.dev/docs/mcp/gemini

Run this command to install the XMemo extension for Gemini CLI. The extension is anchored to the yonro/xmemo-gemini-cli repository.

```bash
gemini extensions install https://github.com/yonro/xmemo-gemini-cli
```

--------------------------------

### Install XMemo MCP client for Kiro

Source: https://docs.xmemo.dev/docs/mcp/kiro

Run this command to automatically install the XMemo MCP client for Kiro. It configures the OAuth client with memory:read and knowledge:read scopes.

```bash
npx @xmemo/client mcp add kiro
```

--------------------------------

### Install xmemo-agent-framework with maf extra

Source: https://docs.xmemo.dev/docs/connect/microsoft-agent-framework

Install the package with the optional maf extra that pins agent-framework-core==1.21.0.

```bash
pip install "xmemo-agent-framework[maf]==0.2.0"
```

--------------------------------

### xmemo Skill command usage examples (bash)

Source: https://docs.xmemo.dev/docs/skills/operations

Bash examples covering memory read/write, context assembly with Knowledge inclusion, task continuity snapshots, ledger entries, and diagnostics. Uses node scripts/xmemo-skill.mjs with commands such as remember, recall, read, update, forget, recall-context, save-state, restart-snapshot, expense-add, overview, and doctor.

```bash
# Memory read and write operations:
node scripts/xmemo-skill.mjs remember --content "Production build uses node 22.22" --path "ops/build"
node scripts/xmemo-skill.mjs recall --query "build node version" --limit 3
node scripts/xmemo-skill.mjs read --id mem_01hxyz... --offset 0 --limit 1000
node scripts/xmemo-skill.mjs update --id mem_01hxyz... --content "Production build uses node 22.22.0 LTS"
node scripts/xmemo-skill.mjs forget --id mem_01hxyz... --confirm

# Context assembly with optional Knowledge inclusion:
node scripts/xmemo-skill.mjs recall-context --query "TLS root configuration" --include_knowledge true

# Task continuity and restart snapshots:
node scripts/xmemo-skill.mjs save-state --key active_task --content "Refactoring migration script"
node scripts/xmemo-skill.mjs restart-snapshot --state_key active_task --session_id sess_alpha_0928

# Ledger and analytics:
node scripts/xmemo-skill.mjs expense-add --item "Cloud hosting" --amount 120 --currency USD
node scripts/xmemo-skill.mjs overview
node scripts/xmemo-skill.mjs doctor
```

--------------------------------

### Create response schema example

Source: https://docs.xmemo.dev/docs/api/memory

Example JSON response for create operations. The implementation returns {id: string, status: "remembered"} for remember and the created memory identifier for store.

```json
{
  "id": "<memory-id>",
  "status": "remembered"
}
```

--------------------------------

### Install standalone XMemo Skill via curl or XMemo CLI

Source: https://docs.xmemo.dev/docs/skills/quickstart

Run the canonical HTTPS installer with XMEMO_SKILL_DIR set to your skills directory plus /xmemo-memory, or use the XMemo CLI with --client claude-code. Requires Node.js >= 22.22.0. In pre-release environments, ensure the parent directory exists before running.

```bash
# Ask your agent to run the installer, or run it directly:
curl -fsSL https://xmemo.dev/skill/install | XMEMO_SKILL_DIR="$HOME/.claude/skills/xmemo-memory" sh

# Or install via XMemo CLI:
xmemo skill install --client claude-code
```

--------------------------------

### Install OpenClaw memory plugin and companion Skill

Source: https://docs.xmemo.dev/docs/connect/openclaw

Install the native OpenClaw memory plugin from ClawHub and the companion Skill using OpenClaw package management. Requires ClawHub package access and Node.js 22.22.0+ for the Skill.

```bash
openclaw plugins install clawhub:@xmemo/openclaw-memory
openclaw skills install @xmemo/xmemo
```

--------------------------------

### Install dsh-xmemo plugin

Source: https://docs.xmemo.dev/docs/connect/deepseek-harness

Adds the native dsh-xmemo plugin to a DeepSeek Harness profile. Replace <name> with your profile name. Requires dsh CLI installed and Node.js 18.0.0 or higher.

```bash
dsh plugin --profile <name> add dsh-xmemo
```

--------------------------------

### Get memory type from normalized agent event

Source: https://docs.xmemo.dev/docs/concepts/memory-model

Imports normalizeAgentEvent and toMemoryCandidate from '@xmemo/client'. Normalizes a command_completed event and logs the resulting memory_type, which is 'episodic' for this example.

```typescript
import { normalizeAgentEvent, toMemoryCandidate } from '@xmemo/client';

const event = normalizeAgentEvent(
  { type: 'command_completed', command: 'pytest', exit_code: 0, output: '12 passed' },
  { source: 'shell', defaultAgentId: 'codex' },
);

console.log(toMemoryCandidate(event).memory_type); // episodic
```

--------------------------------

### recall_context call to restore context before a task

Source: https://docs.xmemo.dev/docs/tools/recall-context

Example call to restore project context before starting a task, using a natural-language query and explicit budget limits. The response opens with a '### XMemo Context' heading and an 'Items: <n>' line, and may include a 'Budget: ...' line when results were dropped or shortened.

```TypeScript
recall_context({
  query: "recent decisions on the memory-os project",
  max_items: 6,
  max_tokens: 1200
})
```

--------------------------------

### Run connectivity and authentication checks

Source: https://docs.xmemo.dev/docs/skills/quickstart

Run these commands from the installed skill directory. The doctor command checks network and service reachability without credentials. The login command starts browser-based device sign-in; the --allow-plaintext flag stores the token unencrypted in ~/.xmemo/skill-credentials.json with 0600 permissions. The auth status command validates that the credential has the required memory scopes.

```bash
node scripts/xmemo-skill.mjs doctor --anonymous
node scripts/xmemo-skill.mjs login --allow-plaintext
node scripts/xmemo-skill.mjs auth status --verify
```

--------------------------------

### GET /v1/recall

Source: https://docs.xmemo.dev/docs/api/memory

Searches memories. This is the same search operation as GET /v1/memories/search.

```APIDOC
## GET /v1/recall

### Description
Searches memories. This is the same search operation as GET /v1/memories/search.

### Method
GET

### Endpoint
/v1/recall

### Response
#### Success Response (200)
Search results.
```

--------------------------------

### client.taskStart(title, options)

Source: https://docs.xmemo.dev/docs/sdk/typescript

Captures a task lifecycle start event. Returns a CaptureResult with fields such as shouldCapture, action, reason, qualityScore, event_id, and optional memory_id.

```APIDOC
## client.taskStart(title, options)

### Description
Captures a task lifecycle start event. Returns a CaptureResult object.

### Method
SDK Method

### Parameters
- **title** (string) - Required - Title of the task.
- **options** (object) - Optional - Additional options.
  - **source** (string) - Optional - Source of the event (e.g., 'codex').
  - **sessionId** (string) - Optional - Session identifier.
  - **scope** (string) - Optional - Scope for the event.

### Request Example
client.taskStart('Implement production adapter hook', { source: 'codex', sessionId, scope });

### Response
#### Success Response
- **shouldCapture** (boolean) - Whether the event should be captured.
- **action** (string) - Action taken.
- **reason** (string) - Reason for the action.
- **qualityScore** (number) - Quality score.
- **event_id** (string) - Event identifier.
- **memory_id** (string) - Optional memory identifier.
```

--------------------------------

### GET /v1/memories/search

Source: https://docs.xmemo.dev/docs/api/memory

Searches memories. This is the same search operation as GET /v1/recall.

```APIDOC
## GET /v1/memories/search

### Description
Searches memories. This is the same search operation as GET /v1/recall.

### Method
GET

### Endpoint
/v1/memories/search

### Response
#### Success Response (200)
Search results.
```

--------------------------------

### First-party stdio proxy configuration (xmemo-mcp)

Source: https://docs.xmemo.dev/docs/mcp/overview

JSON configuration for stdio-only clients such as Claude Desktop. Uses the @xmemo/client CLI package. Paste your actual API key; Claude Desktop does not expand ${env:...} variables.

```json
{
  "mcpServers": {
    "XMemo": {
      "command": "npx",
      "args": [
        "-y",
        "-p",
        "@xmemo/client",
        "xmemo-mcp"
      ],
      "env": {
        "XMEMO_KEY": "<your-xmemo-api-key>",
        "XMEMO_URL": "https://xmemo.dev"
      }
    }
  }
}
```

--------------------------------

### Local proxy setup commands for Copilot CLI

Source: https://docs.xmemo.dev/docs/mcp/copilot-cli

Run these commands to set up the local proxy path. The proxy must be kept running in a background terminal.

```bash
xmemo login
xmemo setup copilot
xmemo mcp proxy  # keep running in a background terminal
```

--------------------------------

### recall example: quick best-effort recall

Source: https://docs.xmemo.dev/docs/tools/recall

Example call to recall with a natural-language query and a limit of 3, used for a quick best-effort lookup.

```typescript
recall({
  query: "current MCP authentication decision",
  limit: 3
})
```

--------------------------------

### Inspect agent profile instructions and record offer status

Source: https://docs.xmemo.dev/docs/skills/quickstart

Use these commands to view the recommended prompt instructions for project agent configuration and to record a deferred or declined offer so the agent does not prompt repeatedly. The '--status later' and '--status never' flags record the user's preference.

```bash
# Inspect agent profile instructions:
node scripts/xmemo-skill.mjs profile

# Record deferred or declined offer:
node scripts/xmemo-skill.mjs profile --status later
node scripts/xmemo-skill.mjs profile --status never
```

--------------------------------

### Set credential via xmemo login or direct configuration

Source: https://docs.xmemo.dev/docs/mcp/copilot-cli

Use 'xmemo login' for local proxy setup, or apply the token directly through Copilot CLI or a supported secret reference for direct configuration.

```bash
# For local proxy:
xmemo login
# For direct configuration, apply token through Copilot CLI or supported secret reference
```

--------------------------------

### Knowledge search JSON response example

Source: https://docs.xmemo.dev/docs/concepts/knowledge-bases

Example JSON response from a knowledge search, showing a result with item ID, revision ID, title, content, reference, and score.

```json
{
  "type": "knowledge_search",
  "results": [
    {
      "knowledge_item_id": "item_runbook_deploy",
      "knowledge_revision_id": "rev_v2_deploy_runbook",
      "title": "Production Deployment Runbook",
      "content": "Production deployments require two peer approvals, clean migration dry-runs, and verified canary health.",
      "reference": "knowledge:item_runbook_deploy@rev_v2_deploy_runbook",
      "score": 3.84
    }
  ]
}
```

--------------------------------

### Force re-install and inspect backups

Source: https://docs.xmemo.dev/docs/skills/updates

Force re-install with automatic backup creation and inspect preserved backups. The backup location is ~/.xmemo/backups/skills/<client_id>/<name>-<timestamp>.

```bash
# Force re-install with automatic backup creation:
xmemo skill install --client codex --force --yes

# Inspect preserved backups:
ls -la ~/.xmemo/backups/skills/codex/
```

--------------------------------

### Interactive device login and token import

Source: https://docs.xmemo.dev/docs/skills/authentication

Start interactive device login with explicit plaintext flag, or pipe an existing token securely from standard input. Verify active session status.

```bash
# Start interactive device login (requires explicit plaintext flag):
node scripts/xmemo-skill.mjs login --allow-plaintext

# Or pipe an existing token securely from standard input:
printf '%s' "$XMEMO_KEY" | node scripts/xmemo-skill.mjs auth add --from-stdin --allow-plaintext

# Verify active session status:
node scripts/xmemo-skill.mjs auth status --verify
```

--------------------------------

### overview

Source: https://docs.xmemo.dev/docs/skills/operations

Provides an overview of memory and system state.

```APIDOC
## overview

### Description
Provides an overview of memory and system state.

### Usage
`overview`

### Authorization
Requires `memory:read`.
```

--------------------------------

### Generate XMEMO_AGENT_INSTANCE_ID

Source: https://docs.xmemo.dev/docs/mcp/windsurf

Generate a stable non-secret instance identifier per local Devin Desktop installation. Persist and reuse this value for the same local install to maintain consistent attribution across restarts.

```bash
export XMEMO_AGENT_INSTANCE_ID='<stable-local-devin-desktop-instance-id>'
# Persist and reuse this value for the same local install
```

--------------------------------

### POST /v1/memories/{memory_id}/forget request example

Source: https://docs.xmemo.dev/docs/api/memory

Example HTTP request to the forget endpoint. The mode defaults to soft_delete; hard_delete and redact are irreversible. The response is typed in the public OpenAPI schema.

```http
POST /v1/memories/<memory-id>/forget
X-API-Key: <your-assigned-api-key>
Content-Type: application/json

{
  "mode": "soft_delete",
  "reason": "No longer needed"
}
```

--------------------------------

### Set XMEMO_AGENT_INSTANCE_ID environment variable

Source: https://docs.xmemo.dev/docs/mcp/kiro

Generate a stable non-secret instance identifier per local Kiro install. Persist and reuse this value for the same local install to keep attribution consistent across sessions.

```bash
export XMEMO_AGENT_INSTANCE_ID='<stable-local-kiro-instance-id>'
# Persist and reuse this value for the same local install
```

--------------------------------

### POST /v1/recall/context request example

Source: https://docs.xmemo.dev/docs/api/memory

Example HTTP request to the context endpoint. The query field is required; other fields have defaults. The response is an untyped object in OpenAPI, but the normal implementation returns a value-density-v2 context object.

```http
POST /v1/recall/context
X-API-Key: <your-assigned-api-key>
Content-Type: application/json

{
  "query": "recent progress on memory-os",
  "scope": "memory-os",
  "memory_type": "auto",
  "status": "active",
  "max_items": 8,
  "max_tokens": 1500,
  "prefer_working": true
}
```

--------------------------------

### List open items before adding another

Source: https://docs.xmemo.dev/docs/tools/todos

Use this to list existing TODOs before creating new ones to avoid duplicates when multiple agents work in the same project scope.

```TypeScript
todo({ action: "list" })
```

--------------------------------

### Create restart snapshot with restart-snapshot

Source: https://docs.xmemo.dev/docs/guides/resume-and-handoff

Captures the complete session continuity package before handoff. Uses the restart-snapshot command with a TTL of 604800 seconds.

```bash
node scripts/xmemo-skill.mjs restart-snapshot --state_key active_task --session_id sess_alpha_0928 --ttl_seconds 604800
```

--------------------------------

### Create XMemo context provider for Microsoft Agent Framework

Source: https://docs.xmemo.dev/docs/connect/microsoft-agent-framework

Create a Connection and Provider with a Policy for reading XMemo context, then wrap it in XMemoContextProvider. Pass context_provider to the host agent context-provider configuration and close the connection when the host session ends.

```python
import os
from xmemo_agent_framework import Connection, Policy, Provider, ReadRoute
from xmemo_agent_framework.maf import XMemoContextProvider

connection = Connection(os.environ["XMEMO_URL"], os.environ["XMEMO_API_KEY"])
read_provider = Provider(
    connection,
    Policy(
        recall_enabled=True,
        route=ReadRoute.RECALL,
        scope="tenant:project:my-project",
        max_items=8,
        max_tokens=2000,
    ),
)
context_provider = XMemoContextProvider(read_provider)
```

--------------------------------

### GET /v1/projects/{project_id}/maintenance/settings

Source: https://docs.xmemo.dev/docs/api/projects

Retrieves project maintenance settings.

```APIDOC
## GET /v1/projects/{project_id}/maintenance/settings

### Description
Retrieves project maintenance settings.

### Method
GET

### Endpoint
/v1/projects/{project_id}/maintenance/settings

### Parameters
#### Path Parameters
- **project_id** (string) - Required - The ID of the project.

### Response
#### Success Response (200)
Returns ProjectMaintenanceSettingsResponse.

#### Error Response (422)
HTTPValidationError

```

--------------------------------

### Direct MCP with XMEMO_KEY configuration

Source: https://docs.xmemo.dev/docs/quickstart

Use this configuration only for clients or headless runners that cannot complete OAuth. Store XMEMO_KEY in the local environment or secret store, keep the hosted MCP URL in config, and never paste the real token into public docs or chat. Optional identity via XMEMO_AGENT_INSTANCE_ID.

```text
MCP URL: https://xmemo.dev/mcp
Token source: XMEMO_KEY environment variable
Optional identity: XMEMO_AGENT_INSTANCE_ID
```
Tokens:
Raw