---
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`, `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](#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).

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

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

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

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

```json
// .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:

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

---

**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)