claude-self-reflect 2.0.0 → 2.3.0

package/README.md

@@ -1,363 +1,180 @@
-# Claude-Self-Reflect - Conversation Memory for Claude
+# Claude Self-Reflect
 
-Give Claude perfect memory across all conversations. Semantic search over your entire conversation history using vector database and MCP (Model Context Protocol).
+Claude forgets everything. This fixes that.
 
-## Motivation, Alternatives & Past Attempts
+## What You Get
 
-**Motivation**: Claude has no memory between conversations. Every chat starts from scratch, requiring you to re-explain context, repeat solutions, and manually search through conversation files.
+Ask Claude about past conversations. Get actual answers.
 
-**Our Solution**: A semantic memory layer that automatically indexes your conversations and provides instant search through Claude's native tools.
+**Before**: "I don't have access to previous conversations"  
+**After**: "We discussed JWT auth on Tuesday. You decided on 15-minute tokens."
 
-**Past Attempts**: 
-- Neo4j graph database - Too complex for simple conversation retrieval
-- Keyword search - Missed semantically similar content
-- Manual organization - Doesn't scale with hundreds of conversations
+Your conversations become searchable. Your decisions stay remembered. Your context persists.
 
-**Why Qdrant + Vectors**: Industry-standard approach used by LangChain, Dify, and others. Optimized for semantic similarity, not complex relationships.
-
-## Glimpse of the Future
-
-Imagine asking Claude:
-- "What did we discuss about database design last month?"
-- "Find that debugging solution we discovered together"
-- "Have we encountered this error before?"
-
-And getting instant, accurate answers from your entire conversation history. That's Claude-Self-Reflect.
-
-## Quick Start
+## Install
 
