Regular Claude Code (Without Memory):

• 🐣 "What's your project structure?" - Asked every. single. time.
• 🔄 "Let me create this function for you" - Function already exists
• 😴 "I don't see any similar code" - There are 5 similar implementations
• 🤷 "Could you show me that error handling pattern again?"
• ⏰ Wastes 10-15 minutes per session on context

God Mode Claude (With Memory):

• 🧙‍♂️ "I see you have 3 similar validation functions. Let me use your validateUserInput pattern from auth.js"
• 🎯 "This error matches the pattern you fixed in commit 3f4a2b1. Here's the same solution adapted"
• 🔮 "Based on your architecture, this belongs in /services with your other API handlers"
• ⚡ "Found 5 instances of this pattern. Want me to refactor them all?"
• 🚀 Starts coding immediately with full context

The Evolution: Memory Guard has transformed from simple duplicate detection into a comprehensive code quality gate The Solution: Memory Guard now analyzes 4 critical dimensions before allowing any code changes

🔄 1. Code Duplication (Primary Focus)

• Detects duplicate functions, classes, and logic patterns
• Finds copy-paste code with minor variations
• Identifies redundant utility implementations

🧠 2. Logic Completeness

• Catches missing error handling and edge cases
• Identifies SQL injection vulnerabilities
• Flags incomplete input validation and security checks

🔗 3. Flow Integrity

• Prevents breaking API contracts and interfaces
• Catches dangerous parameter removals
• Identifies breaking changes to function signatures

⚙️ 4. Feature Preservation

• Prevents removal of existing functionality
• Protects against breaking user workflows
• Ensures backward compatibility

Claude tries: "Let me simplify this authentication function" Memory Guard: "🔗 FLOW INTEGRITY ISSUE: Removing 'fallback_config' parameter breaks 8+ files!" Claude: "You're right! I'll maintain backward compatibility"

🔄 Code Duplication: Prevents recreating existing functions 🧠 Logic Completeness: Catches SQL injection and missing validation 🔗 Flow Integrity: Stops breaking API changes ⚙️ Feature Preservation: Protects existing functionality

🔍 How It Actually Works:

1. Intercepts Every Write/Edit - PreToolUse hook catches all file modifications
2. Comprehensive Analysis - Checks all 4 quality dimensions in parallel
3. Semantic Code Search - Uses MCP memory to find patterns and vulnerabilities
4. Smart Decision Making - Returns specific issue type with actionable suggestions
5. Manual Entry Exclusion - Ignores documentation and human notes, focuses on code only

🧠 The Tech Stack:

• Hook System: settings.json → PreToolUse → memory_guard.py → Claude CLI
• Entity Extraction: Regex patterns detect new Python functions/classes being created
• MCP Integration: Uses mcp__project-memory__search_similar with entityTypes filtering
• Claude CLI: Isolated subprocess with --allowedTools limited to memory functions
• Smart Filtering: Skips .md, .json, .yml files - only checks actual code

⚡ Advanced Features:

• Override Comments: # @allow-duplicate: reason instantly bypasses analysis
• Session Controls: dups off/on/status via UserPromptSubmit hook (prompt_handler.py)
• Per-Project State: .claude/guard_state.json tracks bypass status per session
• Debug Logging: memory_guard_debug.txt in each project root
• Graceful Degradation: Always approves on errors - never blocks legitimate work

You: Install Claude Code Memory from https://github.com/Durafen/Claude-code-memory and help me understand how to use it

Claude: I'll help you install the complete Claude Code Memory system...
[Claude handles everything: clones repos, installs dependencies, configures settings, indexes your project]

# Handles Python/Node.js setup and dependencies automatically
# Note: Not yet tested on Windows or Linux
git clone https://github.com/Durafen/Claude-code-memory.git
cd Claude-code-memory
./install-cross-platform.sh

# Then continue from step 2 below (Configure API keys)

# 1. Clone and setup
git clone https://github.com/Durafen/Claude-code-memory.git
cd Claude-code-memory
python3.12 -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip install -r requirements.txt

# 2. Configure API keys (REQUIRED - won't work without these)
cp settings.template.txt settings.txt
# Edit settings.txt and add:
# - VOYAGE_API_KEY or OPENAI_API_KEY (for embeddings)
# - QDRANT_API_KEY (if using Qdrant authentication)
# - OPENAI_API_KEY (for chat summaries and cleanup)

# 3. Install our enhanced MCP memory server
git clone https://github.com/Durafen/mcp-qdrant-memory.git
cd mcp-qdrant-memory
npm install
npm run build
cd ..

# 4. Configure MCP server environment
cd mcp-qdrant-memory
cp .env.example .env
# Edit .env and add same API keys as settings.txt
cd ..

# 5. Install global wrapper (creates claude-indexer command)
./install.sh  # On Windows: Use Git Bash or WSL

# 6. Install and Start Qdrant Vector Database
## Docker Installation (Recommended)
docker pull qdrant/qdrant
docker run -p 6333:6333 -p 6334:6334 -v $(pwd)/qdrant_storage:/qdrant/storage qdrant/qdrant

