docs(plugins): rework opencode and openclaw install guides

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: radimsem

plugins/openclaw/README.md

@@ -34,21 +34,25 @@ remindb --version
 
 remindb needs a SQLite file built from a source tree before the agent can read from it.
 
-A natural source for OpenClaw is its own state folder at `~/.openclaw/` — `openclaw.json`, hook scripts under `hooks/<id>/`, agent workspaces under `workspace/` (and `workspace-*`), and skill definitions under `skills/`. Indexing it lets OpenClaw query its own persistent context through remindb instead of grepping the dot folder.
+A natural source for OpenClaw is its own state folder at `~/.openclaw/` — `openclaw.json`, hook scripts under `hooks/<id>/`, agent workspaces under `workspace/` (and `workspace-*`), per-agent state under `agents/<id>/`, installed plugins under `extensions/`, and shared skill definitions under `skills/`. Indexing it lets OpenClaw query its own persistent context through remindb instead of grepping the dot folder.
 
-`~/.openclaw/` also accumulates per-agent session transcripts under `agents/<id>/sessions/`, plus `credentials/`, `sandboxes/`, and `sandbox/` — runtime state that bloats the index and includes secrets. Drop a `.remindb.ignore` at `~/.openclaw/` to filter them out (gitignore-style minimal subset: `*`, `**`, trailing `/`, `#` comments; no `!` negation, no `[abc]` ranges):
+`~/.openclaw/` also accumulates session transcripts at `agents/<id>/sessions/*.jsonl`, OAuth + API-key stores at `agents/<id>/agent/auth-profiles.json` (with provider apiKey residues sometimes spilling into adjacent `models.json`), the `extensions/` plugin install dir (you don't want remindb indexing its own bundled `index.ts` / `.mcp.json`), and `sandboxes/` / `sandbox/` runtime state. Drop a `.remindb.ignore` at `~/.openclaw/` to filter them out (gitignore-style minimal subset: `*`, `**`, trailing `/`, `#` comments; no `!` negation, no `[abc]` ranges):
 
 ```bash
 mkdir -p ~/.cache/remindb
 printf '%s\n' \
-    '# Compile only curated context; skip session transcripts and runtime state.' \
+    '# Compile only curated context; skip session transcripts, secrets, and runtime state.' \
     '' \
     '# Session transcripts.' \
     '*.jsonl' \
     '# Per-agent session subtrees (agents/<id>/sessions/).' \
     '**/sessions/' \
-    '# oauth.json — never index secrets.' \
-    'credentials/' \
+    '# OAuth and API-key store (agents/<id>/agent/auth-profiles.json).' \
+    '**/auth-profiles.json' \
+    '# Provider apiKey residues sometimes leak into agents/<id>/agent/models.json.' \
+    '**/models.json' \
+    '# Installed plugins — avoid indexing remindb plugin source.' \
+    'extensions/' \
     '# Sandbox runtime state.' \
     'sandboxes/' \
     '# Sandbox config (containers.json).' \
@@ -78,6 +82,15 @@ Stick them in `~/.bashrc` / `~/.zshrc` / your fish equivalent to make it permane
 
 ### 4. Install the plugin
 
+Both install paths point at a local checkout, so clone the repo first:
+
+```bash
+git clone https://github.com/radimsem/remindb.git ~/code/remindb
+cd ~/code/remindb
+```
+
+Pin to a release tag if you want a stable version: `git -C ~/code/remindb checkout v0.1.0`.
+
 Via OpenClaw CLI:
 
 ```bash
@@ -97,6 +110,17 @@ cp plugins/openclaw/index.ts plugins/openclaw/openclaw.plugin.json plugins/openc
 openclaw gateway restart
 ```
 
+#### Seed remaining context
+
+Step 2 compiled `~/.openclaw/` — OpenClaw's own state folder. The current project's `AGENTS.md` (or `SOUL.md`, `USER.md`, `MEMORY.md`) and in-repo docs (`README.md`, design notes, roadmaps) live in the repo, not under that path. Ask the agent in your first session to fold them in. Use absolute paths — `MemoryCompile` doesn't expand `~`:
+
+```
+remindb__MemoryCompile(path="/home/you/code/my-project/AGENTS.md", message="seed: project rules")
+remindb__MemoryCompile(path="/home/you/code/my-project/README.md", message="seed: project overview")
+```
+
+Re-run whenever a file changes.
+
 ## Configuration
 
 You can also enable the plugin and pin its config in `openclaw.json`:

plugins/opencode/README.md

@@ -42,23 +42,28 @@ remindb compile ~/code/my-project --db ~/.cache/remindb/my-project.db
 
 Drop a `.remindb.ignore` at the workspace root if you need to exclude noise (build outputs, vendored deps, generated files). The same file is honored by `serve`'s background rescan and the `MemoryCompile` tool.
 
-#### Bring OpenCode's hierarchical memory along
+### 3. Configure opencode.json
 
-OpenCode doesn't keep a `memory/` folder — its persistent context is a stack of `AGENTS.md` files. It loads them from three places: the global `~/.config/opencode/AGENTS.md`, project-root and ancestor `AGENTS.md` files traversed upward from your cwd, and a Claude Code fallback at `~/.claude/CLAUDE.md` (unless disabled). Only `AGENTS.md` files at or below the workspace root land in `REMINDB_SOURCE` automatically — ancestors above it and the global file live outside.
+`remindb serve` reads `REMINDB_DB` and `REMINDB_SOURCE` for its `--db` and `--source` flags. The cleanest place to set them for OpenCode is the `environment` object on the `mcp.remindb` entry — OpenCode passes it straight to the spawned subprocess without touching your shell env. The full config looks like this:
 
-Ask OpenCode to compile them once the plugin is running. Use absolute paths — `MemoryCompile` doesn't expand `~`:
-
-```
-remindb__MemoryCompile(path="/home/you/.config/opencode/AGENTS.md", message="seed: global memory")
-remindb__MemoryCompile(path="/home/you/code/parent/AGENTS.md", message="seed: ancestor memory")
-remindb__MemoryCompile(path="/home/you/.claude/CLAUDE.md", message="seed: claude-code fallback")
+```json
+{
+    "$schema": "https://opencode.ai/config.json",
+    "mcp": {
+        "remindb": {
+            "type": "local",
+            "command": ["remindb", "serve"],
+            "environment": {
+                "REMINDB_DB": "{env:HOME}/.cache/remindb/my-project.db",
+                "REMINDB_SOURCE": "{env:HOME}/code/my-project"
+            },
+            "enabled": true
+        }
+    }
+}
 ```
 
-Re-run whenever the file changes.
-
-### 3. Add the MCP entry to your `opencode.json`
-
-Pick one:
+Pick one install path:
 
 **Project-level** (recommended — one workspace per repo):
 
@@ -75,20 +80,9 @@ curl -fsSL https://raw.githubusercontent.com/radimsem/remindb/main/plugins/openc
     -o ~/.config/opencode/opencode.json
 ```
 
-Or merge this block into an existing config by hand:
+The bundled file ships only the bare MCP entry — open it after curling and add the `environment` block from the snippet above. Or skip the curl and write the full snippet by hand into either path.
 
-```json
-{
-    "$schema": "https://opencode.ai/config.json",
-    "mcp": {
-        "remindb": {
-            "type": "local",
-            "command": ["remindb", "serve"],
-            "enabled": true
-        }
-    }
-}
-```
+Heads up: OpenCode only expands `{env:VARIABLE_NAME}` in config values — shell-style `$HOME` or `${HOME}` is treated as a literal string and won't work. Swap the paths for a different workspace (e.g., `{env:HOME}/notes` + `{env:HOME}/.cache/remindb/notes.db`) whenever you want OpenCode to read a different tree. Per-project is recommended so each workspace carries its own DB and source paths — OpenCode reads `opencode.json` on session start, so launching a fresh session from the new directory is enough to swap configs.
 
 **Optional — npm-distributed plugin stub.** If you want the bundle to show up in OpenCode's plugin list, reference the npm package from the same `opencode.json`:
 
@@ -100,6 +94,17 @@ Or merge this block into an existing config by hand:
 
 OpenCode runs `bun install` at startup to resolve the dependency.
 
+**Prefer a shell-inherited env?** Point the two values at your own env vars via the same substitution:
+
+```json
+"environment": {
+    "REMINDB_DB": "{env:REMINDB_DB}",
+    "REMINDB_SOURCE": "{env:REMINDB_SOURCE}"
+}
+```
+
+Then export the pair in `~/.bashrc` / `~/.zshrc` / your fish equivalent and restart OpenCode from that shell.
+
 Confirm the server is connected:
 
 ```bash
@@ -108,39 +113,19 @@ opencode mcp list
 
 You should see `remindb` listed with the full `Memory*` tool suite.
 
-### 4. Point remindb at your workspace via `opencode.json`
-
-`remindb serve` reads `REMINDB_DB` and `REMINDB_SOURCE` as fallbacks for its `--db` and `--source` flags. The cleanest place to set them for OpenCode is the `environment` object on the same `mcp.remindb` entry — OpenCode passes it straight to the spawned subprocess without touching your shell env:
-
-```json
-{
-    "$schema": "https://opencode.ai/config.json",
-    "mcp": {
-        "remindb": {
-            "type": "local",
-            "command": ["remindb", "serve"],
-            "environment": {
-                "REMINDB_DB": "{env:HOME}/.cache/remindb/my-project.db",
-                "REMINDB_SOURCE": "{env:HOME}/code/my-project"
-            },
-            "enabled": true
-        }
-    }
-}
-```
+#### Seed remaining context
 
-Heads up: OpenCode only expands `{env:VARIABLE_NAME}` in config values — shell-style `$HOME` or `${HOME}` is treated as a literal string and won't work. Swap the paths for a different workspace (e.g., `{env:HOME}/notes` + `{env:HOME}/.cache/remindb/notes.db`) whenever you want OpenCode to read a different tree. Keep the file per-project at the workspace root as `opencode.json` so each workspace carries its own DB and source paths — OpenCode reads it on session start, so launching a fresh session from the new directory is enough to swap configs.
+OpenCode doesn't keep a `memory/` folder — its persistent context is a stack of `AGENTS.md` files loaded from three places: the global `~/.config/opencode/AGENTS.md`, project-root and ancestor `AGENTS.md` files traversed upward from your cwd, and a Claude Code fallback at `~/.claude/CLAUDE.md` (unless disabled). Only `AGENTS.md` files at or below the workspace root land in `REMINDB_SOURCE` automatically — ancestors above it and the global file live outside.
 
-Prefer a shell-inherited env? Point the two values at your own env vars via the same substitution:
+Ask OpenCode in your first session to fold them in. Use absolute paths — `MemoryCompile` doesn't expand `~`:
 
-```json
-"environment": {
-    "REMINDB_DB": "{env:REMINDB_DB}",
-    "REMINDB_SOURCE": "{env:REMINDB_SOURCE}"
-}
+```
+remindb__MemoryCompile(path="/home/you/.config/opencode/AGENTS.md", message="seed: global memory")
+remindb__MemoryCompile(path="/home/you/code/parent/AGENTS.md", message="seed: ancestor memory")
+remindb__MemoryCompile(path="/home/you/.claude/CLAUDE.md", message="seed: claude-code fallback")
 ```
 
-Then export the pair in `~/.bashrc` / `~/.zshrc` / your fish equivalent and restart OpenCode from that shell.
+Re-run whenever a file changes.
 
 ## Tools exposed