Project Diary for AI Sessions

Date: 2026-05-18

Short Idea

A project diary is a compact memory layer between permanent project instructions, execution plans, and short session summaries. Its job is to help a new AI session quickly understand what changed recently, which decisions are already settled, and where the project stands now.

The diary is not a chat transcript, changelog, backlog, roadmap, or replacement for AGENTS.md. It is curated operational project memory.

The main problem it solves: one project may continue across several chats in one day, but each new session should not reconstruct context from long conversation history. At the same time, the diary must not grow into a wall of text. Therefore it stores only durable memory - information that remains useful after a context reset.

Why A Diary Is Needed

In a typical AI workflow, a project lives for a long time, but each chat should stay relatively short. At the end of a task the user runs end-session, then starts a new chat and runs new-session.

Without a diary, the next session relies on:

• AGENTS.md - permanent project rules;
• Summarizations.md - compact handoff from the previous session;
• active ExecPlan - if a large execution plan exists;
• the current repository state.

That is often enough, but there is an intermediate class of information:

• "today we added a third language, so content must now exist in RU/EN/AM";
• "we decided not to use WordPress";
• "we found that sitemap generation still handles only two locales";
• "this integration requires a specific workaround";
• "this progress matters, but it is not a permanent repo instruction".

This information is too specific for AGENTS.md, too short-lived for architecture documentation, but too important to lose between chats. The diary is designed for that layer.

Memory Architecture

We split project memory into separate layers:

AGENTS.md
  Permanent project rules:
  commands, constraints, conventions, definition of done.

Summarizations.md
  Compact handoff from the latest session.

ExecPlan / active plans
  Step-by-step plan for a large task.

diary/current.md
  Short snapshot of where the project is now.

diary/decisions.md
  Durable decisions that should not be rediscovered.

diary/days/YYYY-MM-DD.md
  Meaningful changes by date.

This separation matters: the diary must not become a plan, and a plan must not become history. AGENTS.md must not store session noise, and the diary must not become permanent project policy.

Diary Folder Structure

Each project stores its diary in:

diary/
  README.md
  current.md
  decisions.md
  days/
    2026-05-18.md
    2026-05-19.md

We intentionally removed open-threads.md. If unfinished work matters only within a day, it belongs in days/YYYY-MM-DD.md under Carry Forward. If it is a real plan, it belongs in the planning file or the output of the planning skill.

File Responsibilities

diary/README.md

README.md is the local constitution of the project diary.

It defines:

• what counts as durable memory;
• what to write;
• what not to write;
• size limits;
• deduplication rules;
• compaction rules;
• how Write Diary works;
• how Read Diary works;
• how the diary relates to AGENTS.md, Summarizations.md, and plans.

This file prevents future AI sessions from interpreting "diary" differently. The global skill provides the base protocol, while local diary/README.md fixes the rules inside a specific project.

diary/current.md

current.md is a short snapshot of the current project state.

Important: it is not a plan, backlog, or task list. If the project already has a planning skill or ExecPlan, current.md must not duplicate it.

The purpose of current.md is to:

• show where the project stands now;
• point to important context;
• provide a continuation hint - where to look first;
• remind the agent about boundaries: plans live elsewhere, permanent rules live in AGENTS.md.

Target size: around 30 lines. Hard limit: 50 lines.

diary/decisions.md

decisions.md stores durable decisions that future sessions should not casually reopen.

Examples:

• the project supports RU/EN/AM;
• every article must be created in three locales;
• deployment uses Vercel;
• auth uses Supabase;
• WordPress is not used;
• a specific data format or API contract was selected.

Each decision gets an ID:

D-YYYYMMDD-001
D-YYYYMMDD-002

Daily files may reference these IDs instead of repeating the full rationale.

diary/days/YYYY-MM-DD.md

A daily file is a compact record of meaningful changes for one date.

It is not append-only in the usual sense. Write Diary may rewrite the daily file, merge similar points, remove stale carry-forward items, and move durable decisions into decisions.md.

Target daily size: up to 120 lines. Hard limit: 200 lines.

Durable Memory: What To Write

Write only information that helps continue the project after a context reset.

Write when any of these changed:

