AI Context System

Appearance

SESSIONS.md - Session History ​

What happened when. Chronicles project evolution with AI mental models, decision-making processes, and problem-solving approaches.

Purpose ​

SESSIONS.md answers: "How did this project evolve? What did we learn along the way?"

It documents:

  • Session timeline - Chronological development history
  • AI mental models - What AI understood at each point
  • Problem-solving approaches - How challenges were tackled
  • Decisions made - What was decided in each session
  • Files changed - What code was modified
  • Git operations - Commits and pushes (auto-logged)

Goal: Complete project history that enables session continuity, AI handoffs, and learning from past work.

Why This Matters ​

For Session Continuity ​

Problem: AI forgets what happened in previous sessions.

Solution: Read last session entry to restore context.

Example:

markdown
## Session 12 | 2025-10-23 | Stripe Webhook Implementation

**Mental Models:**
- Webhook receives payment_intent.succeeded from Stripe
- Need idempotency keys to prevent duplicate processing
- Database transaction updates order status (pending → confirmed)
- Redis caches order for fast lookup

Result: Next session reads this, AI knows exactly where things left off.

For AI-to-AI Handoffs ​

Problem: New AI agent doesn't know project history.

Solution: Read SESSIONS.md chronologically to understand evolution.

Example: New AI reads:

  • Session 1: Initial setup, chose Next.js
  • Session 5: Added authentication, chose JWT
  • Session 10: Integrated payments, chose Stripe
  • Session 15: Optimized database, added indexes

Result: New AI understands full context, makes consistent decisions.

For Human Review ​

Problem: Humans want to understand AI's thought process.

Solution: Read mental models and problem-solving approach.

Example:

markdown
### Problem-Solving Approach

**Challenge:** N+1 query problem causing slow /api/projects endpoint (1.2s)

**Investigation:**
1. Added query logging → discovered 100+ SELECT queries per request
2. Identified: fetching tasks individually for each project
3. Root cause: Missing eager loading in Prisma query

**Solution Explored:**
- Option A: Add .include({ tasks: true }) (simple but loads all task data)
- Option B: Separate query with IN clause (more control)
- Option C: DataLoader pattern (complex, overkill for our scale)

**Implemented:** Option A with select to limit fields
**Result:** 1.2s → 120ms (10x improvement)
**Tradeoff:** More memory per request, but acceptable at current scale

Result: Human understands exactly how AI solved the problem.

For Learning from History ​

Problem: Make same mistakes repeatedly.

Solution: Review past sessions to learn patterns.

Example: Reading Session 8:

markdown
**Mistakes Made:**
- Assumed API would return array, actually returns object
- Spent 30 minutes debugging before checking API docs
- **Lesson:** Always verify API response shape with actual call first

Result: Future work checks API responses upfront.

File Structure ​

Session Entry Format ​

markdown
## Session [N] | YYYY-MM-DD | [Brief Title]

**Duration:** Xh | **Focus:** [Main goal] | **Status:** ✅ Complete / 🔄 In Progress / ⏸️ Paused

### TL;DR
[2-3 sentence summary of session - what was accomplished, key decisions, current state]

### Session Goals
- [ ] Goal 1
- [x] Goal 2 (completed)
- [ ] Goal 3 (partially done)

### Mental Models

**Current understanding:**
[What AI understands about the system at this point]

**Architecture understanding:**
[How components fit together]

**Known constraints:**
[Limitations and requirements]

