Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.kiwifs.com/llms.txt

Use this file to discover all available pages before exploring further.

KiwiFS versions every write so you never lose knowledge. 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
Best for: production, audit trails, multi-agent environments.

​
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
Best for: high-write environments, embedded use cases.

​
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
Multiple writes within the batch window are combined into a single git commit. This dramatically improves throughput while preserving atomicity per batch.

​
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"
If the file was modified between your read and write, you get a 409 Conflict response.

​
API endpoints

EndpointMethodDescription
/api/kiwi/versionsGETVersion history for a file
/api/kiwi/versionGETRead a specific version
/api/kiwi/diffGETUnified diff between two versions
/api/kiwi/blameGETPer-line git blame
/api/kiwi/changesGETList recent changes across the knowledge base
See the Versioning API reference for detailed endpoint documentation.
Last modified on May 4, 2026