| name | session-management |
| description | Read on session start. Tracks work progress in session files during conversations. Use when recording milestones, decisions, blockers, or when the session-start hook creates a session file. |
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
| Session file | Memory tree |
|---|
| Ephemeral — deleted or archived when no longer active | Durable — persists across all sessions |
| Tracks current task progress | Tracks stable project understanding |
| Milestone-oriented log entries | Fact-oriented structured files |
| Private to one conversation thread | Shared across all agents and conversations |
| Write freely, prune aggressively | Write carefully, never speculate |
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
- Read the current session file first.
- If nothing meaningful happened since the last log entry, do not write.
- If a meaningful milestone occurred, write one checkpoint:
- Refresh Current State
- Update Completed / In Progress / Blockers
- Add one timestamped Session Log line
- Set the session title once the task is clear.
- 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:
- Identify the durable fact (decision, pattern, gotcha, lesson)
- Write it to the relevant
agent-knowledge/Memory/<area>.md
- For architectural decisions: use the
decision-recording skill
- 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)
