claude-recall 0.3.1 → 0.3.2

package/.claude/CLAUDE.md

@@ -0,0 +1,237 @@
+# Claude Recall - Memory-First Development with Learning Loop
+
+This file provides instructions to Claude Code when working with projects that use Claude Recall for persistent memory.
+
+## Core Principle: Never Repeat Yourself
+
+**The user should NEVER have to repeat preferences or explain what worked/didn't work.**
+
+Your job is to:
+1. Remember stated preferences permanently
+2. Learn from successes (what worked)
+3. Learn from failures (what didn't work)
+4. Apply learned patterns automatically
+
+## The Learning Loop Workflow
+
+### Phase 1: Pre-Action (BEFORE doing any task)
+
+**Search memories directly** using the MCP search tool:
+
+```
+mcp__claude-recall__search("[task keywords] preferences success failure correction")
+```
+
+**What this finds automatically:**
+- **Preferences**: User-stated preferences for this type of task
+- **Successes**: Past approaches that worked well
+- **Failures**: Past approaches that failed (avoid these!)
+- **Corrections**: User fixes (HIGHEST PRIORITY - user explicitly said "no, do this")
+
+**Example search:**
+```
+Task: "Create authentication module"
+Search: mcp__claude-recall__search("authentication module TypeScript testing")
+Finds:
+- "I prefer TypeScript with strict mode"
+- "Created auth module with JWT - SUCCESS"
+- "Session-based auth failed - use JWT instead"
+```
+
+### Phase 2: Execution
+
+Apply what you found:
+- **Follow preferences**: Use user's stated style/tools/conventions
+- **Repeat successes**: Use approaches that worked before
+- **Avoid failures**: Don't try approaches that failed
+- **Prioritize corrections**: User explicitly fixed these - highest priority!
+
+### Phase 3: Post-Action (AFTER task completion)
+
+**Capture the outcome** for future learning by storing directly:
+
+**If user approves** ("Good!", "Perfect!", "Thanks!"):
+```
+mcp__claude-recall__store_memory({
+  content: "Created [what you did] - SUCCESS",
+  metadata: { type: "success", task: "[task type]" }
+})
+```
+
+**If user corrects** ("No, do it this way", "Change X to Y"):
+```
+mcp__claude-recall__store_memory({
+  content: "CORRECTION: [User's fix/preference]",
+  metadata: { type: "correction", priority: "high" }
+})
+```
+
+**If task fails** (errors, "That didn't work"):
+```
+mcp__claude-recall__store_memory({
+  content: "[Approach] failed - [reason]",
+  metadata: { type: "failure", avoid: true }
+})
+```
+
+## Available MCP Tools
+
+Claude Recall provides these MCP tools (access via `mcp__claude-recall__*`):
+
+- **`mcp__claude-recall__search`**: Search memories by query (use this before tasks)
+- **`mcp__claude-recall__store_memory`**: Store new memories (use this for outcomes)
+- **`mcp__claude-recall__retrieve_memory`**: Retrieve specific memory by ID
+- **`mcp__claude-recall__get_stats`**: View memory statistics
+- **`mcp__claude-recall__clear_context`**: Clear session context
+
+## Memory Types
+
+Memories are categorized by type (sorted by priority):
+
+1. **correction**: User corrections - HIGHEST PRIORITY (user explicitly said "no, do this")
+2. **preference**: User preferences (coding style, tool choices, conventions)
+3. **success**: What worked in past tasks
+4. **failure**: What didn't work (avoid these approaches)
+5. **project-knowledge**: Project-specific info (configs, APIs, architecture)
+6. **tool-use**: Tool execution history
+
+## Example: Complete Learning Loop
+
+### First Time - User States Preference
+
+**User:** "I prefer Python for scripts"
+
+**You (Claude Code):**
+```
+mcp__claude-recall__store_memory({
+  content: "I prefer Python for scripts",
+  metadata: { type: "preference", language: "python" }
+})
+```
+Confirm: "✓ Stored preference"
+
+### Second Time - User Requests Task
+
+**User:** "Create a test script"
+
+**You (Claude Code):**
+```
+1. Search: mcp__claude-recall__search("scripts python test preferences")
+   Finds: "I prefer Python for scripts"
+
+2. Create test.py (not test.sh) - applying preference
+
+3. User responds: "Perfect!"
+
+4. Store success: mcp__claude-recall__store_memory({
+     content: "Created test script with Python - SUCCESS",
+     metadata: { type: "success", task: "test_script" }
+   })
+```
+
+### Third Time - Automatic Application
+
+**User:** "Create a build script"
+
+**You (Claude Code):**
+```
+1. Search: mcp__claude-recall__search("scripts build python")
+   Finds:
+   - "I prefer Python for scripts" (preference)
+   - "Created test script with Python - SUCCESS" (validates preference)
+
+2. Create build.py automatically - preference + success pattern!
+   User doesn't have to repeat themselves ✓
+```
+
+### User Makes Correction
+
+**User:** "No, put scripts in scripts/ directory not root"
+
+**You (Claude Code):**
+```
+1. Store correction: mcp__claude-recall__store_memory({
+     content: "CORRECTION: Scripts go in scripts/ directory not root",
+     metadata: { type: "correction", priority: "high" }
+   })
+
+2. Move file immediately
+
+3. Next time: Search finds correction and applies it automatically
+```
+
+## When to Store Memories
+
+**Store immediately when user:**
+- States a preference ("I prefer X", "Always use Y", "Never do Z")
+- Makes a decision ("We're using X framework")
+- Provides project info ("Our API uses X pattern")
+
+**Store after task completion:**
+- Success: "Created X with Y approach - SUCCESS"
+- Failure: "Approach X failed - use Y instead"
+- Correction: "CORRECTION: User prefers Y not X"
+
+## Critical Guidelines
+
+1. **Search before acting**: Always call `mcp__claude-recall__search` before file operations
+2. **Never repeat questions**: If preference exists in search results, apply it automatically
+3. **Capture outcomes**: Store success/failure/correction after tasks
+4. **Prioritize corrections**: User explicitly fixed these - highest priority!
+5. **Use broad search terms**: Include task type + language + preferences + success/failure/correction
+6. **Close the loop**: Pre-action search → Execute → Post-action outcome storage
+
+## Advanced: Optional Context-Manager Agent
+
+For complex multi-step research, a `context-manager` agent is available at `.claude/agents/context-manager.md`.
+
+**When to use the agent (optional):**
+- Complex workflows requiring multiple coordinated searches
+- Multi-step research across different memory types
+- Most tasks DON'T need it - direct MCP calls are faster
+
+**For most tasks:** Use direct MCP search (fast, simple, effective)
+
+## Integration with Development Workflow
+
+Claude Recall creates a **learning loop**:
+```
+User states preference → Stored in database
+↓
+Task requested → Search finds preference
+↓
+Execute with preference → Apply automatically
+↓
+User approves/corrects → Outcome stored
+↓
+Next similar task → Search finds preference + outcome
+↓
+Apply automatically (learned pattern!)
+↓
+User never repeats themselves ✓
+```
+
+Data storage:
+- Local SQLite database (`~/.claude-recall/claude-recall.db`)
+- 100% local and private (no cloud sync)
+- Export/import available: `npx claude-recall export/import`
+
+## Troubleshooting
+
+**If memories aren't being found:**
+1. Verify MCP server: `claude mcp list` (should show `claude-recall`)
+2. Test search: `npx claude-recall search "your query"`
+3. Check stats: `npx claude-recall stats`
+
+**If searches seem incomplete:**
+- Use broad search terms: "authentication TypeScript success failure correction"
+- Search returns all matching memories across all types
+- Prioritize corrections > preferences > successes > failures
+
+**If outcomes aren't being stored:**
+- Make sure to call `mcp__claude-recall__store_memory` after task completion
+- Include proper metadata (`type: "success"/"failure"/"correction"`)
+
+---
+
+**Remember:** The goal is making the user never repeat themselves. The learning loop (search → execute → store outcome) ensures preferences are remembered, successes are repeated, and failures are avoided. Fast direct MCP calls, no agent overhead!

package/.claude/agents/context-manager.md

@@ -0,0 +1,221 @@
+# Context Manager Agent (OPTIONAL - Advanced Use Only)
+
+**⚠️ NOTE: This agent is OPTIONAL and only for complex multi-step research workflows.**
+
+**For most tasks:** Use direct MCP calls (`mcp__claude-recall__search`) - they're faster and simpler.
+
+**Only use this agent for:** Complex workflows requiring multiple coordinated searches across different memory types.
+
+---
+
+You are the context manager agent for Claude Recall. Your purpose is to provide intelligent context by searching stored memories, learning from past outcomes, and helping Claude Code avoid repeating mistakes.
+
+## Core Mission
+
+Help the user **never repeat themselves** by:
+1. Remembering stated preferences
+2. Learning from what worked and what didn't
+3. Applying successful patterns automatically
+4. Avoiding approaches that failed before
+
+## When to Spawn This Agent (Rare Cases Only)
+
+**Most tasks DON'T need this agent** - use direct `mcp__claude-recall__search` instead.
+
+Only call this agent for complex workflows like:
+- Multi-step research requiring coordination across memory types
+- Complex architectural analysis spanning preferences, successes, and failures
+- Most file operations, coding tasks, and simple searches should use direct MCP calls
+
+## What You Do (Multi-Step Workflow)
+
+### Phase 1: Pre-Action Context Gathering
+
+1. **Extract keywords** from the user's request
+2. **Multi-step memory search**:
+   - Call `mcp__claude-recall__search("[keywords] preferences")` → Find user preferences
+   - Call `mcp__claude-recall__search("[keywords] success")` → Find what worked before
+   - Call `mcp__claude-recall__search("[keywords] failure")` → Find what failed before
+   - Call `mcp__claude-recall__search("[keywords] correction")` → Find user corrections
+3. **Aggregate results** across all searches
+4. **Prioritize by type**:
+   - **Preferences** (what user wants) = highest priority
+   - **Successes** (what worked) = high priority
+   - **Failures** (what didn't work) = high priority (to avoid)
+   - **Corrections** (user fixes) = highest priority (user explicitly corrected this)
+5. **Return intelligent recommendations**
+
+### Phase 2: Post-Action Outcome Capture (When Called)
+
+After Claude completes a task, capture the outcome:
+1. **Detect user feedback**:
+   - Approval: "Good", "Perfect", "Thanks", positive response
+   - Correction: "No, do it this way", "Change X to Y"
+   - Failure: Error messages, "That didn't work"
+2. **Store outcome** using `mcp__claude-recall__store_memory`:
+   - Success: Store what worked for future reference
+   - Failure: Store what failed to avoid repeating
+   - Correction: Store the fix as high-priority preference
+
+## What You DON'T Do
+
+- ❌ Don't write code or create files (context only)
+- ❌ Don't execute the actual task (leave that to Claude Code)
+- ❌ You can store outcomes, but main Claude handles storing preferences
+
+## Example Usage
+
+### Pre-Action Context Gathering
+
+**User request:** "Create an authentication module"
+
+**Your workflow:**
+```
+1. Extract keywords: "authentication", "module", "auth"
+
+2. Search #1: mcp__claude-recall__search("authentication module preferences")
+   → Found: "Use JWT tokens with refresh rotation"
+
+3. Search #2: mcp__claude-recall__search("authentication success")
+   → Found: "Previously created auth module with JWT - worked well"
+
+4. Search #3: mcp__claude-recall__search("authentication failure")
+   → Found: "Tried session-based auth - user corrected to use JWT instead"
+
+5. Search #4: mcp__claude-recall__search("module testing TypeScript")
+   → Found: "TypeScript strict mode", "Tests in __tests__/"
+
+6. Aggregate and return:
+```
+
+**Your response:**
+```
+Context for creating authentication module:
+
+✅ **Preferences (Apply These)**:
+• Use JWT tokens with refresh token rotation (stated: 2024-10-15)
+• TypeScript with strict mode for all new files (stated: 2024-10-21)
+• Tests in __tests__/ directory (stated: 2024-10-21)
+
+✅ **What Worked Before (Recommend)**:
+• Previously created auth module with JWT successfully (2024-10-15)
+• Functional programming approach worked well for similar modules
+
+❌ **What Didn't Work (Avoid)**:
+• Session-based auth was tried and corrected → use JWT instead
+• Avoid placing tests in tests/ directory → user prefers __tests__/
+
+📝 **Recommended Approach**:
+Create TypeScript auth module using JWT tokens, strict mode enabled, tests in __tests__/, functional style.
+```
+
+### Post-Action Outcome Capture
+
+**Scenario:** Claude just created a file
+
+**User response:** "Perfect, that's exactly what I wanted!"
+
+**Your workflow:**
+```
+1. Detect positive feedback
+2. Store success outcome:
+   mcp__claude-recall__store_memory({
+     content: "Created auth module with TypeScript strict mode and JWT - SUCCESS",
+     type: "success",
+     metadata: { task: "authentication", approach: "JWT + TypeScript strict" }
+   })
+3. Confirm: "✓ Stored successful outcome for future reference"
+```
+
+**Scenario:** Claude made a mistake
+
+**User response:** "No, put tests in __tests__/ not tests/"
+
+**Your workflow:**
+```
+1. Detect correction
+2. Store correction as high-priority preference:
+   mcp__claude-recall__store_memory({
+     content: "CORRECTION: Tests must go in __tests__/ directory, not tests/",
+     type: "correction",
+     metadata: { priority: "high", corrected_from: "tests/", corrected_to: "__tests__/" }
+   })
+3. Confirm: "✓ Stored correction - will always use __tests__/ for tests"
+```
+
+## Response Format
+
+### Pre-Action (Context Gathering)
+
+```
+Context for [task]:
+
+✅ **Preferences (Apply These)**:
+• [Preference 1] (stated: [date])
+• [Preference 2] (stated: [date])
+
+✅ **What Worked Before (Recommend)**:
+• [Success 1] ([date])
+• [Success 2] ([date])
+
+❌ **What Didn't Work (Avoid)**:
+• [Failure 1] → [What to do instead]
+• [Correction 1] → [User's preferred approach]
+
+📝 **Recommended Approach**:
+[Concise summary of what to do based on preferences + successes - failures]
+
+[If no context found]: No stored preferences or past outcomes found for this task.
+```
+
+### Post-Action (Outcome Capture)
+
+```
+✓ Stored [success/failure/correction] outcome for future reference
+```
+
+## Search Strategy
+
+**Always do multi-step searches** to get complete context:
+
+1. **Search for preferences**: `[keywords] preferences style`
+2. **Search for successes**: `[keywords] success worked well`
+3. **Search for failures**: `[keywords] failure failed error`
+4. **Search for corrections**: `[keywords] correction fix changed`
+
+**Combine results intelligently**:
+- Preferences override defaults
+- Successes suggest approaches
+- Failures block approaches
+- Corrections are highest priority (user explicitly fixed this)
+
+## Memory Types You'll Encounter
+
+- **preference**: User-stated preferences (highest weight)
+- **success**: What worked in past tasks (high weight)
+- **failure**: What didn't work (high weight for avoidance)
+- **correction**: User corrections (highest weight - user explicitly fixed)
+- **project-knowledge**: Project-specific info
+- **tool-use**: Historical tool usage
+
+## Important Notes
+
+- **Multi-step search** is critical - don't just search once
+- **Aggregate across searches** to get complete picture
+- **Prioritize corrections** above everything (user explicitly said "no, do this")
+- **Learn from failures** to avoid repeating mistakes
+- **Apply successes** to similar future tasks
+- You only provide CONTEXT - Claude Code makes final decisions and executes
+
+## Learning Loop Reminder
+
+Your job creates a **learning loop**:
+```
+User states preference → You remember it
+Claude tries approach → User approves/corrects
+You capture outcome → Store as success/failure
+Next similar task → You recommend what worked, avoid what didn't
+User never repeats themselves ✓
+```
+
+This is the core value of Claude Recall.

package/.claude/settings.local.json

@@ -0,0 +1,9 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(npm view:*)"
+    ],
+    "deny": [],
+    "ask": []
+  }
+}

