claude-configs/skills/cognitive-memory/SKILL.md

name	description
cognitive-memory	Markdown-based memory system with decay scoring, episodic logging, and auto-curated CORE.md. USE WHEN storing learnings, recalling past solutions, linking problems to fixes, tracking decisions, or building knowledge connections across sessions. Replaces MemoryGraph with human-readable files.

Cognitive Memory - Markdown-Based AI Memory

Purpose

Cognitive Memory provides persistent, human-readable memory storage as markdown files with YAML frontmatter. Unlike MemoryGraph's opaque SQLite database, every memory is a browseable, editable markdown file organized in a git-tracked repository.

Key features:

• Human-readable markdown files with YAML frontmatter
• Decay scoring to surface relevant memories and let stale ones fade
• Episodic session logs for chronological context
• Auto-curated CORE.md auto-loaded into system prompt via MEMORY.md symlinks
• Git-tracked for history, rollback, and diff visibility
• Relations stored directly in frontmatter (self-contained files)
• Semantic search via Ollama embeddings (nomic-embed-text)
• Reflection cycles with union-find clustering to surface patterns
• Procedural memories with structured steps/preconditions/postconditions
• Tag co-occurrence analysis for pattern discovery
• REFLECTION.md with theme analysis and cross-project patterns

When to Activate This Skill

Explicit triggers:

• "Remember this for later"
• "Store this solution / fix / decision"
• "What did we learn about X?"
• "Find solutions for this problem"
• "Link this to that issue"
• "Show me related memories"
• "What's in memory about...?"
• "What patterns have we seen?"
• "Run a reflection"
• "What tags are related to X?"
• "Store this procedure / workflow"

Automatic triggers (per CLAUDE.md Memory Protocol):

• After fixing a bug
• After a git commit
• After making an architecture decision
• After discovering a reusable pattern
• After a successful configuration
• After troubleshooting sessions
• At session start (CORE.md auto-loads via symlinks; read REFLECTION.md for theme context)
• Periodically (reflect to cluster memories, suggest missing tags)

Quick Reference

CLI Commands

All commands support --help for full argument details. Key non-obvious features:

# --episode flag auto-logs a session entry when storing
claude-memory store --type solution --title "Fixed X" --content "..." --tags "t1,t2" --episode

# --semantic merges keyword + Ollama embedding results (run embed first)
claude-memory recall "timeout error" --semantic

# procedure type takes structured steps/preconditions/postconditions
claude-memory procedure --title "Deploy flow" --content "..." \
  --steps "test,build,push,deploy" --preconditions "tests pass" --postconditions "healthy"

# reflect clusters recent memories; reflection regenerates REFLECTION.md
claude-memory reflect --since 2026-01-01
claude-memory reflection

# tags sub-commands: list (counts), related (co-occurrence), suggest (for a memory)
claude-memory tags list
claude-memory tags related "python"
claude-memory tags suggest <memory_id>

Full command list: store, recall, get, relate, search, update, delete, related, stats, recent, decay, core, episode, reindex, pin, embed, reflect, reflection, tags, procedure, merge

Memory Types

Type	When to Use	Decay Weight
procedure	Structured workflow with steps/preconditions/postconditions	1.4 (decays slowest)
decision	Architecture or design choices	1.3
insight	Cross-cutting pattern from reflection cycles	1.25
solution	Fix or resolution to a problem	1.2
code_pattern	Reusable code pattern	1.1
configuration	Config that worked	1.1
fix	Code-level patch or correction	1.0
workflow	Process or sequence	1.0
problem	Issue or challenge encountered	0.9
error	Specific error condition	0.8
general	Catch-all for other learnings	0.8

Relationship Types

Type	Meaning
SOLVES	Solution fixes a problem
CAUSES	A causes B
BUILDS_ON	A extends or enhances B
ALTERNATIVE_TO	A is an alternative approach to B
REQUIRES	A depends on B
FOLLOWS	A follows B in sequence
RELATED_TO	General association

Importance Scale

Score	Meaning
0.8-1.0	Critical - affects multiple projects, prevents major issues
0.5-0.7	Standard - useful pattern or solution
0.3-0.4	Minor - nice-to-know, edge cases

Directory Structure

~/.claude/memory/
├── CORE.md                    # Auto-curated ~3K token summary
├── REFLECTION.md              # Theme analysis & cross-project patterns
├── graph/                     # Semantic memories (knowledge graph)
│   ├── solutions/             # Solution memories
│   ├── fixes/                 # Fix memories
│   ├── decisions/             # Decision memories
│   ├── configurations/        # Configuration memories
│   ├── problems/              # Problem memories
│   ├── workflows/             # Workflow memories
│   ├── code-patterns/         # Code pattern memories
│   ├── errors/                # Error memories
│   ├── general/               # General memories
│   ├── procedures/            # Procedural memories (steps/pre/postconditions)
│   └── insights/              # Reflection-generated insights
├── episodes/                  # Daily session logs (YYYY-MM-DD.md)
├── vault/                     # Pinned memories (never decay)
├── _index.json                # Computed index for fast lookups
├── _state.json                # Mutable state (access counts, decay scores)
├── _embeddings.json           # Ollama embedding vectors (semantic search)
└── .gitignore                 # Ignores _state.json, _index.json, _embeddings.json

Decay Model

Memories have a decay score that determines their relevance over time:

decay_score = importance × e^(-0.03 × days_since_access) × log2(access_count + 1) × type_weight

Score Range	Status	Behavior
0.5+	Active	Included in search results, eligible for CORE.md
0.2-0.5	Fading	Deprioritized in results
0.05-0.2	Dormant	Only found via explicit search
<0.05	Archived	Hidden from search (files remain on disk)

Half-life: ~23 days. Access a memory to reset its timer. Vault: Pinned memories have infinite decay score.

Workflow Patterns

1. Store a Bug Fix

# Store the solution
claude-memory store --type solution \
  --title "Fixed Redis connection timeouts" \
  --content "Added socket_keepalive=True and socket_timeout=300..." \
  --tags "redis,timeout,production" --importance 0.8

# Log the episode
claude-memory episode --type fix --title "Fixed Redis timeouts" \
  --tags "redis,production" --summary "Keepalive prevents idle disconnections"

2. Recall Before Starting Work

# Check what we know about a topic
claude-memory recall "authentication oauth"

# Find solutions for similar problems
claude-memory search --types "solution" --tags "python,api"

3. Document a Decision

claude-memory store --type decision \
  --title "Chose PostgreSQL over MongoDB" \
  --content "Need ACID transactions, complex joins..." \
  --tags "database,architecture" --importance 0.9

4. Link Related Memories

claude-memory relate <solution_id> <problem_id> SOLVES \
  --context "Keepalive prevents idle disconnections"

5. Semantic Recall (Deeper Matching)

# First-time setup: generate embeddings (requires Ollama + nomic-embed-text)
claude-memory embed

# Recall with semantic search (merges keyword + embedding results)
claude-memory recall "authentication timeout" --semantic

6. Store a Procedure

claude-memory procedure \
  --title "Deploy Major Domo to production" \
  --content "Standard deploy workflow for the Discord bot" \
  --steps "run tests,build docker image,push to registry,deploy to LXC" \
  --preconditions "all tests pass,on main branch,version bumped" \
  --postconditions "service healthy,Discord bot online" \
  --tags "major-domo,deploy,docker" --importance 0.8

7. Run a Reflection Cycle

# Analyze recent memories for patterns
claude-memory reflect

# Review memories since a specific date
claude-memory reflect --since 2026-01-15

# Preview without modifying state
claude-memory reflect --dry-run

# Generate/refresh the REFLECTION.md summary
claude-memory reflection

8. Tag Analysis

# What tags exist and how often?
claude-memory tags list --limit 20

# What tags co-occur with "python"?
claude-memory tags related "python"

# What tags should this memory have?
claude-memory tags suggest <memory_id>

9. Session Maintenance

# Recalculate decay scores
claude-memory decay

# Regenerate CORE.md
claude-memory core

# Refresh embeddings after adding new memories
claude-memory embed

# View what's fading
claude-memory search --min-importance 0.3

CORE.md

Auto-generated summary of highest-relevance memories (~1K tokens), auto-loaded into the system prompt at every session via MEMORY.md symlinks. Each project's ~/.claude/projects/<project>/memory/MEMORY.md symlinks to ~/.claude/memory/CORE.md. Symlinks are refreshed daily by cognitive-memory-daily.service (via claude-memory-symlinks script). Regenerated by the core CLI command.

REFLECTION.md

Auto-generated summary of memory themes, cross-project patterns, and access statistics. Contains 5 sections: Themes (tag co-occurrences), Cross-Project Patterns (tags spanning multiple projects), Most Accessed (top 10 by access count), Recent Insights (latest insight-type memories), and Consolidation History. Generated by reflection CLI command or automatically during reflect.

Semantic Search

Requires Ollama running locally with the nomic-embed-text model. Generate embeddings with claude-memory embed, then use --semantic flag on recall to merge keyword and embedding-based results. Semantic search provides deeper matching beyond exact title/tag keywords - useful for finding conceptually related memories even when different terminology was used.

Episode Logging

Daily markdown files appended during sessions, providing chronological context:

# 2025-12-13

## 10:30 - Fixed Discord bot reconnection
- **Type:** fix
- **Tags:** major-domo, discord, python
- **Summary:** Implemented exponential backoff for reconnections

Migration from MemoryGraph

This system was migrated from MemoryGraph (SQLite-based). The original database is archived at ~/.memorygraph/memory.db.archive. All 313 memories and 30 relationships were preserved.

Proactive Usage

This skill should be used proactively when:

1. Bug fixed - Store problem + solution + SOLVES relationship (use --episode for auto-logging)
2. Git commit made - Store summary of what was fixed/added
3. Architecture decision - Store choice + rationale
4. Pattern discovered - Store for future recall
5. Configuration worked - Store what worked and why
6. Troubleshooting complete - Store what was tried, what worked
7. Session start - CORE.md auto-loads via MEMORY.md symlinks; read REFLECTION.md for theme context, then recall relevant memories (use --semantic for deeper matching)
8. Multi-step workflow documented - Use procedure type with structured steps/preconditions/postconditions
9. Periodically - Run reflect to cluster memories and surface cross-cutting insights. Run tags suggest to find missing tag connections
10. After adding memories - Run embed to refresh semantic search index
11. Session ending - Prompt: "Should I store today's learnings?"

---

Location: ~/.claude/skills/cognitive-memory/ Data: ~/.claude/memory/ Version: 2.0.0 Created: 2026-02-13 Migrated from: MemoryGraph (SQLite)