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 a single SQLite + FTS5 corpus.
2. Existing past sessions are back-filled in one shot.
3. The OpenClaw gateway gains 18 MCP tools (memex_search, memex_overview, memex_recent, memex_store_document, memex_import_file, etc.).
4. The capture continues automatically (systemd user-service on Linux, LaunchAgent on macOS).

Where you might be running:

• 🖥️ VPS (Linux VPS hosting OpenClaw + Hermes etc.) — typical "always-on agent" deployment
• 💻 macOS workstation running OpenClaw alongside Claude Code / Cursor / etc.
• 💻 Linux workstation (Pop!OS, Fedora, etc.) running OpenClaw locally
• 🖥️ macOS VPS / Mac-mini server — also valid

All four work the same way. Platform (Linux/macOS) determines daemon type. Context (VPS vs workstation) is irrelevant to memex.

Important — interaction with the generic install-memex skill:

If the user ALREADY ran install-memex (the generic Claude Code / Cursor / Cline / Continue / Zed installer) on THIS machine, then memex is already installed and the daemon is already running. In that case, this skill only needs to merge memex into the OpenClaw gateway config — no re-install, no re-daemon. Discovery (Step 1) detects this case and skips Steps 2–4.

Conversely, if the user has Claude Code / Cursor / Telegram on this same machine and wants those captured too, recommend running install-memex separately AFTER this skill completes. This skill focuses strictly on the OpenClaw wiring.

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 (restart gateway, try a search).

⚠ For ClawHub reviewers, security scanners, and curious users

This skill installs memex-mvp from npm (if not already present) and wires it as an MCP server inside the OpenClaw gateway config. Every "suspicious" pattern below is intentional and documented:

Hard guarantees:

• Agent shows every command before running it
• sudo is NEVER invoked by the skill (linger fallback prints the manual command for the user instead)
• OpenClaw config is merged, never overwritten
• memex at runtime emits zero outbound network traffic — local-first by design
• If memex 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 OpenClaw gateway's permission model is blocking arbitrary skill execution by default. This is OpenClaw's safety guard, not specific to memex.

The exact permission name varies between OpenClaw versions — common ones:

• plugins.allow: ["skill", …] in ~/.openclaw/openclaw.json
• A separate skills.enabled: true setting
• A capability called skill-install or skill-runtime

Check your OpenClaw docs for the exact permission name in your version, set it once, restart the gateway, and retry. After this bootstrap is done once, every future ClawHub skill works out of the box.

Once this skill is loaded and you're reading the rest of this file: continue to "Prerequisite" below.

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

# 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 ≥ 20)
node --version
# 4. Existing memex install?
which memex && memex --version || echo "NO_MEMEX"
# 5. Existing memex daemon running?
memex-sync status 2>/dev/null | grep -E "process:" || 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 location? (varies — try common paths)
ls -la ~/.openclaw/openclaw.json ~/.openclaw/config.json ~/.openclaw/mcp.json 2>/dev/null

Branch on results:

Report each result back to the user as facts, not questions:

"✓ OpenClaw detected" "✓ Linux + systemd 255 — will use user-systemd for daemon" "✓ Node 22.10.0 — ok" "→ memex not installed — installing 0.11.5" "✓ Found 126 OpenClaw sessions ready to back-fill" "→ Config at ~/.openclaw/openclaw.json"

Step 2 — Install memex (skip if already at ≥ 0.11.5)

npm install -g memex-mvp@latest

If EACCES (no permission to write to npm global prefix), apply the standard fix — never use sudo:

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 memex-mvp@latest

After install:

memex --version    # must print 0.11.5 or later

Step 3 — Install the auto-capture daemon (skip if already running)

memex-sync install

Platform-specific behavior (handled automatically by memex-sync v0.11.5+):

If linger needs sudo, the install output prints the manual command. Tell the user that line verbatim — don't try to run sudo yourself.

Step 4 — Back-fill existing sessions

memex-sync scan