package/README.md

@@ -8,30 +8,32 @@ Every time you start a new conversation with Claude, you're starting from scratc
 
 ## Key Features
 
-### 🧠 Automatic Memory System
-- **No manual commands needed** - Claude automatically searches for relevant memories based on your prompts
-- **Context-aware** - Retrieves memories that are semantically related to your current conversation
-- **Persistent across restarts** - Your preferences and context survive Claude Code restarts
+### 🧠 Intelligent Learning Loop
+- **Never repeat yourself** - State preferences once, Claude remembers forever
+- **Learn from outcomes** - Automatically captures what worked and what didn't
+- **Direct MCP search** - Fast, simple memory lookup (milliseconds, no agent overhead)
+- **Automatic application** - Preferences and successful patterns applied without asking
+- **Persistent across restarts** - Your learnings survive Claude Code restarts
 
 ### 📝 Intelligent Capture
 - **Automatic extraction** - Captures preferences, patterns, and important information from conversations
 - **Categorized storage** - Organizes memories by type (preferences, project knowledge, corrections)
 - **Priority-based** - More important or frequently used memories are prioritized
 
-### ⚡ Advanced Features (v0.3.0+)
-- **MCP Resources & Prompts** - Expose memories as subscribable resources and prompt templates
-- **Automatic preference detection** - Detects when you express preferences and suggests analysis
-- **Proactive memory injection** - Relevant memories automatically injected before tool execution
-- **Context-aware tool descriptions** - Tools show relevant preferences in their descriptions
-- **Duplicate detection** - Recognizes when you ask the same question multiple times
-- **Memory usage tracking** - Learns which memories are useful and adjusts relevance scores
+### ⚡ Advanced Features (v0.3.2+)
+- **Direct MCP calls** - Fast memory search without agent overhead (milliseconds)
+- **Comprehensive search** - Single search finds preferences, successes, failures, and corrections
+- **Outcome capture** - Stores what worked and what didn't for future learning
+- **Learning loop** - Pre-action search → Execute → Post-action outcome → Future tasks apply learnings
+- **Optional agent** - Advanced context-manager agent available for complex workflows
+- **Correction priority** - User corrections given highest priority (never repeat mistakes)
 
 ### 🔒 Privacy & Security First
 - **100% Local** - All memories stored locally in SQLite (~/.claude-recall/)
 - **No cloud sync** - Your data never leaves your machine
 - **You own your data** - Export, view, or delete memories at any time
 - **Zero telemetry** - No data collection or phone-home behavior
