A pure filesystem-based memory system for Claude Code. No external dependencies - all operations use standard Unix tools and Claude's native capabilities.
Note: This plugin implements the Memory Interchange Format (MIF) specification for standardized AI memory storage. MIF defines a portable, human-readable format for persistent AI memories.
- Pure Filesystem: All memories stored as markdown files with YAML frontmatter
- MIF Level 3 Compliant: Standardized Memory Interchange Format
- Skill-First Architecture: Skills work standalone without hooks or libraries
- Cognitive Memory Types: Semantic, episodic, and procedural memories
- Custom Ontologies: Extend with domain-specific entity types and relationships
- Semantic Search: Optional vector search via qmd integration
- Bi-Temporal Tracking: Valid time vs. recorded time
- Git Versioned: All changes tracked with git
- Cross-Session Coordination: Blackboard for session handoffs
Research validates the filesystem approach for AI memory. In Letta's LoCoMo benchmark, filesystem-based memory achieved 74.0% accuracy compared to Mem0's graph-based approach at 68.5%. This counterintuitive result has a simple explanation: LLMs are extensively pretrained on filesystem operations, making simple tools more reliable than specialized knowledge graphs or vector databases.
This approach is grounded in Unix philosophy, as articulated in "From Everything is a File to Files Are All You Need". Just as Unix collapsed diverse device interfaces into uniform file operations, AI agents benefit from the same abstraction—complexity is encapsulated, not eliminated.
Key advantages of the filesystem approach:
- LLMs already understand
grep,find, and file operations from training data - Human-readable format enables direct inspection and editing
- Git integration provides full version history with meaningful diffs
- No external services, databases, or cloud dependencies
- Works offline and respects data sovereignty
# Load the plugin
claude --plugin-dir /path/to/mnemonic
# Or add to settings for permanent installation
claude settings plugins add /path/to/mnemonic# Initialize mnemonic for your project
/mnemonic:setup
# Capture a memory
/mnemonic:capture decisions "Use PostgreSQL for storage" --tags database,architecture
# Recall memories
/mnemonic:recall --namespace decisions
# Search memories
/mnemonic:search "authentication"
# Check status
/mnemonic:statusAll memories are stored under ${MNEMONIC_ROOT}/ with a unified path structure:
${MNEMONIC_ROOT}/
├── default/ # Fallback when org detection fails
│ └── {namespace}/ # Cognitive triad namespaces
├── {org}/ # Organization-level
│ ├── semantic/ # Org-wide facts/knowledge
│ │ ├── decisions/
│ │ ├── knowledge/
│ │ └── entities/
│ ├── episodic/ # Org-wide events
│ │ ├── incidents/
│ │ ├── sessions/
│ │ └── blockers/
│ ├── procedural/ # Org-wide procedures
│ │ ├── runbooks/
│ │ ├── patterns/
│ │ └── migrations/
│ └── {project}/ # Project-specific memories
│ ├── semantic/
│ │ ├── decisions/
│ │ ├── knowledge/
│ │ └── entities/
│ ├── episodic/
│ │ ├── incidents/
│ │ ├── sessions/
│ │ └── blockers/
│ ├── procedural/
│ │ ├── runbooks/
│ │ ├── patterns/
│ │ └── migrations/
│ └── .blackboard/ # Project session coordination
└── .git/ # Version control
Memory scope hierarchy:
{org}/{project}/- Project-specific memories (default){org}/- Organization-wide memories (shared across projects)default/- Fallback when org cannot be detected
Each memory is a .memory.md file with YAML frontmatter:
---
id: 550e8400-e29b-41d4-a716-446655440000
type: semantic
namespace: decisions/project
created: 2026-01-23T10:30:00Z
modified: 2026-01-23T14:22:00Z
title: "Use PostgreSQL for storage"
tags:
- database
- architecture
temporal:
valid_from: 2026-01-23T00:00:00Z
recorded_at: 2026-01-23T10:30:00Z
decay:
model: exponential
half_life: P7D
strength: 0.85
provenance:
source_type: conversation
agent: claude-opus-4
confidence: 0.95
relationships:
- type: relates_to
target: a5e46807-6883-4fb2-be45-09872ae1a994
label: "Related caching decision"
- type: supersedes
target: b6f57918-7994-5gc3-cf56-10983bf2b005
---
# Use PostgreSQL for Storage
We decided to use PostgreSQL for our data storage needs.
## Rationale
- Strong ACID compliance
- Excellent JSON support
- Mature ecosystem| Type | Use Case | Examples |
|---|---|---|
| semantic | Facts, concepts, specifications | API docs, config values |
| episodic | Events, experiences, incidents | Debug sessions, deployments |
| procedural | Processes, workflows, how-tos | Deployment steps, runbooks |
Mnemonic uses a cognitive triad namespace hierarchy:
| Top-Level | Sub-namespace | Purpose |
|---|---|---|
semantic/ |
decisions/ |
Architectural choices, rationale |
knowledge/ |
APIs, context, learnings, security | |
entities/ |
Entity definitions (technologies, components) | |
episodic/ |
incidents/ |
Production issues, postmortems |
sessions/ |
Debug sessions, work sessions | |
blockers/ |
Impediments, issues | |
procedural/ |
runbooks/ |
Operational procedures |
patterns/ |
Code conventions, testing strategies | |
migrations/ |
Migration steps, upgrade procedures |
Extend mnemonic with domain-specific entity types, relationships, and discovery:
# Copy the software-engineering ontology
cp skills/ontology/fallback/ontologies/examples/software-engineering.ontology.yaml \
.claude/mnemonic/ontology.yamlThis adds:
- Custom sub-namespaces (architecture, components, deployments)
- Typed entities (technology, component, design-pattern, incident-report, runbook)
- Entity relationships (depends_on, implements, caused_by, resolves)
- Discovery patterns for auto-suggesting entity captures
See docs/ontologies.md for the full guide.
| Command | Description |
|---|---|
/mnemonic:setup |
Configure mnemonic with proactive behavior |
/mnemonic:capture |
Capture a new memory |
/mnemonic:recall |
Search and recall memories |
/mnemonic:search |
Full-text search and enhanced iterative search |
/mnemonic:query |
Structured frontmatter queries using yq |
/mnemonic:status |
Show system status |
/mnemonic:gc |
Garbage collect expired memories |
/mnemonic:list |
List loaded ontologies and namespaces |
/mnemonic:validate |
Validate ontology file |
/mnemonic:custodian |
Memory health checks and maintenance |
/mnemonic:integrate |
Wire mnemonic into other plugins |
Skills are fully self-contained and work without hooks or libraries:
- setup: Configure CLAUDE.md for proactive behavior
- core: Complete memory operations
- search: Advanced search patterns and iterative synthesis
- format: MIF Level 3 templates
- blackboard: Cross-session coordination and agent patterns
- ontology: Custom ontology support with entity types and discovery
- custodian: Memory maintenance, deduplication, and health checks
- integrate: CLAUDE.md integration for new projects
- qmd-setup: Semantic search setup via qmd
- qmd-reindex: Re-index memories for semantic search
Autonomous agents for specialized tasks:
- memory-curator: Conflict detection, deduplication, decay management
- mnemonic-search-subcall: Efficient search agent for iterative query refinement
- compression-worker: Memory summarization for gc --compress
- ontology-discovery: Discovers entities in codebase based on ontology patterns
| Guide | Focus |
|---|---|
| Getting Started | First project setup tutorial |
| CLI Usage | Command-line operations |
| Troubleshooting | Common issues and solutions |
| Architecture | System architecture |
| Semantic Search | QMD vector search setup |
| Library Reference | Python library API reference |
| Ontologies | Custom ontology guide |
| Validation | Memory validation guide |
| ADRs | Architecture decision records |
After running /mnemonic:setup, Claude will:
- Auto-Recall: Silently search for relevant memories when you discuss topics
- Auto-Capture: Automatically save decisions, learnings, and patterns
- Silent Operation: Memory operations happen in the background
Mnemonic provides both traditional keyword search and semantic vector search.
# Full-text search
rg -i "authentication" ${MNEMONIC_ROOT}/ --glob "*.memory.md"
# By namespace
rg "pattern" ${MNEMONIC_ROOT}/*/_semantic/decisions/ --glob "*.memory.md"
# By tag
rg -l "^ - security" ${MNEMONIC_ROOT}/ --glob "*.memory.md"
# By type
rg "^type: episodic" ${MNEMONIC_ROOT}/ --glob "*.memory.md" -l
# Recent files (last 7 days)
find ${MNEMONIC_ROOT} -name "*.memory.md" -mtime -7For semantic/vector search capabilities, use the integrated @tobilu/qmd support:
# One-time setup
/mnemonic:qmd-setup
# Keyword search (BM25)
qmd search "authentication patterns"
# Semantic vector search
qmd vsearch "how do we handle user sessions"
# Hybrid search (BM25 + vector)
qmd query "database migration strategy"
# Scope to specific collections
qmd search "auth" -c mnemonic-zircote # org memories only
qmd search "auth" -c mnemonic-project # this repo only
# Re-index after adding new memories
/mnemonic:qmd-reindexRequirements:
- Node.js >= 22
npm i -g @tobilu/qmd
See skills/qmd-setup/SKILL.md for detailed setup instructions.
Hooks provide proactive automation via hookSpecificOutput.additionalContext:
| Event | Purpose |
|---|---|
| SessionStart | Memory status, health score, registry status |
| PreToolUse | Relevant memory paths when editing files |
| UserPromptSubmit | Capture/recall trigger detection |
| PostToolUse | Capture opportunities from tool results |
| Stop | Commit changes, summarize session |
Hooks inform Claude with context—Claude decides when to read memories or use agents.
The blackboard enables cross-session coordination:
# Write to blackboard
echo "## Task started" >> ${MNEMONIC_ROOT}/.blackboard/active-tasks.md
# Read recent entries
tail -50 ${MNEMONIC_ROOT}/.blackboard/session-notes.mdAll memories are versioned with git:
cd ${MNEMONIC_ROOT}
git log --oneline -20
git show HEAD~3:path/to/memory.memory.md# Project structure
mnemonic/
├── .claude-plugin/
│ └── plugin.json # Plugin manifest
├── agents/
│ ├── memory-curator.md # Maintenance agent
│ ├── mnemonic-search-subcall.md # Search iteration agent
│ ├── compression-worker.md # Memory summarization agent
│ └── ontology-discovery.md # Entity discovery agent
├── commands/
│ └── *.md # Slash commands
├── docs/
│ ├── architecture.md # System architecture
│ ├── semantic-search.md # QMD semantic search guide
│ ├── validation.md # Memory validation guide
│ ├── ontologies.md # Custom ontology guide
│ ├── cli-usage.md # Command-line operations
│ ├── library-reference.md # Python library API
│ ├── troubleshooting.md # Common issues and solutions
│ └── adrs/ # Architecture decision records
├── hooks/
│ ├── hooks.json # Hook configuration
│ └── *.py # Hook implementations
├── lib/
│ ├── paths.py # Path resolution
│ ├── config.py # Configuration
│ ├── ontology.py # Ontology loading
│ ├── search.py # Memory search and scoring
│ ├── memory_reader.py # Memory metadata extraction
│ ├── relationships.py # Relationship writing
│ └── migrate_filenames.py # Filename migration utilities
├── skills/
│ ├── */SKILL.md # Self-contained skills
│ └── ontology/ # Custom ontology support
│ ├── SKILL.md
│ ├── lib/ # Python utilities
│ └── ontologies/ # Base ontology and examples
├── tools/
│ ├── mnemonic-validate # MIF schema validation
│ ├── mnemonic-query # Structured queries
│ └── mnemonic-paths # Path resolution CLI
├── tests/
│ └── unit/ # Unit tests
├── CHANGELOG.md
└── README.md- Claude Code CLI
- Git
- ripgrep (recommended for search)
- yq (required for structured queries)
- Python 3.8+ (for hooks and tools)
- Node.js >= 22
@tobilu/qmd(npm i -g @tobilu/qmd)
# macOS
brew install ripgrep yq
# Ubuntu/Debian
apt install ripgrep
snap install yq
# Optional: semantic search
npm i -g @tobilu/qmd
# Check installation
make check-deps- MIF (Memory Interchange Format) - The specification this plugin implements. An open standard for portable AI memory storage. Schemas: https://mif-spec.dev/schema/
MIT