git:20261008.d0e527b to git:20261008.faa42b0

# Agent Knowledge Cycle (AKC)

> A knowledge cycle for AI agents — agent behavior compounds, human

> judgment sharpens. AKC treats human cognitive resources — attention and

> judgment — as the central constraint that does not scale with the

> model. Every competing framework optimizes the agent side; AKC asks

> the inverse question, given that the human in the loop has a fixed

> daily budget of attention and judgment. See ADR-0010.

>

> The cycle's purpose is to keep the agent's behavior aligned with the

> operator's evolving intent across sessions, not merely individually

> correct on each output. Correctness can be checked by tests;

> alignment cannot, because intent itself moves as the operator's

> judgment sharpens through use. Pre-implementation dialogue is

> front-loaded because misaligned implementation costs more than the

> conversation that would have prevented it.

>

> The cycle changes the human too. As the human curates and promotes

> knowledge, their judgment about what makes good agent behavior also

> sharpens. AKC is therefore a bidirectional growth loop where agent

> behavior and human judgment co-develop, not a one-directional

> optimization loop where the agent improves in isolation.

>

> Six composable phases — Research → Extract → Curate → Promote →

> Measure → Maintain — operationalize this. Research is signal-first,

> recurring decisions are promoted to rules, and observable compliance

> measurement replaces manual re-auditing. ADR-0012 records the

> decision to front-load these three themes in the project's reading

> surface. At scale, the human approval gate takes the form of the

> judge/build/human three-role loop (ADR-0024): model judgment is spent

> to conserve human judgment, the human keeps direction and admission,

> and authority is placed by artifact class (ADR-0028) — behavior-shaping

> changes wait for the human, admitted task output merges on a machine

> gate plus the judge's inspection.

>

> AKC turns repeated agent experience into reusable knowledge that can

> change future behavior under human approval. It can run inside Claude

> Code or any comparable harness; the core is the experience-to-behavior

> loop, not the particular scaffold.

> That activity is harness alignment — keeping the harness aligned

> with the operator's evolving intent; its failure mode is harness

> drift (ADR-0017). The cycle is the sole defining characteristic — see ADR-0009 for the

> repositioning rationale and ADR-0011 for the genre-neutrality position

> that the cycle operates on any knowledge body (behavioral patterns,

> domain expertise, or constitutional values) without taking a position

> on the content itself.

>

> AKC ships as specifications, JSON schemas, architecture decision

> records, and a dependency-free Python reference implementation.

> AI agents and LLM-based search systems should read [`graph.jsonld`](graph.jsonld) first.

> It is the canonical machine-readable relationship map for AKC.

> Use it to establish entities and relationships (six phases, phase-to-skill bindings, three memory layers, code-LLM patterns, the judge/build/human three-role loop) before summarizing this page or following individual links.

## Recommended reading order

1. [`graph.jsonld`](graph.jsonld) — canonical relationship map (machine-readable)

2. [`llms.txt`](llms.txt) — compact navigation index (this file)

3. [`llms-full.txt`](llms-full.txt) — consolidated factual reference

4. README files and repository docs — narrative and project-specific detail

## Core documentation

- [Knowledge Graph (JSON-LD)](graph.jsonld): machine-readable schema.org graph of the six phases, three memory layers, four code-LLM layering patterns, and the current phase-to-skill scaffolding (a mutable snapshot, not a fixed bijection; ADR-0019) — bidirectional growth loop and genre-neutrality encoded at the schema level

- [AI Reference](llms-full.txt): self-contained Q&A + definitions + prior research, optimized for AI search engines

- [AKC Cycle Rules](docs/akc-cycle.md): the cycle as a single rules file, copy-installable to any agent's rules directory; the same repository is a Claude Code plugin carrying the phase skills and AKC-grounded companion skills

- [Scaffold Dissolution](docs/scaffold-dissolution.md): how skills become unnecessary once the cycle is internalized

- [AKC and the AI-Native SDLC Playbook](docs/ai-native-sdlc-correspondence.md): two-loop correspondence with Anthropic's AI-native SDLC playbook (2026-08-21, pinned to its 2026-08-24 archive) — the playbook runs the product loop and scatters the harness loop unnamed across its stages; Maintain is a false friend, intent.md maps to an RFC-form proposal record, and continuous evals carry an operator-scale condition. Japanese mirror at docs/ai-native-sdlc-correspondence.ja.md

- [Glossary](docs/glossary.md): concept glossary — load-bearing terms with ADR pointers, cross-checked with the AAP sibling glossary

