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

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