• project goals;
• scope;
• audience;
• languages, locales, currencies;
• user roles;
• content model;
• architecture;
• data schema;
• API contract;
• integrations;
• deployment;
• build process;
• auth;
• permissions;
• storage;
• important commands;
• external services;
• project workflow.

Also write:

• non-obvious bugs;
• root causes;
• workarounds;
• migration issues;
• compatibility rules;
• important findings;
• verification status;
• decisions that should not be reopened casually;
• facts that will clearly help the next AI session.

What Not To Write

Usually do not write:

• button color changes;
• spacing tweaks;
• typography polish;
• minor copy polish;
• formatting;
• lint-only edits;
• local variable renames;
• routine refactors with no behavior change;
• lists of inspected files without a conclusion;
• temporary errors that were immediately fixed;
• long command output;
• repeated facts already present in current.md, decisions.md, or the daily file.

Exception: a small change should be recorded if it expresses a durable rule. For example:

All destructive actions must use the danger style.

That is no longer "changed a button color"; it is a design-system rule.

Write Diary

Write Diary is the skill responsible for creating and updating the diary.

It owns:

• creating diary/;
• creating base files;
• deciding whether a diary update is needed;
• filtering important vs. unimportant changes;
• updating current.md;
• updating decisions.md;
• creating or updating the daily file;
• deduplication;
• compaction.

If the diary does not exist, Write Diary creates:

diary/
  README.md
  current.md
  decisions.md
  days/
    YYYY-MM-DD.md

If there is no durable update, Write Diary should not add noise. It may simply report that no diary update is needed.

Read Diary

Read Diary is the skill responsible only for reading diary context.

It does not edit files, create the diary, or invent missing context.

It reads:

• diary/README.md;
• diary/current.md;
• diary/decisions.md;
• selected files from diary/days/.

Examples:

Read Diary for today
Read Diary for 3 days
Read Diary for the last 5 days
Read Diary from 2026-05-15 to 2026-05-18

After reading, it returns a compact context warm-up:

Read diary: 2026-05-16..2026-05-18.

Current state:
- ...

Durable decisions:
- ...

Recent changes:
- ...

Carry forward:
- ...

Notes:
- ...

Integration With end-session And new-session

We integrated the diary into the existing session lifecycle.

end-session

end-session is the session shutdown orchestrator.

It should not implement diary rules itself. Instead, it always invokes project-diary-write.

Order:

1. update-exec-plan, if an active ExecPlan exists
2. summarizations - update Summarizations.md
3. project-diary-write - create/update diary or skip if there is no durable update
4. create-agents-md through promote-lessons, only if permanent repo-level lessons appeared

Why project-diary-write runs after Summarizations.md:

• the summary already separates important session content from noise;
• the diary can use a clearer session result;
• AGENTS.md is updated last because it should receive only rare permanent rules.

new-session

new-session is the session startup orchestrator.

It does not create the diary. It reads it only if diary/ already exists.

Order:

1. AGENTS.md
2. Summarizations.md
3. .agent/PLANS.md
4. active ExecPlan
5. project-diary-read, if diary/ exists
6. optional CLAUDE.md, if cross-tool context is useful

Diary read rule:

If today's diary/days/YYYY-MM-DD.md exists:
  read the latest 3 existing daily files, including today.

If today's daily file does not exist:
  read the latest 2 existing daily files.

Always read:
  diary/README.md
  diary/current.md
  diary/decisions.md

This gives the new session recent context without reading the whole project history.

Why new-session Does Not Create diary

We considered letting new-session create an empty diary if none exists. We rejected that design.

Reason: the normal workflow is:

end-session -> new chat -> new-session

If end-session already ran, the diary was either created or project-diary-write deliberately decided that no durable update was needed. Therefore new-session should not mutate files at startup.

Diary creation belongs to Write Diary / end-session, not new-session.

current.md Template

# Current State

Last updated: YYYY-MM-DD HH:MM

Purpose: short snapshot of where the project is now. This is not a plan, backlog, or replacement for `AGENTS.md`.

## Project Snapshot

- Project:
- Current state:
- Main active area:
- Recent meaningful change:

## Important Context

- Supported languages/locales:
- Important content or product rules:
- Important files or modules:
- Important commands or services:

## Continuation Hint

- If continuing work, first check:

## Boundaries

