Getting Started with ClaudeMemory

ClaudeMemory gives Claude Code a persistent, intelligent memory across all your conversations. This guide will walk you through installation, setup, and your first project.

Prerequisites

Ruby 3.2.0+ installed
Claude Code CLI installed and working
Basic familiarity with command line

Installation

Step 1: Install the Gem

gem install claude_memory

Verify installation:

claude-memory --version
# => claude_memory 0.10.0

Step 2: Install the Plugin

From within Claude Code, add the marketplace and install the plugin:

# Add the marketplace (one-time setup)
/plugin marketplace add codenamev/claude_memory

# Install the plugin
/plugin install claude-memory

Verify the plugin is loaded:

/plugin
# Navigate to "Installed" tab - you should see "claude-memory"

Step 3: Initialize Memory

Initialize both global and project-specific memory:

# From your project directory
claude-memory init

This creates:

Global database: ~/.claude/memory.sqlite3 (user-wide knowledge)
Project database: .claude/memory.sqlite3 (project-specific facts)
Hook configuration for automatic memory updates
MCP server setup for Claude to access memory

Expected output:

✓ Created global database at ~/.claude/memory.sqlite3
✓ Created project database at .claude/memory.sqlite3
✓ Configured hooks for automatic ingestion
✓ MCP server ready
✓ Setup complete!

Understanding the Dual-Database System

ClaudeMemory uses two separate databases to intelligently separate knowledge:

Global Database (`~/.claude/memory.sqlite3`)

Purpose: User-wide knowledge that applies everywhere

What gets stored:

Your coding preferences and conventions
Personal style choices
Tool preferences across projects
General development patterns you prefer

Examples:

"I prefer 4-space indentation in all my projects"
"I always use single quotes for strings in Ruby"
"I like descriptive variable names"

Project Database (`.claude/memory.sqlite3`)

Purpose: Project-specific knowledge

What gets stored:

This project's tech stack
Architecture decisions for this codebase
Project-specific conventions
Team agreements and constraints

Examples:

"This app uses PostgreSQL"
"We deploy to Vercel"
"This project follows Rails conventions"

How Facts Get Scoped

Claude automatically detects scope signals in your conversation:

Signal	Scope	Example
"always", "in all projects"	Global	"I always prefer tabs over spaces"
"my preference", "I prefer"	Global	"My preference is verbose error messages"
Project tech choices	Project	"We're using React for the frontend"
"this app", "this project"	Project	"This app uses JWT authentication"

You can also manually promote facts from project to global:

# From command line
claude-memory promote <fact_id>

# Or ask Claude
"Remember that I prefer descriptive commit messages - make that a global preference"

Two Kinds of Memory: Facts and Observations

ClaudeMemory remembers two complementary things:

Facts answer "what is true" — durable, structured truths about your project (uses_database: sqlite, conventions, decisions). This is the semantic layer the sections above describe.
Observations answer "what happened" — an append-only narrative log of the moments in your sessions ("decided to add a corroboration gate so fleeting mentions don't harden into facts"). This is the episodic layer (0.13.0+).

	Facts	Observations
Captures	Durable truths	Events / narrative
Changes	Explicitly (supersession, rejection)	Automatically (dedup, consolidation, expiry)
Promotion	—	Promoted to a fact after corroboration (≥2 sightings)

Why this matters: the distiller used to commit a fact the first time it saw a claim — so a database named once in a comparison could become a false uses_database. Observations make repeated sighting the gate: an observation graduates to a fact only after it recurs. That's an anti-hallucination defense built into the memory model.

Observations are managed for you — deduplicated and consolidated automatically on PreCompact/SessionEnd at no extra API cost. To see or curate them:

# Inspect the episodic log (counts, promotion readiness, compression, recent)
claude-memory observations

# Promote a corroborated observation to a fact
claude-memory observations promote <id> --predicate uses_database --object sqlite

The dashboard's Observations panel shows the same at a glance, and the /reflect skill runs a guided survey → consolidate → promote pass.

Setting Up Your First Project

Scenario 1: Fresh Install (New Project)

If you just installed ClaudeMemory and are starting a new project:

cd ~/projects/my-new-app
claude-memory init

# Analyze your project to bootstrap memory
# (From within Claude Code)
/claude-memory:analyze

The analyze skill will read your project files (Gemfile, package.json, etc.) and automatically extract:

Languages and frameworks
Database systems
Build tools
Testing frameworks

Scenario 2: Adding Memory to Existing Project

If you already have the plugin installed globally and want to add memory to an existing project:

cd ~/projects/existing-app
claude-memory init

# Just the project database gets created
# Global database already exists from initial setup

Then tell Claude about your project naturally:

You: "This is a Rails 7 app with PostgreSQL, using Sidekiq for background jobs"
Claude: [works on your task]
# Facts automatically extracted and stored on session stop

Scenario 3: Multiple Projects

Your global preferences travel with you:

# Project A
cd ~/projects/project-a
claude-memory init
# Uses: ~/.claude/memory.sqlite3 + .claude/memory.sqlite3

