Tools

Mindkeeper

Name: Mindkeeper
Rating: 3.5 (1 reviews)
Author: seekcontext

By seekcontext 👁 11 views ▲ 0 votes

Time machine for your AI's brain — auto-snapshot, diff & rollback for agent context files. OpenClaw plugin + standalone CLI.

GitHub

Install

npm install -g

Configuration Example

{
  "tracking": {
    "include": [
      "AGENTS.md", "SOUL.md", "USER.md", "IDENTITY.md",
      "TOOLS.md", "HEARTBEAT.md", "MEMORY.md",
      "memory/**/*.md", "skills/**/*.md"
    ],
    "exclude": ["BOOTSTRAP.md", "canvas/**"]
  },
  "snapshot": {
    "debounceMs": 30000
  },
  "commitMessage": {
    "mode": "template"
  }
}

README

<p align="center">
  <h1 align="center">mindkeeper</h1>
  <p align="center"><strong>Time Machine for Your AI's Brain</strong></p>
  <p align="center">
    Every personality tweak, every rule change, every memory — tracked, diffable, and reversible.
  </p>
</p>

<p align="center">
  <a href="https://www.npmjs.com/package/mindkeeper-openclaw"><img src="https://img.shields.io/npm/v/mindkeeper-openclaw?label=openclaw%20plugin&color=blue" alt="npm (openclaw plugin)"></a>
  <a href="https://www.npmjs.com/package/mindkeeper"><img src="https://img.shields.io/npm/v/mindkeeper?label=core%20cli&color=blue" alt="npm (core)"></a>
  <a href="https://www.npmjs.com/package/mindkeeper-openclaw"><img src="https://img.shields.io/npm/dm/mindkeeper-openclaw?color=brightgreen" alt="npm downloads"></a>
  <a href="./LICENSE"><img src="https://img.shields.io/badge/license-MIT-green" alt="License"></a>
</p>

<p align="center">
  <a href="#openclaw-plugin">OpenClaw Plugin</a> •
  <a href="#standalone-cli">Standalone CLI</a> •
  <a href="#how-it-works">How It Works</a> •
  <a href="#roadmap">Roadmap</a>
</p>

---

## The Problem

Your AI assistant's personality, rules, and memories live in markdown files — `SOUL.md`, `AGENTS.md`, `MEMORY.md`, and more. These files **are** your AI. They shape how it thinks, responds, and remembers.

But right now, when something goes wrong — a personality tweak that backfires, a rule that breaks your workflow, a memory that gets corrupted — you have no easy way to go back. No history. No diff. No undo.

**mindkeeper** fixes this.

## What It Does

- **Automatic snapshots** — Every change to your agent context files is silently recorded in the background. No manual saves needed.
- **Full history** — See exactly what changed, when, and why. Browse the evolution of your AI's personality over days, weeks, months.
- **Visual diffs** — Compare any two versions of any file side-by-side. See exactly what was added, removed, or modified.
- **Instant rollback** — Reverted a personality trait you liked? Rolled back a useful rule? Restore any file to any previous version with one command.
- **Named checkpoints** — About to make a big change? Save a named snapshot like `stable-v2` so you can always come back.
- **LLM-powered summaries** — In OpenClaw Plugin mode, commit messages are automatically generated by your configured LLM. Your history reads like a changelog, not a list of hashes. Zero extra configuration — mindkeeper reads your existing OpenClaw auth and model settings.

## OpenClaw Plugin

mindkeeper is built as a first-class OpenClaw plugin. Install it once, and your AI gains the ability to manage its own version history.

### Install

```bash
openclaw plugins install mindkeeper-openclaw
```

That's it. The plugin auto-starts a background watcher when your Gateway launches. Every change to your agent context files is tracked automatically.

> **Requirements:** Node.js ≥ 22, OpenClaw with Gateway running.

### Talk to Your AI About Its Own History

Once installed, your AI understands version control. Just ask in natural language:

```
You:   "What changed in SOUL.md recently?"
AI:    Shows you a timeline of personality changes with summaries.

You:   "Compare my current AGENTS.md to last week's version."
AI:    Displays a clear diff highlighting what was added and removed.

You:   "I don't like how you've been responding. Roll back SOUL.md to yesterday."
AI:    Previews the diff, asks for confirmation, then restores the file.
       "Done. Run /new to apply the changes."

You:   "Save a checkpoint called 'perfect-personality' before I experiment."
AI:    Creates a named snapshot you can return to anytime.
```

### Agent Tools

The plugin registers 5 tools your AI can use autonomously:

| Tool | What It Does |
|------|-------------|
| `mind_history` | Browse change history for any tracked file |
| `mind_diff` | Compare any two versions with full unified diff |
| `mind_rollback` | Two-step rollback: preview first, then execute after confirmation |
| `mind_snapshot` | Create named checkpoints before risky changes |
| `mind_status` | Show what files are tracked and what's changed |

### OpenClaw CLI

```bash
openclaw mind status              # See what's tracked and pending
openclaw mind history SOUL.md     # Browse SOUL.md change history
openclaw mind snapshot stable-v2  # Save a named checkpoint
```

## Standalone CLI

mindkeeper also works independently — no OpenClaw required. Use it to version-control any directory of markdown files.

### Install

```bash
npm install -g mindkeeper
```

### Usage

