14. The Knowledge File Format

Everything KaKeKiKoKu knows about your project lives in plain-text .wuniq files stored 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: documents 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. Here is a realistic file sidecar:

[_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).
  • If a content line would itself look like a header, KaKeKiKoKu prefixes it with a backslash (\[) when saving. That is the only escaping in the whole format — no quotes, no indentation rules.

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 60,000 characters on disk. 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 ([_version], [_type], [_uuid]) are KaKeKiKoKu's own bookkeeping. Leave them alone — the engine rewrites them on every save:

  • _version — the KaKeKiKoKu version that last wrote the file. The major digit signals format compatibility.
  • _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 detect drift 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. With stable identifiers, a rename touches nothing.

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 12 outgoing relations within their own character budget, separate from your prose. Twelve 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 thirteenth 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.

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.

Format stability

The format evolves with the product; this chapter describes the current major version, and every file records the version that wrote it in _version. Whatever happens to the format — or to KaKeKiKoKu — your knowledge remains yours: readable today in any editor, and exportable at any moment to standard Markdown with everything resolved, straight from File > Export Knowledge.