4.2 KiB

Raw Blame History

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:

{
  "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:

{
  "tool": "episodic-memory:search",
  "query": "auth refresh implementation"
}

Then:

Read the returned state
Reconstruct tasks from saved data using TaskCreate
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:

{
  "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):

{
  "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):

{
  "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:

Pull task from Linear/GitHub
Track in Tasks during session
Save to episodic memory at session end
Update Linear/GitHub at stage completion

4.2 KiB Raw Blame History