mindkeeper

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.

install

source · Clone the upstream repo

git clone https://github.com/seekcontext/mindkeeper

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/seekcontext/mindkeeper "$T" && mkdir -p ~/.claude/skills && cp -r "$T/packages/openclaw/skills/mindkeeper" ~/.claude/skills/seekcontext-mindkeeper-mindkeeper && rm -rf "$T"

OpenClaw · Install into ~/.openclaw/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/seekcontext/mindkeeper "$T" && mkdir -p ~/.openclaw/skills && cp -r "$T/packages/openclaw/skills/mindkeeper" ~/.openclaw/skills/seekcontext-mindkeeper-mindkeeper && rm -rf "$T"

manifest: packages/openclaw/skills/mindkeeper/SKILL.md

source content

Mindkeeper — Time Machine for Your AI's Brain

Use mindkeeper tools when the user asks about changes, history, or versions of their agent context files (

AGENTS.md

SOUL.md

USER.md

IDENTITY.md

TOOLS.md

HEARTBEAT.md

MEMORY.md

memory/

skills/

Bootstrap (One-time setup)

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.

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.
If the runtime confirms the plugin is missing and the user confirms, run this flow:
- Install the plugin — Run via bash:
```
openclaw plugins install mindkeeper-openclaw
```
- 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.
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.
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."

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
`mind_status`	Show what files are tracked and whether there are unsaved changes
`mind_history`	Browse the change log for one file or all files
`mind_diff`	Compare any two versions of a file side-by-side
`mind_rollback`	Restore a file to a previous version (always preview first)
`mind_snapshot`	Save a named checkpoint before making significant changes

Tracking Scope

Mindkeeper tracks these files by default:

```
AGENTS.md
```
,
```
SOUL.md
```
,
```
USER.md
```
,
```
IDENTITY.md
```
```
TOOLS.md
```
,
```
HEARTBEAT.md
```
,
```
MEMORY.md
```
```
memory/**/*.md
```
```
skills/**/*.md
```

Excluded by default:

BOOTSTRAP.md

canvas/**

.git/

.mindkeeper/

When to Use

User says…	Action
"What changed in SOUL.md?"	`mind_history` with `file: "SOUL.md"`
"Show me the diff from last week"	`mind_history` to find the commit, then `mind_diff`
"Undo that change" / "Roll back AGENTS.md"	Full rollback procedure (see below)
"Save a checkpoint before I experiment"	`mind_snapshot` with a descriptive name
"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 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"
```
```
limit
```
(optional): number of entries to return (default 10, increase for longer searches)

mind_history({ file: "SOUL.md", limit: 20 })
→ { count, entries: [{ oid, date, message }] }

mind_diff

Compares two versions of a file.

from

and

to

are short or full commit hashes from

mind_history

Omit
```
to
```
to compare
```
from
```
against the current version (HEAD).
To see what changed in the latest commit: use
```
from: entries[1].oid
```
(the parent) and
```
to: entries[0].oid
```
or omit
```
to
```
for HEAD. Do NOT use
```
from: entries[0].oid
```
with
```
to: HEAD
```
— that compares the same commit to itself and yields an empty diff.

mind_diff({ file: "SOUL.md", from: "a1b2c3d4" })
→ { file, from, to, additions, deletions, unified }

mind_snapshot

Creates a named checkpoint of the current state of all tracked files. Use before risky changes.

```
name
```
: short identifier, e.g.
```
"stable-v2"
```
or
```
"before-experiment"
```
```
message
```
(optional): longer description

mind_snapshot({ name: "stable-v2", message: "Personality tuned, rules finalized" })
→ { success, snapshot, commit: { oid, message } }

mind_rollback

Always use the two-step procedure. Never skip the preview.

Step 1 — Preview:

mind_rollback({ file: "SOUL.md", to: "a1b2c3d4", preview: true })
→ { preview: true, diff: { unified, additions, deletions }, instruction }

Show the diff to the user and ask for confirmation.

Step 2 — Execute (only after user confirms):

mind_rollback({ file: "SOUL.md", to: "a1b2c3d4", preview: false })
→ { preview: false, success: true, commit: { oid, message } }

After success, tell the user: "Run

/new

to apply the changes to your current session."

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
LLM commit messages are plugin-only for now — currently supported only through the OpenClaw plugin; standalone CLI mode falls back to template messages
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