mnemonic

Mnemonic

A pure filesystem-based memory system for Claude Code. No external dependencies - all operations use standard Unix tools and Claude's native capabilities.

<p align="center"> <img src=".github/readme-infographic.png" alt="Mnemonic Architecture" width="800"> </p>

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.

Features

• 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

Why Filesystem?

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

Installation

# Load the plugin
claude --plugin-dir /path/to/mnemonic

# Or add to settings for permanent installation
claude settings plugins add /path/to/mnemonic

Quick Start

# 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:status

Directory Structure

All 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

Memory Format (MIF Level 3)

Each memory is a .memory.md file with YAML frontmatter: