FAQ

Frequently asked questions about KiwiFS installation, agents, search, and deployment.

What is KiwiFS?

A markdown filesystem for agents and teams — a single Go binary with a web UI, git versioning, full-text and vector search, and access via REST, MCP, NFS, S3, WebDAV, and FUSE.

How is this different from Obsidian?

Obsidian is a desktop app. KiwiFS is a server with a web UI, agent APIs, git audit trail, and server-side search over the same markdown files.

How is this different from Notion or Confluence?

Those tools store content in proprietary databases. KiwiFS stores plain markdown. cat page.md and git clone always work.

Do I need to know Git?

No. Git runs under the hood; the API and web UI hide it. Git is the audit trail, not the primary interface.

Is KiwiFS production-ready?

KiwiFS is in active development (currently v0.19). Core features are stable in internal production use. Public APIs may evolve before v1.0.

Installation

System requirements?

A single static Go binary. SQLite is embedded. The web UI is embedded via go:embed. Runs on macOS, Linux, and Docker.

How do I install?

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

What is in .kiwi/?

Derived state — not your content. Safe to delete and rebuild with kiwifs reindex.

.kiwi/
├── config.toml
├── playbook.md
├── state/search.db
├── comments/
└── templates/

Agents

How do agents write?

Three ways:

1. Filesystem — NFS or FUSE mount: cat, echo, grep
2. REST — PUT /api/kiwi/file
3. MCP — kiwifs mcp --root ~/knowledge (60+ tools)

Can agents use KiwiFS without a running server?

Yes. kiwifs mcp --root ~/knowledge runs in-process against the directory. No HTTP needed.

How do I configure Cursor or Claude Desktop?

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

See MCP.

How does provenance tracking work?

Send X-Actor and X-Provenance on writes. KiwiFS injects derived-from into frontmatter automatically.

Search

What search backends exist?

Tier	Engine
1	grep (zero deps)
2	sqlite (FTS5, BM25 — default)
3	Vector ([search.vector] — optional)

Vector search without a cloud API key?

Use Ollama as the embedder and sqlite-vec as the store for fully local semantic search.

Rebuild the index?

kiwifs reindex --root ./knowledge

Protocols

NFS vs S3 vs WebDAV vs FUSE?

Protocol	Best for
NFS	Docker / Kubernetes mounts
S3	Backup tools, pipelines
WebDAV	Desktop sync, mapped drives
FUSE	Developer workstation remote mount

See Alternate protocols.

Do all protocols share one pipeline?

Yes. Every write gets git commit, index update, and SSE broadcast regardless of entry protocol.

Data

Crash mid-write?

Atomic writes (temp → fsync → rename). Git reflog aids recovery.

Backup?

• git push to any remote
• kiwifs backup / [backup] in config
• kiwifs restore --from ... --to ...
• rsync the knowledge root

Migrate from Obsidian or Notion?

kiwifs import --from obsidian --path ~/vault --root ./knowledge
kiwifs import --from notion --api-key $KEY --database-id $ID --root ./knowledge

License

Commercial use?

BSL 1.1 — self-host and embed freely. You cannot offer KiwiFS itself as a commercial hosted service. Each release converts to Apache 2.0 after four years.

Contribute?

See CONTRIBUTING.md.