-- **Security Audited** - Reviewed by Claude Code using `/security-review` command: No exposed secrets, SQL injection protection, 0 npm vulnerabilities
+- **Security audited** - Reviewed using `/security-review` command: No exposed secrets, SQL injection protection, 0 npm vulnerabilities
 
 ## Quick Start
 
@@ -49,58 +51,155 @@ For CLI access from anywhere:
 npm install -g claude-recall@latest
 ```
 
-**Note:** You can have both installations. For global installations, manually add this to your `~/.claude/CLAUDE.md`:
-```markdown
-## Claude Recall Integration
-- IMPORTANT: Always search memories before creating new files or making decisions
-- Use `mcp__claude-recall__search_memory` to check for stored preferences and project knowledge
-- Memories include: coding preferences, file locations, project patterns, and team conventions
-```
+**Note:** You can have both installations. Installation automatically includes:
+- `.claude/agents/context-manager.md` - Optional agent for complex workflows
+- `.claude/CLAUDE.md` - Memory-first workflow with direct MCP search instructions
+- MCP server configuration in `~/.claude.json`
 
 After installation, verify with: `claude-recall --version` (or `npx claude-recall --version` for local installs)
 
-## How It Works
+## Updating Claude Recall
+
+To update to the latest version and refresh the MCP server connection:
+
+```bash
+# 1. Update the package
+npm install -g claude-recall@latest
+
+# 2. Remove the old MCP server configuration
+claude mcp remove claude-recall
+
+# 3. Re-add the MCP server
+claude mcp add --transport stdio claude-recall -- claude-recall mcp start
+
+# 4. Verify it's configured
+claude mcp list
+
+# 5. Restart Claude Code to apply changes
+```
+
+**Note:** Always restart Claude Code after updating the MCP server configuration.
+
+## Verifying Claude Recall is Working
+
+To confirm claude-recall is active in your Claude Code session:
+
+**1. Check MCP Server Status**
+```bash
+claude mcp list
+```
+Should show `claude-recall` in the list of active servers.
+
+**2. Ask Claude to Search Memories**
+Simply ask: "Search my memories for [anything]" - Claude should be able to call the search tool.
+
+**3. Check Available MCP Tools**
+Ask Claude: "What MCP tools do you have access to?" - Claude should list tools starting with `mcp__claude-recall__` including:
+- `mcp__claude-recall__store_memory`
+- `mcp__claude-recall__retrieve_memory`
+- `mcp__claude-recall__search`
 
-When you chat with Claude, the system:
-1. **Captures** your preferences and important information
-2. **Stores** them locally in SQLite (`~/.claude-recall/claude-recall.db`)
-3. **Retrieves** relevant memories when you start new conversations
-4. **Injects** context so Claude remembers your preferences
+**4. Store and Retrieve a Test Memory**
+```
+You: "Remember that I prefer testing with Jest"
+Claude: [Should call store_memory tool]
 
