14. The Knowledge File Format

KaKeKiKoKu Studio is the application; Wuniq is the plain-text format it uses to store project knowledge. Files in this format use the .wuniq extension and live beside your own files. No database, no hidden store, no binary format. This chapter describes the format — enough to read any .wuniq file in a text editor, understand a diff in a pull request, or audit exactly what KaKeKiKoKu writes into your repository.

Two ground rules frame everything else:

  • Read anywhere. The files are UTF-8 text. Open them in any editor, diff them in git, grep them, archive them — they are yours.
  • Write through KaKeKiKoKu. The engine maintains the identifiers, the index, and the knowledge graph behind these files. Editing them by hand can silently break relations or duplicate identifiers. Let KaKeKiKoKu — or your AI connected to it — do the writing. If a file does get damaged, recovery is AI-guided: see Troubleshooting.

Three kinds of knowledge files

  • File sidecar: accompanies one specific file, right next to it. AuthService.cs → AuthService.cs.wuniq.
  • Folder sidecar: holds the context of a folder from inside it, named after the folder. auth/ → auth/auth.wuniq.
  • Entity: standalone knowledge with no companion file — decisions, conventions, plans. architecture.entity.wuniq.

The [_type] field inside each file is the source of truth for its kind — not the file name. Besides the knowledge files, each project has a .wuniq/ folder holding its configuration (see Configuration); knowledge never lives in there, it lives beside your files.

Anatomy of a file

A .wuniq file is a sequence of blocks. Every block starts with a [header] alone on its own line, followed by its content, followed by a blank line. This sample is legacy format 1.0, without a format marker; its product version records who wrote it:

[_version]
1.12.0

[_uuid]
3f2a9c4e-8b1d-4e7a-9c05-2d6f8e4a1b7c

[_type]
file-sidecar

[_content_hash]
9a4c1e...

[_file_size]
18244

[_file_mtime]
2026-07-02T10:41:07Z

[_modified_at]
2026-07-02T10:44:12Z

[_description]
Authentication service. Validates credentials and issues session tokens.

[_rules]
Never log raw credentials.
Session tokens expire after 20 minutes.

[_careful]
The retry logic hides a race condition if two threads refresh the same token.

[MIGRATION: Session store migration]
wuniq: 9c05e4a1-2d6f-4b7c-8e4a-3f2a9c4e8b1d[Rules]: the new session store this service depends on
Planned in two phases; phase one keeps the legacy table read-only.

[MIGRATION/Phase2]
Cutover checklist lives with the ops runbook.

The parsing rules are deliberately few:

  • A header is [name] alone on its line, preceded by a blank line. Everything after it, up to the next header, is that block's content.
  • The name tells you who owns the block. Names starting with _ come from two fixed, closed lists — not a casing pattern: private fields managed by KaKeKiKoKu ([_version], [_type], [_uuid]…) and the nine reserved sections ([_description], [_summary], [_conclusions], [_does], [_rules], [_careful], [_whyNot], [_soul], [_guide]). [AnyName] is a custom section you created, and [PARENT/Child] is a subsection — one level deep, always written right after its parent.
  • A header can carry a human-readable title after a colon inside the brackets: [MIGRATION: Session store migration]. The identifier is the part before the colon; the title is cosmetic.
  • A header can carry attributes in braces: [Owner]{required} marks a section your project requires (see Configuration).
  • A content line must not look exactly like a format header, even inside a code fence. Put that example inside a sentence or inline code. The old backslash escape is tolerated for recovery but must be rewritten before a normal save.

Sections you write

All knowledge files share the same reserved sections, each with a fixed meaning:

  • _description — what this resource is. Mandatory, 10–280 characters.
  • _summary — the big picture, for someone arriving cold.
  • _conclusions — what was learned or settled here.
  • _does — what it does; concrete behaviors and responsibilities.
  • _rules — invariants that must always hold.
  • _careful — traps, gotchas, things that break.
  • _whyNot — alternatives that were rejected, and why.
  • _soul — the human intent and reasoning behind the resource.
  • _guide — practical instructions for working with it.

Beyond those, create custom sections with one level of subsections, within the resource’s structural bounds: at most 30 top-level sections including _description, and 60 subsections in total across all parents. Blocks are bounded on purpose: every section and subsection holds up to 4,000 characters, and every folder sidecar, file sidecar, or entity holds up to 52,000 characters of prose. Prose means exactly that — what you write. Relation lines are not counted against it: they carry their own budget (next section), so connecting your knowledge never costs you writing space. And whatever happens, a knowledge file never exceeds 64,000 characters measured with normalized LF line breaks. Read deliveries remain capped separately at 60,000 characters. AI-facing read responses have a separate 30,000-character budget: when a full resource does not fit, KaKeKiKoKu returns its description and complete section index so the AI can retrieve whole sections; large folder listings are requested separately with contents. Bounded blocks are a design principle, not a technical shortage — they keep every unit of knowledge small enough to be read, reviewed, and paid for in AI tokens (see Tips & Best Practices).

Fields KaKeKiKoKu manages

