A transcript, the active model context, and long-term instinct are three different things with three different lifecycles. Treating them as one thing is why most chat products either forget everything or drown in their own history. DuoDuo keeps them apart on purpose.
The project files the agent is reading and changing. The session stays attached to this workspace.
duoduo spine, and the subconscious read, and what the daemon rebuilds its routing from after a restart. Each runtime keeps the conversation it resumes in its own session files beside it. The kernel's Git history records every change to the intuition layer and configuration. Locks, PIDs, and heartbeat bookkeeping live separately as ephemeral files—safe to clear, never needed to recover. Run duoduo daemon config to see the paths used on this machine.Three kinds of continuity#
| Layer | Purpose | What survives |
|---|---|---|
| Session history | Continue one conversation with its workspace and model history | The original transcript and session state remain on disk |
| Active context | Give the current model enough recent history to act | It can be compacted when it becomes expensive |
| Intuition & dossiers | Carry distilled instincts and knowledge across sessions | Dossiers, lessons, grooves, and the compact intuition layer live in the kernel |
Compaction manages active context. The subconscious tends the intuition layer and its dossiers. Neither ever needs to delete the original event history.
From event evidence to intuition#
The pipeline is evidence-driven, and it is split in two so that reading experience and rewriting instinct never compete for the same wake:
- External interactions and tasks enter the append-only event history—every channel and every runtime share this one timeline.
- Distil.
gradient-distillerreads a bounded stretch of that history and writes text gradients. - Weave.
intuition-weaver—the only writer of the intuition layer—reads the accumulated gradients and moves the layer: add a line, rewrite one, reorder, retire, or re-point it at something reachable. - Alongside them, entity dossiers are kept current, and a verified correction arc becomes a lesson while a procedure that converged through repeated use becomes a groove.
- The committer stages the kernel working tree and lands one commit, so every step above has a diff and a revert.
In one line: events —distill→ text gradients —weave→ intuition layer.
What a text gradient is#
A gradient tells a model weight which way to move. A text gradient does the same for a line of the intuition layer, in words instead of numbers. Each one names the line it tested, cites the events it tested it against, and says which way the line should move: it helped, it should have fired and did not, or it had nothing to act on. Without the evidence it cites, a text gradient does not exist—so an opinion with no event behind it never reaches the layer.
The intuition layer itself is a compact board—one line, one pointer—loaded into every future foreground session. The dossiers its lines point to stay linked on disk and are opened when a task needs them. On disk, the board and its dossiers live under the kernel's memory/ directory, with the board at memory/CLAUDE.md; the directory keeps that name, and the commands that check it are duoduo memory …. A later session starts with the instincts, not the archive.
Not every pass adds something. Greetings, receipts, transient task detail, and evidence that repeats what is already known produce no gradient, and a weave that finds nothing worth changing leaves the layer alone. The record is preserved either way; the layer only moves when something held up.
It is told what it is not using#
Adding lines is the easy half. The hard half is knowing which lines are dead weight, because a line nobody reads still costs a slot in every prompt.
So the weaver gets a second input next to the gradients: an activation report counting how often each line is actually read during real work. A line that never fires arrives as evidence to rewrite, re-point, or retire it. The count is kept in days when someone actually worked with DuoDuo rather than calendar days, so a quiet week does not age out a line that was earning its place.
It is a layer above your harness's instruction files, not a replacement#
Claude Code reads its CLAUDE.md; Codex and Pi read AGENTS.md. Those files are yours—instructions you wrote, scoped to one harness and one project, read by that harness for itself. DuoDuo leaves them alone and they keep working.
The intuition layer sits above that and answers a different question.
Harness instruction files (CLAUDE.md, AGENTS.md) | Intuition layer | |
|---|---|---|
| Who writes it | You | The subconscious, from event evidence |
| Scope | One harness, one project | Every harness on the host |
| Says what | How this project wants to be worked on | What has actually held up while working on it |
| When it changes | When you edit it | On a cadence, with a Git commit |
They stack rather than compete: your instructions still apply, and the intuition layer adds what nobody sat down to write.
It reaches every runtime because of what it is made of. A lesson fine-tuned into weights belongs to one model; a lesson written into a harness's config belongs to one harness. Written as text, it is bound to neither—so a correction earned in a Claude session is already in the Codex job that runs tonight, and in the Grok partition that wakes tomorrow. Prose is the only representation that crosses all four, which is why the pipeline distills into it rather than into anything more structured.
Manual compaction#
Use /compact in the current conversation or queue it from the host:
duoduo session compact <session-or-alias>
Compaction summarizes older active context to make room. It does not delete the original transcript.
Idle auto-compaction#
Idle auto-compaction is available for channel sessions and is off by default. When enabled, it can prepare a large conversation during a quiet period instead of making the next reply reopen the entire cold context.
Configure it per conversation unless the user explicitly wants a kind-wide policy:
duoduo session config <session-or-alias> get
duoduo session config <session-or-alias> set \
auto_compact_idle_minutes=<chosen-idle-window> \
auto_compact_min_context_tokens=<chosen-context-floor>
Choose these values from the backend's cache behavior, the measured post-compact floor, and how often the user returns after a long gap. The published smart-compaction skill reads the daemon's measurements and applies the break-even rules.
Inspect the intuition layer#
duoduo memory check --dry-run
duoduo memory board-lint
duoduo memory entity-lint
duoduo memory node-lint
The duoduo memory commands are the mechanical, no-model half of keeping the intuition layer and its dossiers in shape. They measure gaps and broken references and can route repair signals to compatible subconscious partitions. The normal checks do not delete anything. Reclaiming data is a separate explicit operation and should begin with a dry run.
Prompt and intuition history#
The kernel is initialized as a Git repository, so every change to the intuition layer, dossiers, subconscious prompts, the playlist, and channel descriptors is a reviewable commit.
Package upgrades preserve existing subconscious prompts because they may have changed on this host. When a release ships revised defaults, compare the published partition tree with your kernel, preserve user-authored partitions, and create a rollback point before refreshing anything.