176 lines
4.2 KiB
Markdown
176 lines
4.2 KiB
Markdown
# Cross-Session Patterns
|
|
|
|
Persisting state across conversation sessions using episodic memory.
|
|
|
|
## The Session Boundary Problem
|
|
|
|
Tasks survive **context compaction** but not **session boundaries**. When a conversation ends:
|
|
- Task state is gone
|
|
- Agent IDs are invalid
|
|
- Decisions are forgotten
|
|
|
|
For work spanning multiple sessions, use episodic memory MCP server.
|
|
|
|
## When to Use Cross-Session Persistence
|
|
|
|
**Use episodic memory when**:
|
|
- Project spans multiple days
|
|
- Complex refactor with many steps
|
|
- Work will be interrupted (meetings, context switches)
|
|
- Handing off to another agent or future self
|
|
- Key decisions need to survive sessions
|
|
|
|
**Just use Tasks when**:
|
|
- Single-session task
|
|
- Work completes within conversation
|
|
- No significant decisions to preserve
|
|
|
|
## Saving Session State
|
|
|
|
At session end or before extended pause:
|
|
|
|
```json
|
|
{
|
|
"tool": "episodic-memory:save",
|
|
"content": {
|
|
"project": "auth-refresh-implementation",
|
|
"timestamp": "2024-01-15T14:30:00Z",
|
|
"status": "in_progress",
|
|
"completed": [
|
|
"JWT validation logic",
|
|
"Refresh endpoint structure",
|
|
"Token claims extraction"
|
|
],
|
|
"remaining": [
|
|
"Token rotation logic",
|
|
"Refresh window handling",
|
|
"Integration tests",
|
|
"Security review"
|
|
],
|
|
"decisions": {
|
|
"library": "jose (already in deps)",
|
|
"algorithm": "RS256 (per existing patterns)",
|
|
"refresh_window": "5 minutes before expiry",
|
|
"rotation": "enabled (single-use refresh tokens)"
|
|
},
|
|
"files_modified": [
|
|
"src/auth/refresh.ts",
|
|
"src/auth/middleware.ts",
|
|
"src/auth/types.ts"
|
|
],
|
|
"current_focus": {
|
|
"file": "src/auth/refresh.ts",
|
|
"line": 42,
|
|
"task": "Implement rotateToken() function"
|
|
},
|
|
"blockers": [],
|
|
"notes": "Using existing JWKS endpoint at /api/auth/.well-known/jwks.json"
|
|
}
|
|
}
|
|
```
|
|
|
|
## Restoring Session State
|
|
|
|
At new session start:
|
|
|
|
```json
|
|
{
|
|
"tool": "episodic-memory:search",
|
|
"query": "auth refresh implementation"
|
|
}
|
|
```
|
|
|
|
Then:
|
|
1. Read the returned state
|
|
2. Reconstruct tasks from saved data using `TaskCreate`
|
|
3. Resume from `current_focus`
|
|
|
|
## What to Save
|
|
|
|
| Category | Why |
|
|
|----------|-----|
|
|
| Completed work | Know what's done |
|
|
| Remaining work | Know what's left |
|
|
| Decisions made | Don't re-decide |
|
|
| Files modified | Know where changes live |
|
|
| Current focus | Resume exactly |
|
|
| Blockers | Know what's blocking |
|
|
| Notes | Context that might be needed |
|
|
|
|
## What NOT to Save
|
|
|
|
- Full file contents (they're in the repo)
|
|
- Detailed reasoning (too verbose)
|
|
- Every intermediate step (only milestones)
|
|
- Transient state (temp variables, debug output)
|
|
|
|
Save the **minimum needed to resume**.
|
|
|
|
## Hooks for Auto-Persistence
|
|
|
|
Configure hooks to auto-save state at session boundaries:
|
|
|
|
```json
|
|
{
|
|
"hooks": {
|
|
"PreToolUse": [
|
|
{
|
|
"matcher": {
|
|
"tool": "exit"
|
|
},
|
|
"action": "Save session state to episodic memory"
|
|
}
|
|
]
|
|
}
|
|
}
|
|
```
|
|
|
|
See outfitter's **claude-hooks** skill for hook configuration details.
|
|
|
|
## Multi-Day Project Pattern
|
|
|
|
For longer projects:
|
|
|
|
**Day 1 (end)**:
|
|
|
|
```json
|
|
{
|
|
"project": "api-redesign",
|
|
"stage": "research",
|
|
"completed": ["Identified 12 endpoints", "Documented current patterns"],
|
|
"remaining": ["Design new patterns", "Plan migration"],
|
|
"key_findings": "Inconsistent error handling across endpoints"
|
|
}
|
|
```
|
|
|
|
**Day 2 (start)**: Search for "api-redesign"
|
|
**Day 2 (end)**:
|
|
|
|
```json
|
|
{
|
|
"project": "api-redesign",
|
|
"stage": "design",
|
|
"completed": ["New error pattern designed", "Migration strategy outlined"],
|
|
"remaining": ["Implement error utilities", "Migrate endpoints"],
|
|
"decisions": {"error_format": "RFC 7807 Problem Details"}
|
|
}
|
|
```
|
|
|
|
**Day 3**: Search, see full history, continue implementation.
|
|
|
|
## Integration with External Trackers
|
|
|
|
Episodic memory is your **session-level** state. External trackers handle **project-level** state:
|
|
|
|
| Tool | Scope | When to Update |
|
|
|------|-------|----------------|
|
|
| Tasks | Within conversation | Every task completion |
|
|
| Episodic memory | Across sessions | Session boundaries |
|
|
| Linear/GitHub | Project lifetime | Stage completions |
|
|
|
|
Workflow:
|
|
1. Pull task from Linear/GitHub
|
|
2. Track in Tasks during session
|
|
3. Save to episodic memory at session end
|
|
4. Update Linear/GitHub at stage completion
|