Journals

Journals are markdown notes about what a quest discovered, decided, and why. Since 0.72 they are the memory of your agents as much as documentation for you: the Chronicler writes one automatically when a Claude Code quest completes, every new quest is shown the entries that look relevant to its task, and agents can search and write them from the terminal.

What a journal entry looks like

Entries are plain markdown files with YAML frontmatter:

---
id: jn_01J9Z4QK7V2M8X3N5P6R9S0T1U
date: 2026-10-13
project: api-gateway
quest_id: 4df63f83-4094-4d16-9517-3d514b405e5b
branch: feat/orders-rate-limit
source: auto
tags: [rate-limit, orders, api-keys]
summary: Keying on client IP throttled the whole office; limits now hang off the API key.
---

# Orders rate limits must be per API key, not per IP

## What I expected
...

• source is auto (written by the Chronicler on completion), manual (you asked for one) or agent (written by an agent with the CLI). Each shows as a badge in the UI.
• tags are three to eight lowercase slugs; summary is one line. Both are generated by the Chronicler and drive search ranking.
• reviewed is added when you Keep an entry during a retention review.

Entries written before 0.72 (which only had date, project and branch) still work and are treated as manual.

How entries are created

graph LR
A[Quest completed] -->|within ~5 min| B[Chronicler reads transcript]
B -->|notable| C[Journal .md with tags + summary]
B -->|routine work| D[Skipped]
M[Make Journal Entry] --> B
E[sidequest-journal write] --> C

Automatically. A background sweep runs at startup and every five minutes. For each completed Claude Code quest it has not seen, it sends the conversation to Claude with the Chronicler prompt. The Chronicler returns a title, summary, tags and body — or declines when the work was routine (version bumps, typo fixes, abandoned tasks), in which case no entry is written. Quests are skipped when:

• the quest’s Skip Auto-Journal menu item is checked;
• it was spawned by a recurring quest whose Journal each run switch is off (the default for recurring quests, since runs are frequent);
• it ran on an agent other than Claude Code;
• the conversation is missing or too short.

Turn automatic entries off with Chronicle completed quests automatically in the journal settings (see below). Quests completed while it is off are never chronicled retroactively.

Manually. Click + in the Journal Entries section at the bottom of the quest log and pick a quest, or right-click a quest and choose Make Journal Entry. The same Chronicler runs; if it finds nothing worth recording it says so.

From an agent. The sidequest-journal write command creates an entry with source: agent. See Sidequest CLI.

How quests use journals

When a quest starts, Sidequest searches the project’s journals using the words of the quest title and picks up to three entries whose title matches or that share at least two terms. Their titles, dates and paths are injected at the top of the session as a gray Sidequest · quest context block (for Claude Code, via a SessionStart hook so it survives /clear and /compact; for other agents, as a prefix to the prompt):

Journal entries from earlier quests that may be relevant. Read one before
relying on it and check its date against the code:
- Webhook retries were double-counting under the old nonce scheme (2026-10-11): ~/.sidequest/journal/api-gateway/webhook-retries-double-counting.md

Beyond those three, the agent can search everything with sidequest-journal search --terms a,b. The sidequest-journal skill that Sidequest installs into ~/.claude/skills/ tells Claude Code to search at the start of a quest, to treat entries as leads rather than facts, and to write an entry only for hard-won, non-obvious findings.

Disable the automatic suggestions with Suggest related journals when a quest starts in the journal settings.

Where journals are stored

By default, entries are saved to:

~/.sidequest/journal/<project-name>/<slug>.md

Filenames are slugs of the title; collisions get a -2, -3 suffix. Archived entries move to an archive/ subfolder (see Retention).

A search index lives at ~/.sidequest/journal-index.db. It is a cache: delete it or run sidequest-journal reindex and it is rebuilt from the files.

Changing the journal directory

1. Expand the Journal Entries section in the quest log.
2. Click the gear icon to open Journal Settings.
3. Click Browse to choose a new directory, or Reset to default.

The same dialog holds the two global switches (Chronicle completed quests automatically, Suggest related journals when a quest starts) and lists Extra search directories — folders you have committed entries into, which are searched alongside the journal directory. Click the × next to one to stop searching it.

Browsing and searching

In the quest log. The Journal Entries section shows the count and, when expanded, a search box, All / Auto / Manual / Agent source tabs and the newest entries for the project. Click an entry to open it in the viewer. Right-click one for Rename, Copy and Commit to project.

Everywhere. Click the owl in the bottom bar (tooltip Search all journals) to search across every project. The left pane lists hits with project, date, summary and tags — click a tag to filter by it — and the right pane renders the selected entry with an Open in Editor button. With an empty query it shows the fifteen most recent entries.

Search terms are matched by prefix and OR-ed; title and tag matches rank highest, and at most two hits per quest are shown.

The viewer renders the markdown (frontmatter hidden) with inline rename, Commit, Copy and Delete (with confirmation).

Committing to your project

Commit to project copies the entry into your repository and commits it:

1. Choose Commit to project from the entry’s menu or the viewer.
2. Pick a directory inside the project (e.g. docs/journals/).
3. Click Commit. Sidequest copies the file, runs git add, and commits with the message docs: add journal entry <name>.

The target directory is remembered as an extra search directory, so the entry stays searchable from its new home. If the commit fails (for example because of a git hook), the copied file is removed again.

Retention

Journals accumulate. Settings > Storage has two controls:

• Journal Retention — Off (audit by hand) (default), 30, 90, 180 or 365 days. Each option shows how many entries it would act on right now. Age counts from the entry’s date, or from the last time you kept it.
• Journal Retention Action — Archive (default; moves the file into the folder’s archive/ subfolder, where search no longer finds it) or Delete.

Automatic retention runs after each five-minute sweep and only touches a project’s own journal directory, never folders you committed entries into.

Review old journals opens a keep-or-kill pass. Choose Older than (7—365 days) and go through entries one at a time with the full body rendered: Keep (K) stamps today’s date as reviewed and restarts its clock, Archive / Delete (X) applies your retention action, and Skip (→) moves on. A summary line reports what you kept, archived and skipped.

When journals are useful

Agent memory. The Chronicler notices things an agent had to work out — an undocumented constraint, a flaky fixture, a config that behaves differently than its name suggests. The next quest that touches the same area is pointed at the note before it starts.

Knowledge transfer. Hand a feature branch to a colleague with the journal entry instead of the whole transcript.

Audit trail. For compliance-sensitive projects, journals are a narrative record of what the agent did and why, tied to branches and dates.

Personal reference. After a long quest, the entry tells you where things stand and what was decided.