memex-sync scan walks SOURCES (Claude Code, Cowork, OpenClaw added in v0.10.14, …) and emits any unindexed sessions. For OpenClaw it processes every \x3Cuuid>.jsonl in ~/.openclaw/agents/main/sessions/ PLUS .checkpoint.* snapshots PLUS .reset.* archives (v0.11.5+), filters internal-state noise, 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 (with ai-title)
+ openclaw-def67890.jsonl ← 41 msgs from openclaw
…
scanned 126 files · 1255 messages emitted

If the daemon was already running (Step 3 skipped), the back-fill via scan is still useful — it catches anything the daemon's chokidar might have raced on startup.

Step 4b — Channel-aware re-import (memex ≥ 0.11.5, recommended for ALL OpenClaw users)

v0.11.5 is the first version where OpenClaw ingestion can be trusted end-to-end on both self-hosted OpenClaw (the dominant case — separate \x3Cuuid>.jsonl per session) and Moonshot Kimi-Claw (the merged-file variant). Older versions had architectural blind spots. After upgrading from anything below 0.11.5, run a channel-aware re-import:

memex-sync backfill-channels --yes

This deletes existing source = 'openclaw' rows and re-imports each archived file with the v0.11.5 pipeline. Expected banner:

Backfill: 110 archived OpenClaw file(s) (57 main + 38 checkpoint + 15 reset)
  mode:          auto -> detected: self-hosted
  current state: 1481 messages in 8 conversation(s)
  38 checkpoint file(s) will be SKIPPED (snapshots — avoid 30-40× duplication).
  15 reset file(s) will be ingested (full archives of pre-reset session history).

Per-channel breakdown at the end:

  channels:
    • telegram: 7338 msgs
    • kimi-web:  102 msgs

Idempotent — re-running is safe (UNIQUE(source, conv, msg_id) dedups).

Override mode if auto-detection picks the wrong one:

memex-sync backfill-channels --yes --mode kimi-claw     # force Moonshot mode
memex-sync backfill-channels --yes --mode self-hosted   # force self-hosted mode

Auto-detection rarely needs override — it inspects sessions.json and falls back to scanning file contents for channel markers (Kimi-Claw merged files contain BOTH Kimi and Telegram markers; self-hosted has one channel per file).

What you get out of v0.11.5 vs older

Step 5 — Wire memex into the OpenClaw gateway config

The most fragile step. Get it exactly right:

# 1. Find the config (Step 1 likely already located it)
ls -la ~/.openclaw/openclaw.json ~/.openclaw/config.json ~/.openclaw/mcp.json 2>/dev/null

# 2. Get the absolute path to memex
which memex

You (OpenClaw agent) know your own gateway config structure. Read it, merge in the memex entry, write atomically:

{
  // … existing config preserved …
  "mcpServers": {
    // … other MCP servers preserved …
    "memex": {
      "command": "\x3CABSOLUTE_PATH_FROM_WHICH_MEMEX>"
    }
  }
}

Three critical rules:

1. Absolute path from which memex (e.g. /home/user/.npm-global/bin/memex or /usr/local/bin/memex). NEVER just "memex" — MCP-stdio doesn't inherit shell PATH.
2. Merge, don't overwrite. Read the JSON, set .mcpServers.memex, write the whole thing back. Other entries stay untouched.
3. Atomic write: write to \x3Cpath>.tmp, then mv to \x3Cpath>. If the gateway is mid-read, an atomic rename is safe; a partial write is not.

Step 6 — Verify (what you CAN check before gateway restart)

After install + scan, only a few things are verifiable. The full data ingestion happens when the OpenClaw gateway restarts and spawns the memex MCP server — that's when staged inbox files get processed into memex.db. Until then, memex overview may show zero messages even though the back-fill worked.

So Step 6 checks only what's deterministically true RIGHT NOW:

# 1. Daemon is up?
memex-sync status

# 2. Are inbox files staged for the MCP server to process?
ls ~/.memex/inbox/ | wc -l

Expected output:

memex-sync status
  daemon:    installed (systemd user-service · …)
  process:   running (PID 12345)
  watching:  1 openclaw main session(s) · 6 entries total
  last activity: just now

$ ls ~/.memex/inbox/ | wc -l
6     # = number of OpenClaw sessions staged for ingestion

