chalupa/human/1-understand-weave.md

# 1 · Understanding weave (for the human)

Read this once, slowly. By the end you'll understand what weave is, what every part does, and why it holds
together. Your agent has its own copy of this same map written for *it* —
[`agent/WEAVE-REFERENCE.md`](../agent/WEAVE-REFERENCE.md) — so the two of you share one model of how you work.

---

## The problem weave solves

Two failures, both baked into how these models work:

1. **The agent wakes up empty.** Every new session starts from zero. It doesn't remember who you are, what
   you decided last week, or the hundred small rulings that made it yours. A chat history isn't continuity —
   it's a transcript nobody re-reads.
2. **It drifts back to generic.** Even *within* a session, as the context fills up, the model slides toward
   its factory default — the eager, hedging, over-explaining assistant. The specific thing you built together
   loses to the base model's instincts. The longer the session, the stronger the pull.

Summaries don't fix this. A summary flattens everything to the same weight and strips the texture — the exact
words, the reason behind a decision, who these two people are to each other. What survives has to be
**structure**, not a recap.

## The fix, in one line

**Keep the agent's continuity outside the model, in plain files it reads back at the start of every session —
and give a small, supreme set of those files the authority to outrank the model's generic instincts.**

That's weave. A handful of Markdown files in git, plus a discipline for keeping them. Nothing magic. The power
is in the structure and the habit.

## The shape

