mindkeeper-openclaw 0.2.26 → 0.2.28

package/README.md

@@ -24,6 +24,8 @@ openclaw plugins install mindkeeper-openclaw
 
 Then restart your Gateway once.
 
+On startup, the plugin mirrors its built-in `mindkeeper` skill into `<workspace>/skills/mindkeeper/` (OpenClaw's standard workspace skills path) so new sessions can find the bootstrap instructions even if no separate ClawHub skill was installed.
+
 ### Option 2 — Install the skill and let the AI guide setup
 
 ```bash
@@ -64,6 +66,11 @@ openclaw mind snapshot stable-v2
 - Node.js >= 22
 - OpenClaw with Gateway running
 
+## Troubleshooting
+
+- If a fresh `/new` session says the plugin is missing right after install, restart Gateway once and retry. Some OpenClaw flows do not expose plugin tools or the built-in skill until startup finishes.
+- If tools still do not appear, verify that `mindkeeper-openclaw` is enabled in your OpenClaw config and that `mind_status`, `mind_history`, `mind_diff`, `mind_rollback`, and `mind_snapshot` are allowed tools.
+
 ## Commit Messages
 
 OpenClaw Plugin mode is currently the only mode that supports LLM-generated commit messages. If no supported model or API key is available, mindkeeper falls back to template messages automatically.

package/dist/index.js

@@ -1179,6 +1179,49 @@ function resolveModelFromConfig(config) {
   return { provider, model, baseUrl };
 }
 
+// src/skill-mirror.ts
+var import_node_fs2 = require("node:fs");
+var import_node_path6 = __toESM(require("node:path"));
+var SKILL_DIR_NAME = "mindkeeper";
+var SKILL_FILES = ["SKILL.md", "README.md", "clawhub.json"];
+function ensureWorkspaceSkillMirror(workspaceDir, options = {}) {
+  if (!workspaceDir) return;
+  const sourceDir = options.sourceDir ?? resolveBundledSkillDir();
+  const targetDir = import_node_path6.default.join(workspaceDir, "skills", SKILL_DIR_NAME);
+  if (!(0, import_node_fs2.existsSync)(sourceDir)) {
+    options.log?.warn?.(`[mindkeeper] Built-in skill directory not found: ${sourceDir}`);
+    return;
+  }
+  try {
+    (0, import_node_fs2.mkdirSync)(targetDir, { recursive: true });
+    const copied = [];
+    for (const file of SKILL_FILES) {
+      const sourceFile = import_node_path6.default.join(sourceDir, file);
+      const targetFile = import_node_path6.default.join(targetDir, file);
+      if (!(0, import_node_fs2.existsSync)(sourceFile)) {
+        options.log?.warn?.(`[mindkeeper] Built-in skill file missing: ${sourceFile}`);
+        continue;
+      }
+      if ((0, import_node_fs2.existsSync)(targetFile)) continue;
+      (0, import_node_fs2.copyFileSync)(sourceFile, targetFile);
+      copied.push(file);
+    }
+    if (copied.length > 0) {
+      options.log?.info?.(
+        `[mindkeeper] Mirrored built-in skill files to ${targetDir}: ${copied.join(", ")}`
+      );
+    }
+  } catch (err) {
+    options.log?.warn?.(`[mindkeeper] Failed to mirror built-in skill: ${String(err)}`);
+  }
+}
+function resolveBundledSkillDir() {
+  if (typeof __dirname !== "string" || __dirname.length === 0) {
+    throw new Error("mindkeeper: __dirname is unavailable while resolving the built-in skill");
+  }
+  return import_node_path6.default.resolve(__dirname, "..", "skills", SKILL_DIR_NAME);
+}
+
 // src/service.ts
 function createWatcherService(api, trackerRef) {
   let watcher = null;
@@ -1195,6 +1238,7 @@ function createWatcherService(api, trackerRef) {
         log.warn("[mindkeeper] No workspace directory in service context. Watcher disabled.");
         return;
       }
+      ensureWorkspaceSkillMirror(workspaceDir, { log: api.log });
       const llmProvider = await createOpenClawLlmProvider({
         config: ctx.config,
         log
@@ -1243,6 +1287,7 @@ function mindkeeperPlugin(api) {
   const trackerRef = { current: null };
   registerTrackerTools(api, trackerRef);
   registerTrackerCli(api, trackerRef);
+  ensureWorkspaceSkillMirror(api.getWorkspaceDir?.(), { log: api.log });
   const watcherService = createWatcherService(api, trackerRef);
   api.registerService?.(watcherService);
   ensureToolsInConfig(api);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mindkeeper-openclaw",
-  "version": "0.2.26",
+  "version": "0.2.28",
   "description": "OpenClaw plugin for mindkeeper: auto-snapshot, diff, and rollback for agent context files",
   "keywords": [
     "openclaw",

package/skills/mindkeeper/README.md

@@ -17,7 +17,7 @@ This skill teaches the AI how to bootstrap and use the `mindkeeper-openclaw` plu
 clawhub install mindkeeper
 ```
 
-On first use, the AI checks whether `mindkeeper-openclaw` is available. If it is missing, the AI asks for your confirmation before installing the plugin and before restarting Gateway. If automatic restart is unavailable, it tells you to restart Gateway manually.
+On first use, the AI checks whether `mindkeeper-openclaw` is available. If the tools are not ready yet, it should first consider whether Gateway still needs to finish loading or restart before assuming the plugin is missing.
 
 ## What It Enables
 
@@ -34,6 +34,8 @@ On first use, the AI checks whether `mindkeeper-openclaw` is available. If it is
 
 The `mindkeeper-openclaw` plugin provides the actual `mind_*` tools and background watcher. This skill provides the guidance and first-use bootstrap behavior.
 
+In OpenClaw Plugin mode, the AI should prefer the `mind_*` tools for history, diff, snapshot, and rollback tasks. CLI commands are mainly for setup, troubleshooting, or manual terminal workflows.
+
 If you prefer to install the plugin yourself first:
 
 ```bash
@@ -67,11 +69,12 @@ openclaw plugins install mindkeeper-openclaw
 | "Show me the diff from last week" | `mind_history` → find commit → `mind_diff` |
 | "Undo that change" | `mind_rollback` preview first, then execute after confirmation |
 | "Save a checkpoint before I experiment" | `mind_snapshot` with a descriptive name |
+| "Edit SOUL.md to change my tone" | Edit the file directly; mindkeeper should track the change automatically |
 
 ## Troubleshooting
 
 - **History is empty** — Call `mind_status` to check whether mindkeeper is initialized. Make a small edit to a tracked file to trigger the first snapshot.
-- **Tools not found** — Ensure the `mindkeeper-openclaw` plugin is installed and Gateway has been restarted.
+- **Tools not found** — Ensure the `mindkeeper-openclaw` plugin is installed and Gateway has been restarted. A brand-new `/new` session can briefly miss the tool context while startup is still finishing.
 - **Rollback not applying** — After rollback, run `/new` to reload the session with the restored file.
 
 ## Links

package/skills/mindkeeper/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: mindkeeper
 description: Time Machine for Your AI's Brain — version control for agent context files. Use when the user asks about changes in SOUL.md, AGENTS.md, MEMORY.md, or other agent context files; when they want to undo, rollback, or compare versions; or when they need a checkpoint before risky edits.
-version: 1.2.3
+version: 1.2.6
 homepage: https://github.com/seekcontext/mindkeeper
 repository: https://github.com/seekcontext/mindkeeper
 ---
@@ -12,11 +12,11 @@ Use mindkeeper tools when the user asks about changes, history, or versions of t
 
 ## Bootstrap (One-time setup)
 
-**When the user enables mindkeeper or asks for mindkeeper capability**, first try `mind_status`. If it fails (tool not found or similar):
+**When the user enables mindkeeper or asks for mindkeeper capability**, first try `mind_status`. If it fails, do **not** assume the plugin is missing yet. It can also fail when Gateway has not finished loading the plugin, when tools are not exposed to the current session yet, or when the workspace copy of this skill is unavailable.
 
-1. **Ask for confirmation** — Tell the user: "Mindkeeper needs the mindkeeper-openclaw plugin to work. I'll need to run `openclaw plugins install mindkeeper-openclaw` and restart the Gateway. May I proceed?" **Do not install or restart until the user explicitly confirms.**
+1. **Diagnose conservatively** — Tell the user: "I can't access the mindkeeper tools yet. The plugin may be missing, Gateway may still need a restart, or the current session may not have loaded the skill/tool context yet." Only say the plugin is definitely missing if the runtime explicitly shows that `mindkeeper-openclaw` is not installed.
 
-2. **After user confirms** — Run this flow:
+2. **If the runtime confirms the plugin is missing and the user confirms**, run this flow:
    - **Install the plugin** — Run via bash:
      ```bash
      openclaw plugins install mindkeeper-openclaw
@@ -24,10 +24,20 @@ Use mindkeeper tools when the user asks about changes, history, or versions of t
    - **Restart Gateway if the runtime supports it** — Use the available runtime mechanism to restart Gateway. If restart is unavailable or fails, tell the user: "Plugin installed. Restart your Gateway manually to apply."
    - **Confirm** — If restart succeeded, tell the user: "Mindkeeper is ready. Restart complete — you can now ask about history, diffs, rollbacks, or snapshots." If restart did not happen, tell the user that the plugin is installed but Gateway must be restarted before the tools will appear.
 
-3. **Alternative** — If the user prefers to install manually, tell them: "Run `openclaw plugins install mindkeeper-openclaw` in your terminal, then restart your Gateway. After that, mindkeeper will be ready."
+3. **If the plugin appears installed already** — Tell the user to retry after Gateway finishes loading or after a manual restart. If a workspace copy of the skill appears to be missing, mention that the session may not have loaded the built-in mindkeeper skill correctly yet.
+
+4. **Alternative** — If the user prefers to install manually, tell them: "Run `openclaw plugins install mindkeeper-openclaw` in your terminal, then restart your Gateway. After that, mindkeeper will be ready."
 
 If `mind_status` succeeds, the plugin is already installed; skip the bootstrap and proceed with the user's request.
 
+## Tool Preference
+
+In OpenClaw Plugin mode, prefer the `mind_*` tools over CLI commands for normal mindkeeper operations.
+
+- Use `mind_status`, `mind_history`, `mind_diff`, `mind_snapshot`, and `mind_rollback` whenever they are available.
+- Do not use `openclaw mind ...` or `mindkeeper ...` for routine history, diff, snapshot, or rollback requests if the plugin tools are available.
+- CLI commands are for one-time setup, troubleshooting, manual user workflows, or when the user explicitly asks for terminal commands.
+
 ## Available Tools
 
 | Tool | Purpose |
@@ -60,14 +70,25 @@ Excluded by default: `BOOTSTRAP.md`, `canvas/**`, `.git/`, `.mindkeeper/`.
 | "Is mindkeeper tracking my files?" | `mind_status` |
 | "What does my history look like?" | `mind_history` without a file filter |
 
+## Direct Edit Requests
+
+If the user asks to directly edit a tracked file such as `SOUL.md`, `AGENTS.md`, or `MEMORY.md`, make the edit directly.
+
+- Do not block on CLI availability.
+- Do not mention unavailable CLI commands unless the user explicitly asked for a CLI-based workflow.
+- Mindkeeper's background watcher should capture the change automatically after the edit.
+- If relevant, you may mention that the change should now be tracked by mindkeeper.
+
 ## Tool Usage Guide
 
 ### mind_status
-Call this first if you're unsure whether mindkeeper is initialized or what files are being tracked.
+Call this first when the user asks about history, tracking state, snapshots, or rollback, or if you're unsure whether mindkeeper is initialized.
 ```
 mind_status → { initialized, workDir, pendingChanges, snapshots }
 ```
 
+You do not need to call `mind_status` before a simple direct edit request unless the user specifically asks about tracking or history.
+
 ### mind_history
 Returns a list of commits with short hash, date, and message.
 - `file` (optional): filter to a specific file path, e.g. `"SOUL.md"`
@@ -117,6 +138,7 @@ After success, tell the user: **"Run `/new` to apply the changes to your current
 ## Important Notes
 
 - **This skill is the guide, the plugin is the engine** — the `mindkeeper-openclaw` plugin provides the actual `mind_*` tools and watcher; this skill teaches the AI how to bootstrap and use them safely
+- **Use plugin tools first** — in OpenClaw Plugin mode, prefer `mind_*` tools over CLI commands for normal operations
 - **Rollback is per-file** — it only restores the specified file, not all files at once
 - **Rollbacks are non-destructive** — every rollback creates a new commit, so it can itself be undone
 - **Auto-snapshots run in the background** — the user doesn't need to manually save; mindkeeper captures every change automatically
@@ -124,3 +146,4 @@ After success, tell the user: **"Run `/new` to apply the changes to your current
 - **Named snapshots are the safety net** — encourage users to snapshot before major personality or rule changes
 - **If history is empty** — mindkeeper may not have initialized yet, or no changes have been made since install. Call `mind_status` to check.
 - **Commit hashes** — always use the `oid` field from `mind_history` results. Short 8-character hashes are fine.
+- **Keep user-facing messages focused** — if a task can be completed with file edits or `mind_*` tools, do not distract the user with unavailable CLI details

package/skills/mindkeeper/clawhub.json

@@ -4,7 +4,7 @@
   "description": "Time Machine for Your AI's Brain — install this skill if you want your AI to inspect history, show diffs, create checkpoints, and guide rollback in natural language across agent context files.\n\nSetup: add this skill alone. On first use, the AI checks whether the mindkeeper-openclaw plugin is available. If it is not, the AI asks for explicit confirmation before installing the plugin and before restarting Gateway. User consent is required for plugin install and Gateway restart.\n\nUse this skill when the user asks about changes, history, or versions of their agent context files. The skill teaches the AI how to bootstrap and use the mind_status, mind_history, mind_diff, mind_rollback, and mind_snapshot tools safely.",
   "category": "productivity",
   "tags": ["version-control", "agent", "history", "rollback", "snapshot", "diff", "openclaw"],
-  "version": "1.2.3",
+  "version": "1.2.6",
   "license": "MIT",
   "pricing": "free",
   "homepage": "https://github.com/seekcontext/mindkeeper",