KiwiFS: a markdown filesystem with git commits, FTS5 search and six access protocols

The gap KiwiFS targets: markdown files that nothing can query

The README frames the problem bluntly: raw .md files are just files, with no search, no versioning and no structure. It then lists the usual alternatives and why each is unsatisfying for this use case: databases agents cannot read, read-only retrieval layers agents cannot write to, ephemeral sandboxes that vanish, and proprietary SaaS you cannot self-host. That is a fair summary of the space. The audience is teams running agents that already produce or consume markdown, plus humans who want to browse the same corpus in a wiki interface. KiwiFS's answer is to keep the files as the single source of truth and treat every index as a derivative you can rebuild. The diagram in the README shows two consumers (an agent using cat and grep against a /kiwi path, and a human in a web UI with wiki links and a graph view) sitting above the same markdown files, with git, an FTS5 plus vector index, and SSE events hanging off the side. The claim worth taking seriously is the last sentence of that section: files are the source of truth, everything else is a derivative index you can rebuild. If that holds, a corrupted index is an inconvenience rather than data loss, which is a materially different failure profile from a wiki backed by a database.

One storage layer behind six protocols

The README states that REST, MCP, NFS, S3, WebDAV and FUSE all flow through one storage layer. That is the architectural decision that matters most here, because it means the access protocol is a transport concern rather than a data-model concern. An agent can write over REST or MCP while a human edits in the browser and a backup job reads over S3, and all three are hitting the same code path. The write path is where the design gets specific: each write is an atomic git commit, and the commit author comes from the X-Actor request header. The README documents the normalization applied before the value reaches git (control characters stripped, capped at 256 characters) and gives a fallback table: REST falls back to anonymous, WebDAV falls back to the server's configured WebDAV actor, webdav by default. Search is layered too, with BM25 via SQLite FTS5 for full text and a pluggable vector side whose embedder and store are configured separately. The README lists OpenAI, Ollama, Cohere, ONNX and a generic http provider as embedder options, and sqlite-vec, Qdrant, pgvector and Pinecone as vector stores. That is a wide matrix, and it means semantic search is optional rather than baked in. DQL adds SQL-like queries over frontmatter with TABLE, LIST, COUNT, WHERE, SORT and GROUP BY. The web UI is embedded in the binary via go:embed, so there is no separate frontend build to deploy.

Getting it running: install, init, serve

The README gives three install paths: brew install kiwifs/tap/kiwifs, a curl install script from the repository's main branch, and go install github.com/kiwifs/kiwifs@latest. The repository badge indicates Go 1.25. Initialization and serving are two commands: kiwifs init --template knowledge --root ./knowledge followed by kiwifs serve --root ./knowledge, after which the REST API listens on port 3333 and the web UI is at http://localhost:3333. Docker is the alternative: docker run -p 3333:3333 -v ./knowledge:/data ameliaanhlam/kiwifs. A minimal agent write is a PUT to /api/kiwi/file with a path query parameter and an X-Actor header, as in curl -X PUT 'localhost:3333/api/kiwi/file?path=pages/auth.md' -H "X-Actor: my-agent" -d "# Authentication\n\nOAuth2 + JWT...". Configuration lives in .kiwi/config.toml, and the README shows the vector search block: [search.vector] with enabled = true, then [search.vector.embedder] with provider, model and api_key keys, where api_key supports environment interpolation in the form ${OP...} (the README excerpt is truncated at that point, so the full interpolation syntax is not visible here). The CLI is described as having 25 or more commands including serve, mcp, query, import, export, lint and connect. If you want to embed the engine rather than run the server, the README points to a Go library at pkg/kiwi.

The X-Actor header is trusted input, and that has consequences

