Use The Daily Calendar

How to use the daily calendar

Note

Status: implemented — shipped by filing v2 part 5, "the calendar" (v9.15.0, PR #548). Goal: Record a diary line or a facet entry for today in the vault's daily register, and correct one you logged wrong on a day that's already closed. Prereqs: Calendar/ exists at the vault root (or beside the memory root in a nested Obsidian layout) — create it once, by hand; the scripts discover the register, they never create it. A resolvable memory root to pass as --vault.

Calendar/YYYY/ is the agent-maintained daily register: one note per day per facet — meetings, correspondence, docs, diary — created only on a day that had content for it, plus a generated day index over whatever exists. diary is the zero-bar catch-all: anything worth a line that doesn't fit a standing facet lands there. See AgentM Filing v2 § The calendar for the original design, and AgentM Vault § the layout for the year map and the bare-date day index's retirement (agentm-vault plan 07).

Steps

1. See what facets are registered.

   python3 harness/skills/memory/scripts/calendar_facets.py --vault <memory-root> facets

   Prints the contract's registry, one per line — meetings, correspondence, docs, diary unless standards/storage-rules.md names others.

2. Record today's diary line. From a session, /memory diary "<text>" is the front door — it wraps the same writer below and prints the same thing. Calling the script directly works identically:

   python3 harness/skills/memory/scripts/calendar_facets.py --vault <memory-root> quick --text "a diary line for today"

   Creates Calendar/YYYY/YYYY-MM-DD-diary.md on first use that day, or appends a new timestamped paragraph to it. Prints created ... or appended ... naming the path written, relative to the vault root. quick always writes to today — it takes no --day.

3. Log a specific facet instead of the diary. From a session: /memory diary --facet meetings "Sync about the release." (add --day YYYY-MM-DD to name a different open day). Calling the script directly works the same way:

   python3 harness/skills/memory/scripts/calendar_facets.py --vault <memory-root> append --facet meetings --text "Sync about the release."

   Same append-only behavior, under Calendar/YYYY/YYYY-MM-DD-meetings.md. --day YYYY-MM-DD names a different day; a day before today refuses (see Troubleshooting) — append only ever adds to a day that's still open, and /memory diary refuses the same way.

4. Check the day index. It regenerates automatically after every append or correction, so this step is for inspection, not required:

   python3 harness/skills/memory/scripts/calendar_index.py --vault <memory-root> --day YYYY-MM-DD --dry-run

   Lists whichever facet notes exist for that day, each with a context phrase and its entry count, plus the day's episodic session traces and system digest when either exists. A day with nothing recorded has no index at all — --dry-run prints (nothing on YYYY-MM-DD) rather than an empty file.

   An episodic session trace is the agent's own memory of one session: one kind: session-trace note under memory/episodic/, written at session end by the Stop hook from the transcript and the recall history, no model call. Its title is the session's first request (a line the host wrote, such as a bracketed [Image: …] annotation or the desktop app's resume notice, is skipped); the body carries up to five sections, each omitted when empty — ## Asked (the request in full), ## Outcome (the session's own closing recap), ## Captured and ## Recalled as wikilinks (a recalled name is linked only when a note of that name exists in the vault), and ## Candidates — every line the miner mined but did not file as a note below HIGH confidence, kept as the rule that fired, an excerpt, and a count (Trace.render, harness/skills/memory/scripts/episodic_trace.py:124-168). Frontmatter carries touched: (renamed from entities:) and, since both Stop hooks now pass --surface, a surface: field naming where the session ran (e.g. claude-code); both sit after the read fields the trace shares with a card, in the card's own order (agentm-vault § The card). A session that left nothing to record — nothing touched and no candidates either — leaves no trace file at all (write_trace, episodic_trace.py:589-613), so a quiet day's index links few or none.

5. See this week's or this month's review. Weekly and monthly reviews are written by the dreaming binary's calendar job, on its own cadence — not something you run by hand day to day. -force skips the binary's own gate and previews a pass right now; add -apply to actually write:

   "$HOME/.local/bin/agentmdream" run -force -apply

   Writes Calendar/YYYY/YYYY-Www-review.md for every closed ISO week in the trailing eight, and Calendar/YYYY/YYYY-MM-review.md for the running month and the one before. A review is written only for a period with something recorded in it, and only when its text changed. A facet note counts when it holds a timed entry or prose beyond the daily template, and a day of prose alone is listed without an entry count. A review's day lines link each day's own facet notes ([[YYYY-MM-DD-facet|facet]] (N)), never a bare-date day link. The same pass also keeps Calendar/moc-calendar-YYYY.md beside each year with a facet note — that year's facet notes, newest day first under a heading per month — rewritten only when its text changes (agentm-vault plan 07). Drop -apply to preview what a pass would do without writing anything. The Python rollups CLI (calendar_rollups.py) retired with the takeover (filing v2 part 6, 2026-09-05); this is how you generate a review now.

6. Correct a day that's already closed. A plain append only ever targets today or a later day you name; naming a day before today with --day raises ClosedDay rather than silently editing the past:

   python3 harness/skills/memory/scripts/calendar_facets.py --vault <memory-root> correct --facet meetings --day 2026-09-03 --text "The release is Thursday, not Friday."

   Writes a new note dated today — e.g. 2026-09-04-meetings-corrects-2026-09-03.md — carrying corrects: and supersedes: back to the original, which stays byte-for-byte as it was. Both days' indexes show the correction.

Verify

• scripts/test_calendar_facets.py covers append-only behavior, the closed-day refusal, and the unknown-facet refusal.
• scripts/test_calendar_corrections.py covers correct() end to end — the new note's frontmatter, the untouched original, and both days' regenerated indexes.
• scripts/test_calendar_index.py covers the generated index: byte-stable regeneration, the empty-day no-index case, and the episodic-traces and digest sections.

Troubleshooting

• error: nothing to record: the text is empty — --text was blank or whitespace-only. Nothing is written.
• ... is closed; the register is corrected by a new dated entry, never by an edit into the past — you passed append --day naming a day before today. Use correct instead (step 6).
• facet '...' is not registered; the register carries ... — the facet named isn't in the contract's registry. Adding one is an edit to standards/storage-rules.md, never a call-site improvisation. Once a diary label recurs on three or more distinct days in thirty, the nightly dream cycle proposes it in the needs-review page's Proposed facets section, and registering it stays your edit (see Review flagged memories and AgentM Filing v2 § The calendar).
• no Calendar/ space beside <vault>: the register is discovered, never conjured — Calendar/ doesn't exist yet at the vault root (or the vault root above a nested memory root). Create the directory once, by hand; nothing in this feature creates it for you.

See also

• AgentM Filing v2 § The calendar — the original design: why the register is discovered rather than created, the rollup cadence, and the facet-promotion rationale.
• AgentM Vault § the layout — the year map, and why the bare-date day index retired (agentm-vault plan 07).
• Memory daemon reference — the facets and calendar record_kinds contract vocabulary.
• Memory daemon reference § the dreaming binary — agentmdream's gate, lock, journal, and its jobs in order, including calendar.
• CI gates reference § check-calendar-root — the shape the calendar root is held to, including the year map.
• Vault write protocol — the lock and atomic-write primitives the calendar's own writer shares with the rest of the vault.