How the Agent Journal Works

The Agent Journal solves a simple but painful problem: important decisions about your projects disappear.

When you (or an agent) start fresh on a codebase, you no longer remember why certain choices were made. You pick reasonable names, structures, or behaviors that accidentally contradict deliberate earlier decisions. Over time, this creates drift that is hard to detect and even harder to correct.

The journal gives that “why” a permanent, queryable home with a personality.

What You Get

• A living memory of decisions — Not just what changed, but why it was changed and how strongly you feel about it.
• Pushback instead of silent contradiction — When future work conflicts with a recorded principle, the journal can argue back at a calibrated intensity instead of letting the bad decision slip through.
• Shared context for humans and agents — Both you and AI coding agents can read the same principles. Agents can propose new ones too.
• Zero pollution of your projects — Everything lives in one private GitHub repo you control. No files, no submodules, no config ever touch your actual project repositories.

The Core Model

Your journal lives in a single private GitHub repository (by convention named after you, e.g. yourname/yourname.md).

Inside it you have two kinds of content:

• global.md — principles that apply across all your projects
• projects/<name>.md — principles specific to one project

doraval never writes directly to this repo from journal add. Instead it uses a safe two-step flow:

1. journal add stages a new principle locally in ~/.doraval/pending/
2. journal sync is the only command that publishes those changes to GitHub

This single-writer pattern means you (and any agents) can propose as many entries as you want without risking conflicts or broken history on the remote.

The Pushback Scale

Every entry has a pushback value from 1 to 10. This is the most important concept in the journal.

Pushback	Tone	What it means for future work
1–3	Nudge	”This is a little different from what we decided. Probably fine.”
4–6	Friction	”This goes against a deliberate choice. You should have a good reason.”
7–10	Wall	”This contradicts something we care about strongly. Override only if you’re sure.”

Even a pushback of 10 is still an argument, not a hard gate. The journal’s job is to make the conflict visible and force a conscious decision.

How It Feels in Practice

You make a meaningful decision while working (naming, architecture, testing approach, CLI behavior, etc.). Later you run:

doraval journal add "Use 'drift' not 'score' for rubric deviation" \
  --pushback 7 \
  --scope naming,cli

You write the rationale in your editor. The entry is staged locally.

When you’re ready (or at the end of a session), you run doraval journal sync. The new principle is now part of your permanent record and will be seen by future agents (and by you when you come back to the project months later).

When an agent or a future doraval skill drift run touches something in the naming or cli scope, the journal can surface the relevant principles with their pushback strength.

Why This Shape?

• One private repo keeps all your decision history in one place you fully control and can browse on GitHub.
• Local staging + explicit sync protects you from accidental or concurrent writes.
• No files in your projects means the journal works even for projects you don’t own or that live in restrictive environments.
• Pushback as a number lets both humans and future tools reason about intensity instead of just binary “important / not important.”

The journal is opinionated memory, not a linter or a blocker. Its power comes from being present and having a point of view — not from stopping you.

Start with doraval journal init to connect a project. The rest becomes natural the first time you capture a decision you don’t want to lose or relitigate.