This is the sharpest limitation in the supplied material, and the README is unusually direct about it. X-Actor is described as trusted input that only carries the identity you can vouch for. On REST, the scoped-token and OIDC middleware overwrite the header with the authenticated identity, so a client cannot forge it. WebDAV is the problem case: its auth is a single shared API key that carries no identity, so KiwiFS takes X-Actor at face value, and anyone holding that key can attribute a write to any actor. Since the actor becomes the git commit author, that means a forged audit trail, not just a cosmetic mislabel. The README's own mitigation is to terminate authentication at a gateway that sets X-Actor itself and strips any client-supplied value before forwarding. If you are considering WebDAV as your primary agent interface, that gateway is not optional. The same section also notes that write identity is currently implemented for REST and WebDAV, with the web UI using REST, so other protocols do not carry actor identity at all. That asymmetry is worth checking against whichever protocol you actually plan to expose.

Where a file-first design stops being the right tool

A markdown-on-disk filesystem makes a specific bet: that your content fits in files, and that a git commit per write is an acceptable cost. If your agents produce high-frequency small writes, every one of them is a commit, and the README does not describe a batching or squashing mechanism. The same applies to concurrent writers: git handles this, but the README does not document conflict behaviour for simultaneous edits to the same path, so that is something to test rather than assume. The vector side is pluggable, which is good for portability and bad for predictability, since search quality then depends on an external service you configure under [search.vector.embedder]; choosing a remote provider means your search index depends on network availability and on a provider's key and quota. The README's own framing of the alternatives is also worth reading critically: the case against databases and SaaS is real for this audience, but a team whose content is genuinely relational, or whose agents need transactional multi-record updates, is not the target user. KiwiFS is a document store with a filesystem interface, and DQL over frontmatter is not a substitute for a query planner over normalized tables.

Obsidian, the closest comparison, and where the two diverge

The repository topics list obsidian alongside wiki, knowledge-base and knowledge-graph, and 19 importers are listed including Obsidian. The overlap is real: wiki links in [[page]] syntax, backlinks, a knowledge graph view, and local markdown files. The difference in approach is the server. Obsidian is a desktop application that opens a vault directory; there is no daemon, no REST API, no MCP endpoint, and no per-write git commit as a first-class feature. KiwiFS is a Go binary that serves the same kind of content over REST, MCP, NFS, S3, WebDAV and FUSE, with the web UI embedded via go:embed. If your only consumer is a human with a laptop, Obsidian is the simpler tool and KiwiFS adds a server you have to run and secure. If your consumers include agents that need to write, query and be audited, the protocol surface is the whole point, and a desktop vault does not offer it. The Obsidian importer suggests the intended migration path runs from the desktop tool toward the server, not the other way round.

Licence, release cadence and what to verify before adopting

The repository metadata reports the licence as NOASSERTION, while the README badge says BSL 1.1. Those two signals disagree, and the discrepancy is the first thing to resolve. BSL 1.1 is a source-available licence with terms that typically restrict production or competing use for a defined period before converting to an open source licence; the specific parameters live in the LICENSE file, not in a badge. If your organization has a policy that only permits OSI-approved licences, read the actual file before you install anything, and treat the badge as a pointer rather than a fact. I am not giving legal advice here; the point is that the machine-readable metadata and the human-readable badge do not match, so one of them is wrong. On maintenance, the release history shows a fast cadence: v0.19.60, v0.19.61 and v0.19.62 all landed within three days in August 2026, with the most recent push timestamp matching the newest release. Frequent patch releases on a 0.19.x line suggest active development, and they also mean you should pin a version rather than track main. The upgrade cost is partly mitigated by the file-first design, since a rebuildable index means a bad upgrade should be recoverable by re-indexing the markdown, but the README does not document an index migration or rollback procedure, so that assumption needs testing on a copy of your data.

Editorial conclusion

Adopt KiwiFS if your agents already write markdown and you want git history, full-text search and MCP access without standing up a separate database or SaaS. Do not adopt it if you need a licence that is unambiguously open source, or if you plan to expose WebDAV directly to untrusted clients, because that path accepts X-Actor at face value. Before committing, verify the actual licence text in the repository rather than the badge, confirm which of the six protocols your clients will use, and test that kiwifs init --template knowledge --root ./knowledge produces a layout your existing files can be migrated into.

Official sources

1. Issues
2. kiwifs/kiwifs on GitHub
3. Project website
4. README
5. Releases