Files as truth

Every page is a plain markdown file on disk; indexes and history are built from those files.

In KiwiFS, every page is a plain markdown file with optional YAML frontmatter. The files on disk are the record. The search index, metadata index, and vector index are derived from them and can be rebuilt at any time with kiwifs reindex. There is no proprietary format and no schema migration.

Why files

• Universal. Every language, tool, and agent can read and write a file.
• Inspectable. cat, grep, find, and your editor work out of the box.
• Diffable. Git gives you history, blame, and merges.
• Durable. Files outlast databases, SaaS tools, and proprietary formats.
• Portable. Copy the folder to move your knowledge anywhere.

Frontmatter as structured data

YAML frontmatter turns a page into a record:

concepts/authentication.md

---
title: Authentication
status: verified
tags: [security, oauth]
owner: platform-team
updated: 2026-04-25
---

# Authentication

OAuth2 and JWT based authentication...

KiwiFS indexes frontmatter so you can query it with DQL and the metadata API, and validate it with schemas.

Layout of a knowledge base

kiwifs init creates the folder from a template. The default kb template looks like this:

knowledge

.kiwi

config.toml

playbook.md

rules.md

schemas

templates

workflows

state

.gitignore

SCHEMA.md

index.md

playbook.md

getting-started

guides

reference

troubleshooting

faq

Path	Holds
SCHEMA.md, index.md	Agent-facing layout and entry page. See Agent playbook.
.kiwi/config.toml	Server configuration. See Configuration.
.kiwi/playbook.md, .kiwi/rules.md	Agent instructions served by kiwi_context
.kiwi/schemas/, .kiwi/templates/, .kiwi/workflows/	Frontmatter schemas, page templates, workflow definitions
.kiwi/state/	Rebuildable indexes. Ignored by git.

As KiwiFS runs, .kiwi/ can also gain comments/, views/, drafts/, and eval/. Other templates (wiki, memory, runbook, adr, research, and more) ship different page folders.

Paths under .kiwi/ are not reachable through the file API, except .kiwi/rules.md and .kiwi/playbook.md.

Every write is versioned

Writes through REST, MCP, NFS, S3, WebDAV, FUSE, or straight to disk all pass through one pipeline: write the file, commit it, update the indexes, and notify connected clients. With the default git strategy, each write is a commit authored by the writer (X-Actor over REST, actor 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

That gives you full history, blame for every line, diffs between any two versions, and rollback. See Versioning.

What this means in practice

1. Backup is git push or rsync. KiwiFS can push to a remote on a schedule.
2. Import writes files; export reads them.
3. Migration is copying a folder.
4. Other tools can work on the same files: git, editors, scripts. KiwiFS notices direct edits and indexes them.
5. No lock-in. If you stop using KiwiFS, your markdown stays readable.

Related

Versioning

git, copy-on-write, or none.

Agent interface

How agents read and write the files.

Backup and sync

Push to a git remote automatically.

Configuration

Every .kiwi/config.toml key.