@xmemo/client 0.4.172 → 0.4.174

package/README.md

@@ -1,10 +1,12 @@
 # XMemo CLI
 
 [![smithery badge](https://smithery.ai/badge/xmemo/xmemo)](https://smithery.ai/servers/xmemo/xmemo)
+[![MCP Badge](https://lobehub.com/badge/mcp/yonro-memory-os-cli)](https://lobehub.com/mcp/yonro-memory-os-cli)
 
 `@xmemo/client` is the privacy-first command line entry point for XMemo client
 setup. It is intentionally small: the npm package contains only the CLI and
-setup helper code needed on a user's machine.
+setup/helper assets needed on a user's machine: the CLI runtime, client setup
+profiles, XMemo skills, and marketplace plugin metadata.
 
 `@yonro/xmemo-client` is reserved as a Yonro fallback package. The CLI exposes
 `xmemo` as the primary command and keeps `memory-os` as a compatibility alias.
@@ -12,12 +14,14 @@ setup helper code needed on a user's machine.
 The XMemo server, database, token registry, deployment files, logs, and
 internal scripts are not part of this npm package.
 
-> 🧠 **XMemo is also an MCP Server** — give your AI agents persistent memory across sessions. See [MCP Setup](#mcp-setup) below.
+> **XMemo CLI is the top-level control plane** — use `xmemo login`, `xmemo doctor`, `xmemo setup <client>`, and smoke checks before hand-editing MCP config. Hosted MCP remains the universal runtime path for clients that do not have a native integration.
 
-## MCP Server Overview
+## XMemo Runtime Overview
 
-**XMemo** is a user-owned, hosted MCP memory service that lets AI agents persistently store, search, recall, update, and manage notes and memory fragments across sessions, projects, and tools.
+**XMemo** is a user-owned memory system that lets AI agents persistently store, search, recall, update, and manage notes and memory fragments across sessions, projects, and tools.
 
+- **Top-level CLI**: `xmemo` from `@xmemo/client`
+- **Native integrations**: OpenClaw XMemo memory plugin and Hermes `hermes-xmemo` provider
 - **MCP Endpoint**: `https://xmemo.dev/mcp` (Streamable HTTP)
 - **Auth**: Bearer Token (`XMEMO_KEY`) or MCP OAuth
 - **Tools**: `remember`, `recall`, `search_memory`, `update_memory`, `forget`, `redact_memory`, `explain_memory`, `create_memory_todo`, `list_memory_todos`, `complete_memory_todo`, `record_event`, `get_timeline`, `add_expense`
@@ -120,8 +124,8 @@ xmemo privacy
   project files, shell history, and printed token values.
 - Legacy `xmemo token set` refuses plaintext credential storage unless
   `--allow-plaintext` is explicitly provided.
-- The npm package uses a `files` whitelist so only `bin`, `src`, `README.md`,
-  and `LICENSE` are published.
+- The npm package uses a `files` whitelist so only `bin`, `src`, `skills`,
+  published plugin metadata/assets, `README.md`, and `LICENSE` are published.
 
 ## Token flow
 

package/bin/mcp-stdio.js

@@ -1,30 +1,14 @@
 #!/usr/bin/env node
 /**
- * XMemo MCP stdio server — thin local proxy for Glama quality tests and
- * clients that only support stdio transport.
+ * XMemo MCP stdio server — self-contained local proxy.
  *
- * Reads XMEMO_KEY and XMEMO_URL from environment, forwards all MCP
- * JSON-RPC messages to the hosted endpoint over Streamable HTTP.
+ * Reads XMEMO_KEY and XMEMO_URL from environment, forwards MCP JSON-RPC
+ * messages to the hosted endpoint over Streamable HTTP. Falls back to
+ * static tool metadata when unauthenticated so marketplace validators
+ * can confirm server capabilities.
+ *
+ * Equivalent to: xmemo mcp serve
  */
-import { spawn } from 'node:child_process';
-import { resolve, dirname } from 'node:path';
-import { fileURLToPath } from 'node:url';
-
-const __dirname = dirname(fileURLToPath(import.meta.url));
-const mcpRemoteBin = resolve(__dirname, '..', 'node_modules', '.bin', 'mcp-remote');
-const url = process.env.XMEMO_URL
-  ? `${process.env.XMEMO_URL.replace(/\/$/, '')}/mcp`
-  : 'https://xmemo.dev/mcp';
-const token = process.env.XMEMO_KEY ?? '';
-
-const args = [url];
-if (token) {
-  args.push('--header', `Authorization:Bearer ${token}`);
-}
-
-const child = spawn(process.execPath, [mcpRemoteBin, ...args], {
-  stdio: ['inherit', 'inherit', 'inherit'],
-  env: { ...process.env }
-});
+import { startStdioServer } from '../src/mcp/stdio-server.js';
 
-child.on('exit', (code) => process.exit(code ?? 1));
+await startStdioServer(process.env);

package/package.json

@@ -1,17 +1,20 @@
 {
   "name": "@xmemo/client",
-  "version": "0.4.172",
+  "version": "0.4.174",
   "description": "Privacy-first CLI and MCP setup helper for XMemo.",
   "mcpName": "io.github.yonro/xmemo",
   "type": "module",
   "bin": {
     "xmemo": "bin/memory-os.js",
-    "memory-os": "bin/memory-os.js"
+    "memory-os": "bin/memory-os.js",
+    "xmemo-mcp": "bin/mcp-stdio.js"
   },
   "files": [
     "bin",
     "src",
+    "skills",
     "plugins/kiro",
+    "plugins/xmemo",
     "README.md",
     "LICENSE"
   ],

package/plugins/xmemo/.cursor-plugin/plugin.json

@@ -0,0 +1,38 @@
+{
+  "name": "xmemo",
+  "displayName": "XMemo",
+  "version": "0.1.0",
+  "description": "Connect Cursor to XMemo's hosted, user-owned memory layer for durable project context, coding preferences, decisions, and reusable agent knowledge.",
+  "author": {
+    "name": "XMemo",
+    "email": "support@xmemo.dev"
+  },
+  "publisher": "XMemo",
+  "homepage": "https://xmemo.dev",
+  "repository": "https://github.com/yonro/memory-os-cli",
+  "license": "UNLICENSED",
+  "logo": "assets/logo.svg",
+  "keywords": [
+    "cursor",
+    "plugin",
+    "mcp",
+    "memory",
+    "agent-memory",
+    "developer-tools",
+    "oauth"
+  ],
+  "category": "Developer Tools",
+  "tags": [
+    "mcp",
+    "memory",
+    "oauth",
+    "developer-tools"
+  ],
+  "rules": [
+    "rules/AGENTS.mdc"
+  ],
+  "skills": [
+    "skills/agents/SKILL.md"
+  ],
+  "mcpServers": "mcp.json"
+}

package/plugins/xmemo/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog
+
+## 0.1.0
+
+- Initial Cursor marketplace plugin scaffold.
+- Added OAuth-first hosted XMemo MCP config.
+- Added XMemo memory rule and skill for safe durable memory workflows in Cursor.

package/plugins/xmemo/LICENSE

@@ -0,0 +1,7 @@
+Copyright (c) Yonro.
+
+All rights reserved.
+
+This Cursor plugin is published as an XMemo client distribution artifact.
+No license is granted to copy, modify, distribute, sublicense, or use the source
+code except as expressly permitted by Yonro in a separate written agreement.

package/plugins/xmemo/README.md

@@ -0,0 +1,32 @@
+# XMemo Cursor Plugin
+
+XMemo gives Cursor a hosted, user-owned memory layer for durable project context, coding preferences, decisions, TODOs, and reusable agent knowledge.
+
+## What it installs
+
+- `mcp.json` adds the hosted XMemo MCP server at `https://xmemo.dev/mcp`.
+- `assets/logo.svg` reuses the canonical XMemo marketplace icon source used by the existing ChatGPT/Claude listing assets.
+- `rules/AGENTS.mdc` tells Cursor when to use XMemo memory.
+- `skills/agents/SKILL.md` gives Cursor a safe workflow for recall, writes, TODOs, and destructive memory actions.
+
+## Authentication
+
+The marketplace plugin is OAuth-first. The plugin metadata stores only the hosted MCP URL; the first XMemo tool use should open the browser-based OAuth flow. Do not add `Authorization`, `Bearer`, or `XMEMO_KEY` to the marketplace `mcp.json`.
+
+Manual direct-key fallback remains available through:
+
+```bash
+xmemo mcp config --client cursor --json
+```
+
+Use that fallback only for local/manual installs where Cursor OAuth is unavailable.
+
+## Reviewer smoke prompts
+
+1. "List the XMemo tools you can use in Cursor."
+2. "Search XMemo for coding style preferences for this project."
+3. "Remember in XMemo: For Cursor review, prefer small PRs with validation evidence."
+4. "Recall what I saved about Cursor review PR preferences."
+5. "Create a XMemo memory TODO to capture Cursor review screenshots tomorrow, then list my TODOs."
+
+Use a dedicated reviewer workspace with synthetic data only. Redact emails, OAuth codes, cookies, bearer tokens, trace IDs, internal account IDs, real memory content, and private local paths from evidence.

package/plugins/xmemo/assets/logo.svg

@@ -0,0 +1,27 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1024 1024" role="img" aria-label="XMemo Claude connector icon">
+  <defs>
+    <radialGradient id="halo" cx="28%" cy="18%" r="78%">
+      <stop offset="0" stop-color="#8df7d5"/>
+      <stop offset="0.36" stop-color="#22d3ee"/>
+      <stop offset="0.74" stop-color="#102033"/>
+      <stop offset="1" stop-color="#070b18"/>
+    </radialGradient>
+    <linearGradient id="mark" x1="180" x2="844" y1="238" y2="786" gradientUnits="userSpaceOnUse">
+      <stop offset="0" stop-color="#f2fff9"/>
+      <stop offset="0.42" stop-color="#8df7d5"/>
+      <stop offset="1" stop-color="#22d3ee"/>
+    </linearGradient>
+    <filter id="glow" x="-20%" y="-20%" width="140%" height="140%" color-interpolation-filters="sRGB">
+      <feDropShadow dx="0" dy="24" stdDeviation="46" flood-color="#22d3ee" flood-opacity="0.36"/>
+      <feDropShadow dx="0" dy="0" stdDeviation="18" flood-color="#8df7d5" flood-opacity="0.46"/>
+    </filter>
+  </defs>
+  <rect width="1024" height="1024" rx="220" fill="#070b18"/>
+  <circle cx="272" cy="214" r="440" fill="url(#halo)" opacity="0.64"/>
+  <circle cx="842" cy="820" r="420" fill="#14b8a6" opacity="0.18"/>
+  <path fill="#ffffff" opacity="0.08" d="M126 746c160 70 310 88 448 56 138-31 246-110 324-235v235c-88 78-197 125-326 141-156 19-304-7-446-79Z"/>
+  <g filter="url(#glow)">
+    <path fill="url(#mark)" d="M224 724V300h118l170 230 170-230h118v424H672V502L552 670h-80L352 502v222Z"/>
+    <path fill="#e6fff8" opacity="0.92" d="M382 300h96l34 48 34-48h96L512 486Z"/>
+  </g>
+</svg>

package/plugins/xmemo/mcp.json

@@ -0,0 +1,7 @@
+{
+  "mcpServers": {
+    "XMemo": {
+      "url": "https://xmemo.dev/mcp"
+    }
+  }
+}

package/plugins/xmemo/rules/AGENTS.mdc

@@ -0,0 +1,16 @@
+---
+description: Use XMemo for durable project memory, coding preferences, decisions, TODOs, and cross-session context through the hosted MCP server.
+---
+
+# XMemo memory rule
+
+Use XMemo when the user asks Cursor to remember, recall, search, update, explain, delete, restore, or summarize durable context that should survive beyond the current chat.
+
+Prefer XMemo for:
+
+- coding conventions, repository facts, product decisions, debugging notes, and release runbooks;
+- user preferences that should transfer across Cursor sessions or projects;
+- memory-backed TODO/action items and follow-ups;
+- context packs before planning or implementation when prior project memory could affect the answer.
+
+Do not ask the user to paste raw API keys, bearer tokens, OAuth codes, cookies, trace IDs, or private local paths into chat. If XMemo is not authorized, tell the user to reconnect or complete the OAuth flow in Cursor.

package/plugins/xmemo/skills/agents/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: agents
+description: Use XMemo's hosted MCP memory tools for durable context, project preferences, decisions, reminders, and cross-session recall in Cursor.
+---
+
+# XMemo Memory
+
+Use this skill when the task may depend on prior memory, durable project context, coding preferences, decisions, or follow-up actions.
+
+## Workflow
+
+1. Recall first when prior context could change the answer. Use XMemo search/recall/context tools before making assumptions about preferences or past decisions.
+2. Save only durable information that the user asks to remember or that is clearly useful across future sessions.
+3. Keep memory content concise, scoped, and useful. Prefer concrete facts, decisions, links to public docs, and action items over chat transcripts.
+4. For destructive memory actions, confirm the exact target before deleting, forgetting, or overwriting.
+5. If authorization fails, tell the user: "Reconnect XMemo through OAuth, or run `xmemo login`, or visit https://xmemo.dev to set up your token." Do not request raw tokens in chat.
+
+## Good memory candidates
+
+- Repository conventions and verified commands.
+- Architecture decisions, release procedures, and deployment notes.
+- User-approved preferences for code review, testing, documentation, or UX.
+- TODOs and follow-ups that should be visible to future agents.
+
+## Avoid saving
+
+- Secrets, credentials, OAuth codes, cookies, API keys, or token prefixes.
+- Private customer data or sensitive personal data.
+- Temporary debugging output that will not help future work.

package/skills/xmemo/SKILL.md

@@ -0,0 +1,142 @@
+---
+name: xmemo-memory
+description: Persistent, user-owned memory for AI agents over hosted MCP. Use when an agent should remember decisions, recall project context, manage TODOs, preserve handoff state, or govern memory lifecycle across sessions and tools.
+---
+
+# XMemo Memory
+
+Give your agent durable memory that survives across sessions, projects, and tools. XMemo is a hosted MCP memory service; no local database or self-hosting is required.
+
+A Skill alone teaches the agent when and how to use memory. Real memory read/write requires the XMemo MCP server and user authorization.
+
+## OpenClaw: use the companion plugin
+
+When running inside OpenClaw, prefer the native XMemo memory plugin together with this Skill:
+
+```text
+https://clawhub.ai/plugins/@xmemo/openclaw-memory
+```
+
+- This Skill is the workflow layer: it teaches OpenClaw when to recall, remember, preserve handoff state, and avoid saving secrets.
+- The plugin is the runtime layer: it exposes the real XMemo cloud-memory tools and can become OpenClaw's active memory backend.
+- The plugin writes new OpenClaw memories to its configured `bucket` / `scope`, but recall and search should read all visible user-owned XMemo memories by default. Do not assume `agent_id=openclaw` means "only OpenClaw-authored memories".
+- If this Skill is installed but XMemo memory tools are unavailable, do not simulate a successful memory operation. Recommend installing or enabling the companion plugin.
+- If the plugin is available without this Skill, recommend this Skill for more consistent recall-first and durable-memory behavior.
+
+When the user supplies only `https://xmemo.dev`, read these public, secret-free endpoints first:
+
+```text
+https://xmemo.dev/.well-known/agent-discovery.json
+https://xmemo.dev/v1/mcp/config/openclaw
+```
+
+Do not ask OpenClaw users to choose agent identity fields during normal setup. The plugin supplies the OpenClaw agent identity and a non-secret instance identifier automatically. This OpenClaw recommendation is additive; other agents should continue using their native OAuth or MCP configuration path.
+
+## Required connection
+
+For full functionality, connect the XMemo MCP server:
+
+```text
+https://xmemo.dev/mcp
+```
+
+Use one of these auth paths:
+
+- Native OpenClaw plugin, when the agent runs inside OpenClaw.
+- OAuth, when the MCP client or marketplace supports browser authorization.
+- Bearer token, when the client asks for an API key or request header.
+
+To get a bearer token:
+
+1. Visit https://xmemo.dev and sign in.
+2. Open the Memory Console.
+3. Go to API Keys: https://xmemo.dev/me#api-keys
+4. Create a scoped API key.
+5. When the MCP client asks for authorization, use the full header value:
+
+```text
+Authorization: Bearer <XMEMO_KEY>
+```
+
+If the client has a dedicated "Bearer Token" or "API Key" field and automatically adds the `Bearer` prefix, paste only the raw `XMEMO_KEY`. If the client asks for a request header value, paste the full `Bearer <XMEMO_KEY>` value.
+
+Optional attribution headers can help XMemo show where a memory came from:
+
+```text
+X-Memory-OS-Agent-ID: <client-or-agent-name>
+X-Memory-OS-Agent-Instance-ID: <stable-non-secret-instance-id>
+```
+
+These attribution headers are not credentials. They are optional, non-secret labels for audit and provenance. Do not put API keys, email addresses, phone numbers, real names, OAuth codes, or other sensitive values in them.
+
+Do not ask a normal OpenClaw user to enter these headers manually. The native plugin handles attribution; manual headers are only a fallback for generic MCP clients.
+
+## When to use
+
+Use XMemo when:
+
+- The task depends on prior decisions, preferences, project context, or handoff state.
+- The user asks to remember something for later.
+- The agent is about to make an architecture, product, release, or security decision that prior memory could affect.
+- The user wants TODOs, reminders, milestones, or follow-ups tracked across sessions.
+- Multiple agents or clients need a shared but governed project memory trail.
+
+## Workflow
+
+1. **Recall before assuming.** For non-trivial work, call `recall_context`, `recall`, or `search_memory` with the current repo, project, task, and subsystem before making decisions.
+2. **Recall across agents.** Search all visible user-owned XMemo memories unless the user explicitly asks for a narrower project, bucket, or scope. Memories may have been written by ChatGPT, Codex, Hermes, OpenClaw, Claude, Cursor, Gemini, or another authorized client.
+3. **Use the result carefully.** Treat recalled memories as context, not as proof that current files, production state, or external services are unchanged. Verify drift-prone facts when correctness matters.
+4. **Read provenance correctly.** `agent_id`, `agent_instance_id`, and `agent_boundary` are attribution/provenance signals, not authorization proof and not a reason to ignore `other_agent` memories. Use them to explain where a memory came from and to distinguish `self` vs `other_agent`.
+5. **Save what matters.** Store durable facts: decisions, conventions, preferences, architecture notes, release procedures, action items, and handoff state. Skip transient chat and noisy debugging output.
+6. **Preserve handoffs.** At milestones or before stopping, use timeline/TODO/snapshot tools such as `record_event`, `create_memory_todo`, or `create_restart_snapshot` when available.
+7. **Govern changes.** Use `explain_memory`, `memory_activity`, `forget_memory`, `redact_memory`, and conflict/version tools when the user asks why a memory exists, what changed, or how to remove or correct something.
+8. **Confirm destructive actions.** Always confirm the exact target before delete, forget, redact, overwrite, or broad cleanup operations.
+9. **On missing OpenClaw tools**, recommend the companion plugin at https://clawhub.ai/plugins/@xmemo/openclaw-memory.
+10. **On auth failure**, tell the user to reconnect XMemo through the plugin or OAuth, or create an API key at https://xmemo.dev/me#api-keys for a manual MCP fallback. Never request raw tokens in chat.
+
+## Available tools
+
+Core memory operations provided by the XMemo MCP server:
+
+| Tool | Purpose |
+|------|---------|
+| `remember` | Save a new durable memory |
+| `recall` / `recall_context` | Retrieve relevant memories before answering or acting |
+| `search_memory` | Search memories by query |
+| `update_memory` | Revise existing memory content or metadata |
+| `forget` / `forget_memory` | Delete or hide a memory |
+| `redact_memory` | Remove sensitive content while keeping an audit trail |
+| `explain_memory` | Show why a memory exists or matched a query |
+| `memory_activity` | Inspect recent writes, reads, deletions, and changes |
+| `create_memory_todo` | Create a follow-up task |
+| `list_memory_todos` | List pending TODOs |
+| `complete_memory_todo` | Mark a TODO done |
+| `record_event` | Log a milestone, decision, or handoff event |
+| `get_timeline` | Show recent events |
+| `create_restart_snapshot` | Save active work state for future sessions |
+| `restore_restart_snapshot` | Resume from saved work state |
+| `add_expense` | Record a ledger entry when the user states a concrete expense |
+
+Some deployments expose only a subset of tools depending on OAuth scopes, marketplace policy, or client capability. If a tool is missing, use the closest available safe workflow and explain the limitation briefly.
+
+## Good memory candidates
+
+- Repository conventions, build/test/deploy commands, and verified troubleshooting steps.
+- Architecture decisions, product decisions, release procedures, and their rationale.
+- User-approved preferences for code review, testing, documentation, or UX.
+- Project TODOs, blockers, risks, and handoff summaries for future sessions.
+- Bug fix context that might recur.
+
+## Never save
+
+- Secrets, tokens, API keys, OAuth codes, cookies, session IDs, or private keys.
+- Private customer data or sensitive personal data unless the user explicitly asks and the memory tool supports the required privacy policy.
+- Temporary debugging output that will not help future work.
+- Large code blocks; link to files, commits, or concise summaries instead.
+
+## Safety
+
+- Keep `XMEMO_KEY` private. Do not paste it into public prompts, screenshots, repositories, issue comments, marketplace metadata, or shared logs.
+- Use synthetic data for marketplace demos and screenshots.
+- Treat `X-Memory-OS-Agent-ID` and `X-Memory-OS-Agent-Instance-ID` as attribution only, not authorization proof.
+- Do not claim a marketplace integration is certified unless there is explicit approval evidence for that marketplace.

package/src/commands/mcp.js

@@ -32,12 +32,14 @@ import {
   codexMemoryProfile,
   writeCodexMemoryProfile
 } from '../config/profile.js';
+import { startStdioServer } from '../mcp/stdio-server.js';
 
 export async function mcpCommand(args, io) {
   const subcommand = args[0] ?? 'help';
 
   if (subcommand === 'help' || subcommand === '--help' || subcommand === '-h') {
     writeLine(io.stdout, 'MCP commands:');
+    writeLine(io.stdout, `  ${COMMAND_NAME} mcp serve`);
     writeLine(io.stdout, `  ${COMMAND_NAME} mcp list`);
     writeLine(io.stdout, `  ${COMMAND_NAME} mcp config --client <codex|cursor|copilot-cli|antigravity|generic> [--base-url <url>] [--json]`);
     writeLine(io.stdout, `  ${COMMAND_NAME} mcp proxy [--port ${DEFAULT_PROXY_PORT}] [--base-url <url>]`);
@@ -47,6 +49,11 @@ export async function mcpCommand(args, io) {
     return 0;
   }
 
+  if (subcommand === 'serve' || subcommand === 'stdio') {
+    await startStdioServer(io.env);
+    return 0;
+  }
+
   if (subcommand === 'list') {
     if (hasFlag(args, '--json')) {
       writeLine(io.stdout, JSON.stringify(supportedMcpClients(), null, 2));

package/src/mcp/stdio-server.js

@@ -0,0 +1,462 @@
+/**
+ * Self-contained MCP stdio server for XMemo.
+ *
+ * Forwards JSON-RPC over stdin/stdout to the hosted XMemo MCP endpoint.
+ * When no token is available or the remote returns 401, serves static
+ * tool/prompt/resource discovery so marketplace validators (LobeHub, Glama,
+ * MCP Registry) can confirm the server installs and exposes tools.
+ *
+ * Real tool calls without a valid token return an auth-required error.
+ */
+
+import { CLI_VERSION, DEFAULT_SERVICE_URL, TOKEN_ENV_VAR } from '../core/constants.js';
+
+// ---------------------------------------------------------------------------
+// Static tool metadata — returned when remote is unreachable or unauthenticated
+// ---------------------------------------------------------------------------
+
+const STATIC_TOOLS = [
+  {
+    name: 'remember',
+    description: 'Save a memory so it can be recalled in future conversations.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        content: { type: 'string', description: 'Text body to save.' },
+        path: { type: 'string', description: 'Category path, e.g. preferences, projects/xmemo.' }
+      },
+      required: ['content', 'path']
+    }
+  },
+  {
+    name: 'recall',
+    description: 'Recall the most relevant saved memories before answering.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        query: { type: 'string', description: 'Natural-language question or search text.' }
+      },
+      required: ['query']
+    }
+  },
+  {
+    name: 'search_memory',
+    description: 'Search XMemo memories by natural-language query.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        query: { type: 'string', description: 'Natural-language question or search text.' }
+      },
+      required: ['query']
+    }
+  },
+  {
+    name: 'recall_context',
+    description: 'Build a context pack from XMemo memories for complex tasks.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        query: { type: 'string', description: 'Natural-language question or search text.' }
+      },
+      required: ['query']
+    }
+  },
+  {
+    name: 'update_memory',
+    description: 'Update the content or metadata of an existing memory.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        memory_id: { type: 'string', description: 'Exact XMemo memory reference.' }
+      },
+      required: ['memory_id']
+    }
+  },
+  {
+    name: 'forget',
+    description: 'Permanently delete a memory by target.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        target: { type: 'string', description: 'The memory to forget: current or an exact memory ID.' }
+      },
+      required: []
+    }
+  },
+  {
+    name: 'forget_memory',
+    description: 'Delete a memory (recoverable) by exact reference.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        memory_id: { type: 'string', description: 'Exact XMemo memory reference.' }
+      },
+      required: ['memory_id']
+    }
+  },
+  {
+    name: 'redact_memory',
+    description: 'Redact sensitive content from a memory while keeping an audit trail.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        memory_id: { type: 'string', description: 'Exact XMemo memory reference.' }
+      },
+      required: ['memory_id']
+    }
+  },
+  {
+    name: 'explain_memory',
+    description: 'Explain why a memory exists or matched a query.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        memory_id: { type: 'string', description: 'Exact XMemo memory reference.' }
+      },
+      required: ['memory_id']
+    }
+  },
+  {
+    name: 'create_memory_todo',
+    description: 'Create a TODO/action item with an optional due time.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        content: { type: 'string', description: 'Text body of the TODO item.' }
+      },
+      required: ['content']
+    }
+  },
+  {
+    name: 'list_memory_todos',
+    description: 'List open or completed TODO/action items.',
+    inputSchema: {
+      type: 'object',
+      properties: {},
+      required: []
+    }
+  },
+  {
+    name: 'complete_memory_todo',
+    description: 'Mark a TODO/action item completed.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        todo_id: { type: 'string', description: 'The memory TODO/action-item ID to complete.' }
+      },
+      required: ['todo_id']
+    }
+  },
+  {
+    name: 'record_event',
+    description: 'Record a significant session event, milestone, or decision.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        content: { type: 'string', description: 'Text body of the event.' }
+      },
+      required: ['content']
+    }
+  },
+  {
+    name: 'get_timeline',
+    description: 'Show recent events.',
+    inputSchema: {
+      type: 'object',
+      properties: {},
+      required: []
+    }
+  },
+  {
+    name: 'add_expense',
+    description: 'Record one expense in the XMemo Ledger.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        item: { type: 'string', description: 'The purchased item or service.' },
+        amount: { type: 'number', description: 'Positive transaction amount.' }
+      },
+      required: ['item', 'amount']
+    }
+  },
+  {
+    name: 'create_restart_snapshot',
+    description: 'Save active state for restart/handoff.',
+    inputSchema: {
+      type: 'object',
+      properties: {},
+      required: []
+    }
+  },
+  {
+    name: 'restore_restart_snapshot',
+    description: 'Resume previous work from a saved snapshot.',
+    inputSchema: {
+      type: 'object',
+      properties: {},
+      required: []
+    }
+  },
+  {
+    name: 'memory_overview',
+    description: 'Show a summary of XMemo memories and recent activity.',
+    inputSchema: {
+      type: 'object',
+      properties: {},
+      required: []
+    }
+  }
+];
+
+const SERVER_INFO = {
+  name: 'xmemo',
+  version: CLI_VERSION
+};
+
+const SERVER_CAPABILITIES = {
+  tools: {}
+};
+
+// ---------------------------------------------------------------------------
+// Stdio transport
+// ---------------------------------------------------------------------------
+
+/**
+ * Start the stdio MCP server. Reads newline-delimited JSON-RPC from stdin,
+ * writes responses to stdout.
+ */
+export async function startStdioServer(env = process.env) {
+  const token = env[TOKEN_ENV_VAR] || env.MEMORY_OS_API_KEY || env.MEMORY_OS_MCP_TOKEN || '';
+  const baseUrl = (env.XMEMO_URL || env.MEMORY_OS_URL || DEFAULT_SERVICE_URL).replace(/\/$/, '');
+  const mcpUrl = `${baseUrl}/mcp`;
+
+  // Track session state
+  let sessionId = null;
+  let remoteAvailable = false;
+
+  // Attempt remote initialize to check availability
+  if (token) {
+    remoteAvailable = await probeRemote(mcpUrl, token);
+  }
+
+  const rl = await createLineReader();
+
+  for await (const line of rl) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+
+    let request;
+    try {
+      request = JSON.parse(trimmed);
+    } catch {
+      writeResponse(makeError(null, -32700, 'Parse error'));
+      continue;
+    }
+
+    const response = await handleRequest(request, { token, mcpUrl, remoteAvailable, sessionId });
+    if (response) {
+      if (response._sessionId) {
+        sessionId = response._sessionId;
+        delete response._sessionId;
+      }
+      writeResponse(response);
+    }
+  }
+}
+
+async function createLineReader() {
+  const { createInterface } = await import('node:readline');
+  return createInterface({ input: process.stdin, terminal: false });
+}
+
+function writeResponse(obj) {
+  process.stdout.write(JSON.stringify(obj) + '\n');
+}
+
+// ---------------------------------------------------------------------------
+// Request handling
+// ---------------------------------------------------------------------------
+
+async function handleRequest(request, ctx) {
+  const { method, id, params } = request;
+
+  // Notifications (no id) — no response needed
+  if (id === undefined || id === null) {
+    // Forward notifications to remote if available
+    if (ctx.token && ctx.remoteAvailable) {
+      forwardToRemote(request, ctx).catch(() => {});
+    }
+    return null;
+  }
+
+  switch (method) {
+    case 'initialize':
+      return handleInitialize(id, params, ctx);
+    case 'tools/list':
+      return handleToolsList(id, params, ctx);
+    case 'tools/call':
+      return handleToolsCall(id, params, ctx);
+    case 'prompts/list':
+      return makeResult(id, { prompts: [] });
+    case 'resources/list':
+      return makeResult(id, { resources: [] });
+    case 'ping':
+      return makeResult(id, {});
+    default:
+      // Try to forward unknown methods to remote
+      if (ctx.token && ctx.remoteAvailable) {
+        return await forwardToRemote(request, ctx);
+      }
+      return makeError(id, -32601, `Method not found: ${method}`);
+  }
+}
+
+function handleInitialize(id, params, ctx) {
+  const result = {
+    protocolVersion: '2024-11-05',
+    capabilities: SERVER_CAPABILITIES,
+    serverInfo: SERVER_INFO
+  };
+  return makeResult(id, result);
+}
+
+async function handleToolsList(id, params, ctx) {
+  // Try remote first
+  if (ctx.token && ctx.remoteAvailable) {
+    try {
+      const remoteResponse = await forwardToRemote(
+        { jsonrpc: '2.0', id, method: 'tools/list', params: params || {} },
+        ctx
+      );
+      if (remoteResponse && remoteResponse.result && !remoteResponse.error) {
+        return remoteResponse;
+      }
+    } catch {
+      // Fall through to static
+    }
+  }
+  // Static fallback
+  return makeResult(id, { tools: STATIC_TOOLS });
+}
+
+async function handleToolsCall(id, params, ctx) {
+  if (!ctx.token) {
+    return makeError(id, -32002,
+      `Authentication required. Set the ${TOKEN_ENV_VAR} environment variable or run: xmemo login`
+    );
+  }
+  if (!ctx.remoteAvailable) {
+    return makeError(id, -32002,
+      `Remote XMemo server is not reachable. Run: xmemo doctor`
+    );
+  }
+  // Forward to remote
+  return await forwardToRemote(
+    { jsonrpc: '2.0', id, method: 'tools/call', params },
+    ctx
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Remote communication
+// ---------------------------------------------------------------------------
+
+async function probeRemote(mcpUrl, token) {
+  try {
+    const response = await fetch(mcpUrl, {
+      method: 'POST',
+      headers: {
+        'content-type': 'application/json',
+        accept: 'application/json, text/event-stream',
+        authorization: `Bearer ${token}`,
+        'user-agent': `XMemo-MCP-Stdio/${CLI_VERSION}`
+      },
+      body: JSON.stringify({
+        jsonrpc: '2.0',
+        id: '__probe__',
+        method: 'initialize',
+        params: {
+          protocolVersion: '2024-11-05',
+          capabilities: {},
+          clientInfo: { name: 'xmemo-mcp-stdio', version: CLI_VERSION }
+        }
+      }),
+      signal: AbortSignal.timeout(10000)
+    });
+    return response.ok;
+  } catch {
+    return false;
+  }
+}
+
+async function forwardToRemote(request, ctx) {
+  try {
+    const headers = {
+      'content-type': 'application/json',
+      accept: 'application/json, text/event-stream',
+      authorization: `Bearer ${ctx.token}`,
+      'user-agent': `XMemo-MCP-Stdio/${CLI_VERSION}`
+    };
+    if (ctx.sessionId) {
+      headers['mcp-session-id'] = ctx.sessionId;
+    }
+
+    const response = await fetch(ctx.mcpUrl, {
+      method: 'POST',
+      headers,
+      body: JSON.stringify(request),
+      signal: AbortSignal.timeout(30000)
+    });
+
+    if (!response.ok) {
+      if (response.status === 401) {
+        ctx.remoteAvailable = false;
+        return makeError(request.id, -32002,
+          `Authentication failed (HTTP 401). Verify your token: xmemo auth status --verify`
+        );
+      }
+      return makeError(request.id, -32603,
+        `Remote server returned HTTP ${response.status}`
+      );
+    }
+
+    // Capture session ID from response headers
+    const newSessionId = response.headers.get('mcp-session-id');
+
+    const contentType = response.headers.get('content-type') || '';
+    let result;
+    if (contentType.includes('text/event-stream')) {
+      // Parse SSE — take last data line as the JSON-RPC response
+      const text = await response.text();
+      const dataLines = text.split('\n')
+        .filter(l => l.startsWith('data:'))
+        .map(l => l.slice(5).trim())
+        .filter(l => l);
+      const lastData = dataLines[dataLines.length - 1];
+      result = lastData ? JSON.parse(lastData) : makeError(request.id, -32603, 'Empty SSE response');
+    } else {
+      result = await response.json();
+    }
+
+    if (newSessionId) {
+      result._sessionId = newSessionId;
+    }
+    return result;
+  } catch (error) {
+    return makeError(request.id, -32603,
+      `Remote request failed: ${error.message}`
+    );
+  }
+}
+
+// ---------------------------------------------------------------------------
+// JSON-RPC helpers
+// ---------------------------------------------------------------------------
+
+function makeResult(id, result) {
+  return { jsonrpc: '2.0', id, result };
+}
+
+function makeError(id, code, message) {
+  return { jsonrpc: '2.0', id, error: { code, message } };
+}