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, graphs, graph-create

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

Directory Structure

Skill layer (Claude Code reads this)

~/.claude/skills/cognitive-memory/
├── SKILL.md                           # This file
└── SCHEMA.md                          # Memory file format reference

Application code

/mnt/NV2/Development/cognitive-memory/
├── client.py                          # Core API + CLI entrypoint
├── cli.py                             # CLI interface
├── common.py                          # Shared utilities
├── analysis.py                        # Reflection/analysis
├── edges.py                           # Edge management
├── embeddings.py                      # Embedding support
├── mcp_server.py                      # MCP server for Claude Code tools
├── feature.json                       # Version metadata
├── scripts/
│   ├── session_memory.py              # SessionEnd hook — auto-stores session learnings
│   ├── edge-proposer.py               # Edge proposer
│   └── memory-git-sync.sh             # Git sync for data dir
└── systemd/
    ├── README.md                      # Install instructions for timers
    ├── cognitive-memory-daily.*       # Daily: decay, core, git sync
    ├── cognitive-memory-embed.*       # Hourly: refresh embeddings
    └── cognitive-memory-weekly.*      # Weekly: reflection cycle

Data Directory Structure

Data lives at $XDG_DATA_HOME/cognitive-memory/ (default: ~/.local/share/cognitive-memory/). Override with COGNITIVE_MEMORY_DIR env var. Named graphs live as siblings (see Multi-Graph below).

~/.local/share/cognitive-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 CORE.md in the data directory. 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).

Multi-Graph

Graphs are named, isolated memory namespaces. Each graph has its own index, state, embeddings, episodes, edges, CORE.md, and REFLECTION.md. Use them to separate unrelated domains (e.g., work vs. personal, per-project isolation).

Storage Layout

~/.local/share/
├── cognitive-memory/              # "default" graph (always exists)
│   ├── graph/, episodes/, vault/
│   ├── _index.json, _state.json, _embeddings.json, _config.json
│   ├── CORE.md, REFLECTION.md
│   └── ...
└── cognitive-memory-graphs/       # Named graphs live here as siblings
    ├── work/                      # Graph "work"
    │   ├── graph/, episodes/, vault/
    │   ├── _index.json, _state.json, ...
    │   └── ...
    └── research/                  # Graph "research"
        └── ...

Creating a Graph

Use graph-create to set up a new graph with the full directory structure:

# Convention path (~/.local/share/cognitive-memory-graphs/work/)
claude-memory graph-create work

# Custom path (registered in default graph's _config.json automatically)
claude-memory graph-create work --path /mnt/data/work-memories

Graphs are also auto-created on first use — storing a memory with graph=<name> creates the directory structure automatically:

# CLI: use --graph before the subcommand
claude-memory --graph work store --type decision \
  --title "Chose Postgres" --content "..." --tags "db,arch"

# MCP: pass graph parameter on any tool
# memory_store(type="decision", title="...", content="...", graph="work")

Using Graphs

Every CLI command and MCP tool accepts a graph parameter:

# CLI
claude-memory --graph work recall "authentication"
claude-memory --graph work stats
claude-memory --graph work embed

# List all graphs (default + configured + discovered on disk)
claude-memory graphs
# MCP: memory_graphs()

Per-Project Graph Routing

Set COGNITIVE_MEMORY_GRAPH to automatically route all memory operations to a specific graph without passing graph= on every call. Configure it per-project in Claude Code's settings:

// .claude/settings.json (in your project root)
{
  "env": {
    "COGNITIVE_MEMORY_GRAPH": "paper-dynasty"
  }
}

Resolution order: explicit graph parameter > COGNITIVE_MEMORY_GRAPH env var > "default".

This means a project can set its default graph, but individual calls can still override it with an explicit graph parameter when needed.

Graph Isolation

• Each graph has independent index, state, embeddings, decay scores, episodes, and edges
• Edges can only connect memories within the same graph — cross-graph edges are not supported
• Embedding configuration (_config.json) is per-graph — each graph can use a different provider
• The graph registry (custom path mappings) lives in the default graph's _config.json

Automated Maintenance

• Systemd timers (decay, core, embed, reflect) run against all graphs via maintain-all-graphs.sh
• Git sync (memory-git-sync.sh) syncs the default graph and any named graphs that are git repos
• edge-proposer.py and session_memory.py accept --graph to target a specific graph

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?"

---

Skill: ~/.claude/skills/cognitive-memory/ App: /mnt/NV2/Development/cognitive-memory/ Data: $XDG_DATA_HOME/cognitive-memory/ (default: ~/.local/share/cognitive-memory/) Version: 3.1.0 Created: 2026-02-13 Migrated from: MemoryGraph (SQLite)