# Verify Qdrant is running:
curl http://localhost:6333/health

# 7. Index your project (30 seconds for most codebases)
claude-indexer -p /your/project -c my-project

# 8. Add MCP server to Claude (auto-configures from settings.txt)
claude-indexer add-mcp -c my-project

That's it! Claude now has photographic memory of your entire codebase.

• 3.99ms semantic search across millions of lines of code
• BM25 keyword search for exact term matching (new in v2.8)
• Hybrid search combines semantic understanding + keyword precision
• 90% faster debugging with pattern memory
• 85% cost reduction with Voyage AI embeddings
• 95.3% variable extraction coverage

Why Tree-sitter? The same parser that powers VS Code, GitHub, and Neovim

• Universal AST parsing for consistent cross-language understanding
• 36x faster than regex with 100% semantic accuracy
• Incremental parsing - only re-parses what changed (15x speed boost)
• Error recovery - handles syntax errors gracefully

File → Language Detection → Tree-sitter Parser → AST → Entity Extraction
                                ↓
                          Language-Specific Parser
                          (Python: Jedi integration)
                          (JS/TS: TypeScript compiler)
                          (HTML/CSS: Component detection)

Supported Languages & Coverage:

• Python (.py): 100% - Functions, classes, methods, decorators, async, walrus operator
• JavaScript (.js, .jsx): 90.6% - Functions, classes, React components, destructuring
• TypeScript (.ts, .tsx): 92% - Full type extraction, interfaces, generics
• HTML (.html): Component detection, ID/class extraction, cross-file CSS relations
• CSS (.css, .scss): Selector parsing, variable extraction, @import tracking
• JSON (.json): Configuration semantic analysis, nested key extraction
• YAML (.yml, .yaml): Workflow detection (GitHub Actions), config parsing
• Go, Rust, Java, C++: Core function/class extraction
• Markdown (.md): Structure analysis, code block extraction

1. AST Analysis: Tree-sitter provides syntax tree
2. Semantic Enhancement: Language-specific analysis (Jedi for Python, TS compiler for TypeScript)
3. Relation Mapping: Cross-file imports, inheritance, function calls
4. Knowledge Graph: Hierarchical entity relationships
5. Vector Embeddings: Voyage AI code-optimized embeddings

• Progressive Disclosure: Metadata chunks (3.99ms) → Implementation on-demand
• Smart Caching: Frequently accessed patterns in memory
• Incremental Updates: SHA256 change detection, only re-index modified files
• Parallel Processing: Multi-threaded parsing for large codebases
• Vector Optimization: 512-dim Voyage AI vs 1536-dim OpenAI (3x storage savings)

Add to your project's CLAUDE.md:

## Memory Usage Instructions
You have access to a complete memory of this codebase. Before writing ANY code:
1. ALWAYS search for existing implementations first
2. Use established patterns found in memory
3. Check for duplicate functionality before creating new functions
4. When debugging, search for similar errors that were fixed before

Add to your ~/.claude/settings.json:

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "python3 '/path/to/Claude-code-memory/utils/prompt_handler.py'"
          }
        ]
      }
    ],
    "PreToolUse": [
      {
        "matcher": "Write|Edit|MultiEdit",
        "hooks": [
          {
            "type": "command",
            "command": "python3 '/path/to/Claude-code-memory/utils/memory_guard.py'"
          }
        ]
      }
    ]
  }
}

# memory_guard.py - Top of file
DEBUG_ENABLED = True                    # Toggle debug logging
DEBUG_LOG_FILE = 'memory_guard_debug.txt'  # Log filename per project

You: "Create a function to hash passwords"
Claude: Let me create a secure password hashing function...
Memory Guard: ❌ BLOCKED: hashPassword() already exists in auth/utils.py:45
Claude: You're right! I'll import the existing hashPassword function instead.

You: "Add password hashing to the user registration"
Claude: I'll add password hashing using your existing function...
[Claude writes: const hashedPwd = await hashPassword(password)]
Memory Guard: ✅ APPROVED - Using existing function, not creating duplicate

# When you need a variant of existing code:
# @allow-duplicate: Specific hash function for legacy API compatibility
def hash_password_legacy(password):
    # Memory Guard sees the comment and instantly approves

You: "dups off" (disable Memory Guard for this session)
Assistant: 🔴 Memory Guard disabled for this session

You: "dups status"
Assistant: 📊 Memory Guard Status: 🔴 DISABLED (use 'dups on' to enable)

You: "dups on" (re-enable protection)
Assistant: 🟢 Memory Guard enabled for this session

search_similar(query, entityTypes, limit, searchMode)

• query: Search term or code pattern
• entityTypes: Filter by ["metadata", "function", "class", "debugging_pattern", "implementation"]
• limit: Max results (default: 50)
• searchMode: "hybrid" (semantic+keyword), "semantic", "keyword" (BM25)

read_graph(entity, mode, limit, entityTypes)

• entity: Specific component name for focused view
• mode: "smart" (AI summary), "entities", "relationships", "raw"
• limit: Max items (smart=150, others=300)
• entityTypes: Filter results by type

get_implementation(entityName, scope)

