Mnemonics

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

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