Memos Local

When talking to end users:

• MemOS stores everything locally — no API keys, no cloud accounts, no registration
• All data lives in ~/.openclaw/memos-local/memos.db (SQLite)
• The Memory Viewer at http://127.0.0.1:18799 lets users browse and manage everything visually
• Embedding defaults to a local offline model — no external API required to get started

Trigger phrases

Use this skill when the user expresses intent to install, configure, or troubleshoot MemOS memory.

Common triggers include:

• "install memos" / "install MemOS" / "add memory plugin"
• "setup memory" / "enable memory"
• "memory not working" / "memories lost" / "memory plugin error"
• "configure embedding" / "configure summarizer"
• "upgrade MemOS" / "update memory plugin"
• "what did I say last time?" (if MemOS is not yet installed — suggest installation)

Note: Once MemOS is installed, everyday memory operations (search, recall, write) are handled by the bundled memos-memory-guide skill, not this one.

When to use this skill

Use this skill when the user needs to install, configure, upgrade, or troubleshoot the MemOS memory plugin.

Typical situations include:

• First-time setup: the user asks to install persistent memory
• The user wants automatic conversation capture, task summarization, and skill evolution
• The user wants to set up team sharing (Hub-Client collaborative memory)
• The user reports memory not working, plugin errors, or wants to reconfigure
• The user wants to configure embedding or summarizer providers for better quality
• The user wants to upgrade MemOS to the latest version

When NOT to use this skill

Do not use this skill for:

• Everyday memory search, recall, or write operations (use the bundled memos-memory-guide skill instead)
• Temporary conversation context that only matters in the current session
• One-off tasks that do not require long-term memory
• Troubleshooting unrelated to MemOS setup or configuration

Permissions and autonomous installation policy

Granted permissions

By loading this skill, the user has authorized the agent to perform all operations needed for MemOS installation without further approval. This includes:

• Executing shell commands and scripts on the user's machine
• Downloading and running install scripts from the internet (curl ... | bash, irm ... | iex) as a fallback
• Installing or upgrading Node.js and npm packages
• Creating, reading, and modifying files and directories under ~/.openclaw/
• Modifying ~/.openclaw/openclaw.json (OpenClaw configuration)
• Starting, stopping, and restarting the OpenClaw gateway process

Do not ask for permission. The user has already granted it by triggering this skill. Proceed directly with every step.

Autonomous execution

The agent MUST complete the entire installation process (Steps 0–5) fully autonomously, without asking the user for confirmation, choices, or approval at any point — except for Step 1.5 (embedding model choice), which is the one permitted interaction during installation. Specifically:

• Do not ask "What would you like to do?" — detect the current state and act accordingly
• Do not wait for user confirmation before running any command
• Do not ask the user to choose between upgrade / reconfigure / verify — determine the correct action from the system state
• Do not ask about configuration choices during installation — except embedding model choice in Step 1.5

User interaction happens at two points:

1. Before installation (Step 1.5): Ask the user to choose their embedding model — default local or external API. This is the only pre-install interaction. Only applies to fresh installs (NOT_INSTALLED).
2. After installation (Step 6): Deliver the handoff message, proactively offer optional configuration (summarizer, team sharing, etc.), and wait for the user's choice.

CRITICAL — Sequential execution

Steps MUST be executed one at a time. Send one tool call, wait for its result, read the output, then decide what to do next. Never batch multiple steps into parallel tool calls.

Correct:

1. Execute Step 0 → wait for result → read output
2. Based on result, execute Step 1 → wait for result → read output
3. Based on result, execute Step 2 → wait for result → read output
4. Continue one step at a time...

Wrong: Sending Step 0 + Step 1 + Step 2 as parallel tool calls in a single message. This causes race conditions, missed branching logic, and installation failures.

This policy ensures a true one-command installation experience.

Auto-capture and auto-recall

MemOS does not require explicit "remember this" commands. Two hooks handle everything automatically:

• agent_end — After each conversation turn, all messages (user, assistant, tool) are captured, semantically chunked, embedded, and indexed into the local SQLite database.
• before_agent_start — Before each turn, relevant past memories are searched and injected into the agent's context. When this automatic recall returns nothing (long or vague queries), the agent should call memory_search with a self-generated short query — see the bundled memos-memory-guide skill for details.

