Memory Events

Capture significant moments in your AI work.

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

One action, many types.

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

terminal · 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

The full primitive catalog.

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

Legacy alias for uncategorized notes, runbooks, and operational context

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

When to use: Compatibility type for existing clients; prefer uncategorized for new captures

uncategorized

Default fallback for notes that do not fit a specific category yet

Examples: Quick scratch note, General context, Temporary reminder

When to use: When you want to save context now and classify it later

operation

Operational execution details and workflow actions

Examples: Ran deployment workflow, Executed migration sequence, Performed rollback

When to use: When capturing operational actions taken during work

command_execution

Terminal and CLI command execution records

Examples: Ran cargo test, Executed npm run build, Used kubectl apply

When to use: When command history or exact execution context matters

file_operation

File-level operations like edits, moves, deletes, and patches

Examples: Renamed module, Patched config file, Moved assets directory

When to use: When file-system changes are the key context to preserve

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

notion_page

Generic Notion page content

Examples: Standalone pages, Unclassified database items, General notes

When to use: Auto-detected from Notion sync when page type cannot be determined

notion_task

Notion task or to-do item

Examples: Project tasks, Action items, Sprint backlog items

When to use: Auto-detected from Notion databases with status/due date properties

notion_meeting

Notion meeting notes

Examples: Team standups, Client meetings, 1:1 notes

When to use: Auto-detected from Notion databases with date and attendee properties

notion_wiki

Notion wiki or knowledge base article

Examples: Documentation, How-to guides, Reference materials

When to use: Auto-detected from Notion databases with tags but no status

notion_bug_report

Bug report from Notion

Examples: Bug tickets, Issue reports, Error logs

When to use: Auto-detected from Notion bug tracking databases

notion_feature

Feature request from Notion

Examples: Feature ideas, Enhancement requests, Product feedback

When to use: Auto-detected from Notion feature request databases

notion_journal

Notion journal or log entry

Examples: Daily logs, Work journals, Personal notes

When to use: Auto-detected from Notion databases with chronological date entries

standup

Daily/weekly standup status from a person or team

Examples: Yesterday/today/blockers, Async standup post, Daily check-in

When to use: When capturing a recurring standup or daily-status check-in

status_update

Recurring status report (weekly/biweekly/monthly)

Examples: Weekly engineering update, Project status report, Monthly review

When to use: When capturing a recurring status update broader than a daily standup

question

Open question that needs an answer or decision

Examples: Should we use Postgres or DynamoDB?, Open question on auth flow, TBD — pricing tier eligibility

When to use: When a question is raised that doesn't have an answer yet but needs one

approval

Formal approval action — design / spec / launch / spend / etc.

Examples: Design approved by GTM, Launch readiness sign-off, Budget approved

When to use: When a formal approval is recorded — distinct from a casual 'lgtm'

feedback

Customer / user-facing feedback — distinct from internal frustration

Examples: Beta-tester feedback, Customer NPS comment, Sales-call feature request

When to use: When capturing customer-facing feedback (use 'frustration' for internal)

discovery

Product discovery finding — research insight, market signal

Examples: Customer interview takeaway, Competitor analysis finding, Usage-data observation

When to use: When capturing a product/research discovery that informs strategy

achievement

Milestone hit, win shipped, or goal achieved

Examples: Hit MAU target, Shipped Phase 4 to prod, Closed first enterprise deal

When to use: When marking a meaningful milestone or win for context in future sessions

Special: lessons

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.

terminal · 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

criticalProduction outages, data loss, security issues

highBreaking changes, significant user impact

mediumWorkflow inefficiencies, minor bugs

lowStyle/preference corrections

Automatic surfacing

Lessons appear when relevant.

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

Recall and filter.

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

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

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

For lessons specifically:

terminal · 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 habits that pay off.

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.

Next steps

Wire memory into your workflow.

MCP Integration

Configure editor rules for automatic capture.

Read

Semantic Search

Search your memory by meaning.

Read