Mnemonics: Memory Management via Historian

CRITICAL: You Must Use @historian

Memory tools are ONLY available via the @historian subagent. You CANNOT call these tools directly:

• memory_remember - Create or update memories
• memory_recall - Search and retrieve memories
• memory_forget - Delete memories
• memory_list_types - List available memory types
• memory_sync - Rebuild the search index

Always delegate to historian:

@historian remember that we decided on PostgreSQL for the database
@historian what did we decide about authentication?

Memory Types

| Type | Use For | Example | |--------------------------|-----------------------------|------------------------------------------------------| | architectural-decision | System architecture choices | "Using PostgreSQL with read replicas for scaling" | | design-decision | UI/UX decisions | "Card layout for dashboard, 3 columns on desktop" | | learning | Lessons and discoveries | "Bun's native TS support removes build step need" | | user-preference | User preferences | "User prefers dark mode, tabs not spaces" | | project-preference | Team conventions | "We use conventional commits, PR reviews required" | | issue | Known problems | "Rate limiting not implemented yet, tracking in #42" | | context | General context (default) | "Project started Feb 2026, MVP target Q2" | | recurring-pattern | Reusable patterns | "Error handling: wrap in try/catch, return {error}" | | conventions-pattern | Coding standards | "Use named exports, avoid default exports" |

Note: Projects may define custom memory types via configuration. Always use @historian list all memory types available to see the complete list for the current project.

When to Delegate to Historian

Remember (create/update):

• After making a significant architectural or design decision
• User states a preference about how they work
• Discovering something important about the codebase or tools
• Learning a lesson that should persist across sessions

Recall (search/retrieve):

• Starting a new session → recall relevant context
• User asks "what did we decide about X?"
• Need to check if a decision was already made
• Looking for known issues or patterns

Forget (delete):

• User wants to remove outdated or incorrect memories
• Cleaning up duplicated or irrelevant entries

Sync (reindex):

• After manually editing memory files in .mnemonics/
• When search results seem outdated

Example Prompts

Remembering

@historian remember that we decided on JWT auth with 15-min expiry
@historian save this learning: Bun handles TypeScript natively without compilation
@historian note that the user prefers minimal UI animations
@historian store this as an architectural-decision: we're using event sourcing for the audit log

Recalling

@historian what did we decide about authentication?
@historian recall any known issues with the API
@historian what are my preferences for this project?
@historian show all architectural decisions
@historian find memories about database choices

Managing

@historian list all memory types available
@historian forget the memory about the old API design
@historian sync the index to include recent memory files

How It Works

1. Memories are stored in .mnemonics/{type}/{title}.md as markdown files with YAML frontmatter
2. Indexing is automatic via qmd (hybrid BM25 + vector search)
3. Historian handles classification, deduplication, and semantic search
4. Files are git-friendly - commit them to share across team

Best Practices

1. Be specific in titles - "qmd-cli-for-writes" not "important decision"
2. Let historian classify - it will search first to avoid duplicates
3. Recall before deciding - check if a decision already exists
4. Commit memory files - they're part of project knowledge