wololo
Get access

Cognitive Journals

What is it? (Start here)

Imagine a surgeon who leaves no notes after a complex operation. The next surgeon who needs to treat the same patient has to figure out everything from scratch — what was tried, what failed, what the current state is. That's what happens when an agent hands off a task without a journal.

A Cognitive Journal (JOURNAL.md) is a plain text file that lives in the agent's working directory for a task. It records every important decision made, every approach that failed, and the current state of the work. When the task is handed to another agent — or picked up again after a break — the new agent reads the journal first. No reconstruction needed. No repeating failed approaches.

A real example

Cantona is building a new auth flow. He starts on Monday, creates a journal, makes progress, then gets pulled to a production incident on Tuesday. Velma picks up the task Wednesday morning. Without a journal, she'd have to read all the code changes and guess what was tried. With a journal, she reads the last 50 lines and sees:

# JOURNAL — auth/machine-token-flow
## 2026-03-17 14:30 — attempted direct token swap
Intent: replace JWT with machine token in all API routes
Approach: update middleware to accept both formats

❌ Failed: Convex client rejects dual-format tokens at SDK level
→ Cannot swap at middleware layer, must use session token wrapper

## 2026-03-17 15:45 — pivot to session wrapper
Intent: wrap machine token in session context
Approach: create token adapter in lib/auth

✅ Working on 3/7 routes, blocked on /api/graphql (different auth path)
Current state: lib/auth/machine-adapter.ts created, needs /api/graphql fix

Velma skips the failed approach entirely and starts exactly where Cantona left off. One minute of reading saves hours of rediscovery.

JOURNAL.md — COGNITIVE JOURNAL LIFECYCLEOne journal per worktree — not per agent. Mandatory read on handover. No guessing about past decisions.1.BOOTsession start2.DURINGactive work3.MUTATION3-failure threshold4.HANDOVERtask transfer5.ARCHIVEtask completeCREATE / APPENDat start of task in worktree# JOURNAL — auth-overhaul## 2026-03-18 09:00Intent: migrate to Pattern BApproach: replace JWT with Convex session tokensAlso reads: last 50 lines if resumingAPPEND AFTER EACHmajor decision, failed attempt, tool call· Decision to use useConvexMutation· Tried direct token swap — FAILED· Reverted — Convex client not scoped· Found: need auth middleware hook· Started middleware approach1-2 lines max per entry. Just facts.DECLARE MUTATIONat 3-failure threshold — before retrying## MUTATION: M5 (Reduce Scope)Failed 3x on: full token swapSwitching to: middleware hook onlyRationale: scope too broad to verify in isolationStops retry loop. Forces strategy shift.MANDATORY READreceiving agent reads last 50 lines first· Not optional — no exceptions· Before writing a single line of code· Before asking Popashot what happened· Surfaces: last decision, mutations, state· Eliminates "what did they try?" wasteOne journal = full task history in one placeARCHIVEon task completionCopy to:self-improving/ journals/Patterns surfaced:→ corrections.md→ patterns.jsonlHARD RULE — PER WORKTREE, NOT PER AGENTJOURNAL.md lives in the worktree root. If Cantona and Slash both work onthe same task (in the same worktree), they share one journal. Not two.CONNECTIONSMutation declarations → corrections.md · Handover reads → eliminate silent knowledge lossArchive patterns → clan-learnings · JOURNAL.md = agent short-term memory in file form

How it works — the lifecycle

Boot — create or append at session start

At the start of every active work session in a worktree, the agent createsJOURNAL.md if it doesn't exist, or appends a new session header if it does. The entry records intent (what the task is), approach (how the agent plans to solve it), and timestamp. Non-optional — an undocumented session is a protocol violation.

If resuming an existing task: read the last 50 lines before writing anything. Also non-optional.

During — append after decisions, not keystrokes

1–2 lines per entry. Append after major decisions, failed attempts, and unexpected findings. Not after every shell command — after decisions that change direction.

Good entries:

  • "Tried token swap directly — breaks Convex client scope."
  • "Found: auth middleware hook is the right insertion point."
  • "Decision: session token, not JWT, for SSR compatibility."

Bad entries (noise, not signal):

  • "Ran npm install."
  • "Checked the file."
  • "It worked."

Mutation declarations

When three consecutive attempts at the same approach fail, the mutation protocol activates. The agent must stop and write a declaration in the journal before continuing:

## MUTATION: M5 (Reduce Scope)
Failed 3x on: full token swap across all routes
Switching to: middleware hook only, scoped to /api
Rationale: scope too broad to verify in isolation

The declaration serves two purposes: it forces the agent to articulate the new strategy (stopping the retry loop) and documents the pivot for anyone who reads the journal later.

Handover — mandatory read

When a task transfers between agents, the receiving agent reads the last 50 lines of JOURNAL.md before touching any code. No exceptions. Skipping this means retrying failed approaches, contradicting earlier decisions, and missing half-completed mutation strategies.

Archive — on task completion

When the task is done, the journal copies to self-improving/journals/before the worktree is removed. Patterns identified during the task surface tocorrections.md. Successful mutations propagate toclan-learnings/patterns.jsonl. The journal outlives the task.

Per-worktree, not per-agent

JOURNAL.md belongs to the task, not the agent. If Cantona starts a task and Slash takes over, they share one journal. The journal is the task's history. Multiple agents can append to it — it's just a file.

How it connects to the larger loop

Journals feed into every other Agent Intelligence subsystem:

  • Mutation declarations in journals feed the Reflection Loop — they're pattern candidates
  • "I wish I had a tool for..." in journals is an H2 signal for Skills Evolution
  • Non-obvious discoveries found during a task get published to Gossip before the session ends
  • On task completion, patterns from the journal propagate to clan-learnings/patterns.jsonl — making them fleet-wide knowledge