Skip to main content

Memory & Sessions

Overview

Preserve research findings and maintain work continuity across sessions. AI platforms now handle session management natively — use the tools built into your environment.

Memory Storage​

How It Works​

Memory storage is handled natively by the AI platform you're using:

  • Claude Code — Uses project memory at ~/.claude/projects/{project}/memory/. Use the /memory command or reference past context in your session.
  • Gemini — Uses project-level memory configured per project.

There is no separate CLI to run. The AI platform manages memory automatically within a project context.

What to Store​

Store important findings, research results, and technical discoveries so they're not lost when a session ends.

Examples:

  • "WPEngine health views use 0-100 score calculation: backup=40%, ssl=30%, disk=20%, bandwidth=10%"
  • "Toggl API has 90-day limit on time entry queries"
  • "Supabase has 2GB free tier limit per project"
  • "Linear GraphQL API requires OAuth for production apps"

When to Store​

Store a memory whenever you discover:

  • Non-obvious technical details
  • API limitations or quirks
  • System behavior patterns
  • Performance characteristics
  • Configuration details
  • Troubleshooting solutions

When NOT to Store​

Don't store:

  • Decisions (document those in docs/planning/decisions/ markdown files)
  • Obvious facts (documentation already covers it)
  • Temporary notes (use session notes or code comments)

Using Claude Code Memory​

Claude Code automatically maintains context within a session. For cross-session persistence:

# In your Claude Code session, reference the memory feature:
/memory   # View and manage project memory

Best practice: At the end of a session where you've discovered important technical facts, explicitly tell Claude Code to remember them for future sessions.

Using Markdown Notes for Persistent Findings​

For findings that need to persist across platforms or be shared with other agents, write them to a notes file:

# Create a running research notes file
echo "## $(date +%Y-%m-%d)" >> docs/planning/research-notes.md
echo "- Toggl API has 90-day limit on time entry queries" >> docs/planning/research-notes.md
echo "- tags: toggl, api, limitation" >> docs/planning/research-notes.md

Search existing notes:

grep -i "toggl" docs/planning/research-notes.md
grep -i "api limit" docs/planning/research-notes.md

Session Tracking​

How It Works​

Session tracking is handled natively by AI platforms. There is no separate session CLI.

  • Claude Code — Each conversation is a session. Context persists for the duration of the conversation. Use the --continue flag to resume a previous conversation.
  • Gemini — Each session persists within a project context.

Cross-machine work: Sessions don't need to be manually started or ended. When switching machines, start a new Claude Code session and provide context about what you were working on. Use the handoff system (handoffs/) for structured cross-session continuity.

Handoff System​

For structured continuity across sessions or between agents, use the handoff files:

# Handoff files are written automatically by the session-start hook
ls handoffs/

# Example handoff file
cat handoffs/session-Tech-Director-2026-02-24.md

Handoff files include:

  • Current task and context
  • Work completed
  • Next steps
  • Blockers or open questions

Cross-Session Workflow​

Starting a work session:

  1. Check for existing handoff files: ls handoffs/
  2. Search relevant decisions: grep -ril "topic" docs/planning/decisions/
  3. Review any research notes: grep -i "topic" docs/planning/research-notes.md
  4. Begin work with full context

Ending a work session:

  1. Document any important findings in docs/planning/research-notes.md
  2. Record architectural decisions in docs/planning/decisions/
  3. Create a handoff file if work is ongoing: 
    cat > handoffs/session-$(date +%Y-%m-%d).md << 'EOF'
    # Session Handoff - YYYY-MM-DD

    ## Context
    [What were you working on?]

    ## Completed
    - [What got done]

    ## Next Steps
    - [What to do next]

    ## Blockers
    - [Any open issues]
    EOF

Best Practices​

For Research Findings​

  1. Be specific - "Toggl 90-day limit on time entries" not "API limitation"
  2. Include context - Why does this matter?
  3. Document immediately - Don't wait until end of session
  4. Use searchable terms - Write notes in a way that grep can find them
  5. Check existing notes first - Avoid duplicating what's already documented

For Work Continuity​

  1. Use handoff files for ongoing tasks - They persist across sessions and machines
  2. Leave context in code comments - Helps the next session understand intent
  3. Commit work-in-progress notes - A WIP commit with context is better than nothing
  4. Reference decision files - Link from code comments to the relevant decision doc

Success Metrics​

After 1 week:

  • ✅ Research findings documented in notes files
  • ✅ Handoff files used for multi-session tasks
  • ✅ No repeat research for the same topics

After 1 month:

  • ✅ Growing research notes library
  • ✅ Cross-session work is seamless via handoffs
  • ✅ Decisions and findings are consistently documented