- Read `AGENTS.md` for permanent project instructions if it exists.
- Read `decisions.md` for durable decisions.
- Read recent `days/` files only when the user asks `Read Diary`.
- Detailed task plans belong in the project's planning file or planning skill output, not here.

decisions.md Template

# Decisions

Purpose: record durable decisions that future AI sessions should not rediscover or casually reverse.

## Format

### D-YYYYMMDD-001 - Decision Title

- Date: YYYY-MM-DD
- Status: active
- Context: why the decision was needed.
- Decision: what was decided.
- Rationale: why this option was chosen.
- Consequences: what future work must assume or preserve.
- Applies to: files, modules, workflows, documents, or project areas.
- Replaces: D-YYYYMMDD-000 or none.

## Active Decisions

<!-- Keep newest first. -->

## Superseded Decisions

<!-- Move replaced decisions here. Keep their replacement ID. -->

Daily File Template

# YYYY-MM-DD

Purpose: compact daily project memory. This file is not a transcript.

## Snapshot

- Project state:
- Main focus:
- Next best action:

## Changes

-

## Decisions

-

## Findings

-

## Verification

-

## Carry Forward

-

Example Daily Entry

# 2026-05-18

Purpose: compact daily project memory. This file is not a transcript.

## Snapshot

- Project state: content pipeline now assumes three required locales.
- Main focus: localization scope.
- Next best action: check sitemap and article generation for AM support.

## Changes

- Added Armenian as a required project locale alongside Russian and English.
- Content tasks must no longer assume one article per topic.

## Decisions

- D-20260518-001 - Project requires RU/EN/AM content variants.

## Findings

- Existing sitemap logic may still assume only RU/EN.

## Verification

- Scope decision only; no code verification performed.

## Carry Forward

- Check sitemap locale handling.
- Update content generation prompts to require RU/EN/AM variants.

Deduplication

Write Diary should compare points by meaning, not exact text.

Rules:

• if a new point clarifies an old one, replace the old point;
• if a new point cancels an old one, keep only the current truth;
• if several points describe one issue, merge them into one finding;
• if a decision already exists in decisions.md, keep only the D-... reference in the daily file;
• if a carry-forward item is completed, remove it from Carry Forward and record the result in Changes or Verification.

Compaction

If a daily file approaches 200 lines:

1. Update Snapshot to the latest true state.
2. Merge repeated entries.
3. Preserve outcomes, decisions, findings, verification, and carry-forward items.
4. Remove narrative, dead investigation paths, command noise, and cosmetic-only details.
5. Move durable decisions to decisions.md.
6. Leave only decision ID references in the daily file.
7. Update current.md only if the compact project snapshot changed.

Practical Lifecycle

Normal usage looks like this:

1. The user works with AI in a project.
2. At the end, the user runs end-session.
3. end-session updates the plan, summary, and invokes project-diary-write.
4. project-diary-write creates or updates diary.
5. The user starts a new chat.
6. At the beginning, the user runs new-session.
7. new-session reads AGENTS.md, summary, plans, and invokes project-diary-read.
8. The AI receives compact recent context and continues work.

Terms And Mental Model

The easiest way to understand this system is context routing: different kinds of knowledge are not merged into one large file; they are routed to different memory targets.

The key idea: not every fact deserves persistence. If a fact matters only during the current task, it can stay in the chat. If it matters to the next session, it belongs in the diary. If it must become a permanent project rule, it becomes a candidate for AGENTS.md.

Responsibility Matrix

This matrix protects the system from memory sprawl. When a new fact appears, the question is not "where can we write it?" but "what role will this fact play in a few days?".

Why This Is Not A Wiki

A wiki usually tries to be a reference system: pages, topics, relationships, explanations. A project diary solves a different problem. It does not describe the whole project; it accelerates continuation.

A wiki answers:

What is this system and how is it structured?

A diary answers:

What changed recently, what is already decided, and where should work continue?

That is why the diary can use a denser format: bullets, short statuses, file paths, decision IDs, verification notes. It does not need literary completeness. It needs a high signal-to-token ratio.

Read/Write Split

We intentionally split reading and writing into separate operations.

Write Diary
  mutates files
  creates diary/
  filters durable memory
  compacts daily notes
  updates decisions/current/day files

Read Diary
  reads files
  does not mutate
  does not create diary/
  does not invent missing context
  returns compact startup context

