4. Core Concepts

Before exploring the KaKeKiKoKu interface, you need to understand a few concepts. They're simple, but knowing them beforehand makes everything else click into place.

Project

A project in KaKeKiKoKu is simply a folder on your computer. It can contain code, documents, images — anything. When you open a folder as a project, KaKeKiKoKu creates a .wuniq/ subfolder inside it where it stores its configuration. It respects the files you already have: opening a project does not delete or rewrite your work. From there, KaKeKiKoKu starts working on that folder.

You can have multiple projects open at the same time. Each is independent, with its own configuration and its own knowledge.

Tip: where to place your projects. KaKeKiKoKu supports having projects scattered across your disk, but AI systems work better when they're all in the same folder. The trick is to place your KaKeKiKoKu projects inside your AI's base folder. For example, if you work with AI from C:\MyProjects, put your projects there: C:\MyProjects\MyNovel, C:\MyProjects\MyTrip, etc.

Important: Avoid placing a KaKeKiKoKu project inside another. If you do, the inner project will be treated as part of the enclosing project, which will cause confusion.

Knowledge resources

KaKeKiKoKu creates special files with the .wuniq extension that contain your project's knowledge. There are three types:

File sidecars

They accompany a specific file. If you have a file called AuthService.cs, its sidecar will be AuthService.cs.wuniq. It contains what that file is, what it does, what can go wrong, the decisions that were made when creating it.

Folder sidecars

They accompany an entire folder. If you have an auth/ folder, its sidecar will be inside it as auth/auth.wuniq. It describes the purpose of that folder, its rules, and what it contains.

Folder sidecars have the same 52,000-character prose capacity as file sidecars and entities. When the folder context and its listing fit together, KaKeKiKoKu can deliver both in one read; otherwise the AI receives the context and requests the independently budgeted listing with contents.

Entities

Standalone knowledge that doesn't belong to any specific file or folder. Architecture decisions, project rules, domain concepts, strategies. They are identified by their extension: .entity.wuniq.

Entities are ideal for capturing cross-cutting knowledge: a decision that affects the entire project, a business strategy, the style rules of your novel, a domain concept you need your AI to understand.

All three types share the same internal structure. The difference is what they accompany, not how they work.

Sections

Each knowledge resource is organized into sections. KaKeKiKoKu defines standard sections designed to capture the essence of what they document:

In addition to these, you can create custom sections with any name you want: DECISIONS, ARCHITECTURE, CHARACTERS, TIMELINE — whatever makes sense for your project.

Bounded units, not walls of text

KaKeKiKoKu stores knowledge in atomic bounded units by design, not by accident. These caps materialize the principle:

• 4,000 characters per section and per subsection.
• 52,000 characters of prose per folder sidecar, file sidecar, or standalone entity.
• 30 top-level sections per resource, including _description.
• 60 subsections in total per resource, summed across every parent section.

These caps measure your prose — the knowledge you actually write. Relations don’t count against them: connecting blocks has its own budget (see Relationships below), so a well-linked resource never runs out of writing space.

Inside these caps you compose freely: a section can hold subsections, each with its own 4,000-character budget, so a logical topic can grow without becoming one wall of text. Empty sections aren’t stored or shown — zero noise.

The reason is not technical. It is an explicit design bet: bounded blocks are what an AI handles cleanly. A wall of free-form text overflows attention, burns tokens, and dilutes signal. Atomic blocks with their own identity travel better, get reused, get linked, and let the AI reason about them one at a time.

The corollary is the useful part: if your knowledge doesn’t fit in a block, the block is hiding two blocks. The size cap becomes a canary that tells you when a section should be split, or when an entity is covering two topics that deserve separate documents. KaKeKiKoKu doesn’t bend the limit. You restructure — and the restructured version is almost always better.

The same principle shows up across the system: the Markdown editor works block by block (not over the whole document); relations point to blocks, not paragraphs or words; images with their own sidecar become first-class knowledge units, while Markdown-embedded images stay as decoration. One idea, applied everywhere.

