KiwiFS versions every write so you never lose data. Choose the strategy that fits your use case.
Strategies
Configure via CLI flag or .kiwi/config.toml:
kiwifs serve --versioning git
[versioning]
strategy = "git"
git (default)
Every write creates a real git commit. You get full git log, git blame, git diff, and git revert for free. The X-Actor header becomes the commit author.
$ git log --oneline knowledge/
e4f5g6h agent:docs-writer update concepts/auth.md
a1b2c3d agent:importer create concepts/auth.md
cow (copy-on-write)
Lighter-weight versioning that stores snapshots without a real git repo. Useful when you want rollback capability but don’t need the full git workflow.
[versioning]
strategy = "cow"
max_versions = 100 # max snapshots per file
none
No versioning at all. Writes overwrite files in place. Use this for ephemeral or scratch knowledge bases.
Best for: development, temporary data, CI pipelines.
Async batching
To reduce git overhead under high write volume, KiwiFS batches commits:
[versioning]
async_commit = true
batch_window_ms = 200 # collect writes for 200ms
batch_max_size = 50 # then commit up to 50 paths in one commit
Optimistic locking
The versioning system powers optimistic concurrency control via ETags. When you read a file, the response includes an ETag header containing the git blob SHA.
# Read and capture ETag
curl -i 'http://localhost:3333/api/kiwi/file?path=concepts/auth.md'
# ETag: "a1b2c3d4..."
# Write with If-Match
curl -X PUT 'http://localhost:3333/api/kiwi/file?path=concepts/auth.md' \
-H "If-Match: a1b2c3d4..." \
-d "updated content"
409 Conflict response.
API endpoints
| Endpoint | Method | Description |
|---|
/api/kiwi/versions | GET | Version history for a file |
/api/kiwi/version | GET | Read a specific version |
/api/kiwi/diff | GET | Unified diff between two versions |
/api/kiwi/blame | GET | Per-line git blame |
/api/kiwi/changes | GET | List recent changes across the knowledge base |
Last modified on May 14, 2026