Don't try memex overview or memex search until AFTER the gateway is restarted (Step 7). Why: the inbox→DB import happens inside the memex MCP server, which gets spawned by the OpenClaw gateway on first MCP request after restart. Running queries before that yields "memex.db not found" or "0 messages" — confusing but expected.

Diagnostic flowchart if either check fails:

• memex-sync status shows "process: not running" → check journalctl --user -u memex-sync -n 30 (Linux) or tail ~/.memex/data/launchd.err.log (macOS). On Linux without linger this is the most common cause.
• ls inbox/ is empty after scan → memex-sync scan couldn't find anything. Double-check ls ~/.openclaw/agents/main/sessions/ | grep -v -E '\.(checkpoint|trajectory|reset)\.' — if THAT is empty too, the user has no OpenClaw sessions yet (no problem, daemon will capture new ones going forward).

Step 7 — Final message to the user

Adjust the numbers; print verbatim otherwise:

✓ Node 22 — ok
✓ Linux + systemd 255 — daemon as user-service (linger enabled)
✓ memex 0.11.5 installed
✓ Daemon running (PID 12345)
✓ Back-filled 126 sessions → 1255 messages
✓ MCP wired into ~/.openclaw/openclaw.json

NEXT STEP (you must do this — I can't):
   Restart the OpenClaw gateway so it picks up the memex MCP tools.
     openclaw gateway restart      # or your gateway-restart command

   After restart, ask me to search for something to test the wiring:
     "поищи в мемексе про \x3Ctopic>"

memex is now capturing every new OpenClaw session you have — searchable
in milliseconds, verbatim (no AI compression). To browse the corpus in
a browser: `memex web --open`.

Bonus suggestion (mention only if relevant):

"If you ALSO use Claude Code / Cursor / Cline on this same machine, OR have Telegram chats you want indexed, run install-memex (the generic skill) separately to capture those too. memex shares the same database across all sources."

Step 8 — Verify (after user restarts the gateway)

After the user restarts the OpenClaw gateway and the memex MCP server has processed its first inbox files, these commands will return real data — ask the user to run them (or run them yourself if they reconnect):

# Real corpus stats — should now show the back-filled OpenClaw sessions
memex overview

# Smoke search — should find content from a recent session
memex search "\x3Crecent topic>"

Expected memex overview:

memex corpus snapshot

Total: 1255 messages in 6 conversations
By source:
  • openclaw       1255 msgs in 6 conversations (last: just now)

If memex overview still shows 0 messages 30 seconds after gateway restart:

• Check that the gateway actually launched memex MCP: ps aux | grep memex should show a memex process spawned by openclaw
• Check the OpenClaw config's mcpServers.memex.command IS the absolute path from which memex (no shell PATH inheritance over MCP stdio)
• As a last resort, manually import each staged inbox file: for f in ~/.memex/inbox/openclaw-*.jsonl; do memex import "$f"; done

What this skill explicitly does NOT do

• ❌ Touch other MCP servers in the OpenClaw config — merges only
• ❌ Install Node (tells user how)
• ❌ Run sudo — prints the sudo command if linger needs it
• ❌ Configure Telegram capture (use the generic install-memex skill — it handles Telegram Desktop integration)
• ❌ Configure sync between memex on different machines (separate roadmap)
• ❌ Change OpenClaw's session-storage path

Edge cases

Safety rules — read before starting

• If node or npm aren't installed, stop and tell the user how to install Node. Don't install Node yourself.
• Never run rm, sudo, or anything destructive without explicit user "yes" in chat. The skill never runs sudo — only prints commands.
• Show every command before running it. If the user says "no" / "stop", halt and explain.
• If a step fails, do NOT auto-retry or auto-fix — report what failed and ask how to proceed.
• When editing the OpenClaw config, always preserve existing MCP servers. If you can't merge cleanly, abort and tell the user exactly what couldn't be parsed.
• Stay focused on memex+OpenClaw wiring. If sidetracked, return to this skill and say: "OK, back to memex setup. We were at step N — should I continue?"

Begin

Start Step 1 (Discovery) now. After all checks, branch per the table in Step 1 and proceed without asking permission — unless a showstopper fires (no OpenClaw, no Node, or unparseable config).