mnemonics

name	mnemonics
description	Memory management by using the historian subagent to store, recall, and manage persistent memories across conversations. Use when you need to remember decisions, preferences, learnings, or retrieve stored context.
license	MIT
compatibility	opencode, opencode-historian plugin and qmd CLI.
metadata	{"author":"Isaac Ng, Ka Ho","version":"1.0.0"}

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