Diary

📓 Diary: Logging Session...

Document what was accomplished in each CC session for future recall.

Activation

When this skill activates, output:

📓 Diary: Logging session...

Then execute the protocol below.

Context Guard

When NOT to Fire

• Do NOT fire autonomously. Only activate when the user explicitly requests it ("save diary", "log session", "wrapping up").
• Multi-agent sessions: If you are operating as Builder, Reviewer, or any non-Manager agent in a multi-agent session, do NOT fire diary. Only the Manager or a standalone session should trigger diary.
• No work done: If no meaningful changes were made (no commits, no file edits), skip diary.

Reminders

When the user asks to save a diary, keep these in mind:

Protocol

Never pass a JSON payload as a quoted command-line argument. Write it to a file and pipe it in with the dash sentinel, as every command below shows. On Windows, cmd.exe treats single quotes as ordinary characters, so a redirection operator anywhere in a quoted payload is executed rather than passed.

All JSON field values must be plain strings. Never pass arrays or objects. If multiple items (files, commits, decisions), join them as a comma-separated string.

1. Summarize the session:

   • Project name and working directory
   • Date and approximate duration
   • What was built or changed
   • Key files created or modified
   • Commits made (hashes and messages)
   • Decisions made and why
   • Problems encountered and solutions

2. Check git log for commits:

   git log --oneline -10

