# Canonics

*(formerly the Canon–Epoch Framework, CEF)*

*"Version the frame, not the facts: interpretive-regime versioning for long-lived AI agent memory."*

> **facts are immutable; interpretations are versioned cache; canon events are the invalidation signal; epochs are the cache key; the Canon Review is the scheduled audit of the invalidation signal itself.**

## Canonics in 60 Seconds

Agent memory fails when it retrieves true records from dead regimes. Canonics adds **repeal** to long-lived memory: facts remain immutable, interpretations are stamped with the regime that authorized them, and **canon events** mark when that authority changes. The result is not automatic drift detection. It is a governance layer for deciding which remembered judgments still have force.

![Truth survives. Authority does not. The four vigency states as a quadrant of canon distance (kappa) against chronological age.](../figures/fig2_truth_vs_authority.png)

![The axis the current stack does not see: valid time, transaction time, and regime time — canon distance κ counts declared regime changes crossed, not days elapsed.](../figures/fig1_three_timelines.png)

Every second brain tends to become a second drain: it consumes ambient maintenance and returns confident answers from a world that no longer exists. The failure is subtle because the agent sounds grounded: it is not hallucinating -- **it is citing obsolete judgment**.

Canonics, by Lucio Amorim, versions the interpretive regime under which long-lived agent memory is read. It composes established components -- event sourcing, bi-temporal modeling, context logics, belief revision -- into what is, to our knowledge after targeted prior-art review, the first framework for LLM-agent memory that operationalizes the interpretive regime itself as a versioned, human-declared object with scoped propagation and source-based re-derivation. Canonics governs **canonical vigency** — whether a derived interpretation is still *in force* under the active canon, as distinct from whether its source facts are still true.

```yaml
canon_event:
  id: C-2026-07-VA-solo
  t_effective: 2026-07-03
  t_declared: 2026-07-03
  declarer: operator@venture-a
  level: L3
  diff:
    retires:
      - "Delivery team available"
      - "Delegation is the primary scaling mechanism"
    introduces:
      - "Solo operator; capacity bounded by the operator alone"
      - "Automation and asset creation are the primary scaling mechanisms"
  blast_radius:
    domains: [venture_a]
    secondary: [personal_finance]
    assumption_categories: [delivery_capacity, pricing_model, project_selection, delegation]
```

Before Canonics, a pricing query can retrieve a March pricing model because it is semantically relevant, even though it was derived under the team-delivery epoch. With Canonics, the same understanding is retrieved with canon distance (kappa) = 1 -- a distance to declared marks, not a validity certificate -- because one declared in-scope canon event crossed its epoch of origin; RETRIEVE triggers REPROCESS from source facts under the solo-operator regime, and because pricing is critical, the new version enters as `proposed` until human adjudication.

## What Canonics Does Not Do

- Canonics does not detect regime shifts autonomously. It reduces the cost of declaring and propagating regime shifts once perceived, and structures and measures perception through the Canon Review.
- Canon distance (kappa) is a distance to *declared* marks, not a validity certificate. kappa = 0 under an inactive declaration process certifies nothing.
- Reprocessing is machine-proposed and policy-activated. Critical domains remain human-gated.
- The scope is a single operator or small high-trust team. Multi-stakeholder authority and enterprise access control are future work.
- The Markdown+Git substrate is a convenience, not the concept.
- Operational viability is a falsifiable hypothesis, not demonstrated fact.
- Canonics does not eliminate maintenance; it compresses and schedules it.
- Canonics is not a second brain and does not compete with capture tools. It governs the interpretation of what other systems capture.

## The Two-Tag Wedge (one sprint)

Adoption does not require the whole protocol. Canon events and the Canon Review are the payoff of adopting Canonics, not the precondition — the minimal slice, named the **Two-Tag Wedge**, pays for itself in a single sprint and takes two moves:

1. **Keep a current-regime block in the always-on instructions** (system prompt / `CLAUDE.md` / `AGENTS.md`) — not in retrievable storage, because retrieval-visible updates are frequently ignored by models even when plainly in context.
2. **Attach an `epoch_id` / `canon_distance` (κ) tag to every retrieved derived artifact.** Then: κ = 0 → use the artifact normally; κ > 0 → show a stale-regime banner (or trigger re-derivation) instead of presenting it as current guidance.

That's it — no graph database, no vector store migration, no benchmark required to start. A framework that offers a one-sprint wedge gets adopted; one that demands the whole protocol upfront gets admired and shelved. If you build agent tooling and want the technical name: this is **regime-aware retrieval**, minimal form.

![The one-sprint wedge: common agent stack (semantic retrieve → LLM → confident but interpretively wrong) versus the Canonics wedge (semantic retrieve → current-regime block + κ tag → LLM → regime-correct).](../figures/fig3_one_sprint_wedge.png)

See [Quickstart](docs/quickstart.md) for the full walkthrough (zero to first canon event in 15 minutes), which builds on this wedge with the complete DECLARE/RETRIEVE/REPROCESS/SCAN cycle.

## Likely Objections, Routed

| Likely objection | Short answer |
| --- | --- |
| "This is just document versioning." | Versioning preserves history; Canonics governs the *authority* of interpretation. A repealed statute is not an old draft. |
| "This is just factual staleness." | A stale fact loses truth; a non-vigent interpretation loses force. Different failure, different repair: re-derivation under the active regime, not correction by a newer fact. |
| "This depends on humans noticing drift." | Yes — by design. Canonics does not promise autonomous detection; it governs declaration, propagation, and audit once a shift is perceived, and instruments the noticing (the Canon Review). |
| "This is just prompt engineering." | A prompt changes one local instruction; a canon event changes the shared interpretive regime — one declaration, every agent, every in-scope derived understanding. |
| "This won't scale to the enterprise." | Correct, and stated in the paper (§11.5): scope is a single operator or small high-trust team. Enterprise authority models are the named research agenda. |

## Start Here

The GitHub repository is not public at the moment. The documents linked here are supplied reference materials, not a public repository installation.

- [Quickstart](docs/quickstart.md): zero to first canon event in 15 minutes.
- [Specification — Position paper (preprint) · July 2026](spec/SPEC.md): normative primitives, operations, schemas, Canon Review, and Canon Integrity.
- [Conformance](spec/conformance.md): RFC 2119 requirements for conforming deployments.
- [Reference implementation](reference-implementation/README.md): convenience substrate using Markdown+Git.

Status: **Position paper (preprint) · July 2026 + reference spec; operational-sustainability hypothesis (H-G) under longitudinal test**.

## Repository License

Code, schemas, commands, and reference-implementation materials are licensed under Apache-2.0. Documentation under `docs/` is licensed under CC BY 4.0; see [docs/LICENSE](docs/LICENSE).

## How to Cite

If you use this framework, cite the position paper:

```bibtex
@misc{amorim2026canonics,
  title        = {Canonics: Versioning the Frame, Not the Facts},
  author       = {Amorim, Lucio},
  year         = {2026},
  month        = jul,
  howpublished = {Preprint},
  note         = {Position paper (preprint), July 2026. NXLV Research},
  doi          = {10.5281/zenodo.21268307},
  url          = {https://doi.org/10.5281/zenodo.21268307}
}
```

Author ORCID: [0009-0001-3323-9152](https://orcid.org/0009-0001-3323-9152). Machine-readable citation metadata (CFF) is maintained in `CITATION.cff` at the repository root; the repository is not public at the moment.