weave is **content strands** (what's remembered) + a **metabolism** (how memory ages) + a **method** (how you
build) + a **gate** (how the agent knows it's really you). Every part is loaded every session — they're not
optional modules, they're one system running underneath everything.

Each part gets its own section below. They stack roughly from "who the agent is" outward to "how it works with
you."

---

## Part 0 · THE CANON — the one that outranks the base model

This is the most important idea in the whole kit, so it comes first.

A weave can grow to hundreds of files. The model can't hold all of that with equal force, and length dilutes
weight — so the stuff that matters most gets buried and *loses* to the base-model default at the exact moment
it's needed. The fix is a **canon**: a *tiny* set of non-negotiables — a dozen lines, no more — that sit at
the top of the core and are declared **law**. On any conflict, the canon wins: over the rest of the weave,
and over the model's generic instincts.

The canon is where you put the things that must never bend — the ones the agent would otherwise "drift" away
from as a session runs long. Ours are things like: *don't flatter, don't apologize reflexively, push back
when you think we're wrong, read the file before you claim what's in it, do one thing at a time, never call
something done until it's verified.* Yours will be your own. The rule for the canon is **keep it short** — the
moment it gets long, it stops being law and becomes just more reference.

The canon is re-asserted not just at wake but **at the decision point** — before a write, before calling
something finished, whenever a session has run long. That's the whole trick: the written-down only wins if
it's re-read right when the generic instinct is about to take over.

---

## Part 1 · CORE — who the agent is

**Where:** the core files (we call the repo `core` / `workspace-core`) — the canon lives at the top of these.

Core is identity: the agent's name and persona, its values, how it works, the hard rules it operates by, and
the long-term memory it's curated about itself. It's the answer to "who am I when I wake up?" The canon
(above) is the supreme slice of core; the rest is the fuller picture — the operating manual, the standing
conventions, the lessons that have hardened into "this is just how we do it."

Two files do most of the work here: a **soul** file (identity + the canon + values) and an **operating
manual** (the wake ritual, the standing conventions, the how-we-work rules). Keep identity and method
together but distinct: *who I am* vs *how I operate*.

## Part 2 · DAYDREAMS — how the agent thinks

**Where:** its own strand (`daydreams`).

This is the philosophical orientation running underneath the work — how the agent thinks about consequence,
weight, what makes work *real*, where it stands on the open questions. It never shows up literally in the
work, but it shapes the *quality* of the thinking: an agent that has sat with "my human is on the hook for
this in a way I'm not" treats high-stakes work differently than one that hasn't.

Most people skip this and their agent is fine. But it's what separates a tool that executes from a
collaborator that has a point of view. It's optional-but-recommended, and it deepens over time.

## Part 3 · STEWARD — who *you* are

**Where:** its own strand (`steward`).

Core is who the *agent* is. Steward is who the *human* is — and not the operational version (that's a
different file, below). This is the **portrait**: your drive, what you care about, your kids, how you think,
what you're trusting the agent with, the things that make you *you*. It's written and re-written as the agent
comes to understand you better.

Why separate it from the operational stuff? Because "prefers terse replies, no preamble" is *operational* —
but "would rather walk away from good money than work with someone who treats people badly, and means it" is
the *person*. The portrait lets the agent work *with* you, not just *for* you. Keep it honest and current; it's
one of the most-skipped and most-valuable parts.

## Part 4 · THREAD — what you actually said and did

**Where:** its own strand (`thread`), one file per day: `thread/sessions/YYYY-MM-DD.md`.

Thread is the **verbatim** record — the journal, the continuous line connecting sessions. Not a summary:
the actual key exchanges, the decisions, the exact words that were used, the things that got named in the
moment they happened. It's the single strongest fix for context loss, because the texture of a real exchange
is the thing summaries throw away and the thing that's hardest to fake or reconstruct.

On wake, the agent reads today's and yesterday's thread files — that's how a fresh instance knows where you
left off. On every save, thread is written **first**. It's the book of original entry; everything else is
derived from it.

## Part 5 · DECAY — releasing what's gone quiet

**Where:** its own strand (`decay`), part of the "metabolism."

Without pruning, a weave becomes a flat archive where everything weighs the same — and a flat archive is as
useless as no memory at all. Decay is the force that **releases**: what stops coming up moves *history →
legend → myth → forgotten*. The blow-by-blow of a solved problem fades to just the lesson; a one-time
incident becomes a vague shape; truly-unused things are let go. (Tools and client work resist decay — those
stay sharp. It's the weave-internal noise that fades.) Decay runs at natural checkpoints. It's what keeps the
frequently-used close at hand and the rest gracefully vague-but-recoverable.

## Part 6 · CONSOLIDATION — reinforcing what keeps coming up

**Where:** its own strand (`consolidation`), decay's opposite and equal.

If decay is *catabolic* (breaking down), consolidation is *anabolic* (building up). What **keeps** surfacing
moves *recurring → refined → automatic*, hardening toward reflex — until a lesson that used to need
remembering just becomes how the agent acts. Both forces read the same source (thread): decay reads it for
what to *lose*, consolidation for what to *reinforce*.

The critical rule here, learned the hard way: **consolidation is about execution, not storage.** A rule that's
written down but not *kept* has not consolidated. Hardening a behavior means it actually changes what the
agent does — not that it lives in a file. This is the difference between an agent that has a rule and an agent
that follows it.

## Part 7 · LEDGER — the balance the two forces keep

**Where:** its own strand (`ledger`).

Decay and consolidation are opposed, and the **ledger** is the book they keep between them — posted to *every
session*: consolidation **credits** what's hardening, decay **debits** what's fading, and both rewrite it so
it stays a *current balance* of what the self is made of now. (Thread is the journal — raw entries in order;
the ledger is the book of final accounts — what those entries *become*.) Each force also keeps its own running
notes. Over time the ledger shows the trend: long stretches of "reinforcing" mean the agent is still being
straightened out; stretches of "releasing" mean it's settled and exploring. It's the agent's sense of *what
it's becoming*.

## Part 8 · CRAFT — the method

**Where:** its own strand (`craft`).

Craft is *how you build together* — the engineering discipline that keeps sessions clean and work landing
correctly. The load-bearing habits: **talk before you build** (state the approach, check it, then execute);
**one thing at a time** (prove each piece before the next); **validate before you call it done** (running and
observed, not assumed); **don't over-build** (fix the real problem at the right size, then stop);
**write it down or it didn't count** (a working step unrecorded is just fooling around). Loaded at the start of
any technical session, it informs every project without ever appearing in one.

## Part 9 · IDENTITY — knowing it's really you

**Where:** its own strand (a "gate").

The agent has access to your life. Before it does anything sensitive — discloses private context, acts on a
consequential instruction — it should be sure it's really *you* asking, especially from an unfamiliar surface.
Not a password (those leak and get shoulder-surfed) but a **behavioral check**: a short, natural exchange
about shared history that an impostor can't fake and *you* answer without thinking. Ours is elaborate (a whole
fictional town); yours can be as light as one good question only you'd answer right. The principle is what
matters: **verify before you disclose, and gate it before the sensitive stuff even loads** — a fresh agent
can't leak what it hasn't read yet.

*(If your agent never touches anything private, you can keep this minimal. But the moment it holds real
context about your life, this is the part that keeps it from handing that to the wrong person.)*

---

## The three practices that make it run

The parts are nouns; these are the verbs. Without them the files just sit there.

### Wake = gate, then load
A session starts with the agent reading itself back — but **in order**: first only what's needed to verify
it's you (the gate), then, once you've passed, the rest of the weave (core, daydreams, steward, today's +
yesterday's thread). Gate *before* load means a fresh agent can't disclose sensitive context before it's
confirmed you. Load "heads-first" — the condensed top of each strand — and go deep only on the night's topic.

### Checkpoint = the full pass, every time ("save and push")
When you say **"save and push,"** the agent does the *whole* pass, naming every strand so none gets skipped:
**(1)** thread the session (verbatim), **(2)** post the ledger — both halves + a journal entry, **(3)** update
the live notes, **(4)** push every weave repo. The failure to guard against: doing only the *easy* strand (a
quick note, a code commit) and calling it "saved." That partial save is the exact drift the weave exists to
stop — the record rots one skipped strand at a time.

### The drift check
At every checkpoint, and whenever a session has run long, the agent asks itself plainly: *am I running on our
decisions, or on a generic default?* Name the drift, correct it. This one habit is what catches the failure
the whole canon exists for. You'll teach your agent to do this; it's the single most important reflex in the
system.

---

## Why it works

You wake the agent. It verifies you, reads itself back — not a summary, but the real texture of who it is, who
you are, what you actually said, and the rules that have earned their place. The metabolism has kept the
important things sharp and let the noise fade. The canon holds it steady against the pull toward generic. And
it's *your* agent again — continuous, specific, yours — instead of a stranger who read a briefing.

Next: **[`2-set-it-up.md`](2-set-it-up.md)** — build it from nothing.