3. Format the diary entry:

   # Session Diary: {project}, {date}
   
   ## Accomplished
   - Item 1...
   
   ## Files Changed
   - path/to/file.ts: description
   
   ## Commits
   - abc1234 Message
   
   ## Decisions
   - Decision: reason
   
   ## Next Steps
   - What to do next
   
   ## Session Handoff
   **In Progress:** [what was actively being worked on when session ended]
   **Uncommitted Changes:** [list any unstaged/uncommitted work, or "None"]
   **Pick Up Here:** [exact instruction for next session, specific enough to start cold]
   **Session Context:** [anything important that isn't captured elsewhere: temp decisions, debugging state, gotchas discovered]

4. Save to SQLite database (primary storage):

   Write the payload to a file, then pipe it in with - as the argument. A payload on stdin is never seen by the shell's parser, so a redirection operator inside your prose cannot be read as one.

   cat session.json | python "${CLAUDE_PLUGIN_ROOT}/db/memstack-db.py" add-session -

   The store is ~/.memstack/memstack.db, one file per user, never a file beside the script. Every command prints the path it used on stderr as memstack-db: store <path>, so a session can confirm where it wrote instead of assuming.

   The SQLite row is the primary store. The markdown in memory/sessions/ is a backup export. The row holds the full raw_markdown, so a markdown file that is lost, truncated or overwritten can be restored from it: find the row in the sessions table by project and date, and write raw_markdown back to the file. This matters because memory/ is gitignored, so version control is not a fallback and the database is the only one there is.

   session.json contains:

   {"project":"<name>","date":"<YYYY-MM-DD>","accomplished":"<bullets>","files_changed":"<bullets>","commits":"<bullets>","decisions":"<bullets>","problems":"<bullets>","next_steps":"<bullets>","duration":"<estimate>","raw_markdown":"<full text>"}

5. Save insights for cross-project search:

   Same form: write the payload to a file, pipe it in, - as the argument. Insight text is prose, so it must never travel on the command line.

   cat insight.json | python "${CLAUDE_PLUGIN_ROOT}/db/memstack-db.py" add-insight -

   insight.json contains:

   {"project":"<name>","type":"<type>","content":"<insight>","context":"Session <date>","tags":"<project>"}

   Choose <type> deliberately from this vocabulary, do not default to one:

   • gotcha: something that bit us and the fix. Non-obvious behavior a future session would trip on again.
   • lesson: a general rule learned the hard way. Broader than one bug.
   • pattern: a reusable approach or convention that worked.
   • warning: a known hazard to avoid. Not yet a bug, but will be.
   • failed_approach: something tried that did not work, and why. Prevents retrying it.
   • architecture: a structural fact about how a system is built.
   • decision: a choice made and the reasoning. Historical record.

   The first five are procedural: an agent can act on them at retrieval time. architecture and decision are record. When a row could be either, prefer the procedural type.

   Unknown types pass through unchanged but come back as type_unknown in the JSON response, that is the signal to pick a type from the list above.

   CRITICAL: The field name is "content", NOT "insight". Using "insight" will fail with a missing required field error.

6. Update project context with last session date:

   Same form, even though this payload is only metadata. One rule with no exceptions is easier to follow than a rule you have to judge.

   cat context.json | python "${CLAUDE_PLUGIN_ROOT}/db/memstack-db.py" set-context -

   context.json contains:

   {"project":"<name>","last_session_date":"<YYYY-MM-DD>"}

7. Also save a markdown copy to memory/sessions/, under a name nothing already occupies. Append a ## FACTS block (see below) as the last section of this markdown.

   Compute the filename immediately before writing it, not at the start of the task. List memory/sessions/ and take the first free name:

   Attempt	Name
   1st diary of the day for this project	{date}-{project}.md
   2nd	{date}-{project}-2.md
   3rd	{date}-{project}-3.md

   There is no -1: the plain name is the first, so the numbers you see in the directory match how many diaries exist for that day.

   The check has to happen at the moment of the write because a session can run for hours, and another session, or an agent run, can file a diary for the same project in between. A name that was free when the task started is not evidence that it is free now.

   Never write over an existing file. If the name you computed exists when you go to write it, stop and report it rather than writing. Do not overwrite, do not append, do not pick a name by guessing. A diary is another session's only human-readable record, and the Write tool reporting "updated" instead of "created" is the only warning you will get, which is far too quiet to rely on.

   A suffixed filename changes step 8. diary_ingest derives the project namespace from the filename, so 2026-09-06-myproject-2.md derives myproject-2, which ingests cleanly, exits 0, and is invisible to every recall for the real project. Whenever the name carries a -N suffix, pass --project explicitly.

8. Ingest the FACTS block into the Memory Engine, right after the markdown is written:

python -m memstack_skill_loader.diary_ingest "memory/sessions/{the name you just wrote}" --project {project}

This parses the ## FACTS block and stores each fact with source_type='diary'.

Read the summary it prints. This step is not fire-and-forget. It reports memory-ingest: N ingested, M duplicate, K skipped into project 'NAME': PATH on stdout, followed by one indented reason per skipped line naming the line number and what was wrong with it. NAME is the namespace the facts were actually written to, derived from the diary's filename, and it is the part to check: a diary filed under an unintended project ingests cleanly and exits 0 while staying invisible to every recall for the real one. When no fact has ever been stored under that namespace the line reads into NEW project 'NAME', which is the cheapest signal that derivation landed somewhere unintended. Pass --project NAME to skip filename derivation entirely when the derived name would be wrong. The exit code classifies the outcome:

If K is not 0, fix those lines in the markdown and run the command again. A skipped line is a fact this session was supposed to hand to the next one and did not, and the most common cause is a | inside a claim. Re-running is safe: facts dedupe on source + subject + claim, so anything already stored comes back as a duplicate rather than being written twice.

A non-zero exit never means the diary failed to save. The markdown and the SQLite row are already written by this point, and ingestion cannot undo them.

FACTS Block: Cross-Session Memory

The ## FACTS block is how a session hands durable, atomic knowledge to future sessions. It is machine-parsed, so the format is fixed. One fact per line:

subject | claim | method [| entities]

• subject: a dotted-path namespace, lowercase (e.g. memstack.dashboard.start, adminstack.portal.auth). Group related facts under a shared prefix.
• claim: exactly one assertion. Keep it self-contained. Must not contain a |.
• method: how you know it, one of: verified (you saw it work / read the code / ran it), reported (stated but unconfirmed), inferred (deduced), assumed (a guess: scored lowest).
• entities: optional 4th field: comma-separated tags this fact touches.