Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/bitwikiorg/continuity/llms.txt

Use this file to discover all available pages before exploring further.

Every state file in CONTINUITY can live at any level of your directory tree. STATE.md, TODO.md, MEMORY.md, CONTEXT.md — all of them can be placed at the root, inside a project folder, inside a subsystem folder, or deeper still. Each level captures a complete picture of the system at its own scope, and the agent reads the whole chain before acting. This page explains how the nesting model works, how scope resolution happens, and what rules prevent a child file from silently undoing a parent’s constraints.

​
The nesting model

Any file can be placed inside a project subdirectory. The result is a hierarchy where each node is a complete state description for its scope. A root STATE.md describes the whole workspace; a project-a/STATE.md narrows the focus to that project; a project-a/sub/STATE.md narrows further to a subsystem. 
/AGENTS.md  /STATE.md  /TODO.md  /MEMORY.md       # root: global state
├── /project-a/STATE.md  /project-a/TODO.md        # child: project-specific state
│   └── /project-a/sub/STATE.md                    # grandchild: subsystem state
└── /project-b/STATE.md  /project-b/MEMORY.md      # child: different project

​
Inheritance rules

RuleWhat it means
Child inheritsLoad order, authority model, and safety defaults flow down from parent to child automatically
Child refinesA child may add project-specific parameters, narrow the agent’s scope, or override index declarations
Child cannot weaken parentSafety rules and authority boundaries set by the parent are preserved — a child may never silently remove them
Conflict resolutionWhen a child and parent disagree on a constraint, the parent wins; escalate blockers to STATE.md
DiscoveryINIT.md builds the full hierarchy tree on boot and loads parent files before child files

​
Child parent declaration

A child file declares its relationship to the parent in its YAML frontmatter or a dedicated section: 
parent: ../STATE.md
refines:
  - scope: project-a only
  - adds: project-specific entries
  - overrides: index (adds project files)
This declaration is what makes the chain explicit and machine-auditable. INIT.md reads these declarations to construct the full hierarchy before any action is taken.

​
Practical nesting example

Consider a monorepo with a backend subsystem and an auth module inside it. Each level gets its own state files: 
/my-project
  AGENTS.md          ← global identity and load order
  STATE.md           ← "Current: Building auth"
  TODO.md            ← high-level tasks

  /backend
    STATE.md         ← "Current: Refactoring JWT"
    TODO.md          ← backend-specific tasks

    /auth
      STATE.md       ← "Current: Writing tests"
When an agent session opens inside /backend/auth/, it loads this chain — in order, from the outermost scope in:
1

Root AGENTS.md

Establishes identity, load order, and global safety rules for the entire workspace.
2

Root STATE.md

Provides project-wide status — in this example, “Building auth” — so the agent understands the high-level objective.
3

/backend/STATE.md

Narrows context to the subsystem — “Refactoring JWT” — which tells the agent what the immediate surrounding work is.
4

/backend/auth/STATE.md

Provides task-level precision — “Writing tests” — the nearest applicable state that governs the current action.
The agent obeys the nearest state for local detail while remaining bound by every ancestor’s constraints.

​
Scoped state resolution

Before an agent acts, it resolves the state chain that governs the work area. The resolution always runs from the outermost scope inward: 
Global state → project state → subsystem state → task state → current action
The agent does not load every file by default. It loads the smallest state chain sufficient for the action. Different work types produce different minimal chains: 
/AGENTS.md
/STATE.md
/TODO.md
/src/AGENTS.md
/src/auth/AGENTS.md
/src/auth/STATE.md
Only the files on the path from root to the target directory are loaded. Files in unrelated branches are skipped.

​
Scoped loading rule

Resolve scope before action.
Obey the nearest applicable state.
Preserve parent constraints.
Update affected state after meaningful change.
The nearest state gives local precision. The parent state provides global continuity. A child may refine scope, add detail, narrow behavior, or specialize context. A child may not silently weaken parent constraints.

​
Post-action reconciliation

After a meaningful change, the agent updates every file whose claims are no longer accurate. The scope chain determines which files are affected. 
Action changes reality.
Reality invalidates old state.
Old state is preserved when needed.
Current state is rewritten.
Indexes are reconciled.
A task completion may update TODO.md, STATE.md, SNAPSHOT.md, and completed/ across multiple scopes — root and project-level — if the change affects both. A new tool discovery may update TOOLS.md and INFRASTRUCTURE.md. A lesson learned updates LEARNINGS.md or adds an entry to memory/.
The agent does not preserve stale state out of politeness. If reality changed, state changes. This is what prevents CONTINUITY drift across long-running projects with deep nesting hierarchies.

Mesh

Beyond hierarchy: many-to-many relationships between state files and shared directories.

Runtime Contracts

Binding lifecycle and machine-readable contracts for recursive multi-agent systems.

Core Tiers

Which files to use at which tier, and when to add nesting.

Ontology

State, History, and Library classes — the taxonomy that governs nesting rules.

Build docs developers (and LLMs) love

Get started for freeTalk to us