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-marketplace

Run it inside Claude Code after adding the marketplace with /plugin marketplace add codenamev/claude_memory.

Contents

Discovered from source

Skills 5

Analyze Project Skill

Analyze the current project and store facts about it in long-term memory.

Workflow

  1. Read key project files to understand the tech stack
  2. Extract facts about languages, frameworks, tools, conventions
  3. 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 dependencies
  • pyproject.toml or requirements.txt - Python dependencies
  • Cargo.toml - Rust dependencies
  • go.mod - Go dependencies
  • pom.xml or build.gradle - Java dependencies

Configuration Files

  • README.md - Project overview and setup instructions
  • tsconfig.json - TypeScript configuration
  • .eslintrc* or eslint.config.* - ESLint configuration
  • .prettierrc* - Prettier configuration
  • .rubocop.yml or .standard.yml - Ruby linting
  • Dockerfile - Container configuration
  • .github/workflows/*.yml - CI/CD configuration

Convention Files

  • .editorconfig - Editor configuration
  • CLAUDE.md or AGENTS.md - AI assistant instructions

What to Extract

Look for and store facts about:

CategoryPredicateExamples
Languagesuses_languageRuby, TypeScript, Python, Go, Rust
Frameworksuses_frameworkRails, React, Next.js, Django, FastAPI
Toolsuses_toolRSpec, Jest, ESLint, Prettier, Docker
Databasesuses_databasePostgreSQL, MySQL, Redis, MongoDB
Package Manageruses_package_managerBundler, npm, pnpm, Poetry, Cargo
CI/CDuses_ciGitHub Actions, CircleCI, GitLab CI
Conventionshas_conventionEditorConfig, 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

  1. Check what exists first: Use memory.recall with broad query like "uses" to see existing facts
  2. Don't duplicate: Skip facts that are already stored
  3. Include quotes: Reference the specific line or file where you found the information
  4. Use stated strength: For explicit declarations in config files
  5. 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 init or /setup-memory

"Hooks not configured"

  • Cause: .claude/settings.json missing hook definitions
  • Fix: Run claude-memory init to add hooks

"CLAUDE.md not importing snapshot"

  • Cause: Missing @.claude/rules/claude_memory.generated.md import
  • 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 ClaudeMemory
  • claude-memory doctor - CLI health check
  • claude-memory status - View system status
  • memory.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:

  • Read for specific files
  • Grep for searching content
  • Glob for finding files by pattern
  • Task (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 error and message keys"
  • 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

PredicateUse forExample
uses_databaseDatabase choicepostgresql, redis
uses_frameworkFrameworkrails, react, nextjs
deployment_platformWhere deployedvercel, aws, heroku
conventionCoding standard"4-space indentation"
decisionArchitectural choice"Use microservices"
auth_methodAuth 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 query
  • memory.store_extraction - Store new facts
  • memory.explain - Get fact details with provenance
  • memory.promote - Promote project fact to global
  • memory.status - Check database health
  • memory.changes - Recent updates
  • memory.conflicts - Open contradictions

Best Practices

  1. Be selective: Only store durable facts that will be useful later
  2. Include quotes: Add the source text for provenance
  3. Set scope correctly: Project-specific vs global preferences
  4. Check before storing: Use memory.recall to 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:

  1. Check current installation status

    • Detect installed gem version
    • Check database existence and health
    • Verify configuration files
  2. Determine required action

    • Fresh install (no databases)
    • Upgrade (version mismatch)
    • Verification (already up to date)
  3. Execute setup/upgrade automatically

    • Run claude-memory doctor for health check
    • Add version markers to .claude/CLAUDE.md
    • Run smoke tests
    • Report results
  4. 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 list shows no claude_memory entry, the gem is not installed. Guide the user: gem install claude_memory
  • If running in plugin mode (CLAUDE_PLUGIN_ROOT is 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)
  • 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:

  1. Ask user: "Install globally only or with project memory? [project/global]"
  2. Run claude-memory init (with --global if selected)
  3. Run claude-memory doctor to verify
  4. Add version marker to .claude/CLAUDE.md
  5. Report success

For Upgrade:

  1. Run claude-memory doctor (auto-runs migrations)
  2. Add/update version marker in .claude/CLAUDE.md
  3. Run claude-memory stats for smoke test
  4. Report upgrade complete

For Verification:

  1. Run claude-memory doctor
  2. Confirm version in .claude/CLAUDE.md
  3. 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:

  1. Restart Claude Code if configuration files were modified
  2. Test memory tools: Try memory.status or memory.recall "<topic>"
  3. 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:

  1. Ask installation preference (project vs global)
  2. Run claude-memory init with appropriate flags
  3. Verify with doctor
  4. Add version marker
  5. Report success and next steps

Upgrade After Gem Update

User updated gem but not configuration:

  1. Run claude-memory doctor (auto-migrates schema)
  2. Update version marker in .claude/CLAUDE.md
  3. Verify with smoke tests
  4. Report upgrade complete

Verification

User wants to check current status:

  1. Run claude-memory doctor
  2. Run claude-memory stats
  3. Check version marker in .claude/CLAUDE.md
  4. 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:

  1. Query memory first: memory.recall "<topic>"
  2. Use semantic shortcuts: memory.decisions, memory.conventions, memory.architecture
  3. Check before exploring: Memory saves time vs reading files
  4. 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

  1. Read key project files (if they exist):

    • Gemfile, package.json, pyproject.toml, Cargo.toml, go.mod
    • README.md, tsconfig.json, Dockerfile
    • .eslintrc*, .prettierrc*, .rubocop.yml, .standard.yml
    • .github/workflows/*.yml
  2. 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)
  3. Use memory.store_extraction to store facts with:

    • Appropriate entity types and predicates
    • Quotes referencing the source file/line
    • strength: "stated" for explicit declarations
  4. 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

  1. Choose appropriate entity types:

    • database, framework, language, platform, tool, convention
  2. Choose appropriate predicates:

    • uses_database, uses_framework, uses_language, uses_tool
    • has_convention, prefers, decision
  3. Set scope:

    • Use scope_hint: "global" if the user says this applies to all projects
    • Use scope_hint: "project" (default) for project-specific facts
  4. Include the user's statement as the quote for provenance.

  5. Confirm what was stored.

MCP servers 1

Sponsors

Details

Marketplace
codenamev/claude_memory
Category
Community