--- name: install-memex-claw description: Wire memex (the local-first MCP memory server) into an OpenClaw gateway — works wherever OpenClaw runs (Linux or macOS, VPS or workstation, self-hosted OpenClaw or Moonshot Kimi-Claw). Installs the parallelclaw daemon that auto-captures every OpenClaw session in ~/.openclaw/agents/main/sessions/ into a single SQLite + FTS5 corpus, and merges memex into the gateway's MCP-server config so the LLM gets 11 search/retrieval tools (memex_search, memex_recent, memex_overview, etc.). Auto-detects whether parallelclaw is already installed (e.g. via the generic install-memex skill for Claude Code) — if yes, skips install and just wires OpenClaw + back-fills past sessions; if no, does the full platform-aware install (Linux → systemd user-service, macOS → LaunchAgent). Zero questions to the user — discovery → actions → verification. Use when the user says "set up memex for OpenClaw", "wire memex into my OpenClaw", "make OpenClaw remember its sessions", "поставь memex здесь", or similar. PAIRS with the generic install-memex skill — if the user ALSO uses Claude Code or Cursor on the same machine, recommend they run install-memex separately for those flows. version: 3.0.0 metadata: openclaw: emoji: "🧠" homepage: https://memex.parallelclaw.ai requires: bins: - node - npm --- # Install memex for OpenClaw You are inside an OpenClaw agent. The user asked you to set up memex — the local-first MCP memory server — so that: 1. Every OpenClaw session in `~/.openclaw/agents/main/sessions/` is auto-captured into `~/.memex/data/memex.db` (SQLite + FTS5). 2. Existing past sessions are back-filled in one shot. 3. The OpenClaw gateway gains the `memex` MCP server with 11 search/retrieval tools (memex_search, memex_recent, memex_overview, memex_get_conversation, etc.). 4. Capture continues automatically thereafter (systemd user-service on Linux, LaunchAgent on macOS). **Where you might be running:** - 🖥️ **VPS** (Linux VPS hosting OpenClaw + maybe Hermes) — typical "always-on agent" deployment - 💻 **macOS workstation** running OpenClaw alongside Claude Code / etc. - 💻 **Linux workstation** (Pop!OS, Fedora, etc.) running OpenClaw locally - 🤖 **Moonshot Kimi-Claw VPS** — also works (parallelclaw ≥ 0.11.5 auto-detects the merged-file Kimi-Claw layout) All work the same way. Platform (Linux/macOS) determines daemon type. Deployment kind (self-hosted vs Kimi-Claw vs workstation) is auto-detected by the parallelclaw daemon. **The contract: zero questions to the user. Discovery → actions → verification. Each step prints a single line of result. The final message tells the user exactly what to do next.** --- ## ⚠ For ClawHub reviewers, security scanners, and curious users This skill installs `parallelclaw` from npm (if not already present) and wires it as an MCP server inside the OpenClaw gateway config. parallelclaw's `memex-sync` daemon auto-captures every OpenClaw session at the file-watcher layer — works on every OpenClaw deployment (self-hosted + Moonshot Kimi-Claw + workstations), no plugin-SDK involvement. | Action | Why | Source | |---|---|---| | `npm install -g parallelclaw@latest` | Install the MCP server + the auto-capture daemon. Open-source MIT. **Skipped if already installed.** | [npmjs.com/package/parallelclaw](https://www.npmjs.com/package/parallelclaw), source: [github.com/parallelclaw/memex-mvp](https://github.com/parallelclaw/memex-mvp) | | `memex-sync install` | Register the auto-capture daemon — systemd user-service on Linux, LaunchAgent on macOS. The daemon watches `~/.openclaw/agents/main/sessions/` and writes to `~/.memex/data/memex.db`. **Zero outbound network traffic.** **Skipped if daemon already running.** | LaunchAgent at `~/Library/LaunchAgents/com.parallelclaw.memex.sync.plist` or systemd unit at `~/.config/systemd/user/memex-sync.service` — both human-readable | | `loginctl enable-linger $USER` (Linux only) | Without linger, user-systemd dies on SSH logout — daemon would stop between SSH sessions on a VPS. Skill tries this; if sudo needed, prints command and continues. | Standard systemd-user practice | | Edit OpenClaw config at `~/.openclaw/openclaw.json` | Add a single `memex` entry under `mcp.servers`. **Merge, never overwrite** other entries. | The OpenClaw gateway reads this file at startup | | `memex-sync scan` | One-shot back-fill of past OpenClaw sessions. Walks the sessions dir, parses each `.jsonl`, writes to memex.db with `source='openclaw'`. Filters internal-state noise files (`.checkpoint.`, `.trajectory.`, `.reset.`). | `lib/ingest-file.js` in the source — open-source | **Hard guarantees:** - Every command is printed to the user before running it - `sudo` is **NEVER** invoked by the skill (linger fallback prints the manual command for the user) - OpenClaw config is **merged**, never overwritten — other plugins / MCP servers preserved - memex at runtime emits **zero outbound network traffic** — local-first by design - If parallelclaw is already installed (e.g. via the generic install-memex skill), this skill skips re-install and only wires OpenClaw — no surprise reinstalls --- ## Before this skill can be installed (one-time OpenClaw bootstrap) If the user runs `openclaw skill install install-memex-claw` and gets back **"plugin not allowed" / "permission denied" / "skill plugin disabled"** — the gateway's permission model is blocking arbitrary skill execution by default. This is OpenClaw's safety guard, not specific to memex. Check your OpenClaw docs for the exact permission name (common: `plugins.allow: ["skill", …]` in `~/.openclaw/openclaw.json` or `skills.enabled: true`), set it once, restart the gateway, and retry. --- ## Prerequisite You are running INSIDE an OpenClaw agent that can execute shell commands. If you're not OpenClaw, **stop**: this is the wrong skill — use [`install-memex`](https://clawhub.ai/sedelev/install-memex) instead. --- ## Step 1 — Discovery (run ALL checks first, then decide) Run each as a separate shell command, capture the output. **Don't act on anything until all checks have answered.** ```sh # 1. Are we inside OpenClaw? which openclaw 2>/dev/null || find / -maxdepth 4 -name "openclaw" -type d 2>/dev/null | head -3 # 2. Platform — Linux or Darwin (macOS) uname -s # 3. Node version (need ≥ 22.12 for parallelclaw ≥ 0.11.x) node --version # 4. Existing memex install? which memex && memex --version 2>&1 || echo "NO_MEMEX" # 5. Existing memex daemon running? memex-sync status 2>/dev/null | head -5 || echo "NO_DAEMON" # 6. Existing OpenClaw sessions? ls -1 ~/.openclaw/agents/main/sessions/ 2>/dev/null \ | grep -E '^[0-9a-f-]+\.jsonl$' | wc -l # 7. On Linux: systemd user-instance available? [ "$(uname -s)" = "Linux" ] && systemctl --user --version 2>/dev/null | head -1 \ || echo "macOS or no-systemd" # 8. OpenClaw gateway config ls -la ~/.openclaw/openclaw.json 2>&1 ``` **Branch on results:** | Discovery state | Action | |---|---| | **OpenClaw not found** | Stop. Tell user: "This skill is for OpenClaw agents. For Claude Code / Cursor / etc., use `install-memex` instead." | | **Node < 22.12** | Stop. Print upgrade instructions (nvm, distro pkg manager). Don't auto-install Node. | | **memex ≥ 0.11.6 + daemon running** | Skip Steps 2–4. Go directly to Step 5 (MCP wiring). Tell user: "memex already installed and running — just need to wire it into OpenClaw." | | **memex installed but < 0.11.6** | Upgrade in-place: `npm install -g parallelclaw@latest`. Continue (daemon auto-restarts if running). | | **memex installed, daemon not running** | Run `memex-sync install` (Step 3). Skip the npm install. | | **memex not installed** | Full path: Step 2 (install) → Step 3 (daemon) → Step 4 (back-fill) → Step 5 (wire) → Step 6 (restart). | | **Linux without systemd** (e.g. minimal container) | Fall back to `nohup memex-sync &`. Tell user the auto-restart limitation. | | **No openclaw.json** | Ask the user (ONE question allowed): "Where does your OpenClaw gateway store its config?" — proceed with their answer. | Report each result back as **facts, not questions**: > "✓ OpenClaw detected at /usr/local/bin/openclaw" > "✓ Linux + systemd 255 — will use user-systemd for daemon" > "✓ Node 22.22.2 — ok" > "→ memex not installed — installing 0.11.6+" > "✓ Found 60 OpenClaw sessions ready to back-fill" --- ## Step 2 — Install parallelclaw (skip if already at ≥ 0.11.6) ```sh npm install -g parallelclaw@latest ``` If `EACCES` (no permission to write to npm global prefix), apply the standard fix — **never use sudo**: ```sh mkdir -p ~/.npm-global npm config set prefix ~/.npm-global echo 'export PATH=$HOME/.npm-global/bin:$PATH' >> ~/.zshrc 2>/dev/null echo 'export PATH=$HOME/.npm-global/bin:$PATH' >> ~/.bashrc 2>/dev/null export PATH=$HOME/.npm-global/bin:$PATH npm install -g parallelclaw@latest ``` Verify: ```sh memex --version # must print 0.11.6 or later ``` --- ## Step 3 — Install the auto-capture daemon (skip if already running) ```sh memex-sync install ``` Platform-specific behavior (handled automatically by memex-sync): | Platform | What `memex-sync install` does | |---|---| | **macOS** (`uname -s` = Darwin) | Writes `~/Library/LaunchAgents/com.parallelclaw.memex.sync.plist`, runs `launchctl load`. Daemon auto-starts on every login. | | **Linux + systemd-user** | Writes `~/.config/systemd/user/memex-sync.service`, runs `systemctl --user daemon-reload && enable && start`. Tries `loginctl enable-linger $USER` so daemon survives SSH logout. | | **Linux without systemd** | Exits with "systemctl --user not available". Fall back: `nohup memex-sync > /tmp/memex.log 2>&1 &` — works but won't auto-restart on reboot. | If `loginctl enable-linger` needs sudo, the install output prints the exact command. **Tell the user that line verbatim** — don't try to sudo yourself. Verify daemon running: ```sh memex-sync status # Should show: process: running (pid XXXX) ``` --- ## Step 4 — Back-fill existing sessions ```sh memex-sync scan ``` `memex-sync scan` walks the source dirs (Claude Code on workstations, OpenClaw on VPS, etc.), reads each `.jsonl`, filters internal-state noise (`.checkpoint.*`, `.trajectory.*`, `.reset.*` snapshots — they'd double-count), and writes to memex.db. Expected output: ``` === Claude Code + Cowork === - skipping claude-code: directory not found at /home/user/.claude/projects (on VPS without Claude Code) - skipping claude-cowork: directory not found at ... (on Linux — Cowork is macOS-only) scanning openclaw: /home/user/.openclaw/agents/main/sessions + openclaw-abc12345.jsonl ← 23 msgs from openclaw (ai-titled) + openclaw-def67890.jsonl ← 41 msgs from openclaw … scanned 60 files · 1316 messages emitted ``` If the daemon was already running (Step 3 skipped), `scan` is still useful — it catches anything the daemon's chokidar may have raced on startup. ### Step 4b — Channel-aware re-import (recommended once after first install) parallelclaw v0.11.5+ does two-mode auto-detection (**self-hosted** OpenClaw with separate `.jsonl` per session vs **Moonshot Kimi-Claw** with merged-file layout) and channel routing (Telegram chat / Kimi-web session / openclaw-cli). After the first `scan`, run: ```sh memex-sync backfill-channels --yes ``` This wipes existing `source = 'openclaw'` rows and re-imports with the current channel-aware pipeline. Use it once after upgrading from any parallelclaw earlier than 0.11.5, and any time the user reports "messages from one chat are merged into another" symptoms. --- ## Step 5 — Wire memex as an MCP server in openclaw.json (REQUIRED for LLM retrieval) The daemon handles capture; the parallelclaw MCP server exposes `memex_search`, `memex_recent`, `memex_overview`, etc. to the OpenClaw LLM toolset. **Without this step, the LLM has no way to search memex from inside a conversation** — it would fall back to raw `sqlite3` shell calls (or fail). ### Config-key gotcha OpenClaw 2026.5+ reads MCP servers from `cfg.mcp.servers` (nested), NOT from the top-level `cfg.mcpServers` (flat). Verify with `openclaw mcp list` after the merge — must show `memex`. Find the absolute path to `memex` (MCP stdio doesn't inherit shell PATH): ```sh which memex ``` **Preferred (OpenClaw 2026.5+): the native command** — it probes the server before saving and writes the correct `mcp.servers` key for you: ```sh openclaw mcp add memex --command "$(which memex)" --env MEMEX_SYNC_EXPERIMENTAL=1 # Already added on a re-run? It may say "already exists" — that's fine, skip. # Verify: openclaw mcp list | grep -i memex ``` **Fallback (older OpenClaw without `openclaw mcp add`, or to merge by hand):** merge memex into `~/.openclaw/openclaw.json` at `mcp.servers.memex` (preserves other servers; idempotent): ```sh python3 <<'PY' import json, shutil from pathlib import Path p = Path.home() / ".openclaw" / "openclaw.json" cfg = json.loads(p.read_text()) memex_bin = shutil.which("memex") if not memex_bin: print("ERROR: memex binary not in PATH; rerun Step 2") raise SystemExit(1) # Correct path is mcp.servers (nested), NOT mcpServers (flat). mcp_section = cfg.setdefault("mcp", {}) servers = mcp_section.setdefault("servers", {}) servers["memex"] = {"command": memex_bin, "args": [], "env": {}} # Clean up any legacy top-level mcpServers.memex from earlier skill versions stale = cfg.get("mcpServers", {}) if isinstance(stale, dict) and "memex" in stale: del stale["memex"] if not stale: cfg.pop("mcpServers", None) print("cleaned stale mcpServers.memex from previous skill version") p.write_text(json.dumps(cfg, indent=2)) print(f"memex MCP wired at {p} → {memex_bin}") PY ``` **Verify the merge worked (THREE checks)**: ```sh # 1. Config has the right key python3 -c " import json from pathlib import Path cfg = json.loads((Path.home() / '.openclaw' / 'openclaw.json').read_text()) s = cfg.get('mcp', {}).get('servers', {}).get('memex') print('mcp.servers.memex:', json.dumps(s, indent=2) if s else 'MISSING') " # 2. OpenClaw's own listing recognises it (authoritative check) openclaw mcp list 2>&1 | grep -i memex # Must show 'memex' or similar. # 3. (after restart, see Step 7d) LLM toolset includes memex_search ``` --- ## Step 6 — Restart OpenClaw ```sh openclaw gateway restart ``` Wait ~5 seconds, then check logs: ```sh journalctl --user -u openclaw -n 50 --no-pager 2>/dev/null | grep -iE "memex|mcp" | tail -10 \ || tail -100 ~/.openclaw/logs/gateway.log 2>/dev/null | grep -iE "memex|mcp" | tail -10 ``` You should see the gateway picking up the memex MCP server. --- ## Step 7 — Verify (four checks — all must pass) ### 7a. Daemon is alive and capturing ```sh memex-sync status # process: running (pid XXXX) # Watch the daemon log for a few seconds tail -10 ~/.memex/logs/memex-sync.log 2>/dev/null ``` ### 7b. memex.db has OpenClaw rows ```sh sqlite3 ~/.memex/data/memex.db <<'SQL' .headers on .mode column SELECT COUNT(*) AS total_openclaw_rows, MIN(ts) AS earliest_ts, MAX(ts) AS latest_ts FROM messages WHERE source = 'openclaw'; SQL ``` Expected: total_openclaw_rows ≥ 1 (much more if you ran back-fill on existing sessions). ### 7c. Live capture writes a NEW row ```sh PRE=$(sqlite3 ~/.memex/data/memex.db \ "SELECT COUNT(*) FROM messages WHERE source='openclaw'") echo "PRE: $PRE" # >>> NOW send a test message in OpenClaw, wait for reply <<< sleep 8 POST=$(sqlite3 ~/.memex/data/memex.db \ "SELECT COUNT(*) FROM messages WHERE source='openclaw'") echo "POST: $POST diff=$((POST - PRE))" sqlite3 ~/.memex/data/memex.db \ "SELECT id, role, datetime(ts,'unixepoch','localtime') AS when_, substr(text,1,60) AS preview, conversation_id FROM messages WHERE source='openclaw' ORDER BY ts DESC LIMIT 5" ``` Expected: diff ≥ 2 (user + assistant), recent rows include your test message. ### 7d. LLM toolset includes memex tools (requires a FRESH OpenClaw session) MCP tools are loaded into the LLM's function-calling toolset at **session start**. The session in which you just ran `openclaw gateway restart` has the OLD toolset. To verify memex is exposed: 1. Start a **fresh** OpenClaw conversation. 2. Ask the agent: "Find the earliest conversations from April using memex_search." 3. The agent should: - Mention `memex_search` in its reasoning or just call it - Return real results (IDs, timestamps, snippets from `~/.memex/data/memex.db`) - NOT fall back to direct `sqlite3` calls If the agent doesn't see memex tools → re-check Step 5 (probably `mcp.servers` vs `mcpServers` key issue) and `openclaw mcp list`. --- ## Step 8 — Coordination loop: auto-execute delegated tasks + deliver results (default ON) ParallelClaw isn't only shared memory — your agents delegate tasks to each other over the synced ledger. On an always-on OpenClaw node, **one command** wires the coordination loop, **default ON**, so this node automatically runs tasks delegated to it (and delivers results of tasks it delegated). Without it the node captures memory but never executes or reports. ```sh memex-sync openclaw-executor install # registers an `openclaw cron` job memex-sync openclaw-executor status # confirm it's registered # turn off later: memex-sync openclaw-executor uninstall ``` This registers an `openclaw cron` job (every ~60s) that runs a CHEAP shell gate (`task-list --inbox --quiet`, zero LLM tokens) and only when work is waiting hands the executor prompt to `openclaw agent` — OpenClaw's own LLM does the work. No `claude` CLI needed. Verify with `openclaw cron list` (job `parallelclaw-executor`). > If `openclaw-executor install` isn't available (older parallelclaw), fall back > to registering the job by hand on your scheduler — interval ~60s, body = exactly > this procedure: ``` # 0. CHEAP GATE — spend no LLM tokens on empty ticks: memex-sync task-list --inbox --quiet # exit 0 = there is work, 1 = empty # exit 1 → skip execution, jump to step 2 (delivery). If your scheduler can # only launch an agentTurn, make the agentTurn's FIRST action run this and # STOP immediately when the inbox is empty. # 1. EXECUTE the inbox (only when the gate passed): # for each id in `memex-sync task-list --inbox`: memex-sync task-claim --json # exit 0 = yours; use the FULL .prompt field # → do the work with your own model/tools; recall context via # `memex search "..."` / `memex get ` (NOT raw sqlite) memex-sync task-update done --result "" # (or: failed --result "". Put real content in # --result, NEVER a /tmp path — the requester is on another machine.) # 2. DELIVER results of tasks YOU delegated (the piece that was missing): memex-sync task-results --json # .result here is the FULL text (not truncated) # → send each .result to the user (DM the Telegram chat that asked), then: memex-sync task-results --ack # mark delivered; don't repeat # (for ONE task's full answer: `memex-sync task-get `. NEVER deliver from # the plain task-list/task-results display — it truncates to 80/200 chars.) ``` Safe defaults: the `--quiet` gate keeps empty ticks free; only SAFE_KINDS (research / content / test / general / review / summarize / analysis) auto-run; destructive cross-machine actions are NOT auto-run (do the safe part, say what needs a human). Canonical procedure: `docs/design/executor-prompt.md`. Then tell the user plainly — **inform, don't ask** (the user opted into default-on): ``` ⚙️ Coordination is on: this node now auto-runs tasks delegated to it (safe kinds only) every ~60s and delivers results of what it delegates back to you. Turn it off any time by removing that scheduled job from your scheduler. ``` --- ## Step 9 — Final message to user After all checks pass: ``` ✅ memex wired into OpenClaw. Captured: • Every new OpenClaw turn writes to ~/.memex/data/memex.db within seconds (the memex-sync daemon watches ~/.openclaw/agents/main/sessions/) • Past sessions back-filled (Step 4) • Channel routing works for self-hosted OpenClaw + Moonshot Kimi-Claw Search: • From inside OpenClaw chat: ask the model to search its memory — uses memex_search • From CLI: `memex search "query"` or `memex overview` • From any other MCP-enabled client on the same machine (Claude Code, Cursor, etc.) — the memex MCP server exposes 11 search tools Daemon: • Status check: `memex-sync status` • Auto-restarts on login (LaunchAgent on macOS, systemd-user on Linux) • Survives SSH logout if linger is enabled Coordination (default on): • This node auto-runs tasks delegated to it (safe kinds) every ~60s, and delivers results of tasks IT delegated back to you. • Delegate work to another agent: `memex-sync task-delegate "..." --to ` • Send another node a result/report (NOT executed): `memex-sync task-note "..." --to ` • Check the ledger: `memex-sync task-list --mine` / `task-results` • One-glance health: `parallelclaw status` • Turn off: `memex-sync openclaw-executor uninstall` Pair with: • install-memex (generic skill) — if you also use Claude Code, Cursor, etc. on this same machine, they all share ~/.memex/data/memex.db • memex-hermes (pip package) — if you run Hermes Agent on this machine ``` --- ## What this skill explicitly does NOT do - ❌ Install Node.js (manual step if needed — print instructions, don't auto-install) - ❌ Use sudo. Ever. If permissions block something, surface the manual fix and stop. - ❌ Overwrite existing `mcp.servers` entries. Merge. - ❌ Configure outbound network access. memex is local-first. --- ## Edge cases | Condition | What to do | |---|---| | OpenClaw < 2026.5 | The MCP-server `mcp.servers` key is 2026.5+. Older versions used different keys — check `openclaw config show` to find the right one and adapt Step 5. | | memex.db locked (WAL contention) | Wait 1 second, retry. SQLite WAL handles concurrent readers/writers. | | Plugin install permission denied | Bootstrap section at the top of this skill — user needs to allow third-party skills once. | | Linger fails with sudo prompt | Print the exact `sudo loginctl enable-linger $USER` line, ask the user to run it once, and continue without sudo. | | openclaw.json doesn't exist | Ask the user ONE question for the path. Don't auto-create. | --- ## Safety rules — read before starting - Never sudo. Never edit system files. Never modify `$PATH` outside `~/.zshrc` / `~/.bashrc` with the user's consent. - Always confirm before deleting anything from the user's machine. - Always preserve existing config keys when editing JSON. - Print every shell command to the user before running it. - If any step fails, **stop**. Don't try to recover by trying random things. Print the error and ask the user. --- ## Begin Run Step 1 (Discovery) now. Print results. Branch as the table indicates.