+### Quick Start (Recommended)
 ```bash
-# One command setup - handles everything interactively
-npm install -g claude-self-reflect && claude-self-reflect setup
-```
-
-**That's it!** The setup wizard will:
-- ✅ Check Python 3.10+ installation
-- ✅ Start Qdrant vector database
-- ✅ Install the Python MCP server
-- ✅ Configure your API keys
-- ✅ Set up Claude Code integration
-
-- **Need details?** See [Installation Guide](docs/installation-guide.md)
-- **Embedding providers?** See [Embedding Provider Guide](docs/embedding-providers.md)
-- **Manual setup?** See [Advanced Configuration](docs/installation-guide.md#manual-setup-advanced-users)
-
-## Architecture Overview
-
-![Architecture Diagram](docs/diagrams/architecture.png)
-
-The system consists of four main components:
-- **Claude Code/Desktop**: The MCP client that requests memory operations
-- **MCP Server**: TypeScript service providing search and store tools
-- **Import Pipeline**: Python service that processes conversation logs
-- **Qdrant Database**: Vector storage with semantic search capabilities
-
-See also:
-- [Data Flow Diagram](docs/diagrams/data-flow.png) - How data moves through the system
-- [Import Process](docs/diagrams/import-process.png) - Detailed import workflow
-- [Search Operation](docs/diagrams/search-operation.png) - How semantic search works
-
-## Why Qdrant Over Neo4j?
-
-1. **Simplicity**: Two tools (store/find) vs complex entity/relationship management
-2. **Performance**: Optimized for semantic search, no graph traversal overhead
-3. **Proven Pattern**: Industry standard for conversation memory (LangChain, Dify, etc.)
-4. **No Import Issues**: Direct vector storage without entity extraction complexity
-
-## Project Structure
-
-```
-claude-self-reflect/
-├── mcp-server/           # Python MCP server using FastMCP
-│   ├── src/              # Server source code
-│   ├── pyproject.toml    # Python package configuration
-│   └── run-mcp.sh        # MCP startup script
-├── scripts/              # Import and utility scripts
-│   ├── import-*.py       # Various import scripts for conversations
-│   └── test-*.py         # Test scripts for features
-├── .claude/agents/       # Claude sub-agents for specialized tasks
-├── config/               # Configuration files
-├── data/                 # Qdrant vector database storage
-└── docs/                 # Documentation and guides
-```
-
-## Components
-
-### 1. Qdrant Vector Database
-- Stores conversation embeddings with metadata
-- Provides fast semantic similarity search
-- Built-in vector indexing and retrieval
-
-### 2. MCP Server for Conversation Memory
-- **Tool 1**: `store_reflection` - Store important insights and decisions
-- **Tool 2**: `reflect_on_past` - Search through conversation history
-- Simple semantic search without complex entity extraction
-- Python-based using FastMCP framework
-
-### 3. Python Importer
-- Reads JSONL files from Claude conversation logs
-- Creates conversation chunks for context
-- Generates embeddings using Voyage AI (voyage-3-large)
-- Stores directly in Qdrant with metadata
-
-
-## Using the Reflection Agent
-
-### In Claude Code
-The reflection agent activates automatically when you ask about past conversations:
-
-![Reflection Agent in Action](docs/images/Reflection-specialist.png)
-
-```
-"What did we discuss about database design?"
-"Find our previous debugging session"
-"Have we encountered this error before?"
-```
-
-Or explicitly request it:
-```
-"Use the reflection agent to search for our API discussions"
-```
+# Step 1: Get your free Voyage AI key
+# Sign up at https://www.voyageai.com/ - it takes 30 seconds
 
-### Direct Tool Usage (Advanced)
-You can also ask Claude to search directly:
-
-```
-User: Can you check our past conversations about authentication?
-Claude: I'll search through our conversation history about authentication...
+# Step 2: Install and run automatic setup
+npm install -g claude-self-reflect
+claude-self-reflect setup --voyage-key=YOUR_ACTUAL_KEY_HERE
 
-User: Remember that we decided to use JWT tokens for the API
-Claude: I'll store this decision for future reference...
+# That's it! The setup will:
+# ✅ Configure everything automatically
+# ✅ Install the MCP in Claude Code  
+# ✅ Start monitoring for new conversations
+# ✅ Verify the reflection tools work
 ```
 
-## 🧪 Testing & Dry-Run Mode
-
-### Validate Your Setup
-
-Before importing, validate that everything is configured correctly:
-
+### Alternative: Local Mode (No API Key)
 ```bash
-# Run comprehensive validation
-python scripts/validate-setup.py
-
-# Example output:
-# ✅ API Key         [PASS] Voyage API key is valid
-# ✅ Qdrant          [PASS] Connected to http://localhost:6333
-# ✅ Claude Logs     [PASS] 24 projects, 265 files, 125.3 MB
-# ✅ Disk Space      [PASS] 45.2 GB free
+npm install -g claude-self-reflect
+claude-self-reflect setup --local
 ```
+*Note: Local mode uses basic embeddings. Semantic search won't be as good.*
 
-### Dry-Run Mode
+5 minutes. Everything automatic. Just works.
 
-Test the import process without making any changes:
+## The Magic
 
-```bash
-# See what would be imported (no API calls, no database changes)
-python scripts/import-openai-enhanced.py --dry-run
+![Self Reflection vs The Grind](docs/images/red-reflection.webp)
 
-# Dry-run with preview of sample chunks
-python scripts/import-openai-enhanced.py --dry-run --preview
+## Before & After
 
-# Validate setup only (checks connections, API keys, etc.)
-python scripts/import-openai-enhanced.py --validate-only
-```
+![Before and After Claude Self-Reflect](docs/diagrams/before-after-combined.webp)
 
-### Example Dry-Run Output
+## Real Examples That Made Us Build This
 
 ```
-🔍 Running in DRY-RUN mode...
-============================================================
-🚀 Initializing Claude-Self-Reflect Importer...
-
-📊 Import Summary:
-  • Total files: 265
-  • New files to import: 265
-  • Estimated chunks: ~2,650
-  • Estimated cost: FREE (within 200M token limit)
-  • Embedding model: voyage-3.5-lite
-
-🔍 DRY-RUN MODE - No changes will be made
-
-⏳ Starting import...
-
-[DRY-RUN] Would ensure collection: conv_a1b2c3d4_voyage
-[DRY-RUN] Would import 127 chunks to collection: conv_a1b2c3d4_voyage
-
-📊 Final Statistics:
-  • Time elapsed: 2 seconds
-  • Projects to import: 24
-  • Messages processed: 10,165
-  • Chunks created: 2,650
-  • Embeddings would be generated: 2,650
-  • API calls would be made: 133
-  • 💰 Estimated cost: FREE (within 200M token limit)
-```
-
-### Cost Estimation
-
-The dry-run mode provides accurate cost estimates:
-
-**Free Tiers:**
-- Voyage AI: 200M tokens FREE, then $0.02 per 1M tokens
-- Google Gemini: Unlimited FREE (data used for training)
-- Local: Always FREE
-
-**Paid Only:**
-- OpenAI: $0.02 per 1M tokens (no free tier)
-
-**Reality Check:** With 500 tokens per conversation chunk, 200M free tokens = ~400,000 conversation chunks. Most users never reach the paid tier.
+You: "What was that PostgreSQL optimization we figured out?"
+Claude: "Found it - conversation from Dec 15th. You discovered that adding 
+        a GIN index on the metadata JSONB column reduced query time from 
+        2.3s to 45ms."
 
-### Continuous Testing
+You: "Remember that React hooks bug?"
+Claude: "Yes, from last week. The useEffect was missing a dependency on 
+        userId, causing stale closures in the event handler."
 
-```bash
-# Test import of a single project
-python scripts/import-openai-enhanced.py ~/.claude/projects/my-project --dry-run
-
-# Monitor import progress in real-time
-python scripts/import-openai-enhanced.py --dry-run | tee import-test.log
+You: "Have we discussed WebSocket authentication before?"
+Claude: "3 conversations found:
+        - Oct 12: Implemented JWT handshake for Socket.io
+        - Nov 3: Solved reconnection auth with refresh tokens  
+        - Nov 20: Added rate limiting per authenticated connection"
 ```
 
-## 🚀 Advanced Features
+## The Secret Sauce: Sub-Agents
 
-### Memory Decay (v1.3.1)
-Remember that brilliant debugging session from last week? Memory Decay ensures it stays at your fingertips. That random chat from 6 months ago? It gracefully fades into the background, just like human memory.
+Here's what makes this magical: **The Reflection Specialist sub-agent**.
 
-#### What is Memory Decay?
+When you ask about past conversations, Claude doesn't search in your main chat. Instead, it spawns a specialized sub-agent that:
+- Searches your conversation history in its own context
+- Brings back only the relevant results
+- Keeps your main conversation clean and focused
 
-Memory Decay transforms your conversation search from a flat, time-agnostic system into an intelligent memory that understands recency matters. When you search for "React hooks debugging", you want last week's breakthrough solution, not that outdated approach from last year.
+**Your main context stays pristine**. No clutter. No token waste.
 
-Here's the magic: Memory Decay applies an exponential decay function to search scores, blending semantic similarity with temporal relevance. The result? Recent conversations get a massive boost while older ones gradually diminish.
-
-#### The Numbers That Matter
+![Reflection Agent in Action](docs/images/Reflection-specialist.png)
 
-Without Memory Decay:
-- Search: "qdrant implementation"
-- Top result: 6-month-old conversation (Score: 0.361)
-- All results: Scores range from 0.35 to 0.36
-- No consideration of when discussions happened
+## How It Works (10 Second Version)
 
-With Memory Decay Enabled:
-- Same search: "qdrant implementation"
-- Top result: Last week's conversation (Score: 0.605)
-- All results: Scores range from 0.59 to 0.61
-- **That's a 68% score boost for recent content!**
+Your conversations → Vector embeddings → Semantic search → Claude remembers
 
-#### How It Works - The Technical Deep Dive
+Technical details exist. You don't need them to start.
 
-The decay formula elegantly combines semantic similarity with time-based relevance:
+## Using It
 
-```
-final_score = semantic_score × (1 - decay_weight) + decay_factor × decay_weight
-```
+Once installed, just talk naturally:
 
-Where:
-- `semantic_score`: How well the content matches your query (0.0 to 1.0)
-- `decay_weight`: How much recency matters (default: 0.3 or 30%)
-- `decay_factor`: Exponential decay based on age: `e^(-age_days / half_life)`
-- `half_life`: Days until relevance drops by 50% (default: 90 days)
+- "What did we discuss about database optimization?"
+- "Find our debugging session from last week"
+- "Remember this solution for next time"
 
-#### Real-World Example
+The reflection specialist automatically activates. No special commands needed.
 
-Let's say you search for "authentication strategy":
+## Memory Decay
 
-**Identical content at different ages:**
-- Today's discussion: Score 1.000 (100% fresh)
-- 30 days old: Score 0.915 (still highly relevant)
-- 90 days old: Score 0.810 (starting to fade)
-- 180 days old: Score 0.741 (significantly diminished)
-- 365 days old: Score 0.705 (barely relevant)
+Recent conversations matter more. Old ones fade. Like your brain, but reliable.
 
-#### Configuration Options
+Works perfectly out of the box. [Configure if you're particular](docs/memory-decay.md).
 
-```env
-# Enable/disable memory decay globally
-ENABLE_MEMORY_DECAY=true        # Default: false (opt-in feature)
+## For the Skeptics
 
-# How much should recency affect scores? (0.0 to 1.0)
-DECAY_WEIGHT=0.3                # 30% weight on recency, 70% on content
+**"Just use grep"** - Sure, enjoy your 10,000 matches for "database"  
+**"Overengineered"** - Two functions: store_reflection, reflect_on_past  
+**"Another vector DB"** - Yes, because semantic > string matching
 
-# How fast should memories fade?
-DECAY_SCALE_DAYS=90             # 90-day half-life (3 months)
-```
+Built by developers tired of re-explaining context every conversation.
 
-#### Per-Search Control
+## Requirements
 
-You have complete control over decay on each search:
+- Claude Code or Claude Desktop
+- Python 3.10+
+- 5 minutes for setup
 
-```javascript
-// Search with decay (prioritize recent)
-await mcp.reflect_on_past({
-  query: "database optimization",
-  useDecay: true
-});
+## Advanced Setup
 
-// Search without decay (all time periods equal)
-await mcp.reflect_on_past({
-  query: "foundational architecture decisions",
-  useDecay: false
-});
-```
+Want to customize? See [Configuration Guide](docs/installation-guide.md).
 
-#### Performance Characteristics
+## The Technical Stuff
 
-We've optimized Memory Decay to be lightning fast:
-- **Overhead**: Just 0.009 seconds for 1000 search results
-- **Method**: Client-side calculation after vector search
-- **Scalability**: Linear with result count, not database size
+If you must know:
 
-#### The Philosophy
+- **Vector DB**: Qdrant (local, your data stays yours)
+- **Embeddings**: Voyage AI (200M free tokens/month)*
+- **MCP Server**: Python + FastMCP
+- **Search**: Semantic similarity with time decay
 
-Memory Decay isn't just a feature - it's a recognition that not all memories are equal. Your conversation history should work like your brain: keeping recent, relevant information readily accessible while letting older details fade naturally. This isn't about losing information - every conversation remains searchable. It's about surfacing what matters most, when it matters most.
+*We chose Voyage AI for their excellent cost-effectiveness ([66.1% accuracy at one of the lowest costs](https://research.aimultiple.com/embedding-models/#:~:text=Cost%2Deffective%20alternatives%3A%20Voyage%2D3.5%2Dlite%20delivered%20solid%20accuracy%20(66.1%25)%20at%20one%20of%20the%20lowest%20costs%2C%20making%20it%20attractive%20for%20budget%2Dsensitive%20implementations.)). We are not affiliated with Voyage AI.
 
-See [Memory Decay Guide](docs/memory-decay.md) for advanced configuration and implementation details.
+### Want More Details?
 
-## 🤝 Why Claude-Self-Reflect?
+- [Architecture Deep Dive](docs/architecture-details.md) - How it actually works
+- [Components Guide](docs/components.md) - Each piece explained
+- [Why We Built This](docs/motivation-and-history.md) - The full story
+- [Advanced Usage](docs/advanced-usage.md) - Power user features
 
-### Key Advantages
-- **Local-First**: Your conversations stay on your machine
-- **Zero Configuration**: Works out of the box with sensible defaults
-- **Claude-Native**: Built specifically for Claude Code & Desktop  
-- **Semantic Search**: Understands meaning, not just keywords
-- **Continuous Import**: Automatically indexes new conversations
-- **Privacy-Focused**: No data leaves your local environment
+## Problems?
 
+- [Troubleshooting Guide](docs/troubleshooting.md)
+- [GitHub Issues](https://github.com/ramakay/claude-self-reflect/issues)
+- [Discussions](https://github.com/ramakay/claude-self-reflect/discussions)
 
-### CLAUDE.md vs Claude-Self-Reflect
+## Contributing
 
-| Aspect | CLAUDE.md | Claude-Self-Reflect |
-|--------|-----------|-------------------|
-| **Purpose** | Project-specific instructions | Conversation memory across all projects |
-| **Scope** | Single project context | Global conversation history |
-| **Storage** | Text file in project | Vector database (Qdrant) |
-| **Search** | Exact text matching | Semantic similarity search |
-| **Updates** | Manual editing | Automatic indexing |
-| **Best For** | Project rules & guidelines | Finding past discussions & decisions |
+See our [Contributing Guide](CONTRIBUTING.md) for development setup and guidelines.
 
-**Use both together**: CLAUDE.md for project-specific rules, Claude-Self-Reflect for conversation history.
+### Releasing New Versions (Maintainers)
 
+Since our GitHub Actions automatically publish to npm, the release process is simple:
 
+```bash
+# 1. Ensure you're logged into GitHub CLI
+gh auth login  # Only needed first time
 
-## Troubleshooting
-
-Having issues? Check our [Troubleshooting Guide](docs/troubleshooting.md) or:
-
-- Ask in [Discussions](https://github.com/ramakay/claude-self-reflect/discussions)
-- Report bugs in [Issues](https://github.com/ramakay/claude-self-reflect/issues)
-
-## Roadmap
-
-**Q1 2025**: Conversation summarization, time-based filtering, export history  
-**Q2 2025**: Multi-modal memory, analytics dashboard, team sharing  
-**Long Term**: Active learning, conversation graphs, enterprise features
+# 2. Create and push a new tag
+git tag v2.3.0  # Use appropriate version number
+git push origin v2.3.0
 
-[Full Roadmap & Contributing](CONTRIBUTING.md)
+# 3. Create GitHub release (this triggers npm publish)
+gh release create v2.3.0 \
+  --title "Release v2.3.0" \
+  --notes-file CHANGELOG.md \
+  --draft=false
 
-## License
+# The GitHub Action will automatically:
+# - Build the package
+# - Run tests
+# - Publish to npm
+# - Update release assets
+```
 
-MIT License - see [LICENSE](LICENSE) for details.
+Monitor the release at: https://github.com/ramakay/claude-self-reflect/actions
 
 ---
 
-<p align="center">
-  Built with ❤️ for the Claude community by <a href="https://github.com/ramakay">ramakay</a>
-</p>
+Stop reading. Start installing. Your future self will thank you.
+
+MIT License. Built with ❤️ for the Claude community.

package/installer/cli.js

@@ -18,7 +18,9 @@ async function setup() {
   console.log('🚀 Claude Self-Reflect Setup Wizard\n');
   
   const setupPath = join(__dirname, 'setup-wizard.js');
-  const child = spawn('node', [setupPath], { stdio: 'inherit' });
+  // Pass along any command line arguments after 'setup'
+  const args = process.argv.slice(3); // Skip node, script, and 'setup'
+  const child = spawn('node', [setupPath, ...args], { stdio: 'inherit' });
   
   child.on('exit', (code) => {
     process.exit(code || 0);
@@ -95,13 +97,21 @@ async function doctor() {
 
 function help() {
   console.log('Claude Self-Reflect - Perfect memory for Claude\n');
-  console.log('Usage: claude-self-reflect <command>\n');
+  console.log('Usage: claude-self-reflect <command> [options]\n');
   console.log('Commands:');
   
   for (const [cmd, desc] of Object.entries(commands)) {
     console.log(`  ${cmd.padEnd(10)} ${desc}`);
   }
   
+  console.log('\nSetup Options:');
+  console.log('  --voyage-key=<key>   Provide Voyage AI API key (recommended)');
+  console.log('  --local              Run in local mode without API key');
+  
+  console.log('\nExamples:');
+  console.log('  claude-self-reflect setup --voyage-key=pa-1234567890');
+  console.log('  claude-self-reflect setup --local');
+  
   console.log('\nFor more information: https://github.com/ramakay/claude-self-reflect');
 }