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