• entityName: Function/class name
• scope: "minimal" (just code), "logical" (+ helpers), "dependencies" (+ imports)

• debugging_pattern (30%): Bug solutions and fixes
• implementation_pattern (25%): Code patterns and algorithms
• integration_pattern (15%): API/database integrations
• configuration_pattern (12%): Setup and deployment
• architecture_pattern (10%): System design decisions
• performance_pattern (8%): Optimization techniques
• knowledge_insight: Research findings
• active_issue: Current bugs (delete when fixed)
• ideas: Feature suggestions

• Metadata chunks: Fast 3.99ms initial search
• Implementation chunks: Full code on-demand
• 90% speed boost: Search metadata first, load code when needed
• Token optimization: Smart 25k token responses vs 393k overwhelming dumps

# Voyage AI - 85% cheaper, code-optimized
VOYAGE_API_KEY=your_key
EMBEDDING_PROVIDER=voyage
EMBEDDING_MODEL=voyage-3-lite

# OpenAI - Industry standard
OPENAI_API_KEY=your_key
EMBEDDING_PROVIDER=openai
EMBEDDING_MODEL=text-embedding-3-small

claude-indexer -p . -c my-project                       # Index current directory
claude-indexer -p /path/to/project -c collection-name   # Index specific project
claude-indexer -p . -c my-project --verbose            # Detailed progress output
claude-indexer -p . -c my-project --clear              # Clear + reindex (preserves manual)
claude-indexer add-mcp -c my-project                   # Configure Claude MCP connection

claude-indexer watch start -p . -c my-project          # File watching current directory
claude-indexer search "authentication" -p . -c my-project --type entity  # Search with filters
claude-indexer search "login function" -p . -c my-project --mode keyword  # BM25 keyword search
claude-indexer search "auth pattern" -p . -c my-project --mode hybrid     # Combined search
claude-indexer file ./src/auth.py -p . -c my-project   # Index single file

claude-indexer service start                           # Multi-project background service
claude-indexer service add-project /path/to/project my-project  # Add project (positional args)
claude-indexer service status                          # Check service health

claude-indexer hooks install -p . -c my-project        # Pre-commit auto-indexing
claude-indexer hooks status -p . -c my-project         # Check hook status
claude-indexer hooks uninstall -p . -c my-project      # Remove git hooks

python utils/manual_memory_backup.py backup -c my-project        # Backup manual entries
python utils/manual_memory_backup.py restore -f backup.json      # Restore from backup
python utils/qdrant_stats.py -c my-project --detailed           # Collection health stats

claude-indexer chat index -p . -c my-project --limit 50         # Process chat history
claude-indexer chat search "debugging patterns" -p . -c my-project  # Search chat insights
claude-indexer chat html-report -p . -c my-project              # Generate HTML report

Required Software:

• Python 3.9+ (3.12+ recommended) - Download
• Node.js 18+ - Download
• Claude Code installed - Get Claude
• Docker (for Qdrant) - Get Docker

API Keys Needed:

• Embeddings: Voyage AI key (recommended) OR OpenAI key
• Chat Analysis: OpenAI key (for GPT-4.1-mini)
• Qdrant: API key (only if authentication enabled)

Quick Prerequisites Check:

python3 --version  # Should be 3.9+
node --version     # Should be 18+
docker --version   # Any recent version
claude --version   # Claude Code CLI

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   Claude Code   │◄──►│  Enhanced MCP    │◄──►│   Qdrant DB     │
│                 │    │     Server       │    │   (Vectors)     │
└─────────────────┘    └──────────────────┘    └─────────────────┘
                                                        ▲
                       ┌────────────────┐               │
                       │ Tree-sitter +  │───────────────┘
                       │     Jedi       │
                       └────────────────┘

• CLAUDE.md - Comprehensive setup and architecture details
• Installation Guide - Platform-specific setup
• Memory Functions - Advanced memory usage
• Troubleshooting - Common issues and solutions

# Re-run the installer
./install.sh
# Or manually add to PATH:
export PATH="$PATH:$HOME/Claude-code-memory"

• "Invalid API key": Check settings.txt has correct keys
• "Embedding provider mismatch": Ensure MCP .env matches settings.txt
• "No results found": Verify same embedding provider for indexing and searching

# Check if Qdrant is running
curl http://localhost:6333/health
# If not, restart Docker:
docker run -p 6333:6333 -v $(pwd)/qdrant_storage:/qdrant/storage qdrant/qdrant

• Ensure both hooks are in ~/.claude/settings.json (UserPromptSubmit + PreToolUse)
• Check memory_guard_debug.txt in your project root
• Verify project has a valid MCP collection configured
• Check your project's CLAUDE.md contains the MCP collection name (e.g., mcp__project-name-memory__)
• Memory Guard auto-detects collection from CLAUDE.md - without it, uses generic name

Found a bug? 🐛 Report it here Want a feature? ✨ Request it here Have feedback? 💬 Start a discussion

Transform Claude from a talented junior into your most senior team member. Give it the superpower of perfect memory and watch it reference your code like it's been on your team for years.

One command. 30 seconds. Claude becomes omniscient.