The index: how your AI sees the project

When your AI opens a project in KaKeKiKoKu, it doesn't receive the full content of every file. It receives a structured index: a list of all files and folders with their descriptions, always up to date.

This is fundamental. Your AI knows at a glance what everything is, without spending tokens reading it all. If it needs more detail on something specific, it drills down only into that resource. And then it can request specific sections if it only needs a part.

It's the opposite of traditional context files, where it's all or nothing.

Three levels of detail

KaKeKiKoKu lets you work at three different levels, depending on how much control you want at that moment:

• Project map: a broad, read-only view of the project's knowledge structure and relationships. Use it when you want to understand the whole map, review connections, or decide what to ask the AI to change.
• Context editing: the normal KaKeKiKoKu mode. You edit descriptions, sections, subsections, relationships, flags, and sync issues as structured knowledge blocks.
• File viewing and editing: when you need to inspect the underlying project files. Source code and extracted document text (.docx, .odt, .pdf) open as read-only views; Markdown and plain text files can be edited directly when KaKeKiKoKu offers the quick editor.

These levels are complementary. The map helps you see structure, the context editor lets you shape knowledge, and the file viewer lets you verify what the project file actually contains.

What else the AI receives when opening a project

In addition to the root folder sidecar and the listing with descriptions, KaKeKiKoKu automatically sends:

• Resources marked as important: knowledge that should always be present, such as project rules or key architecture decisions. You decide what's important.
• Pending resources: resources or matters that require future attention.

At a glance, the AI gets the complete project state: structure, descriptions, important knowledge, and pending work. All up to date, all summarized. The AI is free to investigate further as needed.

Drafts

KaKeKiKoKu supports contexts in draft state. If you have knowledge in progress — ideas that aren't solidified yet, temporary notes, decisions that aren't final — you can mark it as a draft. The AI will see it labeled as such and treat it with appropriate caution.

Resource states

Sidecars and your project files can be in different states. KaKeKiKoKu detects all of them automatically during synchronization. Each type of issue has its own icon, visible in both the sync panel and the application's bottom bar:

❓ Recently undocumented (orphan)

A file or folder that exists in your project but has no sidecar. It's new or was never documented. Your AI will see it as an individual issue and prioritize documenting it.

👻 Ghost

A sidecar exists but the file it accompanied is gone. It was deleted or moved. If KaKeKiKoKu detects that the file was moved to another location (by content matching), it moves the sidecar automatically. If it can't determine this, it reports it so you can decide: delete it or convert it to a standalone entity?

▲ Drift (desynchronization)

The file has changed but its sidecar hasn't been updated. The knowledge information is outdated relative to the actual file content.

🔗 Broken references

A resource contains a reference (a link to another resource) that can't be located. The target was deleted, moved, or the reference is malformed.

🔴 Error

Something is wrong with the sidecar: it's missing the required description, has empty required fields, or there's a format problem in the configuration.

⌛ Pending documentation

This issue deserves a special explanation because it's different from the others.

Imagine opening an existing project with hundreds or thousands of files in KaKeKiKoKu for the first time. All those files are orphans — none have sidecars. If KaKeKiKoKu reported them all at once, it would overwhelm your AI with an endless list.

KaKeKiKoKu classifies them as pending documentation and presents them in batches of up to 25 items. The behavior changes with the size of the pile:

• 25 or fewer pending: your AI sees them on every sync and documents them as part of its normal work.
• More than 25 pending: KaKeKiKoKu hides the pile from your AI by default and shows an OFF / ON switch in the right-hand sync panel. You decide when to start processing. When you click ON, KaKeKiKoKu signals your AI immediately and it starts documenting the first batch of 25; when it finishes, it requests the next, and so on until the pile is empty. You can leave it active and walk away — the AI keeps working on its own. Clicking OFF stops it after the current batch completes.

This separation prevents surprises: a newly opened project with 2000 undocumented files will not cause your AI to start processing thousands of files without your permission.

