gitmind

Git state monitor + multi-source backup & rollback for self-modifying systems.

gitmind watches a git repository, records every rollback — and distinguishes the ones a system performs on itself — snapshots the whole repo as git bundles, and replicates those bundles across variable backup sources (local filesystem, IPFS, Arweave). It is the containment-and-replication layer an autonomous, self-editing agent needs: when a self-change goes wrong, you can see that it happened, classify it, and restore from a replica.

• Self-contained — standard library + git. No services to run.
• Model-agnostic — gitmind is plain infrastructure with no LLM dependency. It works identically whether your agent runs GLM-4.5 / GLM-5.2, Llama, Qwen, Mistral, Claude, or anything else. It backs up code and tensors, not a model.
• MIT licensed.

Install

pip install gitmind          # from PyPI (once published)
# or, from source:
pip install -e .

CLI

python -m gitmind report          # current git state + recent backups + rollback ledger
python -m gitmind snapshot        # record state; classify the transition (advance/rollback/reset)
python -m gitmind backup          # git bundle --all → replicate to every configured source
python -m gitmind rollback <sha>  # safe self-rollback (git revert <sha>..HEAD)
python -m gitmind rollback <sha> --hard   # git reset --hard (gated by GITMIND_ALLOW_HARD=1)

Library

from gitmind import GitMind, LocalSource, IPFSSource

gm = GitMind()                 # auto-detects the git toplevel from cwd
gm.snapshot()                  # monitor tick: log state, detect & classify rollbacks
import asyncio
asyncio.run(gm.backup())       # bundle the repo and fan it out to all sources
gm.report()                    # the diagnostic view

How rollback detection works

It's git-ancestry based, not guesswork. On each snapshot(), gitmind compares the current HEAD to the last one it saw:

• new HEAD is an ancestor of the old one → rollback (HEAD moved backward)
• old HEAD is an ancestor of the new one → advance (ordinary new commits)
• neither → reset (history diverged — a reset/force to another line)

A rollback is a self-rollback when the system calls mark_self_rollback() (or rollback_to(), which marks it) immediately before reverting. The next snapshot reads the flag and records self_rollback — so you can always tell "a human/CI rolled us back" from "we rolled ourselves back." Everything lands in an append-only ledger at .gitmind/ledger.jsonl.

Backup sources (pluggable)

backup() makes one git bundle create --all (a complete, restorable replica) and fans it out concurrently to every configured Source:

source	backing	configured by
LocalSource	a local backup dir (.gitmind/backups/, newest 3 kept)	built-in, always on
IPFSSource	any IPFS node HTTP API (Kubo daemon / pinning gateway)	GITMIND_IPFS_API
your own	anything	subclass Source and pass it in

gm = GitMind(sources=[LocalSource(gm.root), IPFSSource("http://127.0.0.1:5001"), MyArweaveSource()])

Implement Source.put(self, data: bytes, label: str) -> dict to add Arweave, S3, a pinning service, or an on-chain anchor — gitmind fans the bundle out to all of them and records each result.

Why "gitmind"

Built for mindX, a self-improving multi-agent system, where the agent edits its own source. gitmind is the substrate that lets such a system contain a bad self-change (record + classify the rollback), replicate itself across independent stores (no single disk loss is fatal), and restore from any replica. It is useful to any project that wants disciplined, multi-destination git backups with first-class rollback accounting.

---

MIT © 2026 Professor Codephreak / mindX