Claude Memory

Persistent long-term context for Claude Code sessions via a local PostgreSQL DB.

DB connection

Host: localhost:5432
Database: claude_memory
User: $PGUSER (defaults to the current OS user; trust auth, no password)

Python (via psycopg2):

import os, getpass, psycopg2
user = os.environ.get("PGUSER") or getpass.getuser()
conn = psycopg2.connect(host="localhost", port=5432, dbname="claude_memory", user=user)

SQL shell: psql -d claude_memory (use /opt/homebrew/opt/postgresql@16/bin/psql on macOS if $PATH is not set).

Tables

memory_chunks.category enum: decision | pattern | insight | preference | contact | error_solution | project_context | workflow

Workflows

1. Recall ("what do I know about X?")

psql -d claude_memory -c "
SELECT category::text, content, confidence, project_name, created_at
FROM memory_chunks
WHERE content ILIKE '%SEARCH_TERM%'
   OR 'SEARCH_TERM' = ANY(tags)
   OR project_name ILIKE '%SEARCH_TERM%'
ORDER BY confidence DESC, created_at DESC
LIMIT 20;
"

Use scripts/query.py for structured queries:

python3 ~/.claude/skills/claude-memory/scripts/query.py search "pgvector tuning"
python3 ~/.claude/skills/claude-memory/scripts/query.py project "Project Alpha"
python3 ~/.claude/skills/claude-memory/scripts/query.py contact "Jane Doe"
python3 ~/.claude/skills/claude-memory/scripts/query.py decisions
python3 ~/.claude/skills/claude-memory/scripts/query.py stats

2. Add an insight

python3 ~/.claude/skills/claude-memory/scripts/add.py \
  --category decision \
  --content "We use pgvector instead of Milvus because of lower operational complexity" \
  --project claude-memory \
  --tags postgresql,pgvector,architecture \
  --confidence 0.9

Valid categories: decision, pattern, insight, preference, contact, error_solution, project_context, workflow

3. Find similar conversations

SELECT c.id, c.project_name, c.started_at, substring(m.content, 1, 200)
FROM conversations c
JOIN messages m ON m.conversation_id = c.id
WHERE m.content ILIKE '%SEARCH_TERM%'
ORDER BY c.started_at DESC
LIMIT 10;

4. Load project knowledge

SELECT category::text, content, tags, confidence
FROM memory_chunks
WHERE project_name = 'Project Alpha'
ORDER BY category, confidence DESC;

Typical queries during Claude Code sessions

When the user asks:

• "What do I know about topic X?" -> search with ILIKE over content + tags
• "Who is person Y?" -> filter by category=contact
• "What did we decide about Z?" -> category=decision + ILIKE
• "How did we solve problem A?" -> category=error_solution
• "Any patterns for B?" -> category=pattern
• "User preferences?" -> category=preference

Scripts

DB maintenance

Run the ingestion scripts from wherever you cloned the repo (adjust path as needed):

# Ingestion scripts (in the claude-memory repo)
python3 /path/to/claude-memory/scripts/ingest_sessions.py
python3 /path/to/claude-memory/scripts/scan_skills.py
python3 /path/to/claude-memory/scripts/extract_memory.py

# Open the web UI
throughline serve  # -> http://127.0.0.1:8787

Best practices

• Set confidence deliberately: 0.9+ for clear facts, 0.7-0.8 for interpretations, avoid anything under 0.5
• Keep tags low-cardinality: e.g. postgresql, migration rather than full sentences
• Use the project field: enables project-specific filters
• Avoid duplicates: search first before adding
• Pick categories carefully: one chunk = one category