Skip to content

Project state and configuration

Kiyo stores mutable state only in your repository, and only through an authorized Init, Memory sync or repair, or requested output. Installing the plugin creates nothing. This page documents the formats. Every field is advisory Markdown, not a machine schema.

Locations

Section titled “Locations”
Item Default for a new, unconfigured project Rule for existing projects
Project context / config .kiyo/policy.md .kiyo/config.md is an accepted equivalent; create only one, never both; no automatic rename
Memory store .kiyo/memory/ Preserve the established store, including legacy .kiyo/project/memory/; never create a second store
Memory index index.md in the store Preserve an existing index name
Managed instruction block Inside the host’s existing instruction file Only on authorized request; never replaces the file

Paths inside the config resolve relative to the config file itself. For example, memory/index.md in .kiyo/policy.md means .kiyo/memory/index.md.

Configuration fields

Section titled “Configuration fields”

From framework/project-configuration.md (KIYO-CONFIG-001) and the project-context template. The specification marks no field as required and states no defaults beyond the valid “empty” values shown.

Setting Required Valid empty value Purpose Safe example
Project/component scope No none Which root or component this record describes orders-service repository root
Framework version reference No UNKNOWN Intended Kiyo release or revision and its source; installed version recorded separately, only if evidenced UNKNOWN
Canonical Memory index No none Single pointer to the Memory index memory/index.md
Setup authority/source No none The actual initialize request or accepted record; no invented approver initialize request in session
Selected profiles No NONE selected or UNKNOWN Evidence-backed technology profiles per component dotnet (src/Orders)
Profile evidence No UNKNOWN Project-relative config or source that supports the profiles global.json; src/Orders/Orders.csproj
Governance preferences No NONE selected Optional preset and refinements, with status Balanced engineering — PROPOSED
Approved policy references No none established in inspected scope Policy path, section, and scope with acceptance evidence docs/policies/ai.md §3 — accepted, record ENG-POL-12
Candidate policy references No none Unaccepted candidates labeled PROPOSED or UNVERIFIED docs/policies/draft.md — PROPOSED
Reporting language No UNKNOWN Language preference and its source; otherwise follow current instructions English
Evidence output location Optional not configured Project-relative destination; not write approval not configured
Confirmed constraints No none established in inspected scope A sourced accepted constraint —
Unknowns/limitations No none Uninspected scope and unresolved items deployment topology not inspected

Validation and precedence rules:

  • A missing config is a scoped Unknown, not a universal block. A field needed for a sensitive action must be resolved before that action.
  • A bare link or an APPROVED label is insufficient for policy authority.
  • Competing Memory locations must be resolved before any write.
  • A moved or broken reference is unresolved. Kiyo never fetches a replacement or chooses by date.
  • There is no universal file precedence. The host’s instruction hierarchy applies (KIYO-AUTH-001).
  • In a monorepo, one component’s exception does not apply to its siblings.
  • No delta means no write and no date refresh.
  • Environment variables: none are defined. Kiyo’s configuration is Markdown only, and the Test procedure forbids bulk environment reads during discovery.

Memory record envelope

Section titled “Memory record envelope”

From framework/memory-specification.md (KIYO-MEM-003):

Field Required content
id Unique stable ID within the store; new stores may use MEM-<TOPIC>-<NNNN>; collision-checked; never renumbered or reused
record_type observation, proposal, or decision
status Valid for the record type (see Status vocabulary)
statement One concise durable claim, proposal, or decision
source Source kind, repository-relative path, symbol, section, or line; UNKNOWN if unavailable
observed_date First actual observation or capture date, or UNKNOWN
last_modified When this entry’s content changed; not verification evidence
last_verified Latest verification actually performed for this claim, or UNKNOWN
verification_status VERIFIED, STALE, or UNVERIFIED
verification_scope Evidence inspected, claim checked, context, limits, uninspected areas
uncertainty Missing, conflicting, or partial evidence; NONE only with justification
repository_context Non-sensitive repository/worktree key, component, branch, working-tree condition
git_revision Actual observed revision, UNKNOWN, or NOT_APPLICABLE for confirmed non-Git

Optional fields (approval_source, approver, approval_scope, approval_date) appear only with real evidence. The approver is a non-PII role or record reference. related_ids and supersedes must refer to actual records.

Topic files

Section titled “Topic files”
Template Purpose
index.md Scoped navigation by stable ID; pointers only
project.md Purpose, boundaries, constraints, repository identity
architecture.md Observed structure, kept separate from approved intended design
conventions.md Evidenced conventions with scope and exceptions
decisions.md Proposals and traceable approved decisions, with revision history
domain.md Business concepts and accepted rules
integrations.md Integration responsibilities, contracts, unknowns; no secrets
known-issues.md Scoped evidence-backed issues, limitations, unresolved drift

Only files with real entries are created.

Managed instruction block

Section titled “Managed instruction block”

Source: framework/init-activation.md. This is a neutral rendering shape: only evidenced values are rendered, and unused lines are removed.

Managed block shape
<!-- KIYO:BEGIN project-context -->
Kiyo project guidance (advisory; respects the actual native instruction hierarchy).
Adapter revision: init-locator-1.
Last reviewed product version: UNKNOWN.
Applies within: <actual authorized project/module scope>.
Project context: <actual instruction-file-relative config path, when present>.
Project Memory: <actual instruction-file-relative canonical index path>.
Before Kiyo work, read the applicable project context and relevant Memory within
permissions, then follow the selected available skill and its packaged bootstrap.
Choose the skill for the requested task; do not initialize again for every feature.
If Kiyo is unavailable, report that limit and preserve project state; do not claim
that a Kiyo workflow ran or that Core loaded automatically.
<!-- KIYO:END project-context -->
  • init-locator-1 is the block format’s revision, not a product release or host version.
  • The rendered block must stay within 250 words.
  • After insertion the block is user-owned. Plugin update and uninstall never modify or remove it.
  • Duplicate, missing-end, or nested markers need a decision before writes.