From cc-simple-memory
Reference for the Claude Code persistent memory system. Use when running claude-memory commands, managing MEMORY.md files, debugging extraction/GC, or understanding how cross-session memory works.
npx claudepluginhub strml/cc-simple-memory --plugin cc-simple-memoryThis skill uses the workspace's default tool permissions.
Two-layer memory. Proactive in-session updates (via CLAUDE.md) are primary. Stop hook runs background Sonnet extraction as a safety net. Opus GC prevents unbounded growth.
Provides stable principles, keyword registry, and navigation for Claude Code memory system (CLAUDE.md, static memory, hierarchy, imports). Delegates details to docs-management skill.
Organizes, extracts, prunes, and verifies Claude Code persistent memory files: MEMORY.md index, topic extraction, staleness detection, accuracy checks. Use near 200-line limit, after insights, or project changes.
Explains claude-mem's observation capture from Read/Edit/Bash actions, memory injection starting second session, and local storage in ~/.claude-mem. Activates on 'how does it work?' queries.
Share bugs, ideas, or general feedback.
Two-layer memory. Proactive in-session updates (via CLAUDE.md) are primary. Stop hook runs background Sonnet extraction as a safety net. Opus GC prevents unbounded growth.
Session → Claude writes MEMORY.md proactively
Stop → extract-learnings.sh (Sonnet, background, detached)
Every 10th extraction → gc-memory.sh (Opus, consolidates + archives)
/clear → capture-learnings.sh (Sonnet, before context discarded)
| File | Purpose |
|---|---|
~/.claude/projects/<encoded-path>/memory/MEMORY.md | Project memory (auto-loaded) |
~/.claude/projects/<encoded-path>/memory/ARCHIVE.md | Cold storage (GC only) |
~/.claude/rules/global-memory.md | Global cross-project memory (auto-loaded everywhere) |
~/.claude/memory/global-archive.md | Global cold storage |
${CLAUDE_PLUGIN_ROOT}/hooks/extract-learnings.sh | Stop hook (background Sonnet) |
${CLAUDE_PLUGIN_ROOT}/hooks/gc-memory.sh | GC hook (Opus, every 10 extractions) |
${CLAUDE_PLUGIN_ROOT}/hooks/capture-learnings.sh | /clear hook (Sonnet) |
${CLAUDE_PLUGIN_ROOT}/bin/claude-memory | CLI tool |
📌 Both / AND . are replaced with -: sed 's|[/.]|-|g'
Located at ${CLAUDE_PLUGIN_ROOT}/bin/claude-memory (symlinked to ~/bin/claude-memory by setup.sh).
claude-memory show # Display project + global memory
claude-memory search "query" # Search current project transcripts
claude-memory search "query" --all # Search ALL project transcripts
claude-memory log # Recent extraction activity
claude-memory stats # Memory sizes, transcript counts
claude-memory extract --dry-run # Preview extraction without writing
claude-memory gc # Run Opus GC on oversized memory files
claude-memory gc --dry-run # Preview GC output without writing
claude-memory show archive # View archived (cold storage) items
Stop/GC hooks run nested claude -p. Critical env vars:
CLAUDECODE="" CLAUDE_CODE_ENTRYPOINT="" CLAUDE_CODE_SIMPLE=1 \
claude -p --model haiku --effort low \
--no-session-persistence --tools "" --disable-slash-commands \
--strict-mcp-config --settings '{"disableAllHooks":true}' ...
CLAUDE_CODE_SIMPLE=1 cuts token cost from ~6-8k → ~200 (skips CLAUDE.md/skills/MCP)--model sonnet --effort medium/dev/null — kills the process silentlyclaude CLI network — test nested CLI from real terminaldisown required after & — Claude Code waits on process group otherwiseCLAUDECODE="" CLAUDE_CODE_ENTRYPOINT="" required — nested claude -p fails silently otherwiseAdd SKIP_MEMORY_EXTRACTION on its own line in a transcript to skip extraction for that session.
Check with: grep -qE '^SKIP_MEMORY_EXTRACTION$'
Triggers when grep -c '^## user' > 20 AND filtered size > 30000 bytes.
Uses Haiku with timeout 90. mkdir -p /tmp/claude before temp file creation.
!claude-memory stats 2>/dev/null || echo "(claude-memory not on PATH — run /memory-setup)"
MEMORY.md is an index, not a content dump. It is always loaded into context.
Entry types:
- [Short Title](filename.md) — one-line summary (~150 chars max)- Terse fact or rule (one line, no topic file needed)## Feedback, ## Key Facts, ## Solutions, ## Architecture, ## Active Projects, ## DecisionsRules:
(→ topic file)