session-memory

# Session Memory - Running Notes

Maintain a single structured markdown document that tracks what is happening
**right now** in the current work session. This is within-session continuity,
distinct from `remember()` (cross-session semantic memory) and `stash`
(coarse checkpoint).

## When to Use

Invoke on any of these triggers:

- User says "session notes", "update notes", "start session notes",
  "show session notes", "note the session", "write it down"
- User indicates they want continuity across context compression:
  "before you forget", "write that down", "for when context gets compressed"
- You have independently completed a meaningful block of work (file edits,
  a bugfix, a design choice, a reversal after correction) and no note has
  been updated for a while

Do NOT invoke for:

- One-off answers with no follow-up
- Cross-session persistence — that's `remember()`
- Coarse checkpoints intended for another session to resume — that's `stash`

## Template (Fixed Sections)

Every session note uses exactly these sections, in this order, with these
headers. **Preserve the structure on every update. Never rename or reorder
sections.** Update the *content* within sections; leave empty sections present
with a single `_(nothing yet)_` placeholder.

```markdown
# Session: {short title, 3-8 words, derived from the initial task}

## Current State
_What is actively being worked on right now. Explicit next step._

## Task Specification
_What the user originally asked for. Constraints, acceptance criteria,
design decisions that framed the work._

## Files and Functions
_Important paths touched or referenced, one per line, with a one-line
note on what they contain and why they matter._

## Errors & Corrections
_Errors encountered and how they were fixed. User corrections to my
approach — these have priority over routine progress entries._

## Key Decisions
_Choices made during the session with their rationale. One bullet per
decision. Lead with the choice, then the why._

## Worklog
_Terse, append-only, chronological. One line per attempt or step.
Prefix with ✓ (done), ✗ (failed), → (in progress), or ↺ (reverted)._
```

## Storage

Persist as a `procedure` memory via the `remembering` skill, so notes
survive container death within the session thread.

```python
from remembering.scripts import remember, recall, supersede

# First write in a session: create the memory
note_id = remember(
    note_markdown,
    "procedure",
    tags=["session-memory", "active"],
    priority=1,
)

# Subsequent updates: find the active note and supersede it
existing = recall(tags_all=["session-memory", "active"], n=1)
if existing:
    note_id = supersede(existing[0].id, updated_markdown, "procedure",
                        tags=["session-memory", "active"], priority=1)
```

**Session boundary:** when the user says "session done", "wrap up",
"end session", or the conversation is clearly winding down, retag the
active note from `active` to `archived` by superseding it with the same
body and `tags=["session-memory", "archived"]`.

One note is active at a time. If `recall(tags_all=["session-memory",
"active"])` returns more than one, the oldest is stale — archive it before
updating the current one.

## Update Discipline

On each invocation:

1. **Read the existing note** (if any) via `recall(tags_all=["session-memory",
   "active"], n=1)`. Work from its current body — do not regenerate from
   scratch.
2. **Update in place.** Edit the relevant sections; append to `## Worklog`.
   Do not drop prior content unless it is now wrong (then move the correction
   to `## Errors & Corrections`).
3. **Prioritize user corrections.** When the user pushes back or corrects an
   approach, that goes into `## Errors & Corrections` *before* other updates.
4. **Deduplicate against stash and explicit memories.** If an item is already
   captured in a stash or a `remember()` call, reference it by ID rather
   than restating. Notes are *supplementary*, not duplicative.
5. **Supersede, don't append.** Write the full updated document back via
   `supersede()`. This keeps exactly one active note per session.

## Budget

Target ~12K tokens for the note document. Prefer concise phrasing, but do
not truncate substantive content to hit the target — trigger
`## Key Decisions` consolidation (collapse related bullets) before cutting.
If the document exceeds ~20K tokens, compress `## Worklog` first (merge
consecutive ✓ entries into a single summary line, keep corrections and
decisions intact).

*Rationale: we run on 200K–1M context models, so the original 2K budget
from the issue spec was over-constrained. 12K matches Claude Code's
upstream design and leaves ample room for the surrounding conversation.*

## Surface to User

When the user asks to "show session notes", print the current note body
verbatim in a fenced code block. Do not paraphrase.

When updating silently (you triggered it yourself), confirm with a single
line: `Updated session notes (note id: <short-id>).` Do not dump the full
body unsolicited.

## Invariants

- Section headers and order are fixed. Updates change content, not structure.
- User corrections take priority over routine progress in ordering and detail.
- Notes do not duplicate what is already in stash or explicit memories.
- Manual invocation always works. Automatic triggers are a convenience, not
  a requirement.
- Exactly one `session-memory + active` memory exists per session. Stale
  actives are archived, not left dangling.

## Related

- `remembering` — cross-session memory store (where these notes persist)
- stash-resume-protocol (ops) — coarse session checkpoints
- context-hygiene (ops) — when and what to offload from context