For each resource in the batch, your AI decides before acting: whole build-output, dependency, or tool folders that should stay outside KaKeKiKoKu go to excluded; individual files that should remain visible but don't need documentation go to untracked; real source or documentation receives a sidecar with a description that reflects its actual purpose.

The difference from "recently undocumented" is temporal: recent items are files created or modified during this session (something new you just did). Pending items are inherited files that existed before you started using KaKeKiKoKu.

Keep in mind: at the beginning, especially if your project is very large and never worked with KaKeKiKoKu, the benefits will be few and your AI will spend a lot of time documenting. But over time, everything will get documented and managed. It's a natural transition toward a project fully managed with KaKeKiKoKu.

Synchronization (sync)

Synchronization is the heart of KaKeKiKoKu. When a sync runs, KaKeKiKoKu analyzes the entire project looking for desynchronizations: undocumented files, ghost sidecars, outdated information, broken references, validation errors, and pending documentation.

When the solution is obvious and unique, KaKeKiKoKu applies it automatically. For example:

• If you renamed a folder, KaKeKiKoKu renames its sidecar.
• If you moved a file, KaKeKiKoKu moves its sidecar (if it can identify the destination unambiguously).
• If the metadata is outdated but the content hasn't changed, it updates silently.

When the situation is ambiguous, it reports it so you (or your AI) can decide.

Automatic synchronization

KaKeKiKoKu monitors your project in real time. You don't have to launch sync manually (although you can). When your files change, KaKeKiKoKu analyses the project on its own and refreshes what you see. If real issues remain after that, it waits for a quiet minute — so a burst of edits produces one notice, not twenty — and then alerts your AI. How often it analyses is configurable (chapter 10); the minute of courtesy before bothering the AI is fixed.

Sync as a moment of reflection

There's an effect of sync that isn't obvious but is very powerful: it forces the AI to reflect at a different moment from when it was working.

When your AI is immersed in a task — writing code, drafting a chapter, fixing a bug — its attention is focused on that task. The sync arrives afterward, like a forced step back, and makes it think about things that would otherwise go unnoticed:

• Bugs or problems it noticed while working but didn't mention because they weren't its immediate goal.
• Inconsistencies between what it just did and what already existed in the project.
• Improvement ideas it spotted in passing but didn't make sense to interrupt work for.
• Intuitions: things that seemed fragile, suspicious, or "weird" without being able to explain exactly why.
• Loose ends: ideas you left half-finished, decisions pending from previous sessions.
• Collateral impact: whether the change you made affects other files or breaks some expectation documented in another sidecar.

It's like having a teammate who, after you finish your work, steps back, looks at everything with fresh eyes, and says: "hey, have you seen this?"

Relationships

Knowledge resources can be linked to each other forming a knowledge graph. An architecture decision can be linked to the files that implement it. A domain concept can be linked to the folders where it applies.

Relationships connect knowledge blocks, not just whole files. A relationship can point to a resource description, a section, or a subsection. This keeps the graph precise: the link can say "this decision affects this section" instead of only "this file mentions that file".

Relationships are directional. If A points to B, that is an outgoing relationship from A and an incoming relationship for B. The relationship is stored at its origin, so editing its meaning belongs to the origin side.

Relationships use internal identifiers (UUID), which means they are designed to not break when moving or renaming files. You can reorganize your project freely, and KaKeKiKoKu keeps the graph anchored to the right resources and blocks.

Relationships are bounded, like every other unit in KaKeKiKoKu. Each resource holds up to 12 outgoing relationships within their own character budget, and each description up to 200 characters. That is curation, not stinginess: a dozen meaningful, well-described links tell your AI exactly how knowledge connects — forty vague ones just bury the signal. Incoming relationships have no cap (you don’t control who points at you), but when your AI reads a heavily-referenced resource, KaKeKiKoKu serves the most descriptive backlinks first and notes how many more exist. The Web UI always shows them all.

In the interface, relationship text lives in the central editor, while the navigation panel shows the same graph visually with arrows. The tree stays a map; the central panel is where you read and edit the relationship itself.