# Project B
cd ~/projects/project-b
claude-memory init
# Uses: ~/.claude/memory.sqlite3 + .claude/memory.sqlite3 (different file!)

Both projects share your global preferences but have separate project-specific knowledge.

Using ClaudeMemory

Natural Conversation

Memory happens automatically. Just talk to Claude normally:

You: "I'm building a Rails API with PostgreSQL, deploying to Heroku"
Claude: "I'll help you set that up..."

# Behind the scenes (on session stop):
# ✓ Transcript ingested
# ✓ Facts extracted:
#   - uses_framework: rails (project scope)
#   - uses_database: postgresql (project scope)
#   - deployment_platform: heroku (project scope)
# ✓ Stored in .claude/memory.sqlite3
# ✓ No user action needed

Later, in a new conversation:

You: "Help me add a background job"
Claude: [calls memory.recall]
Claude: "Based on my memory, you're using Rails with PostgreSQL on Heroku.
        I recommend using Sidekiq since it integrates well with your stack..."

Analyzing Your Project

Bootstrap memory with project facts:

/claude-memory:analyze

This reads configuration files and extracts structured knowledge:

Gemfile → Ruby gems and versions
package.json → Node dependencies
docker-compose.yml → Services and databases
.tool-versions → Language versions
And more!

Checking What's Remembered

Ask Claude to recall knowledge:

You: "What do you remember about this project?"
Claude: [calls memory.recall]
Claude: "I remember this project uses:
        - Framework: Ruby on Rails 7.1
        - Database: PostgreSQL 15
        - Deployment: Heroku
        - Background Jobs: Sidekiq"

Or use CLI commands:

# Search for facts
claude-memory recall "database"

# Show recent changes
claude-memory changes

# Check for conflicts
claude-memory conflicts

Promoting Facts to Global

When you want a project preference to apply everywhere:

You: "I like using descriptive variable names - remember that for all my projects"
Claude: [stores with scope_hint: global]

Or promote manually:

# List project facts
claude-memory recall --scope project

# Promote by ID
claude-memory promote 42

Verification

Run Doctor Command

Check system health:

claude-memory doctor

Expected output (healthy system):

ClaudeMemory Doctor Report
==========================

✓ Global database: ~/.claude/memory.sqlite3
  - Schema version: 17
  - Facts: 12
  - Entities: 8
  - Status: Healthy

✓ Project database: .claude/memory.sqlite3
  - Schema version: 17
  - Facts: 23
  - Entities: 15
  - Status: Healthy

✓ MCP server: Configured
✓ Hooks: Active (5 hooks registered)

All systems operational.

Check Database Creation

Verify files exist:

# Global database
ls -lh ~/.claude/memory.sqlite3
# => -rw-r--r-- 1 user staff 128K Jan 26 10:30 /Users/user/.claude/memory.sqlite3

# Project database
ls -lh .claude/memory.sqlite3
# => -rw-r--r-- 1 user staff 64K Jan 26 10:35 .claude/memory.sqlite3

Open the Dashboard (0.10.0+)

Once you have a few sessions worth of memory, the dashboard is the fastest way to see what's actually in there:

claude-memory dashboard

Opens http://localhost:3377 with a moments feed (every recall, context injection, and extraction event), a Trust sidebar showing your global "fingerprint" and 30-day utilization ratio, a deduped Conflicts panel, and a Knowledge panel grouping facts by predicate.

See docs/dashboard.md for the full panel guide.

Test Memory Recall

Have a conversation with Claude to test:

You: "What database am I using?"
Claude: [calls memory.recall]
Claude: "According to my memory, this project uses PostgreSQL."

# Success! Memory is working.

Common Workflows

Workflow 1: Setting Up a New Project (Plugin Already Installed)

You've installed the plugin globally, now you're starting a new project:

# 1. Create or enter your project directory
cd ~/projects/new-app

# 2. Initialize project memory
claude-memory init

# 3. Start Claude Code and talk about your project
claude

# 4. Let Claude know about your stack
"This is a Next.js 14 app with TypeScript, using Supabase for the database"

# 5. Verify memory
"What do you remember about this project?"

Workflow 2: Moving Between Projects

Your global preferences travel with you:

# Project A
cd ~/projects/api-server
claude
"Help me add authentication"
# Claude recalls: api-server uses Express + PostgreSQL

# Project B
cd ~/projects/frontend
claude
"Help me add authentication"
# Claude recalls: frontend uses Next.js + Supabase
# Claude ALSO recalls: Your global preference for descriptive names

Workflow 3: Sharing Project Memory with Team

The project database can be committed to git:

# Option 1: Commit project memory (recommended)
git add .claude/memory.sqlite3
git commit -m "Add project memory snapshot"
# Team members get bootstrapped knowledge

# Option 2: Ignore project memory (each person builds their own)
echo ".claude/memory.sqlite3" >> .gitignore
# Each developer has personal project memory

Recommendation: Commit project memory for teams to share architectural decisions and tech stack knowledge.

Workflow 4: Privacy Control

Exclude sensitive data using privacy tags:

