
claude-memory
Long-term memory for Claude Code. Recalls architecture, conventions, and decisions across sessions, plus an episodic observation log of what happened — so Claude explains your codebase without file traversal, follows your patterns, learns from corrections, and never re-asks what it already learned.
- version
- 0.13.2
- GitHub stars
- 27
Install
/plugin install claude-memory@claude-memory-marketplaceRun it inside Claude Code after adding the marketplace with /plugin marketplace add codenamev/claude_memory.
Contents
Discovered from sourceSkills 5
Analyze Project Skill
Analyze the current project and store facts about it in long-term memory.
Workflow
- Read key project files to understand the tech stack
- Extract facts about languages, frameworks, tools, conventions
- Store facts using
memory.store_extraction
Files to Read
Read these files (if they exist) to understand the project:
Package/Dependency Files
Gemfile- Ruby dependencies (Rails, RSpec, etc.)package.json- JavaScript/TypeScript dependenciespyproject.tomlorrequirements.txt- Python dependenciesCargo.toml- Rust dependenciesgo.mod- Go dependenciespom.xmlorbuild.gradle- Java dependencies
Configuration Files
README.md- Project overview and setup instructionstsconfig.json- TypeScript configuration.eslintrc*oreslint.config.*- ESLint configuration.prettierrc*- Prettier configuration.rubocop.ymlor.standard.yml- Ruby lintingDockerfile- Container configuration.github/workflows/*.yml- CI/CD configuration
Convention Files
.editorconfig- Editor configurationCLAUDE.mdorAGENTS.md- AI assistant instructions
What to Extract
Look for and store facts about:
| Category | Predicate | Examples |
|---|---|---|
| Languages | uses_language | Ruby, TypeScript, Python, Go, Rust |
| Frameworks | uses_framework | Rails, React, Next.js, Django, FastAPI |
| Tools | uses_tool | RSpec, Jest, ESLint, Prettier, Docker |
| Databases | uses_database | PostgreSQL, MySQL, Redis, MongoDB |
| Package Manager | uses_package_manager | Bundler, npm, pnpm, Poetry, Cargo |
| CI/CD | uses_ci | GitHub Actions, CircleCI, GitLab CI |
| Conventions | has_convention | EditorConfig, 2-space indentation |
Example Analysis
After reading Gemfile:
source 'https://rubygems.org'
gem 'rails', '~> 7.0'
gem 'pg'
gem 'rspec-rails', group: :test
Store these facts:
{
"entities": [
{"type": "language", "name": "Ruby"},
{"type": "framework", "name": "Rails"},
{"type": "database", "name": "PostgreSQL"},
{"type": "tool", "name": "RSpec"}
],
"facts": [
{
"subject": "repo",
"predicate": "uses_language",
"object": "Ruby",
"quote": "Gemfile present",
"strength": "stated"
},
{
"subject": "repo",
"predicate": "uses_framework",
"object": "Rails",
"quote": "gem 'rails', '~> 7.0'",
"strength": "stated"
},
{
"subject": "repo",
"predicate": "uses_database",
"object": "PostgreSQL",
"quote": "gem 'pg'",
"strength": "stated"
},
{
"subject": "repo",
"predicate": "uses_tool",
"object": "RSpec",
"quote": "gem 'rspec-rails'",
"strength": "stated"
},
{
"subject": "repo",
"predicate": "uses_package_manager",
"object": "Bundler",
"quote": "Gemfile present",
"strength": "stated"
}
]
}
Best Practices
- Check what exists first: Use
memory.recallwith broad query like "uses" to see existing facts - Don't duplicate: Skip facts that are already stored
- Include quotes: Reference the specific line or file where you found the information
- Use
statedstrength: For explicit declarations in config files - Be selective: Only store durable, useful facts—not every dependency
Scope
- Use
scope_hint: "project"for project-specific facts (default) - Use
scope_hint: "global"for user preferences found in global config files
Debug Memory Setup
When invoked with /debug-memory, this skill runs comprehensive diagnostics on your ClaudeMemory installation.
What This Checks
This skill will verify:
- ✅ Database existence (global and project)
- ✅ Schema version compatibility
- ✅ Hook configuration
- ✅ CLAUDE.md setup
- ✅ Published snapshot status
- ✅ MCP server connectivity
- ✅ Recent ingest activity
Step 1: Run Setup Check
First, check the memory system status using the MCP tool:
memory.check_setup
This returns:
- initialized: true/false
- version: ClaudeMemory version
- issues: List of problems found
- recommendation: Actionable next steps
Step 2: Analyze Results
Based on the check results:
If initialized = true
✅ System is healthy! Show the user:
- Version information
- Database stats
- Last successful operations
If initialized = false
⚠️ System needs setup. Check for:
- Missing database: Run
claude-memory init - Missing CLAUDE.md: Not importing memory snapshot
- Missing hooks: Hooks not configured in settings.json
- Version mismatch: Need to upgrade with
gem update claude-memory
Step 3: Provide Recommendations
Give the user clear next steps:
For missing setup:
# Initialize ClaudeMemory
claude-memory init
# Or use the setup skill
/setup-memory
For configuration issues:
# Check system health
claude-memory doctor
# View current status
claude-memory status
For version issues:
# Upgrade to latest version
gem update claude-memory
claude-memory init # Re-run init after upgrade
Step 4: Verify Fix
After user follows recommendations, run memory.check_setup again to confirm the issue is resolved.
Common Issues
"Database not found"
- Cause: ClaudeMemory not initialized
- Fix: Run
claude-memory initor/setup-memory
"Hooks not configured"
- Cause:
.claude/settings.jsonmissing hook definitions - Fix: Run
claude-memory initto add hooks
"CLAUDE.md not importing snapshot"
- Cause: Missing
@.claude/rules/claude_memory.generated.mdimport - Fix: Add import to
.claude/CLAUDE.md
"Version mismatch"
- Cause: Old ClaudeMemory version installed
- Fix: Run
gem update claude-memory
"No recent ingest activity"
- Cause: Hooks not triggering or failing silently
- Fix: Check hook configuration with
claude-memory doctor
Example Output
Running ClaudeMemory diagnostics...
✅ Global database: healthy
- Location: ~/.claude/memory.sqlite3
- Schema: v7
- Facts: 42
✅ Project database: healthy
- Location: .claude/memory.sqlite3
- Schema: v7
- Facts: 127
- Last ingest: 2026-01-29T21:47:41Z
✅ Hooks: configured
✅ Snapshot: published
✅ CLAUDE.md: importing snapshot
All systems operational! Memory is working correctly.
When to Use This Skill
Use /debug-memory when:
- Memory tools are failing with errors
- Unsure if ClaudeMemory is properly installed
- Hooks don't seem to be running
- Facts aren't being captured
- After upgrading ClaudeMemory
- Setting up a new project
Related Commands
/setup-memory- Install or upgrade ClaudeMemoryclaude-memory doctor- CLI health checkclaude-memory status- View system statusmemory.check_setup- The underlying MCP tool
Memory-First Research Pattern
When answering questions about code, architecture, patterns, decisions, or technical choices, follow this workflow:
Step 1: Query Memory First
Before reading files or exploring code, check if memory already has the answer:
memory.recall "<topic>"
Example queries:
memory.recall "authentication flow"memory.recall "database choice"memory.recall "error handling patterns"
Step 2: Use Specialized Shortcuts
For specific types of questions, use targeted memory tools:
Before Implementing Features
memory.decisions
Returns architectural decisions and constraints that may affect implementation.
Before Working with Frameworks/Databases
memory.architecture
Returns framework choices, database selection, and architectural patterns.
Before Writing Code
memory.conventions
Returns coding style, naming conventions, and project standards.
If Finding Contradictions
memory.conflicts
Returns open disputes that need resolution.
Step 3: Evaluate Memory Results
If memory has sufficient information:
- Answer using recalled facts
- Cite fact IDs or sources: "From memory (fact #42): ..."
- Avoid unnecessary file reads
If memory has partial information:
- Share what memory knows
- Note what needs investigation: "Memory shows we use PostgreSQL, but I need to check the connection pooling setup..."
- Proceed to file exploration for missing details
If memory has no information:
- Note explicitly: "Memory has no prior knowledge about [topic]"
- Proceed to file exploration
- After learning, consider if this should be stored in memory
Step 4: Explore Code (Only If Needed)
When memory is insufficient, use file exploration tools:
Readfor specific filesGrepfor searching contentGlobfor finding files by patternTask(Explore agent) for broad investigations
Step 5: Distinguish Sources
When presenting findings, clearly separate:
- Recalled knowledge: "From memory: We use RSpec for testing"
- Discovered information: "From code exploration: Found additional test helper in
spec/support/"
Why This Pattern Matters
Saves Time
Memory provides instant access to distilled knowledge without re-reading hundreds of files.
Provides Context
Past decisions, lessons learned, and rationale are preserved in memory.
Reduces Tokens
Recalled facts are concise compared to reading entire files.
Ensures Consistency
Prevents contradicting previous decisions or duplicating solved problems.
Improves Quality
Understanding past context leads to better decisions aligned with project history.
Anti-Patterns to Avoid
❌ Don't skip memory checks:
User: "What database do we use?"
Bad: *immediately reads config files*
Good: *checks memory.architecture first*
❌ Don't assume memory is wrong:
Bad: "Memory says PostgreSQL, let me verify by reading the config..."
Good: "Memory says PostgreSQL. Need any specific config details?"
❌ Don't ignore memory conflicts:
Bad: *finds conflict, picks one arbitrarily*
Good: "memory.conflicts shows authentication method disputed—let me investigate and resolve"
Example Workflow
User asks: "How do we handle errors in API responses?"
Step 1: Check memory
memory.recall "error handling API"
memory.conventions
Step 2: Evaluate results
- Memory shows: "Convention: API errors return JSON with
errorandmessagekeys" - Memory shows: "Decision: 4xx for client errors, 5xx for server errors"
Step 3: Answer with citations
"From memory: We handle API errors by returning JSON with error and message keys. Client errors use 4xx status codes, server errors use 5xx. Is there a specific error case you're working with?"
Step 4: Only if needed, explore code If user asks: "Show me the error middleware" Then use Read/Grep to find the implementation.
This workflow is automatically loaded when you ask technical questions. You don't need to invoke it manually—it guides Claude's research process behind the scenes.
Memory Skill
You have access to a long-term memory system. Use it to remember important facts across sessions.
When to Store Facts
After completing a task or learning something important about the project, store durable facts using memory.store_extraction. Look for:
- Tech stack: databases, frameworks, languages, platforms
- Conventions: coding standards, naming patterns, preferences
- Decisions: architectural choices, design decisions
- Preferences: user preferences that should persist
How to Store Facts
Call the memory.store_extraction MCP tool with:
{
"entities": [
{"type": "database", "name": "postgresql"}
],
"facts": [
{
"subject": "repo",
"predicate": "uses_database",
"object": "postgresql",
"quote": "We use PostgreSQL for persistence",
"strength": "stated",
"scope_hint": "project"
}
]
}
Predicates
| Predicate | Use for | Example |
|---|---|---|
uses_database | Database choice | postgresql, redis |
uses_framework | Framework | rails, react, nextjs |
deployment_platform | Where deployed | vercel, aws, heroku |
convention | Coding standard | "4-space indentation" |
decision | Architectural choice | "Use microservices" |
auth_method | Auth approach | "JWT tokens" |
Scope
project: Only this project (default)global: All projects (user preferences)
Use global when user says "always", "in all projects", or "my preference".
How to Recall Facts
Use memory.recall to search for relevant facts:
{"query": "database", "limit": 10}
Available Tools
memory.recall- Search facts by querymemory.store_extraction- Store new factsmemory.explain- Get fact details with provenancememory.promote- Promote project fact to globalmemory.status- Check database healthmemory.changes- Recent updatesmemory.conflicts- Open contradictions
Best Practices
- Be selective: Only store durable facts that will be useful later
- Include quotes: Add the source text for provenance
- Set scope correctly: Project-specific vs global preferences
- Check before storing: Use
memory.recallto avoid duplicates
ClaudeMemory Setup & Upgrade
This skill automatically sets up or upgrades ClaudeMemory based on your current state.
What This Skill Does
When invoked, it will:
-
Check current installation status
- Detect installed gem version
- Check database existence and health
- Verify configuration files
-
Determine required action
- Fresh install (no databases)
- Upgrade (version mismatch)
- Verification (already up to date)
-
Execute setup/upgrade automatically
- Run
claude-memory doctorfor health check - Add version markers to
.claude/CLAUDE.md - Run smoke tests
- Report results
- Run
-
Provide next steps
- Restart recommendations if needed
- Usage guidance
Instructions
IMPORTANT: This skill should take action, not just provide instructions.
Step 1: Check Installation Status
gem list claude_memory
claude-memory --version
claude-memory doctor
Analyze the output to determine current state.
- If
gem listshows noclaude_memoryentry, the gem is not installed. Guide the user:gem install claude_memory - If running in plugin mode (
CLAUDE_PLUGIN_ROOTis set), hooks and MCP are managed by the plugin — only databases and memory instructions need setup.
Step 2: Determine Action Required
- Not installed: Databases don't exist
- Action: Run
claude-memory init(ask user for --global flag preference)
- Action: Run
- Installed but outdated: Version marker missing or old
- Action: Run upgrade steps (doctor, add version marker, verify)
- Up to date: All healthy
- Action: Report status only
Step 3: Execute Required Actions
For Fresh Install:
- Ask user: "Install globally only or with project memory? [project/global]"
- Run
claude-memory init(with --global if selected) - Run
claude-memory doctorto verify - Add version marker to
.claude/CLAUDE.md - Report success
For Upgrade:
- Run
claude-memory doctor(auto-runs migrations) - Add/update version marker in
.claude/CLAUDE.md - Run
claude-memory statsfor smoke test - Report upgrade complete
For Verification:
- Run
claude-memory doctor - Confirm version in
.claude/CLAUDE.md - Report all healthy
Step 4: Report Results
Provide a clear summary:
- ✅ What was done
- 📊 Current status (facts, schema version, etc.)
- 🔄 Next steps (if any)
After Setup/Upgrade
Always remind the user:
- Restart Claude Code if configuration files were modified
- Test memory tools: Try
memory.statusormemory.recall "<topic>" - Use memory-first workflow: Check memory before reading files
What Gets Created
Databases
~/.claude/memory.sqlite3- Global knowledge (preferences, conventions).claude/memory.sqlite3- Project-specific facts and decisions
Configuration Files
.claude/CLAUDE.md- Workflow instructions for memory-first usage.claude/settings.json- Hooks for automatic ingestion.claude.json- MCP server configuration.claude/rules/claude_memory.generated.md- Published snapshot
Hooks
ClaudeMemory automatically ingests transcripts on these events:
- SessionStart - Catch up on previous session
- Stop - After each response
- SessionEnd - Final ingestion before closing
- PreCompact - Before context summarization
Common Scenarios
Fresh Install
User has never installed ClaudeMemory:
- Ask installation preference (project vs global)
- Run
claude-memory initwith appropriate flags - Verify with
doctor - Add version marker
- Report success and next steps
Upgrade After Gem Update
User updated gem but not configuration:
- Run
claude-memory doctor(auto-migrates schema) - Update version marker in
.claude/CLAUDE.md - Verify with smoke tests
- Report upgrade complete
Verification
User wants to check current status:
- Run
claude-memory doctor - Run
claude-memory stats - Check version marker in
.claude/CLAUDE.md - Report all findings
Troubleshooting Guide
If automatic setup fails, provide these solutions:
Permission Denied
chmod +x $(which claude-memory)
Database Locked
- Close other Claude sessions
- Run
claude-memory recover
Missing Ruby ClaudeMemory requires Ruby 3.2.0+. Check with:
ruby --version
Hooks Not Working Re-run setup:
claude-memory init
Memory-First Workflow
After successful setup, always remind users:
- Query memory first:
memory.recall "<topic>" - Use semantic shortcuts:
memory.decisions,memory.conventions,memory.architecture - Check before exploring: Memory saves time vs reading files
- Combine knowledge: Merge recalled facts with code exploration
This workflow leverages distilled knowledge from previous sessions.
Commands 3
Analyze this project to understand its tech stack, frameworks, tools, and conventions.
Steps
-
Read key project files (if they exist):
Gemfile,package.json,pyproject.toml,Cargo.toml,go.modREADME.md,tsconfig.json,Dockerfile.eslintrc*,.prettierrc*,.rubocop.yml,.standard.yml.github/workflows/*.yml
-
Extract facts about:
- Languages (Ruby, TypeScript, Python, Go, Rust)
- Frameworks (Rails, React, Next.js, Django, FastAPI)
- Tools (RSpec, Jest, ESLint, Prettier, Docker)
- Databases (PostgreSQL, MySQL, Redis, MongoDB)
- Package managers (Bundler, npm, pnpm, Poetry, Cargo)
- CI/CD (GitHub Actions, CircleCI, GitLab CI)
-
Use
memory.store_extractionto store facts with:- Appropriate entity types and predicates
- Quotes referencing the source file/line
strength: "stated"for explicit declarations
-
Report what you learned and stored.
Recall facts stored in memory about this project.
Use memory.recall to search for relevant facts. Try queries like:
- "uses" - to find tech stack facts
- "framework" - to find framework choices
- "database" - to find database facts
- "tool" - to find tooling facts
- "convention" - to find coding conventions
Summarize what you know about this project's tech stack and conventions.
$ARGUMENTS
Store the following in memory using memory.store_extraction:
$ARGUMENTS
Guidelines
-
Choose appropriate entity types:
database,framework,language,platform,tool,convention
-
Choose appropriate predicates:
uses_database,uses_framework,uses_language,uses_toolhas_convention,prefers,decision
-
Set scope:
- Use
scope_hint: "global"if the user says this applies to all projects - Use
scope_hint: "project"(default) for project-specific facts
- Use
-
Include the user's statement as the
quotefor provenance. -
Confirm what was stored.
MCP servers 1
Sponsors
Details
- Marketplace
- codenamev/claude_memory
- Category
- Community