memex-mvp 0.5.3 → 0.5.4

package/README.md

@@ -48,6 +48,24 @@ Or use one-shot `sudo npm install -g memex-mvp`.
 npx memex-mvp install
 ```
 
+### Install via AI skill (Claude Code / OpenClaw)
+
+If you'd rather have an AI agent walk you through everything, drop the
+[install-memex skill](skills/install-memex/) into `~/.claude/skills/`:
+
+```sh
+mkdir -p ~/.claude/skills
+curl -fsSL https://raw.githubusercontent.com/parallelclaw/memex-mvp/main/skills/install-memex/SKILL.md \
+  -o ~/.claude/skills/install-memex/SKILL.md
+```
+
+Then in Claude Code (or any Skills-aware agent) just say:
+
+> install memex
+
+…or `/install-memex`. The agent handles `npm install`, MCP-config wiring,
+auto-capture daemon, and verification — ~2 minutes.
+
 ---
 
 ## Connect to your MCP client

package/README.ru.md

@@ -105,6 +105,22 @@ sudo npm install -g memex-mvp
 
 После установки `memex-sync install` поднимет фоновый daemon (`~/.memex/{inbox,data}/` создадутся автоматически при первом запуске).
 
+### Установка через AI-скилл (Claude Code / OpenClaw)
+
+Если хочешь чтобы агент сам всё сделал — закинь [install-memex skill](skills/install-memex/) в `~/.claude/skills/`:
+
+```bash
+mkdir -p ~/.claude/skills
+curl -fsSL https://raw.githubusercontent.com/parallelclaw/memex-mvp/main/skills/install-memex/SKILL.md \
+  -o ~/.claude/skills/install-memex/SKILL.md
+```
+
+Затем в Claude Code (или любом Skills-aware агенте) скажи:
+
+> установи memex
+
+…или `/install-memex`. Агент сам сделает `npm install`, пропишет MCP-config, поднимет daemon и проверит что всё работает — ~2 минуты.
+
 ### Подключение к Claude Code
 
 Сначала возьми **два абсолютных пути** в терминале:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "memex-mvp",
-  "version": "0.5.3",
+  "version": "0.5.4",
   "description": "Local-first MCP server for cross-agent AI memory. One SQLite + FTS5 corpus across Claude Code, Cowork, Cursor, Continue, Zed, Obsidian, and Telegram — passively captured, verbatim, searchable from any MCP-compatible client.",
   "type": "module",
   "main": "server.js",
@@ -16,6 +16,7 @@
     "ingest.js",
     "lib/",
     "bot/",
+    "skills/",
     "HELP.md",
     "README.md",
     "LICENSE"

package/skills/install-memex/README.md

@@ -0,0 +1,58 @@
+# install-memex skill
+
+An [Anthropic Skill](https://docs.claude.com/docs/en/agents/skills) that
+walks Claude Code (or any MCP-compatible agent that supports the Skills
+spec) through installing **memex** on the user's machine — npm install,
+MCP-config wiring, auto-capture daemon, and end-to-end verification.
+
+Roughly 2 minutes wall-clock; requires Node.js and shell access.
+
+## Install the skill
+
+```sh
+mkdir -p ~/.claude/skills
+cp -r /path/to/memex-mvp/skills/install-memex ~/.claude/skills/
+```
+
+Or via curl from this repo:
+```sh
+mkdir -p ~/.claude/skills/install-memex
+curl -fsSL https://raw.githubusercontent.com/parallelclaw/memex-mvp/main/skills/install-memex/SKILL.md \
+  -o ~/.claude/skills/install-memex/SKILL.md
+```
+
+## Use it
+
+In any Skills-aware agent (Claude Code, OpenClaw, …):
+
+```
+/install-memex
+```
+
+…or just say "install memex" — the skill description is written so
+Claude picks it up automatically from natural-language requests.
+
+## What it does (high level)
+
+1. **Discovery** — read-only checks for which MCP client you're using and which AI tool data already lives on this machine.
+2. **`npm install -g memex-mvp`** — with EACCES fallbacks (one-shot sudo OR permanent prefix-fix; user picks).
+3. **MCP config merge** — single absolute `"command": "<path from which memex>"` entry into your client's mcpServers config. Never overwrites your other servers.
+4. **`memex-sync install`** — registers the macOS LaunchAgent for live auto-capture.
+5. **`memex-sync scan`** — one-time backfill of every session that already exists on disk.
+6. **Verification + restart hint.**
+
+## Why a skill (vs. just copy-pasting the install prompt)
+
+- **`/install-memex`** is shorter than "open the landing, click 'Copy install prompt', paste here"
+- Skills are auto-discovered by name — `description` field lets Claude invoke this from any phrasing of "install memex"
+- Future updates to the install flow auto-propagate if you re-fetch the skill, instead of relying on the user re-copying
+
+## Related
+
+- 🏠 [memex.parallelclaw.ai](https://memex.parallelclaw.ai) — landing page (also has copy-paste version of this prompt)
+- 📦 [memex-mvp on npm](https://www.npmjs.com/package/memex-mvp)
+- 📖 [Main memex repo](https://github.com/parallelclaw/memex-mvp)
+
+## License
+
+MIT — see [LICENSE](../../LICENSE) at the repo root.

package/skills/install-memex/SKILL.md

@@ -0,0 +1,169 @@
+---
+name: install-memex
+description: Install memex (local-first MCP server for cross-agent AI memory) on the user's machine. Detects which MCP client is active, registers memex in its config, sets up the auto-capture daemon, and verifies end-to-end. Use when the user says "install memex", "set up memex", "add memex to this", or similar. Takes ~2 minutes; requires Node.js and shell access.
+---
+
+# Install memex
+
+You are installing **memex** on this machine. Memex is a local-first MCP server that captures the user's AI conversations across Claude Code, Cowork (including subagents), Cursor, Obsidian, and Telegram exports into a searchable SQLite + FTS5 index that any MCP-compatible agent can query through 11 standard tools.
+
+Repo: https://github.com/parallelclaw/memex-mvp
+Landing: https://memex.parallelclaw.ai
+npm: https://www.npmjs.com/package/memex-mvp
+
+## How memex works (read this so you don't get confused by paths below)
+
+Memex has its OWN storage at `~/.memex/data/memex.db`. It READS from each tool's native data location automatically — Claude Code from `~/.claude/projects/`, Cursor from its `state.vscdb`, Cowork from its sessions dir, Obsidian from configured vaults. You do NOT need to change where Claude Code, Cursor, or any other tool saves its data. Memex is a passive observer.
+
+## Prerequisite
+
+This skill only works if you are running INSIDE an AI agent that has direct access to the user's shell — i.e. one of: Claude Code (CLI), Cursor, Cline, Continue, or Zed. Web-based agents (ChatGPT in browser, Claude.ai web, Claude Desktop without tools, etc.) cannot execute `npm`/file operations. If you are NOT a CLI-based agent with shell access, stop now and tell the user to use the manual install at https://memex.parallelclaw.ai/#quickstart.
+
+## Discovery — do this BEFORE the numbered steps
+
+Scan the user's setup so you can tailor advice and tell them exactly what memex will pick up.
+
+1. Identify which MCP client you're running inside (you should know from context — Claude Code CLI, Cursor, Cline, Continue, or Zed).
+2. Run these read-only checks one by one:
+   ```sh
+   ls -d ~/.claude/projects 2>/dev/null
+   ls -d ~/Library/Application\ Support/Claude/local-agent-mode-sessions 2>/dev/null
+   ls -d ~/Library/Application\ Support/Cursor 2>/dev/null
+   ls ~/.continue/config.json 2>/dev/null
+   ls -d ~/.config/zed 2>/dev/null
+   ```
+3. Report to the user in plain language:
+   - "You're running inside [X]. I will edit [path] in step 2 below."
+   - "Tools with data found on this machine: [list]"
+   - "Tools NOT found (memex won't capture from these): [list]"
+   - "After install, memex will auto-index conversations from: [detected sources]"
+4. Wait for the user's "ok" before starting step 1.
+
+## Five-step install
+
+Do these in order. Show each command before running it. Stop and ask if anything fails or looks wrong.
+
+### 1. Install memex from npm
+
+```sh
+npm install -g memex-mvp
+```
+
+If you get `EACCES` (macOS system Node), tell the user to choose:
+
+**Option A** — one-shot sudo:
+```sh
+sudo npm install -g memex-mvp
+```
+
+**Option B** — fix prefix permanently (better long-term):
+```sh
+mkdir -p ~/.npm-global
+npm config set prefix ~/.npm-global
+echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
+source ~/.zshrc
+npm install -g memex-mvp
+```
+
+**Ask which the user prefers — don't guess.**
+
+If `node` or `npm` are missing, STOP and tell the user to install Node.js (recommend nvm.sh or `brew install node`). Don't try to install Node yourself.
+
+**Verify:** `which memex` prints an absolute path; `memex-sync --help` runs without error.
+
+### 2. Wire memex into the MCP client
+
+Common config locations:
+
+| Client       | Config file                                         |
+|--------------|-----------------------------------------------------|
+| Claude Code  | `~/.claude/config.json` (or platform equivalent)    |
+| Cursor       | `~/.cursor/mcp.json`                                |
+| Cline        | VS Code `settings.json` (`cline.mcpServers`)        |
+| Continue     | `~/.continue/config.json`                           |
+| Zed          | `~/.config/zed/settings.json` (`context_servers`)   |
+
+Tell the user which one you've inferred and which file you'll edit. If unclear, ask.
+
+Read the existing config (if present). Show the user a diff before saving.
+
+Get the **absolute** path to the memex binary — GUI apps (Cursor, Cline, Claude Desktop) on macOS often don't inherit shell PATH, so a bare `"command": "memex"` fails with `spawn memex ENOENT`. Run:
+
+```sh
+which memex
+```
+
+Capture that path (e.g. `/Users/<you>/.npm-global/bin/memex` or `/usr/local/bin/memex`). If it's a shim, also run `realpath $(which memex)` to resolve to the real binary.
+
+MERGE this entry into `mcpServers` — never overwrite other servers the user has:
+
+```json
+{
+  "mcpServers": {
+    "memex": {
+      "command": "<absolute path from which memex>"
+    }
+  }
+}
+```
+
+One path, no `args`. The published npm package wires up its own entry point.
+
+If the config file doesn't exist, create the parent directory and write a minimal valid file with just memex.
+
+**Verify:** re-read the file after save; confirm `memex` entry is present and `command` is an absolute path.
+
+### 3. Turn on live auto-capture
+
+```sh
+memex-sync install
+memex-sync status
+```
+
+`status` should print "daemon installed", "running (PID …)", "watching N sessions".
+
+**Verify:** status output shows a non-zero PID.
+
+### 4. Backfill existing history
+
+The daemon only catches NEW sessions going forward. To index everything already on disk:
+
+```sh
+memex-sync scan
+```
+
+This walks `~/.claude/projects/`, Cowork sessions, Cursor `state.vscdb`, and any configured Obsidian vaults once, ingesting whatever exists.
+
+Optionally:
+```sh
+memex-sync backfill-projects
+```
+
+Tags older conversations with their `project_path` so `memex_list_projects` works on them.
+
+**Verify:** after scan, `memex-sync status` shows a non-zero "ingested" count.
+
+### 5. Tell the user what to do next
+
+Tell the user to fully quit and reopen the MCP client (Cmd+Q on macOS) so it picks up the new memex tools.
+
+After restart, suggest they try any of:
+- "show me what memex has in memory" → triggers `memex_overview`
+- "what projects has memex captured" → triggers `memex_list_projects`
+- "search memex for [recent topic]" → triggers `memex_search`
+
+These confirm everything works end-to-end.
+
+## Safety rules — read before starting
+
+- If `node` or `npm` aren't installed, stop and tell the user to install Node.js (recommend nvm.sh or `brew install node`). Don't try to install Node yourself.
+- Never run `rm`, `sudo`, or anything destructive without explicit confirmation from the user.
+- Show every command before running it. If the user says "no" or "stop", halt and explain.
+- If a step fails, do NOT auto-retry or auto-fix — tell the user what failed and ask how to proceed.
+- When editing the MCP config, always preserve existing entries. If you can't merge cleanly, abort and tell the user.
+- Do NOT modify the host application's settings beyond adding the memex entry to its `mcpServers` config. Specifically: do not redirect where Cursor / Claude Code / any other tool saves its data. Memex reads from each tool's native location automatically. The only file you should touch is the MCP config file listed in step 2.
+- Stay focused on the main install task. If sidetracked into a sub-task (changing workspace, fixing an unrelated config issue, looking up something else), once it's done you MUST return to the memex install and explicitly tell the user: "OK, back to memex install. We were at step N — should I continue?". Don't go silent after a side task. Don't assume the user wants to abandon the install — always confirm.
+
+## Begin
+
+Greet the user, confirm which MCP client you're running inside, and run the Discovery checks before any install actions.