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

---
name: cognitive-memory
description: 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:

```bash
# --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

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)

```bash
# 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

```bash
# 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

```bash
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)

```bash
# 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

```bash
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

```bash
# 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

```bash
# 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`

```bash
# 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

```bash
# 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).

## Episode Logging

Daily markdown files appended during sessions, providing chronological context:

```markdown
# 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**: `$XDG_DATA_HOME/cognitive-memory/` (default: `~/.local/share/cognitive-memory/`)
**Version**: 3.1.0
**Created**: 2026-02-13
**Migrated from**: MemoryGraph (SQLite)