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:6379Start 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 logcurrent.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 statedecisions.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)
- Write
current.mdwith all sections filled - Copy to
archive/YYYY-MM-DD.md - Update
decisions.mdwith any new decisions - Verify file written:
cat .context/current.md | head -5
Restore (Start of Session)
- Read
.context/current.md - Read
.context/decisions.md - Verify environment matches (runtime versions, services)
- Check file map:
git statusvs expected state - Resume from "In Progress" section
Context Switch (Between Projects)
- Save current project context
- Load target project context
- 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.mdbecomes 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