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.