```bash
# Initialize vault for your workspace
mindkeeper init ~/.openclaw/workspace

# View change history
mindkeeper history SOUL.md

# Compare two versions
mindkeeper diff SOUL.md abc1234 def5678

# Rollback with preview and confirmation
mindkeeper rollback SOUL.md abc1234

# Create a named checkpoint
mindkeeper snapshot before-experiment --message "Saving current personality"

# Start background watcher
mindkeeper watch
```

### CLI Reference

| Command | Description |
|---------|-------------|
| `init [dir]` | Initialize a vault for a directory |
| `status` | Show tracking status and pending changes |
| `history [file]` | View change history (optionally filtered by file) |
| `diff <file> <from> [to]` | Compare two versions of a file |
| `rollback <file> <to>` | Rollback a file with preview and confirmation |
| `snapshot [name]` | Create a named snapshot |
| `watch` | Start file watcher daemon |

## How It Works

mindkeeper maintains a **shadow Git repository** alongside your workspace using [isomorphic-git](https://isomorphic-git.org/) (pure JavaScript, no system Git required). The Git data lives in `<workspace>/.mindkeeper/` while your files stay exactly where they are.

```
~/.openclaw/workspace/
├── AGENTS.md              ← tracked, stays in place
├── SOUL.md                ← tracked, stays in place
├── MEMORY.md              ← tracked, stays in place
├── memory/
│   └── 2026-03-04.md      ← tracked, stays in place
├── skills/
│   └── my-skill/SKILL.md  ← tracked, stays in place
└── .mindkeeper/           ← git history data (hidden, auto-managed)
```

**Key design decisions:**

- **No file duplication** — files are tracked in-place, not copied
- **No conflicts** — the shadow repo is completely independent from any existing `.git` in your workspace
- **No dependencies** — pure JavaScript Git engine, works everywhere Node.js runs
- **Per-workspace isolation** — each workspace has its own `.mindkeeper/`, naturally supporting multiple profiles

### What Gets Tracked

By default, mindkeeper tracks the files that define your AI:

| Category | Files |
|----------|-------|
| Personality & Rules | `AGENTS.md`, `SOUL.md`, `IDENTITY.md` |
| User Context | `USER.md`, `TOOLS.md`, `HEARTBEAT.md` |
| Memory | `MEMORY.md`, `memory/**/*.md` |
| Skills | `skills/**/*.md` |

Excluded by default: `BOOTSTRAP.md`, `canvas/**`, `.git/`, `.mindkeeper/`.

All tracking patterns are [fully configurable](#configuration).

### Auto-Snapshot Flow

```
  File changed → Queue change → [30s debounce] → Stage files → Generate message → Commit
                      ↑                                               │
                 More changes reset                          Template or LLM
                   the timer                                   summary
```

Changes are batched with a 30-second debounce window. If you edit `SOUL.md` multiple times within 30 seconds, only one snapshot is created with the final state. A lockfile mechanism prevents duplicate watchers.

## Configuration

### Workspace config — `.mindkeeper.json`

This file is tracked by the vault and safe to share. Place it in your workspace root.

```json
{
  "tracking": {
    "include": [
      "AGENTS.md", "SOUL.md", "USER.md", "IDENTITY.md",
      "TOOLS.md", "HEARTBEAT.md", "MEMORY.md",
      "memory/**/*.md", "skills/**/*.md"
    ],
    "exclude": ["BOOTSTRAP.md", "canvas/**"]
  },
  "snapshot": {
    "debounceMs": 30000
  },
  "commitMessage": {
    "mode": "template"
  }
}
```

### Global config — `~/.config/mindkeeper/config.json`

This file is **never tracked** and never shared. Use it for sensitive settings like API keys.

```json
{
  "commitMessage": {
    "mode": "llm",
    "llm": {
      "apiKey": "sk-xxx",
      "model": "claude-sonnet"
    }
  }
}
```

> **Security**: Sensitive fields (e.g., `commitMessage.llm.apiKey`) are **only allowed in global config**. If mindkeeper detects an API key in your workspace config, it refuses to start and tells you exactly what to move. This prevents accidental credential leakage when sharing vaults.

## Architecture

```
mindkeeper/
├── packages/
│   ├── core/              # npm: mindkeeper
│   │   ├── src/
│   │   │   ├── vault.ts           # Core Vault class (init, snapshot, history, diff, rollback)
│   │   │   ├── store/git-store.ts # isomorphic-git with gitdir separation
│   │   │   ├── watcher.ts         # chokidar + debounce + lockfile
│   │   │   ├── config.ts          # Layered config with sensitive field enforcement
│   │   │   ├── diff.ts            # Structured diff engine (jsdiff)
│   │   │   └── message/           # Template + LLM commit message generators
│   │   ├── bin/mindkeeper.ts      # CLI entry point
│   │   └── test/                  # Unit + integration tests
│   │
│   └── openclaw/          # npm: mindkeeper-openclaw
│       ├── src/
│       │   ├── tools.ts           # 5 agent tools for AI-driven version control (mind_*)
│       │   ├── cli.ts             # openclaw mind subcommands
│       │   ├── service.ts         # Auto-start watcher service
│       │   └── llm-provider.ts    # LLM commit messages via OpenClaw's auth
│       ├── skills/mindkeeper/SKILL.md
│       └── openclaw.plugin.json
│
├── pnpm-workspace.yaml
└── LICENSE                        # MIT
```

## Roadmap

### v0.2 — Visual

- [ ] **Web UI** — Visual timeline, side-by-side diff viewer, one-click rollback
- [ ] **Full snapshot rollba

... (truncated)

tools