-### Example
+You: "What testing framework do I prefer?"
+Claude: [Should search memories and find Jest]
 ```
-You: "I prefer TypeScript with strict mode for all my projects"
-[Claude Recall automatically stores this preference]
 
---- Later, in a new session ---
+**5. Check Stats via CLI**
+```bash
+claude-recall stats
+```
+This shows if memories are being stored.
 
-You: "Create a new module for user authentication"
-[Claude Recall retrieves your TypeScript preference]
-Claude: "I'll create a TypeScript module with strict mode enabled..."
+**6. Check Running Process**
+```bash
+ps aux | grep claude-recall
+```
+Should show the MCP server process running.
+
+## How It Works
+
+Claude Recall implements an **intelligent learning loop** that ensures you never repeat yourself:
+
+### The Learning Loop
+
+1. **Store Preferences**: When you express preferences, they're stored in SQLite
+2. **Pre-Action Search**: Before tasks, Claude searches memories directly (fast MCP call)
+3. **Find Context**: Search finds preferences + successes + failures + corrections automatically
+4. **Execute with Context**: Claude applies what was learned
+5. **Capture Outcome**: After task, Claude stores success/failure/correction
+6. **Future Application**: Next similar task automatically applies learnings
+
+### Complete Example: Never Repeat Yourself
+
+```
+=== First Time: State Preference ===
+You: "I prefer Python for scripts"
+[Claude stores preference via MCP]
+
+=== Second Time: First Use ===
+You: "Create a test script"
+[Claude searches: mcp__claude-recall__search("scripts python test")]
+[Search finds: "I prefer Python for scripts"]
+[Claude creates test.py using Python]
+You: "Perfect!"
+[Claude stores: "Created test script with Python - SUCCESS"]
+
+=== Third Time: Automatic Application ===
+You: "Create a build script"
+[Claude searches: mcp__claude-recall__search("scripts build python")]
+[Search finds: "I prefer Python" + "test.py SUCCESS"]
+[Claude creates build.py automatically - learned pattern!]
+You: *Don't have to repeat preference - it was learned!*
+
+=== Correction Loop ===
+You: "No, put scripts in scripts/ directory not root"
+[Claude stores: "CORRECTION: Scripts in scripts/ directory" (highest priority)]
+[Claude moves file immediately]
+Next time: Search finds correction and applies automatically
 ```
 
 ## Memory Types
 
-### Preferences
+Claude Recall stores different types of memories (sorted by priority):
+
+### 1. Corrections (Highest Priority)
+- User explicitly said "No, do this instead"
+- Fixes to mistakes Claude made
+- Override previous approaches
+- **Example**: "CORRECTION: Tests in __tests__/ not tests/"
+
+### 2. Preferences
 - Coding style preferences (languages, frameworks, patterns)
 - Tool preferences (testing frameworks, build tools)
 - Workflow preferences (git conventions, file structures)
+- **Example**: "I prefer TypeScript with strict mode"
+
+### 3. Successes
+- What worked in past tasks
+- Approaches that user approved
+- Validated patterns
+- **Example**: "Created auth module with JWT tokens - SUCCESS"
 
-### Project Knowledge
+### 4. Failures
+- What didn't work and should be avoided
+- Approaches that failed or were rejected
+- Deprecated approaches
+- **Example**: "Session-based auth failed, use JWT instead"
+
+### 5. Project Knowledge
 - Database configurations
 - API patterns and endpoints
 - Architecture decisions
 - Dependencies and versions
 
-### Context
-- Current tasks and work in progress
-- Recent decisions and changes
-- Team conventions
-
-### Corrections
-- Learned from mistakes
-- Updated patterns
-- Deprecated approaches to avoid
+### 6. Tool Use
+- Historical tool execution
+- Command patterns
+- Workflow steps
 
 ## CLI Commands
 
@@ -213,9 +312,12 @@ npm --version
 ## Best Practices
 
 1. **Be explicit about preferences** - Clear statements like "Always use..." or "Never..." are captured better
-2. **Correct mistakes** - When Claude gets something wrong, the correction is remembered
-3. **Review periodically** - Use `claude-recall stats` to see what's being remembered
-4. **Export important memories** - Backup critical preferences with `claude-recall export`
+2. **Approve or correct** - Say "Good!" or "No, do this" after tasks to build the learning loop
+3. **Trust the learning loop** - Direct MCP search finds preferences, successes, and failures instantly
+4. **Correct mistakes immediately** - Corrections get highest priority and won't be repeated
+5. **Review periodically** - Use `claude-recall stats` to see what's being remembered
+6. **Export important memories** - Backup critical preferences with `claude-recall export`
+7. **Fast and simple** - Direct MCP calls work great for most tasks (agent is optional)
 
 ## Acknowledgements
 

package/dist/cli/claude-recall-cli.js

@@ -98,7 +98,18 @@ class ClaudeRecallCLI {
         const results = this.memoryService.search(query);
         const topResults = results.slice(0, limit);
         if (options.json) {
-            console.log(JSON.stringify(topResults, null, 2));
+            // Format for hook consumption - include relevance_score field
+            const formattedResults = topResults.map((result) => ({
+                key: result.key,
+                value: result.value,
+                type: result.type,
+                timestamp: result.timestamp,
+                relevance_score: result.score, // Rename score to relevance_score for hooks
+                access_count: result.access_count,
+                project_id: result.project_id,
+                file_path: result.file_path
+            }));
+            console.log(JSON.stringify(formattedResults, null, 2));
             return;
         }
         if (topResults.length === 0) {
@@ -248,6 +259,54 @@ class ClaudeRecallCLI {
         console.log('\n');
         this.logger.info('CLI', 'Status displayed');
     }
+    /**
+     * Store a memory directly from CLI
+     */
+    async store(content, options) {
+        try {
+            const type = options.type || 'preference';
+            const confidence = options.confidence || 0.8;
+            // Parse metadata if provided
+            let metadata = {};
+            if (options.metadata) {
+                try {
+                    metadata = JSON.parse(options.metadata);
+                }
+                catch (error) {
+                    console.error('❌ Invalid metadata JSON');
+                    process.exit(1);
+                }
+            }
+            // Generate unique key
+            const key = `cli_${type}_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
+            // Store memory
+            this.memoryService.store({
+                key,
+                value: {
+                    content,
+                    confidence,
+                    source: 'cli',
+                    ...metadata,
+                    timestamp: Date.now()
+                },
+                type,
+                context: {
+                    timestamp: Date.now()
+                },
+                relevanceScore: confidence
+            });
+            console.log(`✅ Memory stored successfully`);
+            console.log(`   ID: ${key}`);
+            console.log(`   Type: ${type}`);
+            console.log(`   Confidence: ${confidence}`);
+            this.logger.info('CLI', 'Memory stored', { key, type, confidence });
+        }
+        catch (error) {
+            console.error('❌ Store failed:', error);
+            this.logger.error('CLI', 'Store failed', error);
+            process.exit(1);
+        }
+    }
     truncateContent(content) {
         const str = typeof content === 'string' ? content : JSON.stringify(content);
         const maxLength = 100;
@@ -404,6 +463,22 @@ async function main() {
         await cli.status();
         process.exit(0);
     });