The private fields at the top of every file ([_format], [_version], [_type], [_uuid]) are KaKeKiKoKu's own bookkeeping. Leave them alone — the engine rewrites them on every save:

  • _format — the physical format, currently 1.1. An absent marker means legacy 1.0.
  • _version — the KaKeKiKoKu product version that last wrote the file. It does not decide format compatibility or the transport protocol.
  • _uuid — the resource's stable identifier (more on this below).
  • _type — file-sidecar, folder-sidecar, or entity.
  • _content_hash, _file_size, _file_mtime — on file sidecars, a fingerprint of the companion file so KaKeKiKoKu can tell when the file changed after its context without re-reading everything.
  • _modified_at — when the knowledge file itself last changed.
  • _important, _pending, _draft — the flags you set from the interface, stored with the resource so they travel with it.

Relations: stable by design

Relations are the lines that begin with wuniq: at the start of a section's content:

wuniq: 9c05e4a1-2d6f-4b7c-8e4a-3f2a9c4e8b1d[Rules]: the new session store this service depends on

On disk, the target is the other resource's stable identifier — its _uuid — not its path. This is a deliberate engineering decision, and it is what makes KaKeKiKoKu knowledge robust:

  • Moves and renames never break knowledge. Rename a folder, reorganize a module — every relation pointing into it stays intact, because the identifier doesn't change.
  • Your git history stays clean. If relations stored paths, renaming one folder would force a rewrite of every file that references anything inside it — huge diffs, noisy pull requests, merge conflicts between branches. Stable identifiers avoid those path rewrites. Changes to containing knowledge can still update accepted references.

The human-readable part travels on the same line: the target section in brackets and the relation's description after the colon. So even in a raw diff you can read what the relation means; only the exact target is an identifier. To see relations fully resolved as paths, you have three views: any read through KaKeKiKoKu (your AI sees paths, never identifiers), the Web UI, and File > Export Knowledge, which produces standard Markdown with every relation resolved to a plain path.

Relations are bounded, like everything else in KaKeKiKoKu — and for the same reason. A relation's description holds up to 200 characters: it is a label, not an essay, because the knowledge itself lives in the target resource. Each resource holds up to 20 outgoing relations within their own character budget, separate from your prose. Twenty well-described links tell an AI exactly how knowledge connects; forty vague ones are noise wearing a graph costume. And when a resource becomes popular — dozens of others pointing at it — KaKeKiKoKu curates what the AI receives on each read: the most descriptive incoming relations first, plus a note of how many more exist. However connected your project gets, every read stays lean and predictable. A resource that wants a twenty-first outgoing link is the same canary as a section that wants a 5,000th character: it is covering too much, and splitting it is the better move.

One rule matters above all here, and the rest of this manual repeats it: never edit wuniq: lines by hand. Create, move, and remove relations through KaKeKiKoKu or your AI.

Accepted knowledge in format 1.1

Effective saves add [_format] with value 1.1. Relationships can carry a system-managed segment between their endpoint and their reason:

wuniq: target-uuid[Rules] {source_hash=sha256:v1:<64-hex>;target_hash=sha256:v1:<64-hex>}: Reason for the relationship

Those references let either end compare current knowledge with knowledge it accepted. They are omitted from AI knowledge renderings and Markdown exports and do not reduce your prose or relationship-description capacity. A whole-resource reference includes all its blocks; a section includes its children; a leaf includes its own prose. Titles, reasons, paths, UUIDs and manual flags do not change knowledge.

Reading or analyzing a legacy context never converts it. Missing references remain absent in its parsed model; Studio can remember a first known reference provisionally in project memory. The next effective owner save materializes what is known. Closing before that save loses provisional memory, so Studio cannot invent what changed before it observed a context. Existing valid stored references take precedence; deleting one resets only that end and can silently accept current knowledge.

A context with a newer format or hash recipe asks you to update Studio, without interpreting or modifying it. A present invalid or duplicated reference instead blocks normal saves as an integrity problem. Studio 1.18 and earlier do not understand tracked 1.1 relationships; update older installations before using them. The newer-version protection cannot change those older applications.

Restoring a backup accepts the resulting knowledge only for connections whose knowledge or address actually changed. Unrelated pending reviews remain pending. If some additional owner cannot be saved, Studio reports the incomplete maintenance; the archived backup is never rewritten.

Version control and your repository

.wuniq files are ordinary text: they diff, merge, and review like any source file, and their bounded size keeps diffs small. In a pull request, section names and descriptions make most knowledge changes readable at a glance; for relation targets, read the description beside the identifier or open the resource in KaKeKiKoKu. Teams that prefer not to version knowledge can ignore *.wuniq and the .wuniq/ folder in git — but knowledge that travels with the repository is usually the point.

KaKeKiKoKu protects unresolved merges. If a .wuniq file contains a complete Git conflict block (<<<<<<<, =======, >>>>>>> at the start of their lines), KaKeKiKoKu blocks synchronization for that project instead of parsing both alternatives as valid knowledge. The conflicted context is temporarily removed from navigation and search, and the right-hand issue panel offers a focused AI repair action. KaKeKiKoKu never chooses one branch automatically. The AI is instructed to preserve identity, relations, and non-conflicting knowledge, ask when the merge is ambiguous, and leave Git staging or commits to you. This check reads the file itself, so it also catches markers that were accidentally staged or committed.

If a merge conflicts on an accepted hash, retain either valid branch value for that endpoint. Never erase both values to resolve the conflict: an absent hash would establish a new provisional reference and could hide a pending review. Resolve knowledge and each endpoint independently.

Format stability

Format 1.1, the product version in _version, and the connection protocol are separate. Whatever happens to the format — or to KaKeKiKoKu — your knowledge remains yours: readable today in any editor, and exportable to standard Markdown with resolved relationships, straight from File > Export Knowledge.