Examples

Copy-paste recipes for agent memory, writes with provenance, DQL, restructuring, import, export, and deployment.

Short, working recipes for common KiwiFS tasks. Each one links to the page with the full reference.

Agent memory knowledge base

Start from the memory template and let agents read the playbook on connect:

Terminal

kiwifs init --template memory --root ./knowledge
kiwifs serve --root ./knowledge

knowledge

SCHEMA.md

playbook.md

index.md

log.md

pages

episodes

.kiwi

An agent calls kiwi_context first, then follows the operations in the playbook. See Agent playbook and Init templates.

Agent writes

REST: write one file with provenance

Terminal

curl -X PUT 'http://localhost:3333/api/kiwi/file?path=pages/auth.md' \
  -H 'X-Actor: my-agent' \
  -H 'X-Provenance: run:run-249' \
  --data-binary $'# Authentication\n\nOAuth2 + JWT.'

X-Provenance adds a derived-from entry to the page’s frontmatter.

REST: write several files in one commit

Terminal

curl -X POST 'http://localhost:3333/api/kiwi/bulk' \
  -H 'Content-Type: application/json' \
  -d '{
    "files": [
      {"path": "pages/auth.md", "content": "# Auth\n\nUpdated."},
      {"path": "pages/sessions.md", "content": "# Sessions\n\nNew."}
    ],
    "actor": "agent:exec_abc",
    "message": "run 249"
  }'

REST: append to a log

Terminal

curl -X POST 'http://localhost:3333/api/kiwi/file/append?path=log.md' \
  -H 'X-Actor: my-agent' \
  --data-binary $'\n- 2026-10-19: updated auth'

Filesystem mount

Terminal

echo "# Finding" > /mnt/kiwi/pages/finding-042.md

See Alternate protocols.

Find everything one run produced

Terminal

curl 'http://localhost:3333/api/kiwi/meta?where=$.derived-from[*].id=run-249'

MCP tool sequences

First connection

kiwi_context

Ingest a source

kiwi_search("authentication")
kiwi_write("pages/auth.md", content)
kiwi_read("index.md")
kiwi_write("index.md", updated)
kiwi_append("log.md", "- added auth")

Answer a question

kiwi_search("payment timeout")
kiwi_read("pages/payments.md")

Remember and consolidate

kiwi_remember(observation)            # writes episodes/{date}/{id}.md
kiwi_memory_report                    # episodes not yet merged
kiwi_write("pages/topic.md", merged_content_with_merged_from)
kiwi_forget("episodes/2026-10-19/abc.md")

See Episodic memory.

Write a widget or quiz

kiwi_widget_reference("tree")         # syntax for a widget fence
kiwi_quiz(...)                        # format a Kiwi Quiz callout
kiwi_write("lessons/heaps.md", content)
kiwi_lint("lessons/heaps.md")

See Widgets.

Restructure safely

kiwi_refactor_plan(manifest)          # preview, nothing written
kiwi_refactor_apply(manifest, digest) # one commit
kiwi_refactor_revert(commit)          # undo if needed

Some plans need a person to approve them in the web UI first. See Refactor.

Health check

kiwi_analytics
kiwi_health_check("pages/auth.md")
kiwi_lint

Query with DQL

Table

kiwifs query 'TABLE title, status FROM "pages" WHERE status = "draft" SORT priority DESC'

See DQL.

Move pages without breaking links

Write a manifest, preview it, then apply it as one commit:

restructure.yaml

moves:
  - from: notes/*-meeting.md
    to: meetings/
merges:
  - from: faq/duplicate.md
    into: faq/canonical.md
rename_tags:
  - {from: ml, to: machine-learning}
delete_empty_dirs: true

Terminal

kiwifs refactor plan restructure.yaml --root ./knowledge
kiwifs refactor apply restructure.yaml --root ./knowledge
kiwifs refactor revert <commit> --root ./knowledge   # undo

Every link to a moved page is rewritten in the style it was written in. See Refactor.

Import

PostgreSQL

kiwifs import --from postgres --dsn "postgres://user:pass@host/db" --table users --root ./knowledge

See Import overview.

Export

JSONL with content

kiwifs export --format jsonl --include-content -o knowledge.jsonl

See Document export.

Production config

.kiwi/config.toml

[server]
public_url = "https://wiki.example.com"

[auth]
type = "apikey"
api_key = "${KIWI_API_KEY}"

[search.vector]
enabled = true

[search.vector.embedder]
provider = "ollama"
model = "nomic-embed-text"

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

[backup]
remote = "[e-mail]:org/knowledge.git"
interval = "5m"

See Configuration and Authentication.

Docker

Terminal

docker run -d --restart always \
  -v /data/knowledge:/data \
  -p 3333:3333 \
  ameliaanhlam/kiwifs

The image runs kiwifs serve --root /data by default. See Docker.

Go embed

main.go

import "github.com/kiwifs/kiwifs/pkg/kiwi"

srv, err := kiwi.New("/data/knowledge", kiwi.WithSearch("sqlite"))
if err != nil {
    log.Fatal(err)
}
mux.Handle("/wiki/", http.StripPrefix("/wiki", srv.Handler()))

See Go embed.

Related

FAQ

Common questions.

MCP

Every MCP tool.