Agent playbook

Every kiwifs init template except blank ships a few agent-facing files beside your pages. An agent loads them with one call to kiwi_context and knows the layout, the frontmatter conventions, and the house rules before it writes anything.

The files

File	Purpose	Who edits it
`SCHEMA.md`	Folder layout, frontmatter fields, naming conventions	You, per knowledge base
`.kiwi/playbook.md`	Step-by-step tool sequences for common operations	You; the template provides a starting point
`.kiwi/rules.md`	Always and never rules for every connected agent	You, with the CLI or the API
`index.md`	Entry page that links to every section	Agents keep it current
`log.md`	Append-only record of changes (`memory` template)	Agents append to it

kiwifs init copies the template’s playbook to .kiwi/playbook.md, which is the copy kiwi_context serves. .kiwi/playbook.md and .kiwi/rules.md are the only .kiwi/ files reachable through the file API.

Load context in one call

MCP
REST

Call kiwi_context with no arguments. It returns the schema, playbook, index, and rules as one document. Agents should call it first when they connect.The schema alone is also available as the read-only resource kiwi://schema.

Terminal

curl 'http://localhost:3333/api/kiwi/context'

{
  "schema": "# Schema\n...",
  "playbook": "# Playbook\n...",
  "index": "# Index\n...",
  "rules": "# Agent Rules\n..."
}

A missing file comes back as an empty string.

Typical operations

Each template’s playbook spells out its own sequences. These are the common shapes.

Ingest: add a new source

kiwi_context
kiwi_search("authentication")                 # update instead of duplicating
kiwi_write("pages/auth.md", content, provenance="ingest:rfc-6749")
kiwi_read("index.md")
kiwi_write("index.md", updated_index, if_match=etag)
kiwi_append("log.md", "- added pages/auth.md")

Query: answer a question

kiwi_brief("how does auth work?")             # one token-budgeted pack
kiwi_read("pages/auth.md")                    # if you need the whole page

Remember: record an observation

kiwi_remember(content, scope="user:alice")   # writes episodes/<date>/<id>.md

Consolidate: fold episodes into durable pages

kiwi_memory_report
kiwi_read("episodes/2026-05-21/run-7f3a.md")
kiwi_write("pages/topic.md", merged_content)  # with merged-from in frontmatter

Restructure: move or merge pages

kiwi_refactor_plan(manifest)                  # preview and digest, nothing written
kiwi_refactor_apply(manifest, digest)         # one commit, links kept intact

Audit: check health

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

Rules

.kiwi/rules.md holds rules that apply to every agent, such as “search before creating a page” or “never store secrets”. kiwi_context includes it, so MCP agents get it automatically. For agents that read rules from their own config, export it.

Terminal

kiwifs rules                                          # print the rules
kiwifs rules edit                                     # open in $EDITOR
kiwifs rules export --format claude                   # print in a harness format
kiwifs rules sync --format cursor --output .cursor/rules/kiwi.md
kiwifs rules sync --format skill                      # writes .cursor/skills/team-wiki/SKILL.md

Formats are cursor, claude, agents, openclaw, and skill. sync needs --output for every format except skill. Add --remote http://host:3333 to read the rules from a running server instead of the local file. Over REST, GET /api/kiwi/rules reads the rules (add format= for an export) and PUT /api/kiwi/rules replaces them. See Utilities API.

Provenance on writes

Record which run produced a page. KiwiFS appends an entry to its derived-from frontmatter.

curl -X PUT 'http://localhost:3333/api/kiwi/file?path=pages/auth.md' \
  -H 'X-Actor: agent:researcher' \
  -H 'X-Provenance: run:run-249' \
  --data-binary @auth.md

kiwi_write("pages/auth.md", content, actor="agent:researcher", provenance="run:run-249")

MCP

Client setup and the full tool reference.

Episodic memory

Episodes, consolidation, and coverage reports.

Schemas

Validate frontmatter on every write.

Templates

What each kiwifs init template ships.

Getting Started

Core Concepts

Widgets

Guides

Data Import

Data Export

Deployment

The files

Load context in one call

Typical operations

Rules

Provenance on writes

MCP

Episodic memory

Schemas

Templates

​The files

​Load context in one call

​Typical operations

​Rules

​Provenance on writes

​Related

MCP

Episodic memory

Schemas

Templates

The files

Load context in one call

Typical operations

Rules

Provenance on writes

Related