Continuity - Synthetic Memory for AI Coding Assistants Logo
Continuityby Hackerware
Start
Tutorial 5 of 771% complete
All tutorials
5 minBeginner

Session Notes

Track progress collaboratively

Session Notes: Collaborative AI Workspace

Duration: 5 minutes | Difficulty: Beginner

What Are Session Notes?

Session Notes are a shared workspace between you and AI. Both can read and write.

Think of it as a scratchpad that persists across sessions:

  • •AI logs blockers it encounters
  • •You add session goals
  • •Both track what's been tried
  • •Context survives tool restarts

The Session Notes Structure

markdown
# Session Notes - January 10, 2026

## Session Goals
- Implement user authentication
- Add rate limiting to API

## Key Decisions Made
- JWT over sessions for stateless auth
- bcrypt for password hashing

## Blockers & Challenges
- TypeScript strict mode causing type errors in auth module

## Attempted Approaches
### What Worked
- Using Passport.js for OAuth flow

### What Didn't Work
- Custom JWT middleware had timing vulnerabilities

## Next Steps
- Implement refresh token rotation
- Add unit tests for auth module

## Open Questions
- Should we use Redis for token blacklist?

Reading Session Notes

Full document

output
@continuity read_session_notes

Specific section

output
@continuity read_session_notes section="blockers"

Available sections:

  • •session_goals
  • •key_decisions
  • •blockers
  • •attempted_approaches
  • •next_steps
  • •open_questions

Updating Session Notes

Append to a section

output
@continuity update_session_notes
section="blockers"
content="Can't find UserService class - might need to check imports"
mode="append"

Replace entire section

output
@continuity update_session_notes
section="session_goals"
content="Implement OAuth 2.0 with Google and GitHub providers"
mode="replace"

When AI Updates Notes

AI should update session notes when:

Encountering a blocker

output
@continuity update_session_notes
section="blockers"
content="Database connection failing - check credentials in .env"

Finding what doesn't work

output
@continuity update_session_notes
section="attempted_approaches"
content="❌ Using synchronous file reads - caused event loop blocking"

Making progress

output
@continuity update_session_notes
section="key_decisions"
content="Using async/await throughout for consistency"

Identifying next steps

output
@continuity update_session_notes
section="next_steps"
content="Add error handling for network failures"

When You Update Notes

Before starting work:

output
@continuity update_session_notes
section="session_goals"
content="Fix the login bug reported in issue #42"
mode="replace"

When you have questions:

output
@continuity update_session_notes
section="open_questions"
content="Should we support SSO for enterprise customers?"

After a session:

output
@continuity update_session_notes
section="next_steps"
content="Continue with password reset flow tomorrow"

Session Notes Best Practices

1. Set Goals at Start

Before each session, update goals:

output
@continuity update_session_notes
section="session_goals"
content="Debug the memory leak in WebSocket handler"
mode="replace"

2. Log Blockers Immediately

Don't wait - note blockers as they happen:

output
@continuity update_session_notes
section="blockers"
content="Webpack build failing with Module not found error"

3. Document What Didn't Work

Save future-you from repeating mistakes:

output
@continuity update_session_notes
section="attempted_approaches"
content="❌ Upgrading to React 19 broke styled-components"

4. Track Decisions Made

Quick notes for context:

output
@continuity update_session_notes
section="key_decisions"
content="Using Vitest instead of Jest for faster tests"

Session Notes vs Decisions

Session NotesDecisions
Temporary, session-scopedPermanent, project-scoped
Quick notes, WIPPolished, documented
Scratchpad formatStructured Q&A format
Updated frequentlyUpdated rarely
For current workFor future reference

When to promote notes to decisions

If something in session notes is:

  • •A lasting architectural choice
  • •Worth remembering in 6 months
  • •Relevant to other team members

...then log it as a proper decision:

output
@continuity log_decision
question="Why Vitest over Jest?"
answer="10x faster test runs, native ESM support, better TypeScript integration"
tags=["testing", "tooling", "vitest"]

Real-World Example

Starting a debugging session

output
@continuity update_session_notes
section="session_goals"
content="Find and fix memory leak in production"
mode="replace"

@continuity update_session_notes
section="blockers"
content=""
mode="replace"

During investigation

output
@continuity update_session_notes
section="attempted_approaches"
content="✅ Used Chrome DevTools heap snapshot - found leak in event listeners"

@continuity update_session_notes
section="blockers"
content="Need to trace which component is attaching listeners without cleanup"

Finding the solution

output
@continuity update_session_notes
section="key_decisions"
content="Added useEffect cleanup for all event listeners"

@continuity update_session_notes
section="next_steps"
content="Add ESLint rule to require cleanup in useEffect"

Session Notes Persistence

Session notes are stored in .continuity/session-notes.md

They persist:

  • •Across AI tool restarts
  • •Across VS Code restarts
  • •Between work sessions

From our testing:

"Session notes from Dec 29, 2025 still accessible in January 2026" — decision-17680990 (Fluent Memory Test Results)

Viewing Session Notes in VS Code

  1. •Open .continuity/session-notes.md directly
  2. •Edit in VS Code - changes sync automatically
  3. •AI will see your edits on next read

The file uses standard Markdown, so you get:

  • •Syntax highlighting
  • •Preview mode
  • •Git versioning

Key Takeaways

  1. •Shared workspace - AI and human collaborate
  2. •Six sections - Goals, decisions, blockers, approaches, next steps, questions
  3. •Append or replace - Choose update mode
  4. •Persists across sessions - Notes survive restarts
  5. •Promote to decisions - When notes become permanent knowledge

Quick Commands Reference

ActionCommand
Read all notesread_session_notes
Read sectionread_session_notes section="blockers"
Add to sectionupdate_session_notes section="X" mode="append"
Replace sectionupdate_session_notes section="X" mode="replace"

← Semantic Search | MCP Tools Reference →