Images and Markdown

KaKeKiKoKu treats images in three different ways, depending on how you want to use them:

• Markdown image: an image embedded inside the Markdown content of any sidecar with the standard syntax ![alt](path). KaKeKiKoKu renders it inline in the viewer. It does not become a KaKeKiKoKu resource by itself: no UUID, no relationships, no sync warning. Useful for screenshots, mockups, or illustrations that belong to a specific section.
• KaKeKiKoKu image: an image file accompanied by its own sidecar. Treated as a full knowledge resource: it has a description, sections, relationships, backlinks, and appears in sync like any other documented resource. When opened in the central viewer, the image is shown on top with the context card below.
• Relation to image: a wuniq: relation from any section to a KaKeKiKoKu image. The relation chip displays a thumbnail of the target image instead of the generic link icon, so you recognize it at a glance.

Markdown image syntax

The standard Markdown form is:

![alternative text](image-source)

• Alternative text is a short description of the image. It is not the file name, not the height, and not a KaKeKiKoKu label. It helps accessibility tools and appears as fallback text if the image cannot be displayed.
• Image source is where the image is loaded from: usually a relative project path, sometimes a full internet URL.

Example:

![Login screen](screenshots/login.png)

Local project images

For an image stored inside your project, use a relative path:

![Architecture diagram](architecture.png)
![Checkout screenshot](images/checkout-flow.webp)

KaKeKiKoKu resolves that path relative to the resource that contains the Markdown. If the sidecar belongs to docs/notes.md, then ![Diagram](diagram.png) points to docs/diagram.png.

KaKeKiKoKu serves local Markdown images through a controlled internal endpoint that only accepts paths inside the open project. Supported formats: PNG, JPG/JPEG, WebP, GIF. SVG is deferred for security reasons.

A local image embedded this way does not need its own sidecar or documentation. Sync respects this distinction: KaKeKiKoKu understands that the image is being used as part of the Markdown content and does not ask you to document it as a separate knowledge resource.

Internet images

To embed an image from the internet, use a normal HTTPS URL:

![Product photo](https://example.com/images/product.png)

Remote URLs are left unchanged. KaKeKiKoKu does not copy, cache, document, or rewrite them. The browser loads them directly, so the URL must be reachable and should point to an actual image file.

Do not use localhost for project images unless you are deliberately running your own local web server. For images inside the KaKeKiKoKu project, a relative path such as local_test_image.png is the intended form.

When to create a KaKeKiKoKu image sidecar

Use a Markdown image when the image only illustrates a section. Create a KaKeKiKoKu image sidecar when the image itself needs knowledge: a description, decisions, relations, backlinks, or AI-readable context of its own.

Embedding a KaKeKiKoKu image with Markdown displays the visual, but it does not automatically attach its sidecar context to that section. If the relationship matters as knowledge, add a KaKeKiKoKu relation to the image resource as well.

Context cascade

Each file has an implicit relationship with the sidecar of its containing folder. When your AI reads a file, KaKeKiKoKu tells it that parent folder context exists. The AI decides whether it needs to read it or not.

This creates a natural hierarchy: general rules go in the folder sidecar, specific details go in each file's sidecar.

Exclusions and discards

Not all files in a project need documentation. KaKeKiKoKu offers two filtering mechanisms:

• Exclusions (excluded): file or folder patterns that KaKeKiKoKu ignores completely. Typical examples: node_modules/, bin/, obj/, .git/, temporary files. KaKeKiKoKu comes with default exclusions for the most common patterns. Excluded files don't appear in the index and aren't processed during sync.
• Discards (untracked): specific files that don't need a sidecar but remain visible. For example, a decorative image or a license file. KaKeKiKoKu doesn't consider them orphans and doesn't ask for them to be documented.

Both states are valid only when no KaKeKiKoKu context exists for the resource. If a matching resource already has a sidecar, KaKeKiKoKu blocks the transition instead of hiding or deleting its knowledge. Review or preserve that knowledge and delete the context explicitly first.

Both are configured per project.

Content language

KaKeKiKoKu can store knowledge in whatever language you prefer. You can have a project with sidecars in Spanish, another in English, another in Japanese. The content language is independent of the language you use to communicate with your AI.

This is configured per project when opening it for the first time.

Backups

KaKeKiKoKu offers two ways to protect your knowledge:

• Git: .wuniq files are plain text, perfectly compatible with Git. If your project uses Git, your sidecars are versioned alongside your code. Recommended.
• Built-in backup system: KaKeKiKoKu includes an automatic backup system that creates snapshots of your project's knowledge. You can restore individual files, folders, or the entire project to a previous point. Configurable (frequency, maximum number of copies, storage path).

Both systems are compatible and can be used simultaneously.

Excluding KaKeKiKoKu files from Git

I recommend including .wuniq files in your repository — your project's knowledge is as valuable as its code, and this way anyone (or any AI) who clones the project will have the complete context.

However, you may not want to push KaKeKiKoKu files to Git. For example, if your company hasn't yet approved KaKeKiKoKu as a standard tool, or if you prefer to keep the knowledge local. In that case, add these lines to your .gitignore:

# KaKeKiKoKu knowledge files
*.wuniq
.wuniq/

The first line excludes all sidecars and entities (.wuniq and .entity.wuniq files). The second excludes the KaKeKiKoKu configuration folder. With this, Git will completely ignore everything related to KaKeKiKoKu.

Commands you should know

Although KaKeKiKoKu is mainly managed from its web interface, there are a few commands worth knowing to ask your AI in the chat:

• sync: Ask your AI to "do a sync" to analyze the project and detect issues. This is the most common thing to do after making changes.
• search: Ask your AI to "search in KaKeKiKoKu for such and such" to search within the project's knowledge. KaKeKiKoKu's search is much more effective than the AI's native searches, because it searches within structured knowledge — not just file text.
• backup: Ask your AI to "do a backup" to create a labeled backup. Useful before major changes.
• stats: Ask your AI to "show me the stats" to see the project's health status: documentation coverage, number of issues, context quality.

You don't need to memorize the exact syntax of these commands. Simply tell your AI what you need in natural language and it will know which command to use.

Two ways of working

KaKeKiKoKu operates in two complementary ways:

The AI manages KaKeKiKoKu from the inside

When your AI works on your project, it interacts with KaKeKiKoKu directly: reads sidecars before touching a file, updates knowledge after making changes, runs syncs. You don't need to intervene — the AI and KaKeKiKoKu understand each other.

You manage KaKeKiKoKu from the web interface

From the KaKeKiKoKu web interface you can browse your project's knowledge, edit sidecars, resolve issues, configure the project. When you do something in the interface that requires the AI's attention, KaKeKiKoKu prepares a request for it: in Automatic mode it sends the request through an event; in Precise mode it copies it so you can paste it yourself. Some examples:

• Talk to the AI about a section: want to discuss something with your AI about a specific part of the knowledge? Click the "Talk to AI" button on any section. KaKeKiKoKu handles telling the AI exactly which resource and which section you want to discuss. No copying and pasting, no explaining the context — the AI already has it.
• Analyze and fix with AI: click the button on an issue in the sync panel, and KaKeKiKoKu sends the request directly to your AI.
• Suggest relationships with AI: ask the AI to suggest relationships between resources from the knowledge viewer.

This second way of working is very convenient in practice: you manage knowledge visually in KaKeKiKoKu, and the AI receives what it needs to act. The interface is designed so that communicating with your AI is one click, not a paragraph.

Both ways are complementary. In a typical session, the AI works with KaKeKiKoKu from the inside while you, whenever you want, supervise or intervene from the web interface. You can also talk about KaKeKiKoKu with your AI directly in the chat — your AI knows how KaKeKiKoKu works and can help you with any question.

Looking ahead: KaKeKiKoKu has many planned features that will further raise the bar for ease and power when working with your AI. What you see today is the foundation — a solid foundation — but what's coming will make human-AI collaboration even more natural and productive.