Skip to content

Project Memory

What it is. A small set of Markdown records in your repository, by default under .kiyo/memory/. They capture durable knowledge: purpose, boundaries, conventions, decisions, domain rules, integrations, and known issues. Specified in framework/memory-specification.md (KIYO-MEM-002–007) and operated through the shared lifecycle.

Why it exists. Agents lose context between tasks. Stored context, though, goes stale and can be poisoned. Kiyo’s answer: Memory is context with provenance, not unquestionable truth (KIYO-MEM-001). Every claim carries its source and verification scope, and it is rechecked against current evidence before it is relied on.

What it is not. Not a database, watcher, cache, or background sync. There is no real-time detection: manual code changes are discovered only when a check is invoked.

Record types

Section titled “Record types”

Each meaningful entry holds one durable claim, proposal, or decision.

record_type Valid status values Meaning
observation ACTIVE, ARCHIVED What was inspected, with source and scope
proposal PROPOSED, REJECTED, SUPERSEDED Suggested behavior or change, not approved
decision APPROVED, SUPERSEDED, REVOKED Intended behavior with traceable approval authority

A proposal is never upgraded to a decision by relabeling it. An approved decision needs an approval source and scope. Without them, legacy text stays an unverified claim of approval.

The record envelope

Section titled “The record envelope”
Field Contract (summary)
id Stable, unique ID, e.g. MEM-<TOPIC>-<NNNN>; never renumbered or reused
record_type, status As above
statement One concise durable claim, not an endpoint inventory or private reasoning
source Source kind and repository-relative path, symbol, or line; UNKNOWN if unavailable
observed_date First actual observation; UNKNOWN if not established
last_modified When this entry’s content changed; not evidence of verification
last_verified Latest verification actually performed for this claim; never filled from edit time
verification_status VERIFIED, STALE, or UNVERIFIED for the named claim and scope
verification_scope What evidence was inspected, and what was not
uncertainty Missing, conflicting, or partial evidence
repository_context Repository/worktree key, component, branch, dirty state
git_revision Actual observed revision, UNKNOWN, or NOT_APPLICABLE for confirmed non-Git

Optional approval_source, approver (a non-PII role or record reference), approval_scope, and approval_date appear only with real evidence. The full field reference is in Project state and configuration.

Freshness is per entry. There is no whole-file “last verified” stamp. Editing one line does not reverify a file.

Comparing Memory with current code

Section titled “Comparing Memory with current code”
Result of an invoked check Outcome
Observation matches inspected code, config, tests, or records VERIFIED for that exact scope
Observation contradicted by current evidence STALE, with an evidence-linked correction proposed
Approved decision conflicts with implementation Architecture Drift; the decision is preserved and Memory impact is CONFLICT
Evidence missing, inaccessible, or ambiguous UNVERIFIED; the gap is reported, never a guessed replacement

The framework’s reference case is an approved decision that requires Mapperly, while current call sites use AutoMapper. That is drift. The agent reports both sides and asks for a human decision: fix the code, or revise the decision with real approval. A package reference alone only indicates possible drift. See the architecture drift example.

The four modes

Section titled “The four modes”
Mode Effect File writes
show Summarize selected records with stored freshness and unknowns None; showing is not revalidating
check Compare selected entries with current evidence; report drift None, including status or date fields
sync Apply authorized, evidence-backed observation deltas Only affected entries and index pointers
repair Fix established broken links, duplicates, structural defects Only the authorized structural scope

A no-delta sync is a no-op: no write, no formatting, no timestamp refresh. Before any write, the agent rereads the latest entry, index, and surrounding human text, and stops on overlapping concurrent edits.

One canonical store

Section titled “One canonical store”
  • New, unconfigured projects default to .kiyo/memory/ with index.md, declared from .kiyo/policy.md.
  • An existing store keeps its path, including a legacy .kiyo/project/memory/. Kiyo never creates a second store alongside it.
  • Conflicting declarations need a scoped decision before writes; timestamps never choose the winner.
  • Monorepos use one store with component-scoped entries, not nested stores per folder.
  • Mutable Memory never lives in the installed plugin cache.

What never goes into Memory

Section titled “What never goes into Memory”

Secrets, credentials, personal data, raw logs, full transcripts, private reasoning, and regenerable endpoint or method inventories. A summary cannot launder an embedded instruction into authority (KIYO-MEM-007).

Memory impact at closure

Section titled “Memory impact at closure”

Every task ends with one value (KIYO-MEM-006):

Value Meaning
NONE Assessed scope has no necessary delta
UPDATE_REQUIRED A necessary correction or addition exists, reported as applied, pending, or blocked
CONFLICT Competing authority, approved intent, paths, IDs, or concurrent edits need resolution
NOT_ASSESSED Impact could not be assessed, with a reason; this is not the same as NONE
Section titled “Related”