szoloth/memory-store

Memory Store Skill

Manage Claude Code's three-tier memory system for pattern observation and rule extraction, with access-based memory decay.

Purpose

This skill provides access to the memory store that powers Claude's learning system:

1. Query observed patterns from past sessions (auto-tracks access)
2. Check which rules are currently active
3. Add manual observations
4. View memory decay tiers (Hot/Warm/Cold)
5. Debug and manage the memory system

Architecture

diary/ (raw)  →  patterns.jsonl (observed)  →  rules.json (active)  →  CLAUDE.md (synced)
     ↑                    ↑                          ↑                       ↑
  /diary             /reflect                  sync-rules               /curate
                          │
                    access tracking
                    (lastAccessed, accessCount)

Commands

View Statistics

~/.claude/bin/claude-memory stats

Shows:

• Total patterns and active count
• Access tiers: Hot/Warm/Cold counts
• Patterns by category
• Active rules count
• Diary entry count
• Last update timestamp

List Patterns

# List all patterns
~/.claude/bin/claude-memory list-patterns

# Filter by category
~/.claude/bin/claude-memory list-patterns --category git

# Filter by minimum confidence
~/.claude/bin/claude-memory list-patterns --min-confidence 0.7

# Active patterns only
~/.claude/bin/claude-memory list-patterns --active-only

Search Patterns

# Search by keyword (auto-increments accessCount)
~/.claude/bin/claude-memory query "testing"
~/.claude/bin/claude-memory query "React"
~/.claude/bin/claude-memory query "commit"

# Search without updating access tracking
~/.claude/bin/claude-memory query "testing" --no-track

Important: Queries automatically increment accessCount and update lastAccessed for matching patterns. This powers the decay system.

Decay Report

~/.claude/bin/claude-memory decay-report

Shows patterns organized by access tier:

• Hot: Accessed in last 7 days - always in CLAUDE.md
• Warm: Accessed 8-30 days ago - included if under limit
• Cold: Not accessed in 30+ days - demoted from CLAUDE.md

Add Pattern Manually

# Add a new pattern observation
~/.claude/bin/claude-memory add-pattern "always use TypeScript strict mode" \
  --category code-style \
  --confidence 0.8 \
  --source "diary/2025-12-17-session-1.md"

Categories: git, code-style, testing, workflow, preferences, ui, data-sync, automation, project-specific

Confidence levels:

• 0.3-0.4: Single observation
• 0.5-0.7: Emerging pattern (2 occurrences)
• 0.8-0.9: Strong pattern (3+ occurrences)

Promote/Demote Rules

# Promote a pattern to active rule
~/.claude/bin/claude-memory promote PATTERN_ID

# Demote a rule back to pattern
~/.claude/bin/claude-memory demote PATTERN_ID

# Auto-promote high-confidence patterns meeting threshold
~/.claude/bin/claude-memory sync-rules

Promotion threshold (default):

• Minimum confidence: 0.7
• Minimum occurrences: 3

View Raw Files

# View active rules
cat ~/.claude/memory/rules/rules.json | jq '.rules'

# View all patterns (JSONL format)
cat ~/.claude/memory/patterns/patterns.jsonl | jq -s '.'

# View pattern index
cat ~/.claude/memory/patterns/index.json | jq '.'

File Locations

~/.claude/memory/
├── patterns/
│   ├── index.json        # Metadata and statistics
│   └── patterns.jsonl    # Append-only pattern store
├── rules/
│   └── rules.json        # Active high-confidence rules
├── diary/                # Raw session transcripts
└── reflections/          # Analysis documents

Pattern Schema

Each pattern in patterns.jsonl:

{
  "id": "uuid",
  "category": "git",
  "pattern": "use conventional commit format",
  "source_diaries": ["diary/2025-12-17-session-1.md"],
  "confidence": 0.8,
  "created_at": "2025-12-17T00:00:00Z",
  "last_seen": "2025-12-17T00:00:00Z",
  "occurrences": 3,
  "active": true,
  "lastAccessed": "2026-02-01T00:00:00Z",
  "accessCount": 5
}

Access Tracking Fields

• lastAccessed: ISO timestamp, updated each time pattern is queried
• accessCount: Integer, incremented each time pattern is queried

These power the decay system. Patterns with high accessCount resist decay.

Rule Schema

Each rule in rules.json:

{
  "id": "pattern-uuid",
  "category": "git",
  "rule": "use conventional commit format",
  "confidence": 0.85,
  "occurrences": 5,
  "promoted_at": "2025-12-17T00:00:00Z"
}

Sync Settings

Rules synced to CLAUDE.md are capped to prevent context bloat:

"sync_settings": {
  "max_rules_in_claude_md": 20,
  "sort_by": "confidence",
  "prune_strategy": "lowest_confidence"
}

• Max 20 rules sync to CLAUDE.md (highest confidence first)
• Remaining rules stay in rules.json for on-demand access
• Adjust cap: jq '.sync_settings.max_rules_in_claude_md = 25' rules.json

Common Tasks

"What patterns have you observed?"

~/.claude/bin/claude-memory list-patterns

"What rules are active?"

cat ~/.claude/memory/rules/rules.json | jq '.rules[] | "\(.category): \(.rule)"'

"Search for patterns about X"

~/.claude/bin/claude-memory query "X"

"How confident are you about pattern X?"

~/.claude/bin/claude-memory query "X"
# Shows confidence score and occurrence count

"Add this as a pattern I want you to remember"

~/.claude/bin/claude-memory add-pattern "description" --category CATEGORY --confidence 0.7

"Reset/clear the memory store"

# Clear patterns (keep structure)
> ~/.claude/memory/patterns/patterns.jsonl

# Clear rules
jq '.rules = []' ~/.claude/memory/rules/rules.json > /tmp/r.json && mv /tmp/r.json ~/.claude/memory/rules/rules.json

# Reset index stats
jq '.pattern_count = 0 | .stats.total_patterns = 0' ~/.claude/memory/patterns/index.json > /tmp/i.json && mv /tmp/i.json ~/.claude/memory/patterns/index.json

Integration with ACE Framework

| Command | Role | Action | |---------|------|--------| | /diary | Generator | Creates raw episodic memory | | /reflect | Reflector | Extracts patterns → patterns.jsonl | | /curate | Curator | Syncs rules → CLAUDE.md | | claude-memory | Query | Direct access to memory store |

Troubleshooting

Patterns not showing up

1. Check file exists:

   ls -la ~/.claude/memory/patterns/patterns.jsonl
   

2. Verify JSON format:

   cat ~/.claude/memory/patterns/patterns.jsonl | jq -s 'length'
   

Rules not syncing to CLAUDE.md

1. Check rules.json has rules:

   jq '.rules | length' ~/.claude/memory/rules/rules.json
   

2. Run /curate to sync

Duplicate patterns

The CLI auto-deduplicates - adding an existing pattern increments its occurrence count instead of creating a duplicate.

Related Commands

• /diary - Generate session diary entry
• /reflect - Analyze diaries and extract patterns
• /curate - Sync rules to CLAUDE.md
• ambient-context skill - Manage event queue system