This is an important engineering boundary. If one skill reads, writes, creates, interprets, and plans at the same time, responsibilities quickly blur. A dedicated write path keeps persistence strict. A dedicated read path makes session startup predictable and cheap.

Lifecycle Routing

working session
  |
  v
end-session
  |
  +--> update-exec-plan      # if an active plan exists
  +--> summarizations        # compact restart file
  +--> project-diary-write   # durable memory only
  +--> create-agents-md      # only rare permanent lessons

new chat
  |
  v
new-session
  |
  +--> AGENTS.md
  +--> Summarizations.md
  +--> active ExecPlan
  +--> project-diary-read    # if diary/ exists

In this design, end-session and new-session do not know diary internals. They invoke specialized skills. This keeps the orchestration layer thin.

Entry Classification

Before writing, Write Diary should classify the candidate fact:

This classification prevents the diary from becoming a backlog. A single fact may have two projections: a short daily event in days/ and a stable decision in decisions.md.

Signal Examples

A good diary point:

- Added Armenian as a required locale alongside Russian and English.
- Future content tasks must produce RU/EN/AM variants.

Why this is signal:

• it changes scope;
• it affects future tasks;
• it prevents wrong assumptions;
• it avoids reading the old chat.

A bad diary point:

- Changed button spacing and adjusted some text.

Why this is noise:

• no durable consequence;
• unclear where and why;
• it does not help the next session;
• it looks like changelog or commit detail.

Write Diary As A Persistence Gate

Write Diary acts as a persistence gate. Its job is not to "write something"; its job is to decide whether information deserves persistence.

Algorithm:

collect candidate facts
classify durable vs non-durable
drop cosmetic/noisy facts
merge with existing daily note
update decisions if a durable decision exists
update current only if snapshot changed
compact if limits are close

The most important outcome sometimes looks like this:

No durable diary update needed.

That is not a failure. It is entropy control.

Read Diary As Context Warm-Up

Read Diary should not become a full project scan. Its job is to warm up a new session with the smallest set of high-signal files.

Default startup read:

diary/README.md
diary/current.md
diary/decisions.md
latest 2-3 diary/days/*.md

Why not read everything:

• old daily notes may be superseded;
• decisions have already been moved into a separate file;
• the current snapshot should contain the latest truth;
• reading all history breaks token economy.

If historical investigation is needed, the user can request a date range explicitly:

Read Diary from 2026-05-15 to 2026-05-18

Token Economy

The purpose of the diary is not to add another mandatory document. The purpose is to reduce the cost of context restoration.

Correct token economy looks like this:

The diary saves tokens only while it stays:

• compact;
• selectively read;
• non-duplicative with plans and summaries;
• free of cosmetic noise;
• regularly compacted;
• clear about decisions vs daily notes.

If the diary is read in full every time, it stops being a memory optimization and becomes memory overhead.

Failure Modes

Implementation Checklist

Minimal implementation:

1. Create global skill project-diary-write.
2. Create global skill project-diary-read.
3. Integrate project-diary-write into end-session.
4. Integrate project-diary-read into new-session.
5. Allow Write Diary to create diary/ on the first durable update.
6. Prevent new-session from creating diary/.
7. Keep current.md as a short snapshot.
8. Move durable decisions into decisions.md.

Implementation checks:

end-session must invoke Write Diary
new-session must invoke Read Diary
Read Diary must not write files
Write Diary must be allowed to say "no update needed"
daily files must not become append-only transcripts

Extended Routing Example

Fact: "Added Armenian as a required locale"
Route:
  days/YYYY-MM-DD.md -> Changes
  decisions.md -> D-YYYYMMDD-001
  current.md -> Supported languages/locales

Fact: "Changed button color"
Route:
  none

Fact: "All destructive actions now use danger style"
Route:
  decisions.md -> durable design decision
  AGENTS.md -> only if this is a permanent repo convention

Fact: "Next step is to finish sitemap"
Route:
  plan file, if part of a plan
  Carry Forward, if it is a short daily continuation item

Quality Criterion

The diary works correctly if a new AI session can understand:

• what is true now;
• what changed recently;
• which decisions must not be casually reopened;
• what was verified;
• where to look next;
• which recent facts matter but are not permanent project rules yet.

If a note does not help with this, it should not be written.