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, tracking decisions, or building knowledge connections across sessions.

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
• 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"
• "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 entrypoint: claude-memory (wrapper at ~/.local/bin/claude-memory)

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

# recall uses semantic+keyword merge by default (when embeddings exist)
claude-memory recall "timeout error"
# use --no-semantic for keyword-only (faster, ~3ms vs ~200ms)
claude-memory recall "timeout error" --no-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, search, update, delete, stats, recent, decay, core, episode, reindex, pin, embed, reflect, reflection, tags, procedure, merge, edge-get, edge-search, edge-update, edge-delete, config

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

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

Skill Directory Structure

~/.claude/skills/cognitive-memory/
├── client.py                          # Core API + CLI entrypoint
├── mcp_server.py                      # MCP server for Claude Code tools
├── SKILL.md                           # This file
├── SCHEMA.md                          # Format reference for all file types
├── feature.json                       # Skill manifest
├── scripts/
│   ├── session_memory.py              # SessionEnd hook — auto-stores session learnings
│   └── ensure-symlinks.sh             # Refreshes MEMORY.md symlinks to CORE.md
├── systemd/
│   ├── README.md                      # Install instructions for timers
│   ├── cognitive-memory-daily.*       # Daily: decay, core, symlinks
│   ├── cognitive-memory-embed.*       # Hourly: refresh embeddings
│   └── cognitive-memory-weekly.*      # Weekly: reflection cycle
└── dev/
    ├── PROJECT_PLAN.json              # Development roadmap
    └── migrate.py                     # One-time MemoryGraph migration

Data 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
│   └── edges/                 # Rich edge files (first-class relationship objects)
├── 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 (with Edge)

# 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
# Returns: memory_id = abc-123

# Link it to the problem memory that prompted the fix
# (use memory_recall or memory_search to find the related memory first)
claude-memory relate abc-123 def-456 SOLVES \
  --description "Keepalive fix resolves the idle timeout disconnections"

# 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. Semantic Recall (Deeper Matching)

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

# Recall uses semantic+keyword merge by default
claude-memory recall "authentication timeout"
# Use --no-semantic for keyword-only
claude-memory recall "authentication timeout" --no-semantic

5. 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

6. 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

7. 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>

8. Create Edges Between Related Memories

Edges are first-class relationship objects that connect memories into a traversable graph. Always look for opportunities to link memories — this makes recall and future RAG retrieval significantly richer.

Relation types: SOLVES, CAUSES, BUILDS_ON, ALTERNATIVE_TO, REQUIRES, FOLLOWS, RELATED_TO

# Via MCP (preferred in Claude Code sessions):
# memory_relate(from_id, to_id, rel_type, description, strength)

# Via CLI:
claude-memory relate <from_id> <to_id> BUILDS_ON \
  --description "Extended the deploy procedure with rollback steps"

# Find what a memory is connected to (up to 3 hops deep)
claude-memory related <memory_id> --max-depth 2

# Search edges by type or connected memory
claude-memory edge-search --types SOLVES
claude-memory edge-search --from <memory_id>

When to create edges:

• Solution fixes a known problem → SOLVES
• New memory extends or refines an earlier one → BUILDS_ON
• Error leads to a known failure mode → CAUSES
• Two approaches to the same problem → ALTERNATIVE_TO
• Memory depends on another being true/done first → REQUIRES
• Steps in a sequence → FOLLOWS
• Conceptually related but no specific type fits → RELATED_TO

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. Recall uses semantic+keyword merge by default when embeddings exist (~200ms with warm cache). Use --no-semantic for keyword-only (~3ms). Embeddings are cached in memory (mtime-based invalidation) so repeated recalls avoid re-parsing the 24MB embeddings file. Semantic search provides deeper matching beyond exact title/tag keywords - useful for finding conceptually related memories even when different terminology was used.

MCP Server

Cognitive Memory v3.0 includes a native MCP server for direct Claude Code tool integration. Instead of CLI calls via Bash, Claude Code can call memory tools directly.

Registration: Configured in ~/.claude.json under mcpServers.cognitive-memory.

Available tools: memory_store, memory_recall, memory_get, memory_search, memory_relate, memory_related, memory_edge_get, memory_edge_search, memory_reflect, memory_reflection, memory_stats, memory_episode, memory_tags_list, memory_tags_related, memory_embed, memory_core, memory_decay, memory_config

Rich Edges

Relationships between memories are now first-class objects with their own markdown files in graph/edges/. Each edge has:

• Full YAML frontmatter (id, type, from/to IDs and titles, strength, timestamps)
• Description body explaining the relationship in detail
• Backward-compatible: edge_id field added to memory relation entries for fast BFS traversal

Edge CLI commands: edge-get, edge-search, edge-update, edge-delete Edge file format: {from-slug}--{TYPE}--{to-slug}-{6char}.md

Embedding Providers

Supports multiple embedding providers with automatic fallback:

• Ollama (default): Local, free, uses nomic-embed-text (768 dimensions)
• OpenAI (optional): Higher quality, uses text-embedding-3-small (1536 dimensions)

Configure with: claude-memory config --provider openai --openai-key "sk-..." View config: claude-memory config --show

Provider changes trigger automatic re-embedding (dimension mismatch safety). Config stored in _config.json (gitignored, may contain API key).

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 (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 (semantic is on by default)
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. Related memories exist - Create edges to connect them. After storing a new memory, check if it relates to existing ones (SOLVES a problem, BUILDS_ON a prior solution, is ALTERNATIVE_TO another approach, etc.). Well-connected memories produce richer recall and graph traversal for RAG retrieval.
12. Session ending - Prompt: "Should I store today's learnings?"

---

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