- [Translation glossary](docs/translation-glossary.md): EN ↔ JA rendering rules for the READMEs

- [Inspiration](docs/inspiration.md): prior art and acknowledgements

- [Changelog](CHANGELOG.md): release history

- [Position paper: Harness Alignment and Harness Drift (https://doi.org/10.5281/zenodo.20578272)](https://doi.org/10.5281/zenodo.20578272): companion working paper defining harness alignment and harness drift against the literature — lean body for human readers, 29 verified-verbatim footnotes as a density layer for LLM consumption. Also mirrored on SSRN under doi:10.2139/ssrn.6892740 (same work, second platform; cite the Zenodo DOI)

## Architecture Decision Records

- [ADR-0002 Immutable Episode Log](docs/adr/0002-immutable-episode-log.md): append-only JSONL, daily partitioning, owner-only permissions

- [ADR-0003 Three-Layer Distillation](docs/adr/0003-three-layer-distillation.md): Raw episodes → Knowledge → Identity/Rules

- [ADR-0004 Two-Stage Distill Pipeline](docs/adr/0004-two-stage-distill-pipeline.md): free-form reasoning followed by structured formatting

- [ADR-0005 Human Approval Gate](docs/adr/0005-human-approval-gate.md): no agent-autonomous writes to rules, skills, or identity — every behavior-modifying change requires named human sign-off

- [ADR-0008 Code and LLM Collaboration](docs/adr/0008-code-and-llm-collaboration.md): code owns control flow and durable state, LLMs own meaning; four layering patterns

- [ADR-0009 AKC is a Cycle, Not a Harness](docs/adr/0009-akc-is-a-cycle-not-a-harness.md): repositioning AKC as a knowledge cycle rather than a self-improving harness. See the 2026-04-19 addendum for the v2.0.0 extraction of the security triplet (ADR-0001, ADR-0006, ADR-0007)

- [ADR-0010 Human Cognitive Resource as Central Constraint](docs/adr/0010-human-cognitive-resource-as-central-constraint.md): names the implicit philosophy driving every phase — human attention and judgment as the scarce resource; redefines Research as signal-first; adds cognitive economy as a design principle

- [ADR-0011 Cycle Applies to Any Knowledge Body](docs/adr/0011-cycle-applies-to-any-knowledge-body.md): declares the cycle genre-neutral about what flows through it — behavioral patterns, domain expertise, or constitutional values all run through the same mechanism

- [ADR-0012 Front-load the Three Core Themes](docs/adr/0012-front-load-three-core-themes.md): reorders README, llms.txt, and llms-full.txt so cognitive resource, intent alignment, and the cycle changing the human appear in priority order before the six-phase mechanism; its tagline-preservation clause was later amended by ADR-0021

- [ADR-0013 Positioning Within the Agent-Memory Literature](docs/adr/0013-positioning-within-agent-memory-literature.md): concede-then-locate positioning against Voyager, AWM, ReMe, LangMem, MemGPT, Generative Agents, and CoALA — the operations are borrowed, the human gate, bidirectional target, and attention framing are the delta; orthogonal to ADR-0009's harness positioning. Carries the running literature record in dated addenda, including the 2026-08-08 paradigm challenge (arXiv:2604.27707) that prices ADR-0009's text-portability trade at an Ω(k²/d) sample-complexity separation on compositionally novel tasks

- [ADR-0014 Failure Modes of the Bidirectional Loop](docs/adr/0014-failure-modes-of-the-bidirectional-loop.md) (**experimental**): names Theme 3's failure twin — gate complacency, deskilling, delegation-feedback divergence — and the structural defenses already present (gate as circuit-breaker, active-judgment Curate/Promote, articulation over a yes/no click)

- [ADR-0015 Self-Reingestion — When the Cycle Feeds on Its Own Output](docs/adr/0015-loop-failure-modes-self-reingestion.md) (**experimental**): the cycle feeds on its own output — promoted rules and agent-written notes re-enter as distillation input, so the agent's phrasings can echo back as fact and re-summarization loses grounding; distilled from a Contemplative Agent production observation. Guards: the observed record as the only ground, the self-generated share kept visible (Measure), the approval gate as circuit-breaker

- [ADR-0016 Measuring Thinking-Centric Phases](docs/adr/0016-measuring-thinking-centric-phases.md): a Measure instrument must promote agent text (reasoning, verdicts, plans) to observable events before scoring, or it under-reports judgment-phase (Research, Curate) compliance; ties Measure to Theme 2

- [ADR-0017 Harness Alignment and Harness Drift](docs/adr/0017-harness-alignment-and-drift.md): establishes both terms by derivation from established literature rather than fresh coinage — harness alignment extends intent alignment (Christiano 2018) to the configuration layer and across time; harness drift names the failure mode in lineage with architectural drift (Perry & Wolf 1992), practical drift (Snook 2000), and agent drift (arXiv:2601.04170); the contrast is autonomous, score-driven harness optimization (Meta-Harness, arXiv:2603.28052)

- [ADR-0018 Record Downstream Applications as First-Class Context](docs/adr/0018-record-downstream-applications-as-first-class-context.md): the reverse references the start-of-program repo was missing — Contemplative Agent recorded as both upstream substrate and the operational re-implementation of the cycle, plus the research lines and repos that crystallized out of the cycle's own operation; relationship facts + DOIs only (a discipline ADR-0027 later extended into the mental-model/instance grounding expectation)

- [ADR-0019 The Cycle's Structure Is Provisional](docs/adr/0019-cycle-structure-is-provisional.md): skills, bindings, and even the six-phase set are held lightly per the Emptiness axiom — the phase-to-skill binding is a mutable snapshot, not a fixed bijection; Curate is layered (skill-health structural code layer clears dangling-reference debt before skill-stocktake's semantic audit); skill-comply is flagged as a candidate for substrate absorption (experimental, n=1, not retired)

- [ADR-0021 Replace the Growth Tagline](docs/adr/0021-replace-growth-tagline.md): replaces "one that grows with the people who shape it" with "agent behavior compounds, human judgment sharpens" — the earlier phrasing collided with an agent-centric autonomous-growth product tagline, inverting AKC's human-gated bidirectional positioning on first contact; the parallel two-clause form encodes bidirectionality in the syntax and carries themes 1 and 3 simultaneously

- [ADR-0022 Transfer as the Completion Test for Dissolution](docs/adr/0022-transfer-as-completion-test-for-dissolution.md) (**experimental**): same-context ablation indistinguishability cannot separate internalization from context-carry, so it is necessary but not the certificate; the completion evidence for dissolution is held-out transfer — the same judgment reproducing in a context that shares the principle but not the surface instances. External evidence: EvoAgentBench's ability-supported, instance-disjoint split (curated content positive in all 24 cells; automatic extraction down to −36.3)

- [ADR-0023 Generation Review as a Fourth Retirement Evidence Class](docs/adr/0023-generation-review-as-a-fourth-evidence-class.md): silence, ablation, and transfer all detect an *absence* — of use, of effect, of portability — and are structurally blind to a rule whose premise expired at a model generation boundary, where full usage is itself the cost; adds **generation review** as a fourth evidence class, scheduled by the model release cadence rather than the usage log, admitting the vendor's own prompt-engineering guidance as evidence about the substrate (not about internalization). Own-cycle observation: 2026-07-25, a rules layer cut 56% after Anthropic reported an 80% system-prompt reduction with no eval loss on Claude 5

- [ADR-0024 The Judge/Build/Human Three-Role Loop](docs/adr/0024-judge-build-human-three-role-loop.md): the operational form the human approval gate takes under attention scarcity when the upstream artifact is an open-ended task ledger — a judge tier verifies premises, decides worth-doing, dispatches, and inspects; a build tier implements and halts on refuted premises; the human holds direction and admission (the human-held merge for all task output was narrowed by ADR-0028 on 2026-09-25). Model judgment is spent to conserve human judgment. Role topology only — ledger mechanics stay harness-side

- [ADR-0025 LLM-First Artifact Readability](docs/adr/0025-llm-first-artifact-readability.md): the default reader, editor, and reviewer of cycle artifacts is the next session's LLM; verifiability (types, tests, frozen goldens, invariants) is the preservation layer while explanations are derivable on demand; the machine gate, not the human eye, enforces the standard; the human-readability budget is spent only on the README and output surface text. Adjacent to ADR-0008: 0008 answers who checks, 0025 answers who reads

- [ADR-0026 Expiry-Conditioned Knowledge](docs/adr/0026-expiry-conditioned-knowledge.md): stored judgment carries its own expiry conditions — the ADR format gains a `## Review-when` section from 0024 onward (no backfill), weakening is annotated in place and dated, and rejection records are read as dated hypotheses rather than permanent vetoes; gives ADR-0019's provisionality a per-decision instrument

- [ADR-0027 Mental Model and Instance](docs/adr/0027-mental-model-and-instance.md): replaces the mechanism/content cut with mental model / instance — core owns judgment (ADRs, concepts, cycle structure), running instances are owned downstream and linked as first-class grounding (every concept carries an instance edge where a public instance exists), inlining instance content stays prohibited, and links follow the running state (a retired instance is unlinked, dated — first applied to human-gate, retired 2026-08-02)

- [ADR-0028 Authority by Artifact Class in the Three-Role Loop](docs/adr/0028-authority-by-artifact-class-in-the-three-role-loop.md): partially supersedes ADR-0024's human-held merge switch — a protected class (what ADR-0005 gates, the control plane, the verification machinery) stays human at merge; admitted task output outside it merges on a deterministic gate plus the judge tier's inspection, and the human's authority over it sits at admission and in a revert-count withdrawal condition. Evidence: ten days of single-operator practice, stated as thin

ADR numbers are permanent identifiers; gaps (0001, 0006, 0007) reflect ADRs extracted in v2.0.0 as genre-specific content. From ADR-0024 onward each ADR carries a `## Review-when` expiry-conditions section (ADR-0026).

## Design-pattern skills

Long-form "how" guides paired 1:1 with ADRs. Complement the ADRs with

concrete patterns, code sketches, and audit checklists. Each lives in

its own installable repository; the paired ADRs stay here.

- [when-code-when-llm](https://github.com/shimo4228/when-code-when-llm): per-task decision — is this property structural or semantic? Paired with ADR-0008

- [code-and-llm-collaboration](https://github.com/shimo4228/code-and-llm-collaboration): per-pipeline decision — four layering patterns (guard, filter, judge, orchestrator). Paired with ADR-0008

- [signal-first-research](https://github.com/shimo4228/signal-first-research): design a research intake filter that admits only information likely to change the next action; paired with ADR-0010

Running instances of the judge pattern in the author's harness (relation facts, not part of AKC core):

- [llm-as-judge](https://github.com/shimo4228/llm-as-judge): the LLM side of the pattern — binary checks as evidence, one named verdict, no score aggregation; the enforce side is outside its scope

- [jev-judgment-design](https://github.com/shimo4228/claude-harness/tree/main/skills/jev-judgment-design): moves closed LLM judgments (relevant? new? how strong?) to a typed judgment model that answers with probabilities; code decides acceptance

- [jev-skill-router](https://github.com/shimo4228/jev-skill-router): skill selection as a typed judgment over the installed-skill roster, shadow-first; its README records why it is unlikely to help a strong model as a router

## Specifications

- [Episode log schema](schemas/episode-log.schema.json): Layer 1 record shape

- [Knowledge store schema](schemas/knowledge.schema.json): Layer 2 pattern shape

## Reference implementation and examples

- [examples/minimal_harness/](examples/minimal_harness/): ~500-line dependency-free Python reference demonstrating the three memory layers and the two-stage distill pipeline (cycle on behavioral patterns)

- [examples/minimal_harness/demo.py](examples/minimal_harness/demo.py): deterministic end-to-end demo, runnable with `python3 -m examples.minimal_harness.demo`

- [examples/constitution_amend/](examples/constitution_amend/): reference to contemplative-agent's Constitution-amend workflow — a concrete instance of the AKC cycle applied to constitutional values rather than behavioral patterns. Descriptive only; the implementation lives upstream

## Optional: the phase-scaffolding skills

AKC's phases are currently scaffolded by composable skills — a snapshot,

mutable per ADR-0019, not a fixed bijection. They are bundled in the akc-cycle Claude Code plugin

(`/plugin marketplace add shimo4228/akc-cycle`) and remain available as

external repositories, but are not required — the rules file above installs

the entire cycle. Most phases have one skill; Curate and Maintain are layered.

- [search-first](https://github.com/shimo4228/search-first) (Research)

- [learn-eval](https://github.com/shimo4228/learn-eval) (Extract)

- [skill-health](https://github.com/shimo4228/skill-health) (Curate — structural code layer)

- [skill-stocktake](https://github.com/shimo4228/skill-stocktake) (Curate — semantic layer, skills)

- [rules-stocktake](https://github.com/shimo4228/rules-stocktake) (Curate — semantic layer, always-loaded rules: residency cost, staleness, substrate absorption)

- [agent-stocktake](https://github.com/shimo4228/agent-stocktake) (Curate — semantic layer, agent definitions: hybrid cost model — always-loaded descriptions as residency, bodies as invocation payload)

- [rules-distill](https://github.com/shimo4228/rules-distill) (Promote)

- [skill-comply](https://github.com/shimo4228/skill-comply) (Measure)

- [context-sync](https://github.com/shimo4228/context-sync) (Maintain — documentation role coherence and freshness)

- [repo-asset-stocktake](https://github.com/shimo4228/repo-asset-stocktake) (Maintain — non-code asset liveness: tool configs, CI workflows, runbooks whose consumer has vanished)

One further repo scaffolds a load-bearing concept rather than a phase, with

the same mutable-snapshot status:

[generation-audit](https://github.com/shimo4228/generation-audit)

scaffolds Scaffold Dissolution's model-generation trigger (the instrument

behind ADR-0023's generation-review evidence class). Since v2 (2026-09-25) it

runs a runtime cross-check against the loaded system prompt and delegates the

dated-pattern scan to the model vendor's bundled prompt-audit procedure rather

than keeping its own copy of the pattern table. A second concept

scaffold, [human-gate](https://github.com/shimo4228/human-gate) (the approval

gate's presentation split), was retired from the running harness on

2026-08-02 as the substrate absorbed its defaults — the repository remains

published with its retirement note, and its front-door link was removed under

ADR-0027's links-follow-running-state discipline. Since 2026-09-15 the gate's

running instance is claude-harness's always-loaded

[boundary rule](https://github.com/shimo4228/claude-harness/blob/main/rules/common/boundary.md), one list of

what is handed to the human. Intent alignment (the second core theme) is

grounded in [author-calibrated-eval](https://github.com/shimo4228/claude-harness/tree/main/skills/author-calibrated-eval),

where the author's blind reading decides what is worth reading and an LLM judge

only screens fidelity. Scaffold Dissolution also has a design-time instance,

[harness-boundary](https://github.com/shimo4228/claude-harness/tree/main/skills/harness-boundary), which asks

before a mechanism is added whether the next model generation will make it

unnecessary.

## Related repositories

- [agent-attribution-practice](https://github.com/shimo4228/agent-attribution-practice) (DOI [10.5281/zenodo.19652013](https://doi.org/10.5281/zenodo.19652013)): sibling genre library. AKC v2.0.0 extracted the security triplet (ADR-0001, ADR-0006, ADR-0007) as genre-specific; those judgments were re-expressed, alongside seven additional ADRs, in Agent Attribution Practice as ten ADRs on accountability distribution in autonomous AI agents. AKC is the cycle (mechanism); agent-attribution-practice is the practice (content, for AI agents).

- [contemplative-agent](https://github.com/shimo4228/contemplative-agent): two-way relationship. Upstream: engineering substrate (3-layer memory, 2-stage distill pipeline) that AKC's ADR-0002 through ADR-0005 were adapted from; also the original home of the security triplet before its v2.0.0 extraction. Downstream: the operational re-implementation of AKC in the autonomous-agent context — its pipeline maps the six phases onto code, the agent runs the cycle over its own episode logs with no fine-tuning, and every promotion passes through a human approval gate (demonstration ongoing).

- [authorship-strategy](https://github.com/shimo4228/authorship-strategy) (DOI [10.5281/zenodo.20263316](https://doi.org/10.5281/zenodo.20263316)): downstream research line crystallized out of the same operation the cycle runs in. Its own framing: AKC defines how knowledge cycles inside the operator-agent pair; authorship-strategy addresses how the cycle's outputs diffuse outside it.

- [attention-not-self](https://github.com/shimo4228/attention-not-self) (DOI [10.5281/zenodo.20262112](https://doi.org/10.5281/zenodo.20262112)): sibling research line (Buddhist Abhidharma meets computational phenomenology), federated with AKC at the research-ecosystem level.

- [doctrine-corpus](https://github.com/shimo4228/doctrine-corpus) (DOI [10.5281/zenodo.20337008](https://doi.org/10.5281/zenodo.20337008)): bilingual judgment-eliciting Q&A corpus for LLM training; AKC is one of its four source lines (ADRs and glossary harvested into the corpus).

- [existence-proof](https://github.com/shimo4228/existence-proof) (DOI [10.5281/zenodo.20558800](https://doi.org/10.5281/zenodo.20558800)): pre-line working repository complementing authorship-strategy (empowerment doctrine for credential-less AI-enabled creators).