Session Context Bridge

Session Context Bridge

> Never start from zero. Carry context across sessions automatically.

The Problem

Every new session starts blind. You lose:

What you were working on yesterday

Decisions made and why

Unfinished tasks and their state

Environment details (paths, configs, credentials setup)

Relationships between files and projects

Claude-mem (65K stars) proved this is a massive need. This is the lightweight, framework-agnostic version.

When to Use

"save my context", "restore session", "continue from yesterday"

End of every working session

Start of every new session

Before context-switching between projects

How It Works

End of Session: Save

## Session Context — 2026-04-22 03:00
Active Task
Building API endpoint for user onboarding
Status: 70% complete, auth middleware done, tests pending
Key Decisions
1. Chose JWT over session cookies (reason: mobile-first, stateless)
2. Rate limiting: 100 req/min per user
3. Database: PostgreSQL with UUID primary keys
File Map
src/auth/middleware.ts — JWT validation (DONE)
src/routes/onboarding.ts — Main endpoint (IN PROGRESS, line 47)
tests/onboarding.test.ts — Not started
prisma/schema.prisma — User model updated
Blockers
Waiting on design team for email template
Need staging database credentials from DevOps
Environment
Node v22.22.2, pnpm 10.28
DATABASE_URL in .env (not committed)
Redis running on localhost:6379

Start of Session: Restore

## Restoring Context from 2026-04-22 03:00
Resume Point
→ Continue src/routes/onboarding.ts at line 47
→ Next: implement email verification flow
→ Then: write tests
Context Loaded
3 key decisions loaded
File map: 4 files
2 blockers noted
Environment confirmed
Ready to continue.

Context File Structure

project/
├── .context/
│   ├── current.md        ← Active session context (always up-to-date)
│   ├── archive/
│   │   ├── 2026-04-20.md ← Previous sessions
│   │   └── 2026-04-21.md
│   └── decisions.md      ← Long-running decision log

current.md Template

# Session Context
> Last updated: [TIMESTAMP]
🎯 Active Task
[What you're working on right now]
✅ Completed This Session
[x] Task 1
[x] Task 2
🔄 In Progress
[ ] Task 3 (status: ___)
📋 Todo (Next Session)
[ ] Task 4
[ ] Task 5
🧠 Key Decisions
1. [Decision] — [Reason]
📁 File Map
| File | Status | Notes |
|------|--------|-------|
| path/to/file | DONE/WIP/TODO | Description |
🚧 Blockers
[What's blocking you]
🔧 Environment
Runtime versions
Active services
Config state

decisions.md Template

# Decision Log
> Architectural and design decisions with reasoning.
[DATE] — [Decision Title]
Decision: [What was decided]
Context: [What was the situation]
Reason: [Why this option was chosen]
Alternatives: [What else was considered]
Revisit if: [Conditions that might change this decision]

Bridge Protocol

Save (End of Session)

1. Write current.md with all sections filled 2. Copy to archive/YYYY-MM-DD.md 3. Update decisions.md with any new decisions 4. Verify file written: cat .context/current.md | head -5

Restore (Start of Session)

1. Read .context/current.md 2. Read .context/decisions.md 3. Verify environment matches (runtime versions, services) 4. Check file map: git status vs expected state 5. Resume from "In Progress" section

Context Switch (Between Projects)

1. Save current project context 2. Load target project context 3. Note: different .context/ directories per project

Anti-Patterns

❌ Writing novels — context should be scannable in 30 seconds

❌ Including raw output — summarize, don't copy-paste

❌ Forgetting environment state — "works on my machine" starts here

❌ Only saving when done — in-progress state is MORE valuable

❌ Not archiving — current.md becomes useless without history

Integration with Existing Tools

OpenClaw: Context files auto-loaded via workspace

Claude Code: Use as CLAUDE.md supplementary context

Cursor: Map to .cursor/rules/context.mdc

Generic: Works with any agent that can read files

License

MIT