You: "My API key is <private>sk-abc123def456</private>"
Claude: [uses it during session, but won't store it]

# What gets stored: "API key configured for external service"
# What DOESN'T get stored: "sk-abc123def456"

Supported tags:

<private>content</private> - Excludes content from memory
<no-memory>content</no-memory> - Same as private
<secret>content</secret> - Same as private

Troubleshooting

MCP Tools Not Appearing

Problem: Claude doesn't seem to have access to memory tools

Solutions:

Check claude-memory is in PATH:

which claude-memory
# Should show: /path/to/bin/claude-memory

Verify plugin installation:

/plugin
# Navigate to "Installed" tab, look for "claude-memory"

Check for errors:

/plugin
# Navigate to "Errors" tab for any issues

Restart Claude Code:
```
# Exit and relaunch claude command
```

Facts Not Being Stored

Problem: Claude doesn't remember things from previous conversations

Possible causes:

Session didn't stop: Prompt hooks require the session to actually stop (not just pause)
- Solution: Exit Claude Code properly with /exit or Ctrl+D
Hooks not registered: Check hook configuration
- Solution: Run claude-memory init again to reconfigure hooks
Database not created: Missing database files
- Solution: Run claude-memory doctor to diagnose
Extraction failed: Claude couldn't parse facts
- Solution: Be explicit: "Remember that we use PostgreSQL"

Database Not Created

Problem: .claude/memory.sqlite3 doesn't exist after init

Solutions:

Check permissions:

ls -la .claude/
# Should be writable by your user

Create directory manually:

mkdir -p .claude
chmod 755 .claude
claude-memory init

Check disk space:

df -h .
# Ensure you have available space

Migration Failures

Problem: Error messages about schema migration during upgrade

What happens automatically:

Schema migrations run on first database access
Migrations are atomic (all-or-nothing)
Your data is safe (migrations don't delete data)

Recovery:

# Check current state
claude-memory doctor

# If database is corrupted, check schema
claude-memory doctor --verbose

# Last resort: reinitialize (THIS WILL ERASE DATA)
mv .claude/memory.sqlite3 .claude/memory.sqlite3.backup
claude-memory init

Conflicts Between Facts

Problem: Claude shows conflicting information

Solution: Check and resolve conflicts:

# List conflicts
claude-memory conflicts

# Or ask Claude
"Are there any conflicting facts in memory?"

# Resolve by updating facts (Claude will supersede old facts)
"Actually, we switched from MySQL to PostgreSQL last week"

Advanced Usage

Manual Fact Management

# Search facts
claude-memory recall "authentication"

# Show detailed provenance
claude-memory explain <fact_id>

# List recent changes
claude-memory changes --since "2026-01-20"

# Run maintenance
claude-memory sweep

Custom Hook Configuration

Modify .claude/settings.json to customize when memory updates:

{
  "hooks": {
    "Stop": {
      "command": "claude-memory hook ingest"
    }
  }
}

Debugging

Enable verbose output:

# See what's happening during ingestion
claude-memory hook ingest --verbose < ~/.claude/sessions/latest.jsonl

# Check database contents
sqlite3 .claude/memory.sqlite3 "SELECT * FROM facts LIMIT 5;"

Next Steps

Now that you're up and running:

📖 Read Examples for common use cases
📊 Open the Dashboard for live inspection (0.10.0+)
🔧 Explore Plugin Documentation for advanced configuration
🏗️ Review Architecture for technical details
💬 Join Discussions to share feedback

Quick Reference

Command	Purpose
`claude-memory init`	Initialize databases and hooks
`claude-memory doctor`	Check system health
`claude-memory recall <query>`	Search for facts
`claude-memory promote <fact_id>`	Make fact global
`claude-memory reject <id_or_docid>`	Mark a fact as rejected
`claude-memory changes`	Recent updates
`claude-memory conflicts`	Show contradictions
`claude-memory dashboard`	Open the local web UI (0.10.0+)
`claude-memory digest --since 7`	Markdown report of the last 7 days (0.10.0+; gains Context cost + Quality sections in 0.11.0)
`claude-memory show [--pending] [--source]`	Print what memory would inject at next SessionStart (0.11.0+)
`claude-memory stats --stale`	List facts not recalled recently (0.10.0+)
`claude-memory stats --tokens [--since DAYS]`	SessionStart context-token budget histogram (0.11.0+)
`claude-memory stats --tools`	MCP tool-call telemetry (0.9.0+)
`claude-memory census`	Privacy-safe predicate audit across projects (0.10.0+)
`claude-memory dedupe-conflicts --dry-run`	Preview historical conflict-row dedup (0.10.0+)
`claude-memory reclassify-references --dry-run`	Preview reference-material retag (0.10.0+)
`claude-memory compact`	VACUUM databases
`claude-memory export`	Dump facts to JSON
`/claude-memory:analyze`	Bootstrap project knowledge

Support

🐛 Report a bug
💬 Discussions
📧 Questions? Open an issue!

Ready to start? Jump back to your project and have a conversation with Claude. Memory happens automatically! 🚀

FilesExpand file tree

GETTING_STARTED.md

Latest commit

History