Versioning

Every write is versioned with git, copy-on-write snapshots, or not at all.

KiwiFS records a version for every write, whichever protocol it came through. Pick a strategy based on how much history you need: full git history with blame, lightweight per-file snapshots, or none.

Strategy	History	Blame	Draft spaces	Best for
git (default)	Real git commits	Yes	Yes	Production, audit trails, multi-agent work
cow	Per-file snapshots in .versions/	No	No	Simple rollback without a git repository
none	None	No	No	Scratch data, CI, throwaway runs

Set it with a flag or in config. The flag wins when both are set.

Terminal

kiwifs serve --versioning git

git

Every write becomes a git commit in the knowledge base’s own repository. The writer’s identity becomes the commit author: the X-Actor header over REST, or the actor argument over MCP. Writes without an actor are attributed to anonymous over REST and mcp-agent over MCP.

Terminal

$ git log --format='%h %an  %s'
e4f5g6h agent:docs-writer  agent:docs-writer: concepts/auth.md
a1b2c3d agent:importer     agent:importer: concepts/auth.md

Because it is a normal repository, git log, git blame, git diff, and git revert all work. Edits made directly on disk are picked up by the file watcher and committed the same way.

Batched commits

Under heavy write load, KiwiFS batches commits. Writes from the same actor that land within the batch window share one commit; a different actor always starts a new commit, so authorship never mixes.

Key	Flag	Default	Meaning
async_commit	--async-commit	true	Batch commits in the background
batch_window_ms	--batch-window	200	How long to collect writes
batch_max_size	--batch-max-size	50	Most paths in one commit

A batched commit with several files lists every path in its message, so git log stays useful.

cow

Copy-on-write keeps a snapshot of a file in .versions/<path>/ before each overwrite and before a delete. Older snapshots beyond max_versions per file are pruned.

.kiwi/config.toml

[versioning]
strategy = "cow"
max_versions = 100   # snapshots kept per file (default 100)

Version history, reading an old version, and line diffs work. Blame and word-level diffs return 501.

none

Writes overwrite files in place, and the history endpoints return empty results. The write pipeline, search index, and live events still run.

Optimistic locking

Every read returns an ETag: the git blob hash of the content. Send it back in If-Match and the write fails with 409 Conflict if someone changed the file since you read it. This works under every strategy, because the hash is computed from the content itself.

Terminal

# Read and note the ETag header
curl -i 'http://localhost:3333/api/kiwi/file?path=concepts/auth.md'

# Write only if nobody else has
curl -X PUT 'http://localhost:3333/api/kiwi/file?path=concepts/auth.md' \
  -H 'If-Match: "a1b2c3d4..."' \
  -H 'X-Actor: agent:docs-writer' \
  --data-binary @auth.md

Over MCP, pass the ETag from kiwi_read as if_match to kiwi_write.

Moves and restructuring

Renames, moves, and merges go through the refactor engine. Every wiki link and markdown link that pointed at the old path is rewritten, and the move plus every relinked page land in a single commit, so one git revert undoes the whole change. See Refactor.

Read history

REST

Endpoint	Purpose
GET /api/kiwi/versions?path=	Version list for a file: hash, date, author, message
GET /api/kiwi/version?path=&version=	File content at one version
GET /api/kiwi/diff?path=&from=&to=	Unified diff. Add granularity=word for a word diff (git only).
GET /api/kiwi/blame?path=	Per-line author and commit (git only)
GET /api/kiwi/changes	Recent commits across the knowledge base, with long polling

Terminal

curl 'http://localhost:3333/api/kiwi/versions?path=concepts/auth.md'

MCP

kiwi_versions lists the history of a file. kiwi_changes lists recent changes across the knowledge base.

Web UI

Open a page and choose History to browse versions, compare any two, and see who changed each line.

Related

Versioning API

Parameters and responses for history, diff, and blame.

Draft spaces

Stage a batch of edits on a branch before merging.

Backup and sync

Push the repository to a git remote on a schedule.

Files as truth

Why the files, not the index, are the record.