> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kiwifs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

```bash Terminal theme={null}
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](https://docs.kiwifs.com/concepts/agent-playbook.md) and [Init templates](https://docs.kiwifs.com/guides/templates.md).

## Agent writes

> [accordion] REST: write one file with provenance
>
> ```bash Terminal theme={null}
> 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.

> [accordion] REST: write several files in one commit
>
> ```bash Terminal theme={null}
> 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"
>   }'
> ```

> [accordion] REST: append to a log
>
> ```bash Terminal theme={null}
> 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'
> ```

> [accordion] Filesystem mount
>
> ```bash Terminal theme={null}
> echo "# Finding" > /mnt/kiwi/pages/finding-042.md
> ```
>
> See [Alternate protocols](https://docs.kiwifs.com/guides/alternate-protocols.md).

> [accordion] Find everything one run produced
>
> ```bash Terminal theme={null}
> curl 'http://localhost:3333/api/kiwi/meta?where=$.derived-from[*].id=run-249'
> ```

## MCP tool sequences

> [accordion] First connection
>
> ```text theme={null}
> kiwi_context
> ```

> [accordion] Ingest a source
>
> ```text theme={null}
> kiwi_search("authentication")
> kiwi_write("pages/auth.md", content)
> kiwi_read("index.md")
> kiwi_write("index.md", updated)
> kiwi_append("log.md", "- added auth")
> ```

> [accordion] Answer a question
>
> ```text theme={null}
> kiwi_search("payment timeout")
> kiwi_read("pages/payments.md")
> ```

> [accordion] Remember and consolidate
>
> ```text theme={null}
> 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](https://docs.kiwifs.com/concepts/episodic-memory.md).

> [accordion] Write a widget or quiz
>
> ```text theme={null}
> 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](https://docs.kiwifs.com/concepts/widgets.md).

> [accordion] Restructure safely
>
> ```text theme={null}
> 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](https://docs.kiwifs.com/concepts/refactor.md).

> [accordion] Health check
>
> ```text theme={null}
> kiwi_analytics
> kiwi_health_check("pages/auth.md")
> kiwi_lint
> ```

## Query with DQL

```bash Table theme={null}
kiwifs query 'TABLE title, status FROM "pages" WHERE status = "draft" SORT priority DESC'
```

```bash Count by group theme={null}
kiwifs query 'COUNT FROM "pages" GROUP BY status'
```

```bash Aggregate theme={null}
kiwifs aggregate --group status --calc count,avg:priority
```

```bash REST theme={null}
curl -G 'http://localhost:3333/api/kiwi/query' \
  --data-urlencode 'q=TABLE title FROM "pages"'
```

See [DQL](https://docs.kiwifs.com/concepts/dql.md).

## Move pages without breaking links

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

```yaml restructure.yaml theme={null}
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
```

```bash Terminal theme={null}
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](https://docs.kiwifs.com/concepts/refactor.md).

## Import

```bash PostgreSQL theme={null}
kiwifs import --from postgres --dsn "postgres://user:pass@host/db" --table users --root ./knowledge
```

```bash Obsidian theme={null}
kiwifs import --from obsidian --path ~/vault --root ./knowledge
```

```bash Notion theme={null}
export NOTION_API_KEY=secret_...
kiwifs import --from notion --database-id abc123 --root ./knowledge
```

```bash CSV dry run theme={null}
kiwifs import --from csv --file data.csv --root ./knowledge --dry-run
```

See [Import overview](https://docs.kiwifs.com/import/overview.md).

## Export

```bash JSONL with content theme={null}
kiwifs export --format jsonl --include-content -o knowledge.jsonl
```

```bash With embeddings theme={null}
kiwifs export --format jsonl --include-embeddings -o vectors.jsonl
```

```bash PDF (server-side) theme={null}
curl -X POST 'http://localhost:3333/api/kiwi/export/document' \
  -H 'Content-Type: application/json' \
  -d '{"format":"pdf","path":"pages/report.md"}' -o report.pdf
```

See [Document export](https://docs.kiwifs.com/export/documents.md).

## Production config

```toml .kiwi/config.toml theme={null}
[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 = "git@github.com:org/knowledge.git"
interval = "5m"
```

See [Configuration](https://docs.kiwifs.com/configuration.md) and [Authentication](https://docs.kiwifs.com/guides/auth-tokens.md).

## Docker

```bash Terminal theme={null}
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](https://docs.kiwifs.com/deploy/docker.md).

## Go embed

```go main.go theme={null}
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](https://docs.kiwifs.com/deploy/go-embed.md).

## Related

> [card] [FAQ](https://docs.kiwifs.com/guides/faq.md)
>
> Common questions.

> [card] [MCP](https://docs.kiwifs.com/concepts/mcp.md)
>
> Every MCP tool.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.