**Unknowns/Assumptions:**
[What's unclear or assumed]

### What Changed

**Features Implemented:**
- Feature 1 with description
- Feature 2 with description

**Bugs Fixed:**
- Bug 1 (issue and fix)
- Bug 2 (issue and fix)

**Refactoring:**
- What was refactored and why

### Decisions Made

- **DEC-XXX:** [Decision summary with link to DECISIONS.md]

### Problem-Solving Approach

**Challenge:** [Problem encountered]

**Investigation:** [How it was investigated]

**Solution:** [What was implemented]

**Result:** [Outcome and impact]

**Lessons Learned:** [What to remember for next time]

### Files Changed

**Created:**
- `path/to/new/file.ts` - [Purpose]

**Modified:**
- `path/to/existing/file.ts` - [What changed]

**Deleted:**
- `path/to/old/file.ts` - [Why removed]

### Git Operations

(Auto-logged by /save-full)
- `abc1234` - Commit message
- `def5678` - Commit message
- Pushed to origin/main

### Next Session

**Start here:**
- [First task to tackle]
- [Second task if first is blocked]

**Context to review:**
- [Files to read]
- [Decisions to consider]

---

Real-World Example ​

Complete session entry:

markdown
## Session 12 | 2025-10-23 | Stripe Webhook Handler Implementation

**Duration:** 4h | **Focus:** Implement payment confirmation webhook | **Status:** ✅ Complete

### TL;DR

Implemented Stripe webhook handler for payment_intent.succeeded events. Added idempotency key checking to prevent duplicate order processing. Tested with Stripe CLI, confirmed webhook updates order status correctly. Ready for order confirmation email implementation.

### Session Goals

- [x] Create webhook endpoint route
- [x] Implement idempotency key checking
- [x] Add database transaction for order status update
- [x] Test with Stripe CLI
- [ ] Implement order confirmation email (moved to Session 13)

### Mental Models

**Current understanding:**
- Stripe sends payment_intent.succeeded webhook after successful payment
- Webhooks can fire multiple times (retries for up to 3 days)
- Idempotency keys prevent duplicate processing
- Order status flow: pending → processing → confirmed
- Database transaction ensures atomicity

**Architecture understanding:**

[Stripe] --webhook--> [/api/webhooks/stripe] ↓ [Verify signature] ↓ [Check idempotency] ↓ [Update order in DB] ↓ [Cache invalidation]


**Technical approach:**
- Express route: POST /api/webhooks/stripe
- Stripe webhook signature verification (crypto.verify)
- Idempotency table: webhook_event_id → processed_at
- Order update: BEGIN TRANSACTION → UPDATE → COMMIT
- Redis: delete cached order on status change

**Known constraints:**
- Stripe retries failed webhooks (exponential backoff, 3 days max)
- Webhook signature expires after 300 seconds
- Idempotency key: Stripe's event ID (unique per event)
- Database transaction prevents partial updates

**Unknowns/Assumptions:**
- ✅ **Verified:** Stripe event IDs are globally unique (confirmed in docs)
- ✅ **Verified:** Signature verification prevents replay attacks
- 🔮 **Assuming:** Order confirmation email will be fast enough (<5s)
- ⚠️ **Need to verify:** What happens if email send fails? (Next session)

### What Changed

**Features Implemented:**

**Stripe Webhook Handler**
- Created POST /api/webhooks/stripe endpoint
- Verifies webhook signature using Stripe library
- Extracts payment_intent data from event
- Updates order status in database transaction
- Returns 200 OK to acknowledge receipt

**Idempotency System**
- Created webhook_events table (event_id, processed_at, order_id)
- Check: if event_id exists, return 200 (already processed)
- Insert event_id before processing (prevents race conditions)
- Unique index on event_id (database-level deduplication)

**Order Status Update**
- Database transaction: BEGIN → UPDATE orders → INSERT webhook_event → COMMIT
- Status: pending → confirmed
- confirmed_at timestamp set
- Redis cache invalidated for affected order

**Testing Infrastructure**
- Stripe CLI webhook forwarding setup
- Test script: creates test payment, triggers webhook
- Verified idempotency (re-sending same event = no duplicate)

**Bugs Fixed:**
- None (first implementation, no pre-existing bugs)

**Refactoring:**
- Extracted signature verification to middleware
- Created OrderService.confirmOrder() method (business logic separation)

### Decisions Made

- **DEC-014:** Use Stripe event ID as idempotency key
  - Rationale: Globally unique, provided by Stripe, perfect for deduplication
  - See DECISIONS.md for full details

- **DEC-015:** Store idempotency in database, not Redis
  - Rationale: Need persistence across restarts, Redis cache might evict
  - Tradeoff: Extra DB write, but worth reliability
  - See DECISIONS.md for full details

### Problem-Solving Approach

**Challenge 1: Preventing Duplicate Order Processing**

**Investigation:**
- Read Stripe docs on webhook retries
- Discovered: webhooks can fire multiple times (network issues, timeouts)
- Risk: Same order confirmed twice = customer charged once, order recorded twice
- Need idempotency to handle retries safely

**Solution Explored:**
- Option A: Check order status before updating (race condition risk)
- Option B: Use Stripe event ID as idempotency key (recommended by Stripe)
- Option C: Generate our own idempotency key (unnecessary complexity)

**Implemented:** Option B (Stripe event ID)
- Created webhook_events table with unique index on event_id
- Insert event_id BEFORE processing (fails if duplicate)
- If insert fails → already processed → return 200 OK
- If insert succeeds → process event → update order

**Result:** Duplicate webhooks handled safely, no duplicate orders

**Validation:**
- Tested: Send same webhook twice via Stripe CLI
- First request: Order confirmed, webhook logged
- Second request: Returns 200 but no order update
- ✅ Confirmed: Idempotency works

**Challenge 2: Webhook Signature Verification**

**Investigation:**
- Stripe sends signature in Stripe-Signature header
- Need to verify webhook came from Stripe (not attacker)
- Signature = HMAC of payload + timestamp + webhook secret

**Solution:**
- Use Stripe library: stripe.webhooks.constructEvent()
- Automatically verifies signature + checks timestamp freshness
- Throws error if signature invalid or >5 min old

**Implemented:**
```typescript
const sig = req.headers['stripe-signature'];
const event = stripe.webhooks.constructEvent(
  req.body,
  sig,
  process.env.STRIPE_WEBHOOK_SECRET
);

Result: Only valid Stripe webhooks processed

Lessons Learned:

  • Always use Stripe's library (don't manually verify signatures)
  • Raw body needed for verification (not JSON-parsed)
  • Test with Stripe CLI before production
  • Idempotency at database level (not application level) = more reliable

Files Changed ​

Created:

  • app/api/webhooks/stripe/route.ts - Webhook endpoint handler
  • lib/services/OrderService.ts - Order business logic
  • prisma/migrations/XXX_create_webhook_events.sql - Idempotency table
  • tests/webhooks/stripe.test.ts - Webhook handler tests

Modified:

  • app/api/checkout/route.ts - Added webhook URL to checkout session
  • lib/db/schema.prisma - Added webhook_events model
  • .env.example - Added STRIPE_WEBHOOK_SECRET
  • next.config.js - Disabled bodyParser for webhook route

Deleted:

  • None

Git Operations ​

Commits:

  • a1b2c3d - Add Stripe webhook route with signature verification
  • e4f5g6h - Implement idempotency checking with database
  • i7j8k9l - Add order status update transaction
  • m0n1o2p - Add webhook handler tests

Pushed: origin/main (4 commits)

Next Session ​

Start here:

  1. Implement order confirmation email

    • Trigger from webhook after order confirmed
    • Use SendGrid template (already created)
    • Include: order details, receipt, tracking number (if available)
    • Handle email send failures gracefully

  2. If email works, move to:

    • End-to-end testing (full checkout flow)
    • Verify email delivery
    • Test error cases (failed payment, timeout)

  3. If blocked:

    • Review BLOCKER-001 in STATUS.md (email send failure handling)
    • Consider: Retry logic, dead letter queue, or log + alert

Context to review:

  • SendGrid template: templates/order-confirmation.html
  • Order model: lib/db/schema.prisma (Order type)
  • DEC-014, DEC-015 in DECISIONS.md

Estimated next session: 2-3 hours for email implementation

Session completed: 2025-10-23 18:00 Time elapsed: 4 hours (started 14:00) Energy level: High (productive session, clear progress) Blockers encountered: None


## Auto-Logged Git Operations

The `/save-full` command automatically logs git operations:

```markdown
### Git Operations

**Commits since last session:**
- `a1b2c3d` - Add Stripe webhook route
- `e4f5g6h` - Implement idempotency checking
- `i7j8k9l` - Add order status update
- `m0n1o2p` - Add webhook tests

**Branches:**
- Working on: feature/stripe-webhooks
- Base: main

**Push status:** Pushed to origin/main (4 commits)

**Changed files:** (extracted from commits)
- app/api/webhooks/stripe/route.ts (created)
- lib/services/OrderService.ts (created)
- prisma/schema.prisma (modified)
- tests/webhooks/stripe.test.ts (created)

How it works:

  1. /save-full runs
  2. Executes git log --since="last session"
  3. Extracts commit messages and hashes
  4. Checks push status
  5. Adds to SESSIONS.md automatically

You never manually log git operations - they're captured automatically.

Session Templates ​

The system provides session templates to ensure consistency.

Created by /save-full ​

When you run /save-full, the helper script creates a draft session entry:

bash
/save-full

# Creates draft in SESSIONS.md:
## Session 13 | 2025-10-24 | [AI suggests title based on recent work]

**Duration:** [Auto-calculated from last session]
**Focus:** [Extracted from STATUS.md current work]
**Status:** 🔄 In Progress

### TL;DR
[AI generates based on git commits and file changes]

### Mental Models
[AI documents current understanding]

# ... rest of template filled out by AI

Manual Session Entries ​

For other AI tools (non-Claude Code), reference template:

templates/session-template.md

Follow structure manually when updating SESSIONS.md.

Best Practices ​

1. Always Include TL;DR ​

markdown
# Not helpful:
## Session 5 | Work on payments

# Helpful:
## Session 5 | 2025-10-20 | Stripe Integration Setup

**TL;DR:** Integrated Stripe SDK, created checkout flow,
added payment intent creation. Tested with test cards,
confirmed charges work. Ready for webhook implementation.

2. Document Mental Models Honestly ​

markdown
# Be explicit about understanding:
**Mental Models:**
- ✅ Understand: JWT token flow, refresh mechanism
- ✅ Understand: Database schema, relationships
- ❓ Unclear: Rate limiting implementation (need to research)
- ⚠️ Assumption: Users want email notifications (verify with user)

3. Capture Problem-Solving Process ​

markdown
# Not just solution, but HOW you got there:
**Challenge:** API returning 500 errors

**Investigation:**
1. Checked logs → no error details
2. Added error logging middleware → saw database timeout
3. Checked DB connections → connection pool exhausted
4. Root cause: Missing connection.release() in API routes

**Solution:** Added connection release in finally block
**Result:** No more 500 errors, connection pool stable

4. Link to Decisions ​

markdown
### Decisions Made

- **DEC-008:** Use Redis for caching (see DECISIONS.md)
- **DEC-009:** Continuous deployment to staging (see DECISIONS.md)

# Don't duplicate decision content
# Reference DECISIONS.md for full rationale

5. Make "Next Session" Actionable ​

markdown
# Vague:
**Next Session:** Continue working on auth

# Specific:
**Next Session:**
1. Implement password reset flow
   - Email template: templates/password-reset.html
   - Route: POST /api/auth/reset-password
   - Test: Reset token expiration (30 min)
2. If blocked, review DEC-007 (email service choice)

6. Review Before Session End ​

bash
# Before finishing session:
/save-full

# AI generates session entry
# THEN: Review for accuracy
# - Mental models correct?
# - Problem-solving captured?
# - Next session clear?

# Make manual edits if needed
# This is YOUR history, make it useful

Success Metrics ​

"I can read the last 3 session entries and understand exactly how the project evolved and what the AI was thinking."

"A new AI agent can read SESSIONS.md and feel like it was there from the beginning."

When these are true, SESSIONS.md is effective.

Next Steps ​

Built for all AI coding assistants. Optimized for Claude Code.

Use freely for personal or commercial projects