robotaitai/project-bedrock/session-management

Session Management

Session files preserve in-progress context through long sessions and help new sessions resume quickly from prior work.

The session file path is provided by the session-start hook (e.g., ~/.cursor/projects/<project-id>/sessions/). For project-shared session notes, use agent-knowledge/Sessions/.

Session vs memory — the key distinction

Rule: if a fact belongs to future sessions, it goes in memory. If it only matters for this session, it stays in the session file.

Session file format

Filename: YYYY-MM-DD-<title-slug>-<UUID>.tmp (slug defaults to session until the task is clear, then updated)

## Current State
[One-line description of current focus]
 
### Completed
-[Milestone outcomes, not step-by-step details]
 
### In Progress
-[What is actively being worked on]
 
### Blockers
-[What is preventing progress]
 
### Notes for Next Session
-[What to load immediately when resuming]
 
### Context to Load
-[Which memory areas and files to read on resume]
 
## Session Log
**HH:MM** - [Milestone outcome in one line]

How to update

1. Read the current session file first.
2. If nothing meaningful happened since the last log entry, do not write.
3. If a meaningful milestone occurred, write one checkpoint:

• Refresh Current State
• Update Completed / In Progress / Blockers
• Add one timestamped Session Log line

1. Set the session title once the task is clear.
2. Keep entries milestone-oriented — not every tool call.

When NOT to write

• Between sequential tool calls in the same task
• For trivial progress (e.g., reading a file, minor edits)
• When the hook fires but no real milestone occurred

Writeback gate — before closing a session

Before ending a session with meaningful output, check:

Did this session change durable project understanding?

If yes — follow the memory-writeback rule:

1. Identify the durable fact (decision, pattern, gotcha, lesson)
2. Write it to the relevant agent-knowledge/Memory/<area>.md
3. For architectural decisions: use the decision-recording skill
4. Once written to memory, remove or summarize it in the session file (avoid duplication)

If no meaningful new project understanding was produced — no writeback needed. State this explicitly:

Memory writeback: none needed (no new durable facts this session).

Examples that should NOT trigger writeback:

• Progress within one task but no stable new conclusion
• Temporary debugging state
• Notes that only matter to the current conversation
• Evidence review that did not change curated understanding

Session log entry format

**HH:MM** - [Milestone outcome in one line]

Example:

**14:32** - bootstrapped memory tree (hybrid profile, 5 area files created)
**15:10** - backfill complete: stack, architecture, gotchas populated from git history
**15:45** - decision recorded: use-raw-sql (decisions/2025-01-15-use-raw-sql.md)