mnemonics - SKILL.md Agent Skill

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

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

Best Practices

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