Memory

Event Types

Memory events capture significant moments in your AI interactions. Each type serves a specific purpose and helps the AI provide better context in future sessions.

Quick Reference

All event types use the session(action="capture", ...) action (lessons have a dedicated action: session(action="capture_lesson", ...)).

session(action="capture", ...)

{
  "action": "capture",
  "event_type": "decision",  // See types below
  "title": "Brief summary",
  "content": "Detailed explanation...",
  "importance": "medium"     // low, medium, high
}

All Event Types

decision

Architectural or design decisions with rationale

Examples: Tech stack choices, API design decisions, Database schema choices

When to use: When you or the user makes a significant technical or project decision

preference

User preferences, coding style, and workflow habits

Examples: TypeScript strict mode, Tabs vs spaces, Preferred libraries

When to use: When you learn how the user likes to work

insight

Discoveries, learnings, and observations about the codebase

Examples: How auth flow works, Where config is stored, Performance bottlenecks found

When to use: When you discover something important about the codebase

note

General notes, runbooks, and operational context

Examples: Demo reset steps, Operational runbook, Client-specific quirks

When to use: When you want to save context that doesn't fit a specific category

implementation

Implementation details, checklists, and technical how-tos

Examples: Migration steps, Deployment checklist, Feature rollout plan

When to use: When capturing step-by-step implementation guidance for future use

task

Completed work, implementations, and action items

Examples: Implemented feature X, Fixed bug Y, Refactored module Z

When to use: When completing significant work worth remembering

conversation

Meeting notes, discussions, and general context

Examples: Sprint planning notes, Design review discussion, Stakeholder feedback

When to use: For general context that doesn't fit other categories

bug

Bug reports and issues found

Examples: Race condition in auth, Memory leak in worker, UI breaks on mobile

When to use: When documenting bugs for future reference

feature

Feature requests and implementations

Examples: User requested dark mode, Add export functionality, Implement webhooks

When to use: When capturing feature ideas or implementations

correction

When you're corrected on something

Examples: Wrong API endpoint used, Misunderstood requirements, Incorrect assumption

When to use: When the user corrects a misunderstanding

warning

Important warnings to remember

Examples: Don't modify X file, API rate limits, Legacy code - handle carefully

When to use: For important cautions about the codebase

frustration

User frustration points to avoid

Examples: Repeated same mistake, Slow response times, Misunderstood intent

When to use: When the user expresses frustration (helps improve future interactions)

lesson

Lessons learned from mistakes or corrections

Examples: Always verify assets in git before pushing, Check branch before commits, Confirm values before asking again

When to use: When capturing mistakes, corrections, or preventions that should be remembered for future sessions

Lessons Learned

Lessons are a special event type with additional structured fields. They capture mistakes, corrections, and preventions that are automatically surfaced in future sessions to prevent repeating errors.

When to Capture Lessons

• User expresses frustration (caps, "COME ON", repeated corrections)
• User corrects the AI ("No, you should...", "That's wrong")
• Code breaks due to a preventable mistake
• Production issues caused by AI-generated code
• A command/tool fails and you learn the correct fix

Capturing Lessons

Use the dedicated session(action="capture_lesson", ...) action:

session(action="capture_lesson", ...)

{
  "action": "capture_lesson",
  "title": "Always verify assets in git before pushing",
  "severity": "critical",    // low, medium, high, critical
  "category": "workflow",    // workflow, code_quality, verification, communication, project_specific
  "trigger": "Pushed code referencing images without committing them",
  "impact": "Production 404 errors - broken landing page",
  "prevention": "Run 'git status' to check untracked files before pushing",
  "keywords": ["git", "images", "assets", "push", "404"]
}

Lesson Fields

Field	Description
`title`	What to remember - concise summary
`severity`	`critical` (production), `high` (breaking), `medium` (workflow), `low` (minor)
`category`	workflow, code_quality, verification, communication, project_specific
`trigger`	What action caused the problem
`impact`	What went wrong as a result
`prevention`	How to prevent this in the future
`keywords`	Keywords for semantic matching in future contexts

Severity Guide

critical

Production outages, data loss, security issues

high

Breaking changes, significant user impact

medium

Workflow inefficiencies, minor bugs

low

Style/preference corrections

Automatic Surfacing

Events are automatically included in session_init and context_smart responses based on semantic relevance. High and critical severity lessons appear as warnings before risky operations.

Example Warning

When about to push code that references assets:

L:⚠️ Verify assets in git before pushing: Run git status to check untracked files

Retrieving Events

Use session(action="recall", ...) to find past events:

session(action="recall", ...)

{
  "action": "recall",
  "query": "What did we decide about authentication?"
}

For lessons specifically:

session(action="get_lessons", ...)

{
  "action": "get_lessons",
  "query": "git push",        // Optional: semantic search
  "category": "workflow",     // Optional: filter by category
  "severity": "high",         // Optional: minimum severity
  "limit": 10
}

Best Practices

Capture immediately

Save events as soon as they happen, while context is fresh

Be specific

Include exact details, commands, or steps that matter

Choose the right type

Use the most specific event type - decisions vs preferences vs insights

Use lessons for corrections

Always use session(action="capture_lesson", ...) for mistakes - they get special treatment