KiwiFS

Markdown filesystem for agents and teams.

Searchable. Structured. Versioned. One binary, zero config.

Docs · API · Storybook · Examples · FAQ · Roadmap · Architecture · Contributing

curl -fsSL https://raw.githubusercontent.com/kiwifs/kiwifs/main/install.sh | sh
kiwifs init --root ./knowledge && kiwifs serve --root ./knowledge
# Open http://localhost:3333

Or with Docker:

docker run -p 3333:3333 -v ./knowledge:/data ameliaanhlam/kiwifs

The problem

Markdown is the lingua franca of agents and developers, but raw .md files are just files. No search, no versioning, no structure. Current solutions make you choose: databases agents can't read, read-only retrieval layers agents can't write to, ephemeral sandboxes that vanish, or proprietary SaaS you can't self-host.

KiwiFS makes markdown files writable, searchable, queryable, versioned, and human-readable. Files are the source of truth. Everything else is a derivative index you can rebuild.

AGENT                              HUMAN
cat /kiwi/pages/auth.md            Web UI (wiki links, graph view,
grep -r "timeout" /kiwi/             block editor, dark mode)
echo "# Report" > /kiwi/r.md      Cmd+K search, backlinks, TOC

       |                                |
     Markdown files on disk (single source of truth)
       |                |              |
    Git versioning   FTS5 + vector   SSE events
    (audit trail)    (search index)  (live updates)

Features

See all features and configuration

Quickstart

# Install (macOS / Linux)
brew install kiwifs/tap/kiwifs
# or: curl -fsSL https://raw.githubusercontent.com/kiwifs/kiwifs/main/install.sh | sh
# or: go install github.com/kiwifs/kiwifs@latest

# Initialize
kiwifs init --template knowledge --root ./knowledge

# Serve
kiwifs serve --root ./knowledge
# REST API on :3333, web UI at http://localhost:3333

# Write from an agent
curl -X PUT 'localhost:3333/api/kiwi/file?path=pages/auth.md' \
  -H "X-Actor: my-agent" \
  -d "# Authentication\n\nOAuth2 + JWT..."

Write identity

Writes take the actor from the X-Actor request header and use it as the git commit author. Currently implemented for REST and WebDAV; the web UI uses REST. The header is normalized before it reaches git: control characters are stripped and the value is capped at 256 characters.

When the header is empty or missing, the fallback depends on the protocol:

X-Actor is trusted input, so it 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 auth is a single shared API key that carries no identity, so KiwiFS takes X-Actor at face value — anyone holding that key can attribute a write to any actor. Terminate authentication at a gateway that sets X-Actor itself and strips any client-supplied value before forwarding.

Vector embedder options

Semantic search needs an embedder and a vector store. Configure both under [search.vector] in .kiwi/config.toml:

[search.vector]
enabled = true

[search.vector.embedder]
provider = "openai"       # openai | ollama | cohere | onnx | http | ...
model = "text-embedding-3-small"
api_key = "${OPENAI_API_KEY}"

[search.vector.store]
provider = "sqlite-vec"

Offline ONNX embedder

For zero-dependency semantic search, use a local ONNX sentence-transformer model. Download artifacts, build with the onnx tag, and point config at the files:

kiwifs model download all-minilm-l6-v2
go build -tags onnx -o kiwifs .

[search.vector.embedder]
type = "onnx"       # provider = "onnx" also works
model_path = "~/.kiwi/models/all-MiniLM-L6-v2/onnx/model.onnx"
dimensions = 384
# tokenizer_path optional — auto-discovered from parent dir after kiwifs model download

For Korean/Japanese/Chinese collections, prefer kiwifs model download multilingual-e5-small and set query_prefix = "query: " plus passage_prefix = "passage: ". See docs/EXAMPLES.md for full ONNX setup.

Connect your AI tools

Local (Claude Desktop / Cursor / any MCP client):

{
  "mcpServers": {
    "kiwifs": {
      "command": "kiwifs",
      "args": ["mcp", "--root", "/path/to/knowledge"]
    }
  }
}

Cloud (KiwiFS Cloud workspace):

{
  "mcpServers": {
    "kiwi": {
      "url": "https://api.kiwifs.com/api/workspaces/my-workspace/mcp",
      "headers": { "Authorization": "Bearer ${env:KIWI_API_KEY}" }
    }
  }
}

Or auto-configure all detected clients with one command:

kiwifs connect my-workspace --write auto

How it compares

Who this is for

AI agent builders — Your agents write markdown via MCP, REST, or cat. Humans browse the same files in a web UI with wiki links and graph view. Context compounds across sessions instead of vanishing.

Teams replacing Confluence / Notion — Markdown files on disk, wiki links, graph view, Notion-like editor. git clone your entire wiki. Self-hosted. No vendor lock-in.

Compliance-heavy industries — Every change is a git commit with SHA-1 hash chain. Immutable audit trail. git blame for per-line attribution.

DevOps / platform teams — Runbooks that agents update after every incident. Humans review in the UI. No more docs that rot.

Architecture

┌──────────────────────────────────────────────────────────┐
│  KiwiFS                                    single Go binary
│                                                          │
│  ┌────────────────────────────────────────────────────┐  │
│  │  Web UI (embedded via go:embed)                    │  │
│  │  shadcn/ui · CodeMirror · react-markdown · Sigma.js│  │
│  └────────────────────┬───────────────────────────────┘  │
│                       │                                  │
│  ┌────────────────────▼───────────────────────────────┐  │
│  │  Access: REST :3333 · NFS :2049 · S3 :3334 · WebDAV│  │
│  └────────────────────┬───────────────────────────────┘  │
│                       │                                  │
│  ┌────────────────────▼───────────────────────────────┐  │
│  │  Core                                              │  │
│  │  Storage · Git versioning · FTS5 + Vector search   │  │
│  │  Watcher (fsnotify) · SSE events · Schema/lint     │  │
│  └────────────────────┬───────────────────────────────┘  │
│                       │                                  │
│  ┌────────────────────▼───────────────────────────────┐  │
│  │  Filesystem: local · NFS · EFS · JuiceFS · FUSE-S3 │  │
│  └────────────────────────────────────────────────────┘  │
└──────────────────────────────────────────────────────────┘

Community Integrations

Built something on KiwiFS? Open a discussion and we'll list it here.

Inspired by

• PocketBase — single Go binary, zero config, just works. KiwiFS brings the same philosophy to markdown infrastructure.
• Obsidian — files are the database. Wiki links. Graph view. KiwiFS is Obsidian for the web, plus agents and an API.
• Karpathy's LLM Wiki — raw sources in, compiled wiki out, agent maintains it. KiwiFS is the production runtime for this pattern.
• Notion / Confluence — great UIs, but your content is locked in their database and agents can't use them. KiwiFS gives you the editing experience without the lock-in.

License

Business Source License 1.1 — free to use, self-host, and modify. The only restriction: you can't offer KiwiFS as a commercial hosted service. Each release converts to Apache 2.0 after 4 years.

If you want to offer KiwiFS as a managed service or need a commercial license, get in touch.

"KiwiFS" and the KiwiFS logo are trademarks of the KiwiFS Authors. See LICENSE for trademark usage guidelines.

Star History

Contributors

Thanks to everyone who has contributed to KiwiFS.

Want to help? See CONTRIBUTING.md.