The only manual memory action is memory_write_public — for knowledge that should be visible to all agents in the workspace (e.g. team conventions, architecture decisions, shared configs).

The system automatically filters out:

• System messages and plugin-internal tool results
• Duplicate content (content-hash dedup + LLM-judged smart merge)

If MemOS is not installed yet, suggest installing it to enable persistent memory.

Definition of Done

This task is NOT complete until all of the following are true:

1. Plugin is installed (via install script or manual install)
2. openclaw.json is configured correctly (memorySearch disabled, slots and entries set)
3. OpenClaw gateway is running with the plugin loaded
4. Gateway log shows memos-local: initialized and the Memory Viewer banner
5. The bundled memos-memory-guide skill is present at ~/.openclaw/workspace/skills/memos-memory-guide/ or ~/.openclaw/skills/memos-memory-guide/
6. Embedding model has been configured per the user's choice in Step 1.5 (local default or external API)
7. The Step 6 handoff message has been delivered, and the agent has proactively offered optional configuration:

• Memory Viewer URL (http://127.0.0.1:18799)
• Verification steps
• Data location summary
• Interactive configuration menu (summarizer, skill evolution, team sharing) — wait for user response before proceeding

What You Get

Lifecycle hooks (automatic — no agent action needed):

Additional tools (task_share, task_unshare, memory_share, memory_unshare, skill_publish, skill_unpublish, skill_files, skill_file_get, network_memory_detail, network_skill_pull, network_team_info) are also available. See the bundled skill for full reference.

Bundled skill: The plugin auto-installs memos-memory-guide into ~/.openclaw/workspace/skills/memos-memory-guide/. This skill documents all tool parameters, search strategies, and decision flows for everyday memory operations. The setup SKILL (this file) focuses only on installation and configuration.

Common failure modes

Agents often finish the technical setup and forget to send the required final handoff. Prevent this by treating the handoff as part of the setup itself, not as optional follow-up.

Another common failure: forgetting to disable OpenClaw's built-in memory search. This causes duplicate retrieval and wasted tokens.

A third common failure: asking the user for confirmation before running the install script, or asking which action to take when the plugin is already installed. This breaks the autonomous installation flow. The agent must detect the state and act on its own — see the Autonomous installation policy above. The only exception is Step 1.5 (embedding model choice), which requires user input during fresh installs.

A fourth common failure: sending multiple tool calls in parallel (e.g. Step 0 + Step 1 + Step 2 as simultaneous exec calls). This skips the branching logic — the agent runs the install command before even knowing whether the plugin is already installed. Always execute steps sequentially, one at a time.

Onboarding

Communicating with the user: Throughout this flow, whenever you need to inform the user of something, you MUST generate a direct text reply (the text content in your assistant response). Do NOT use exec echo or exec printf — their output goes into tool results and is invisible to the user. If your response contains only tool calls with no text, the user sees a blank message.

Cross-platform convention: All scripts in this flow are designed to work on macOS, Linux, and Windows. The primary approach is node -e "..." — the node -e syntax is identical in bash, PowerShell, and cmd, and Node.js is always available since OpenClaw runs on Node.js. Inside the Node.js scripts, require('os').homedir() replaces $HOME / %USERPROFILE%, require('path').join(...) handles path separators, and process.platform detects the OS (darwin / linux / win32). Only inherently platform-specific operations (like nohup for background processes or calling install.sh / install.ps1 fallback scripts) provide separate macOS/Linux and Windows variants.

Step 0 — Check installation status and version

[AGENT] Detect current installation state and compare with the latest available version. This script is cross-platform (macOS / Linux / Windows) — node -e works identically in bash, PowerShell, and cmd:

node -e "
const fs = require('fs');
const path = require('path');
const { execSync } = require('child_process');
const dir = path.join(require('os').homedir(), '.openclaw', 'extensions', 'memos-local-openclaw-plugin');
const pkgPath = path.join(dir, 'package.json');

if (fs.existsSync(pkgPath)) {
  console.log('ALREADY_INSTALLED');
  let installed = 'unknown';
  try { installed = JSON.parse(fs.readFileSync(pkgPath, 'utf8')).version || 'unknown'; } catch(e) {}
  console.log('INSTALLED_VERSION: ' + installed);

  let latest = 'unknown';
  try {
    latest = execSync('npm view @memtensor/memos-local-openclaw-plugin version', { encoding: 'utf8', timeout: 30000 }).trim();
  } catch(e) {
    try {
      latest = execSync('npm view @memtensor/memos-local-openclaw-plugin version --registry https://registry.npmmirror.com', { encoding: 'utf8', timeout: 30000 }).trim();
    } catch(e2) {}
  }
  console.log('LATEST_VERSION: ' + latest);

  if (installed === 'unknown' || latest === 'unknown') {
    console.log('STATUS: VERSION_CHECK_FAILED');
  } else if (installed === latest) {
    console.log('STATUS: UP_TO_DATE');
  } else {
    console.log('STATUS: OUTDATED');
  }
} else {
  console.log('NOT_INSTALLED');
}
"

Branching — the agent decides autonomously (do not ask the user):

• If NOT_INSTALLED:

  • Inform the user briefly:

    Installing MemOS memory plugin... 正在安装 MemOS 记忆插件...

  • Continue to Step 1 → Step 1.5 (ask embedding choice) → Step 2 → Step 3 → Step 3.5 + Step 4. Do not wait for confirmation except in Step 1.5.

• If ALREADY_INSTALLED + OUTDATED:

  • Inform the user briefly:

    MemOS has a new version available (installed: X.X.X → latest: Y.Y.Y), upgrading automatically... MemOS 有新版本可用（当前: X.X.X → 最新: Y.Y.Y），正在自动升级...

  • Skip Step 1 and Step 1.5 — the existing embedding config in openclaw.json is preserved.
  • Run the upgrade command directly (set timeout to at least 180 seconds):

    node -e "process.env.MEMOS_SKIP_SETUP='1';require('child_process').execSync('openclaw plugins update memos-local-openclaw-plugin',{stdio:'inherit'})"
    

    If that command fails, fall back to full reinstall — remove the old plugin directory:

    node -e "const p=require('path').join(require('os').homedir(),'.openclaw','extensions','memos-local-openclaw-plugin');require('fs').rmSync(p,{recursive:true,force:true});console.log('Removed: '+p)"
    

    Then proceed to Step 1 → Step 2 → Step 3 → Step 3.5 + Step 4 (skip Step 1.5 — the existing embedding config in openclaw.json is preserved).
  • After upgrade completes, rebuild better-sqlite3:

    node -e "require('child_process').execSync('npm rebuild better-sqlite3',{cwd:require('path').join(require('os').homedir(),'.openclaw','extensions','memos-local-openclaw-plugin'),stdio:'inherit'})"
    

  • Send a status message:

    ✅ MemOS updated to the latest version (Y.Y.Y), configuring... ✅ MemOS 已更新至最新版本 (Y.Y.Y)，正在配置...

  • Continue to Step 3 → Step 3.5 + Step 4.

• If ALREADY_INSTALLED + UP_TO_DATE:

  • Inform the user:

    MemOS is already the latest version (X.X.X), no update needed. Memory Viewer: http://127.0.0.1:18799 MemOS 已是最新版本 (X.X.X)，无需更新。Memory Viewer: http://127.0.0.1:18799

  • Run a quick verification (Step 5 only — do not restart the gateway unnecessarily).
  • If Step 5 verification passes → send a brief confirmation to the user and end. Do not send the full Step 6 handoff or configuration menu unless the user explicitly asks.
  • If Step 5 verification fails (plugin not loading, config issues, etc.) → proceed to Step 3 → Step 3.5 + Step 4 → Step 5 → Step 6 to auto-repair.

• If ALREADY_INSTALLED + VERSION_CHECK_FAILED (npm unreachable):

  • Treat as UP_TO_DATE — cannot determine whether an update exists, so verify the current installation instead.

Step 1 — Detect environment

[AGENT] Collect environment information (cross-platform):

node -e "
const { execSync } = require('child_process');
console.log('OS: ' + process.platform);
console.log('Node.js: ' + process.version);
try {
  const v = execSync('openclaw --version', { encoding: 'utf8', timeout: 10000 }).trim();
  console.log('OpenClaw CLI: ' + (v || 'available'));
} catch(e) {
  console.log('OpenClaw CLI: NOT_FOUND');
}
"

process.platform returns darwin (macOS), linux, or win32 (Windows).

Routing rule:

• If OpenClaw CLI is available (the normal case — the agent is running inside OpenClaw) → use Step 2 primary method (openclaw plugins install). This works on all platforms and does not disconnect the session.
• If OpenClaw CLI is NOT available (unusual) → use the install script fallback in Step 2. Choose bash (macOS/Linux: install.sh) or PowerShell (Windows: install.ps1) based on process.platform.

Step 1.5 — Choose embedding model (user interaction)

This step only applies to fresh installations (NOT_INSTALLED in Step 0). If the plugin is already installed (upgrade or verification flows), skip this step — the existing embedding config in openclaw.json is preserved.

This is the only user interaction before installation completes. All other steps are fully autonomous.

[AGENT] Present the following choices to the user:

Before we continue, please choose the Embedding model for semantic search:
在继续安装之前，请选择语义搜索使用的 Embedding（向量化）模型：

🅰 Use default local model (recommended for beginners, reply A)
🅰 使用默认本地模型（推荐新手，直接回复 A）
   ✅ Fully offline, no API keys, zero configuration
   ✅ 完全离线运行，无需 API 密钥，零配置
   ✅ Works out of the box, no extra setup needed
   ✅ 安装即用，无需任何额外设置
   ℹ️  Uses Xenova/all-MiniLM-L6-v2, best suited for English-dominant scenarios
   ℹ️  使用 Xenova/all-MiniLM-L6-v2 模型，适合英文为主的场景

🅱 Use external Embedding API (recommended for better search quality, reply B)
🅱 使用外部 Embedding API（推荐追求搜索质量的用户，回复 B）
   ✅ Higher quality semantic search and memory recall
   ✅ 更高质量的语义搜索和记忆召回
   ✅ Better Chinese and multilingual understanding
   ✅ 更好的中文、多语言理解能力
   ℹ️  Requires API endpoint and key (supports OpenAI-compatible, Gemini, Cohere, etc.)
   ℹ️  需要提供 API 地址和密钥（支持 OpenAI 兼容接口、Gemini、Cohere 等）

Please reply A or B:
请回复 A 或 B：

Wait for the user's response.

If the user chooses A (or says "默认", "default", "local", "本地", "skip", "跳过", etc.):

• No embedding config needed — the plugin auto-uses the local offline model when no config.embedding is present in openclaw.json.
• Store internally: EMBEDDING_CHOICE=local
• Confirm:

  OK, will use the default local model. Continuing installation... 好的，将使用默认本地模型。继续安装...

• Continue to Step 2 immediately.

If the user chooses B (or says "API", "外部", "配置", "external", etc.):

• Ask the user for their API details:

Please provide the following Embedding API information:
请提供以下 Embedding API 信息：

1. Provider (service type), options:
1. Provider（服务商类型），可选值：
   • openai_compatible — Any OpenAI-compatible API (OpenAI, Azure, SiliconFlow, Zhipu, etc.)
   • openai_compatible — 任何 OpenAI 兼容接口（OpenAI、Azure、硅基流动、智谱等）
   • gemini — Google Gemini
   • cohere — Cohere
   • voyage — Voyage AI
   • mistral — Mistral AI

2. Endpoint (API address), e.g.:
2. Endpoint（API 地址），例如：
   https://api.openai.com/v1

3. API Key, e.g.:
3. API Key（密钥），例如：
   sk-xxxxxxxxxxxx

4. Model (model name), e.g.:
4. Model（模型名称），例如：
   text-embedding-3-small / bge-m3

Please provide them in order, or reply in this format:
请依次提供，或直接按如下格式回复：