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

journal update (and sync as its first step) pulls the latest from the remote into your local ~/.doraval/journals/ cache so that list, drift checks, and future check see everyone else’s decisions.

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 the lowest-effort way is simply:

dora journal add "Use 'update' not 'refresh' for cache refreshes"

(If you ran dora init and configured your coding agent, dora will use that agent on the fly via its own prompt tool + a scaffold to produce good pushback/tags/rationale.)

For full control, structured entries from agents, or long rich content, use the --json path or --raw-markdown <file-or-> (see the journal-add command page for examples of long-form notes).

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).

To pull in the latest decisions from others (or from another machine), run doraval journal update at the start of your session. sync also refreshes the local cache before publishing.

When an agent or a future doraval skill drift run touches something in the naming or cli tags, 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. Use list and update to explore and stay fresh, add + sync to contribute, and the principles will start pushing back (via future check and drift integration) when something drifts from your recorded decisions.