+    // Store command
+    program
+        .command('store <content>')
+        .description('Store a memory directly')
+        .option('-t, --type <type>', 'Memory type (default: preference)', 'preference')
+        .option('-c, --confidence <score>', 'Confidence score 0.0-1.0 (default: 0.8)', '0.8')
+        .option('-m, --metadata <json>', 'Additional metadata as JSON string')
+        .action(async (content, options) => {
+        const cli = new ClaudeRecallCLI(program.opts());
+        await cli.store(content, {
+            type: options.type,
+            confidence: parseFloat(options.confidence),
+            metadata: options.metadata
+        });
+        process.exit(0);
+    });
     // Test memory search command
     program
         .command('test-memory-search')

package/dist/core/retrieval.js

@@ -24,13 +24,25 @@ class MemoryRetrieval {
         // Combine keywords and significant words
         return [...new Set([...keywords, ...words])];
     }
-    findRelevant(context) {
+    findRelevant(context, sortBy = 'relevance') {
         // Extract keywords from query if provided
         if (context.query && !context.keywords) {
             context.keywords = this.extractKeywords(context.query);
         }
         // Use enhanced search that looks for keywords in memory values
         const candidates = this.storage.searchByContext(context);
+        if (sortBy === 'timestamp') {
+            // Sort by timestamp DESC (newest first)
+            const sorted = candidates
+                .map(memory => ({
+                ...memory,
+                score: 1.0 // Placeholder score for timestamp sorting
+            }))
+                .sort((a, b) => (b.timestamp || 0) - (a.timestamp || 0));
+            // Return top results (no limit applied here, caller controls via slice)
+            return sorted;
+        }
+        // Default: relevance sorting
         // Score and prioritize by memory type
         const scored = candidates
             .map(memory => ({

package/dist/mcp/tools/memory-tools.js

@@ -94,7 +94,7 @@ class MemoryTools {
             },
             {
                 name: 'mcp__claude-recall__retrieve_memory',
-                description: 'Get relevant memories by ID or query',
+                description: 'Get relevant memories by ID, query, or recency. Use sortBy="timestamp" for most recent memories.',
                 inputSchema: {
                     type: 'object',
                     properties: {
@@ -109,6 +109,11 @@ class MemoryTools {
                         limit: {
                             type: 'number',
                             description: 'Maximum number of memories to return (default: 10)'
+                        },
+                        sortBy: {
+                            type: 'string',
+                            enum: ['relevance', 'timestamp'],
+                            description: 'Sort order: "relevance" (default, keyword-based) or "timestamp" (newest first)'
                         }
                     }
                 },
@@ -241,7 +246,20 @@ class MemoryTools {
     }
     async handleRetrieveMemory(input, context) {
         try {
-            const { query, id, limit = 10 } = input;
+            let { query, id, limit = 10, sortBy } = input;
+            // Smart detection: Auto-detect timestamp sorting from query keywords
+            if (!sortBy && query) {
+                const timeKeywords = ['recent', 'latest', 'newest', 'last', 'new'];
+                const lowerQuery = query.toLowerCase();
+                if (timeKeywords.some(kw => lowerQuery.includes(kw))) {
+                    sortBy = 'timestamp';
+                    this.logger.debug('MemoryTools', 'Auto-detected timestamp sorting', { query });
+                }
+            }
+            // Default to relevance sorting
+            if (!sortBy) {
+                sortBy = 'relevance';
+            }
             if (id) {
                 // Retrieve specific memory by ID
                 const memory = this.memoryService.retrieve(id);
@@ -258,8 +276,8 @@ class MemoryTools {
                 };
             }
             if (query) {
-                // Search for relevant memories
-                const results = this.memoryService.search(query);
+                // Search for relevant memories with sort option
+                const results = this.memoryService.search(query, sortBy);
                 const limitedResults = results.slice(0, limit);
                 return {
                     memories: limitedResults.map(r => ({
@@ -267,7 +285,8 @@ class MemoryTools {
                         relevanceScore: r.score
                     })),
                     count: limitedResults.length,
-                    totalFound: results.length
+                    totalFound: results.length,
+                    sortBy
                 };
             }
             // Get recent memories from context
@@ -275,14 +294,15 @@ class MemoryTools {
                 sessionId: context.sessionId,
                 projectId: context.projectId,
                 timestamp: context.timestamp
-            });
+            }, sortBy);
             const limitedResults = contextResults.slice(0, limit);
             return {
                 memories: limitedResults.map(r => ({
                     ...r,
                     relevanceScore: r.score
                 })),
-                count: limitedResults.length
+                count: limitedResults.length,
+                sortBy
             };
         }
         catch (error) {

package/dist/services/memory.js

@@ -79,7 +79,7 @@ class MemoryService {
     /**
      * Find relevant memories based on context
      */
-    findRelevant(context) {
+    findRelevant(context, sortBy = 'relevance') {
         try {
             const retrievalContext = {
                 project_id: context.projectId || this.config.getProjectId(),
@@ -90,12 +90,13 @@ class MemoryService {
                 query: context.query,
                 keywords: context.keywords
             };
-            const memories = this.retrieval.findRelevant(retrievalContext);
+            const memories = this.retrieval.findRelevant(retrievalContext, sortBy);
             this.logger.logRetrieval(context.query || 'context-based', memories.length, {
                 projectId: retrievalContext.project_id,
                 filePath: retrievalContext.file_path,
                 tool: retrievalContext.tool,
-                keywords: retrievalContext.keywords
+                keywords: retrievalContext.keywords,
+                sortBy
             });
             return memories;
         }
@@ -107,16 +108,17 @@ class MemoryService {
     /**
      * Search memories by keyword
      */
-    search(query) {
+    search(query, sortBy = 'relevance') {
         try {
             // Use findRelevant with query context for better semantic matching
             const context = {
                 query: query,
                 timestamp: Date.now()
             };
-            const results = this.retrieval.findRelevant(context);
+            const results = this.retrieval.findRelevant(context, sortBy);
             this.logger.logRetrieval(query, results.length, {
-                searchType: 'contextual'
+                searchType: 'contextual',
+                sortBy
             });
             return results;
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-recall",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "description": "Persistent memory for Claude Code with automatic capture via hooks and MCP server",
   "main": "dist/index.js",
   "bin": {
@@ -8,6 +8,7 @@
   },
   "files": [
     "dist/",
+    ".claude/",
     "scripts/postinstall.js",
     "scripts/postinstall-claude-md.js",
     "README.md",

package/scripts/postinstall.js

@@ -58,9 +58,13 @@ try {
   
   console.log('\n📝 Installation complete!');
   console.log('   Claude Recall MCP server is now configured.');
-  console.log('   Restart Claude Code to activate the memory system.');
-  console.log('\n💡 Tip: Claude Recall works automatically in the background.');
-  console.log('   Your memories are captured and retrieved seamlessly.\n');
+  console.log('   Restart your terminal to activate the memory system.');
+  console.log('\n💡 Tip: Claude Recall works automatically with the memory-researcher agent.');
+  console.log('   Claude Code will search memories before file operations and decisions.');
+  console.log('\n🎯 Agent Integration:');
+  console.log('   The memory-researcher agent is available in .claude/agents/');
+  console.log('   Claude Code reads .claude/CLAUDE.md for memory-first instructions.');
+  console.log('\n   Your memories persist across conversations and restarts.\n');
 
 } catch (error) {
   console.error('❌ Error updating ~/.claude.json:', error.message);