claude-recall 0.7.9 → 0.8.0

package/.claude/CLAUDE.md

@@ -15,8 +15,8 @@ This file provides instructions to Claude Code when working with projects that u
 
 Your job is to:
 1. Remember stated preferences permanently
-2. Learn from successes (what worked)
-3. Learn from failures (what didn't work)
+2. Learn from failures and corrections (what didn't work, how it was fixed)
+3. Capture meaningful success patterns (when overcoming challenges, not trivial actions)
 4. Apply learned patterns automatically
 
 ## The Learning Loop Workflow
@@ -55,15 +55,7 @@ Apply what you found:
 
 ### 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]" }
-})
-```
+**Capture meaningful outcomes** for future learning:
 
 **If user corrects** ("No, do it this way", "Change X to Y"):
 ```
@@ -75,9 +67,26 @@ mcp__claude-recall__store_memory({
 
 **If task fails** (errors, "That didn't work"):
 ```
+Failures are AUTO-CAPTURED with counterfactual reasoning.
+No manual storage needed - the system detects failures automatically.
+```
+
+**If task succeeds AFTER overcoming challenges** (fail → correct → success):
+```
+ONLY store success when there was a learning cycle:
+- After you tried approach A, failed, then approach B worked
+- After user corrected your approach and THEN it succeeded
+- When task required multiple iterations to get right
+
+DO NOT store success for:
+- Trivial tool executions (creating files, running commands)
+- First-try successes with no challenges
+- Actions that just followed existing preferences
+
+Example of meaningful success:
 mcp__claude-recall__store_memory({
-  content: "[Approach] failed - [reason]",
-  metadata: { type: "failure", avoid: true }
+  content: "Tried session-based auth (failed), switched to JWT tokens (SUCCESS) - JWT works better for stateless API",
+  metadata: { type: "success", task: "authentication", learning_cycle: true }
 })
 ```
 
@@ -182,10 +191,8 @@ Confirm: "✓ Stored 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" }
-   })
+4. ✗ DO NOT store success - this was just applying a known preference
+   No challenge overcome, no learning cycle.
 ```
 
 ### Third Time - Automatic Application
@@ -195,14 +202,31 @@ Confirm: "✓ Stored preference"
 **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)
+   Finds: "I prefer Python for scripts" (preference)
 
-2. Create build.py automatically - preference + success pattern!
+2. Create build.py automatically - preference applied!
    User doesn't have to repeat themselves ✓
 ```
 
+### Learning Cycle Example - When to Store Success
+
+**User:** "Set up authentication"
+
+**You (Claude Code):**
+```
+1. Try approach: Create session-based auth with cookies
+2. Error: "CORS issues in stateless API"
+3. User feedback: "This is a stateless API, sessions won't work"
+4. Try approach: JWT tokens with Bearer authentication
+5. Success! Works correctly.
+
+6. ✓ STORE THIS - it's a learning cycle:
+   mcp__claude-recall__store_memory({
+     content: "Session auth failed for stateless API (CORS). JWT tokens work - use Bearer authentication for stateless APIs",
+     metadata: { type: "success", task: "authentication", learning_cycle: true }
+   })
+```
+
 ### User Makes Correction
 
 **User:** "No, put scripts in scripts/ directory not root"
@@ -225,11 +249,17 @@ Confirm: "✓ Stored preference"
 - 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")
+- Makes a correction ("No, do it this way", "Change X to Y")
+
+**Store after task completion (ONLY for learning cycles):**
+- **Success (rare!)**: Only when overcoming challenges - "Tried X (failed), then Y (SUCCESS)"
+- **Failure (auto-captured)**: System detects automatically, no manual storage needed
+- **Correction**: Always store user corrections with high priority
 
-**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"
+**DO NOT store:**
+- Trivial successes (file creation, simple tool execution)
+- First-try successes with no challenges
+- Actions that just followed existing preferences
 
 ## Critical Guidelines
 

package/.claude/hooks/pubnub_pre_tool_hook.py

@@ -0,0 +1,92 @@
+#!/usr/bin/env python3
+"""
+PubNub-enabled pre-tool hook for Claude Recall.
+
+This lightweight hook:
+1. Publishes tool execution event to PubNub (async, non-blocking)
+2. Allows execution to proceed immediately
+3. Memory Agent subscribes to events and provides context asynchronously
+
+No blocking, no waiting - just publish and continue.
+This makes hooks fast and Claude Code responsive.
+
+Exit codes:
+- 0: Always allow (non-blocking design)
+"""
+import json
+import sys
+import subprocess
+import os
+from typing import Dict, Any
+
+# Path to Node.js publisher
+PUBLISHER_PATH = os.path.join(
+    os.path.dirname(os.path.dirname(__file__)),
+    'dist', 'pubnub', 'publisher-cli.js'
+)
+
+
+def publish_tool_event(hook_data: Dict[str, Any]) -> bool:
+    """
+    Publish tool execution event to PubNub.
+    Fire-and-forget - doesn't wait for response.
+    """
+    try:
+        tool_name = hook_data.get('tool_name', '')
+        tool_input = hook_data.get('tool_input', {})
+        session_id = hook_data.get('session_id', '')
+        project_id = hook_data.get('project_id', '')
+
+        # Construct event data
+        event_data = {
+            'sessionId': session_id,
+            'toolName': tool_name,
+            'toolInput': tool_input,
+            'projectId': project_id
+        }
+
+        # Publish via Node.js CLI (non-blocking)
+        subprocess.Popen(
+            ['node', PUBLISHER_PATH, 'tool-pre', json.dumps(event_data)],
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+            start_new_session=True  # Detach from parent
+        )
+
+        return True
+
+    except Exception as e:
+        # Never block on errors - just log and continue
+        print(f"[PubNub Hook] Warning: Event publish failed: {e}", file=sys.stderr)
+        return False
+
+
+def main():
+    """
+    Main hook entry point.
+    Always allows execution - memory context will arrive asynchronously.
+    """
+    try:
+        # Read hook data from stdin
+        hook_data = json.load(sys.stdin)
+
+        # Publish event (non-blocking)
+        publish_tool_event(hook_data)
+
+        # Always allow execution to proceed
+        # Memory Agent will provide context asynchronously via PubNub
+        sys.exit(0)
+
+    except json.JSONDecodeError as e:
+        # Parse error - log warning but don't block
+        print(f"[PubNub Hook] Warning: Failed to parse hook input: {e}", file=sys.stderr)
+        sys.exit(0)
+
+    except Exception as e:
+        # Any other error - log but don't block
+        print(f"[PubNub Hook] Warning: Hook error: {e}", file=sys.stderr)
+        sys.exit(0)
+
+
+if __name__ == '__main__':
+    main()

package/.claude/hooks/pubnub_prompt_hook.py

@@ -0,0 +1,93 @@
+#!/usr/bin/env python3
+"""
+PubNub-enabled prompt capture hook for Claude Recall.
+
+Publishes user prompts to PubNub for the Memory Agent to analyze
+and extract preferences/patterns autonomously.
+
+Non-blocking, fire-and-forget design.
+
+Exit codes:
+- 0: Always allow (non-blocking)
+"""
+import json
+import sys
+import subprocess
+import os
+from typing import Dict, Any
+
+# Path to Node.js publisher
+PUBLISHER_PATH = os.path.join(
+    os.path.dirname(os.path.dirname(__file__)),
+    'dist', 'pubnub', 'publisher-cli.js'
+)
+
+
+def publish_prompt_event(hook_data: Dict[str, Any]) -> bool:
+    """
+    Publish user prompt to PubNub for Memory Agent analysis.
+    Fire-and-forget - doesn't wait for response.
+    """
+    try:
+        # Extract prompt content (handle different Claude Code versions)
+        prompt_content = (
+            hook_data.get('prompt', '') or
+            hook_data.get('content', '') or
+            hook_data.get('message', '')
+        )
+
+        if not prompt_content:
+            return False
+
+        session_id = hook_data.get('session_id', '')
+        project_id = hook_data.get('project_id', '')
+
+        # Construct event data
+        event_data = {
+            'sessionId': session_id,
+            'content': prompt_content,
+            'projectId': project_id
+        }
+
+        # Publish via Node.js CLI (non-blocking)
+        subprocess.Popen(
+            ['node', PUBLISHER_PATH, 'prompt', json.dumps(event_data)],
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+            start_new_session=True  # Detach from parent
+        )
+
+        return True
+
+    except Exception as e:
+        # Never block on errors
+        print(f"[PubNub Hook] Warning: Prompt publish failed: {e}", file=sys.stderr)
+        return False
+
+
+def main():
+    """
+    Main hook entry point.
+    Always allows execution - prompt analysis happens asynchronously.
+    """
+    try:
+        # Read hook data from stdin
+        hook_data = json.load(sys.stdin)
+
+        # Publish prompt event (non-blocking)
+        publish_prompt_event(hook_data)
+
+        # Always allow prompt to proceed
+        sys.exit(0)
+
+    except json.JSONDecodeError as e:
+        print(f"[PubNub Hook] Warning: Failed to parse hook input: {e}", file=sys.stderr)
+        sys.exit(0)
+
+    except Exception as e:
+        print(f"[PubNub Hook] Warning: Hook error: {e}", file=sys.stderr)
+        sys.exit(0)
+
+
+if __name__ == '__main__':
+    main()

package/.claude/settings.json

@@ -0,0 +1,25 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Write|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 .claude/hooks/pubnub_pre_tool_hook.py"
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 .claude/hooks/pubnub_prompt_hook.py"
+          }
+        ]
+      }
+    ]
+  }
+}

package/.claude/skills/memory-management/SKILL.md

@@ -31,9 +31,9 @@ This Skill teaches Claude Code how to use Claude Recall's persistent memory syst
    - Code style, framework preferences
    - File organization, naming conventions
 
-4. **Success/Failure** (Priority 3) - What worked and what didn't
-   - Successful implementations to repeat
-   - Failed approaches to avoid
+4. **Success/Failure** (Priority 3) - Learning cycles only
+   - **Success (rare!)**: Only when overcoming challenges - fail → correct → success cycles
+   - **Failure (auto-captured)**: System detects failures automatically with counterfactual reasoning
 
 ## Phase 1: Search Memories (REQUIRED FIRST STEP)
 
@@ -73,8 +73,8 @@ mcp__claude-recall__search("deploy build docker git workflow")
 
 - **DevOps workflows**: Git branching, testing rules, deployment steps
 - **Preferences**: User's stated coding style, tool choices
-- **Successes**: Past approaches that worked well
-- **Failures**: Past approaches that failed (avoid these!)
+- **Learning cycles**: Approaches that overcame challenges (fail → correct → success)
+- **Failures (auto-captured)**: Past approaches that failed (avoid these!)
 - **Corrections**: User fixes (HIGHEST PRIORITY - user explicitly said "no, do this")
 
 ## When to Store Memories
@@ -196,11 +196,9 @@ Finds: "I prefer Python for scripts" + "We use TDD"
 
 Step 2: Create test_script.py with TDD approach
 
-Step 3: User approves → Store success
-mcp__claude-recall__store_memory({
-  content: "Created test script with Python + TDD - SUCCESS",
-  metadata: { type: "success", task: "test_script" }
-})
+Step 3: User approves
+✗ DO NOT store success - this was just applying known preferences
+No challenge overcome, no learning cycle
 ```
 
 ### Third Time (Automatic Application)
@@ -213,12 +211,34 @@ mcp__claude-recall__search("script build python tdd")
 Finds:
 - "I prefer Python for scripts" (preference)
 - "We use TDD" (devops)
-- "Created test script with Python + TDD - SUCCESS" (validates approach)
 
 Step 2: Create build.py with tests automatically
 User doesn't have to repeat preferences! ✓
 ```
 
+### Learning Cycle Example (When to Store Success)
+
+```
+User: "Integrate with payment API"
+
+Step 1: Try REST approach
+- Built REST client with fetch()
+- Error: "CORS blocked in production"
+
+Step 2: User feedback
+User: "Our infra doesn't support CORS, use GraphQL endpoint"
+
+Step 3: Switch to GraphQL
+- Implemented GraphQL client
+- SUCCESS! Works in production
+
+Step 4: ✓ STORE THIS - it's a learning cycle
+mcp__claude-recall__store_memory({
+  content: "Payment API: REST failed (CORS blocked). GraphQL endpoint works - use GraphQL for all payment integrations",
+  metadata: { type: "success", task: "payment_api", learning_cycle: true }
+})
+```
+
 ## Best Practices
 
 1. **Search broadly** - Include task type + language + workflow keywords

package/.claude/skills/memory-management/references/capture-examples.md

@@ -5,45 +5,73 @@ This document provides templates for manually storing memories when automatic ca
 ## When to Use Manual Storage
 
 Use `mcp__claude-recall__store_memory` when:
-- Complex multi-step workflows need to be documented
-- Lessons learned from failures
-- User corrects your work
-- Nuanced context that patterns might miss
+- **User corrects your work** (highest priority)
+- **Learning cycles** - When you overcame a challenge (tried A, failed, then B worked)
+- **Complex multi-step workflows** need to be documented
+- **Nuanced context** that automatic capture might miss
 
-## Success Examples
+**DO NOT** use for:
+- Trivial successes (file creation, simple tool execution)
+- First-try successes with no challenges
+- Actions that just followed existing preferences
 
-### Basic Success
+## Success Examples (Learning Cycles Only!)
+
+**IMPORTANT**: Only store success memories when there was a **learning cycle** - you tried something, it failed, then another approach worked. This captures valuable insights, not trivial actions.
+
+### Learning Cycle: Authentication Approach
 ```javascript
+// ✓ Store this - overcame a challenge
 mcp__claude-recall__store_memory({
-  content: "Created authentication with JWT tokens - SUCCESS",
-  metadata: { type: "success", task: "authentication" }
+  content: "Tried session-based auth with cookies (FAILED - CORS issues in distributed API). Switched to JWT tokens with Bearer auth - SUCCESS. JWT works better for stateless architecture.",
+  metadata: {
+    type: "success",
+    task: "authentication",
+    learning_cycle: true,
+    failed_approach: "session_cookies",
+    working_approach: "jwt_bearer"
+  }
 })
 ```
 
-### Success with Context
+### Learning Cycle: Audio Capture Strategy
 ```javascript
+// ✓ Store this - iterated to find the right solution
 mcp__claude-recall__store_memory({
-  content: "Implemented push-to-talk with pyaudio instead of continuous VAD - SUCCESS. Much better performance and user control.",
+  content: "Continuous VAD approach failed (too CPU intensive). Tried buffering (FAILED - lag issues). Implemented push-to-talk with pyaudio - SUCCESS. Much better performance and UX control.",
   metadata: {
     type: "success",
     task: "audio_capture",
+    learning_cycle: true,
     improvement: "performance + ux"
   }
 })
 ```
 
-### Success with Technical Details
+### Learning Cycle: Performance Fix
 ```javascript
+// ✓ Store this - debugging led to solution
 mcp__claude-recall__store_memory({
-  content: "Fixed memory leak by moving PyAudio initialization outside the loop - SUCCESS. Memory usage dropped from 500MB to 50MB.",
+  content: "Memory leak investigation: Tried garbage collection tuning (no effect). Checked event listeners (not the issue). Found PyAudio initialization inside loop - moved outside - SUCCESS. Memory dropped 500MB → 50MB.",
   metadata: {
     type: "success",
     task: "performance",
+    learning_cycle: true,
     metric: "10x memory reduction"
   }
 })
 ```
 
+### ✗ DON'T Store Trivial Success
+```javascript
+// ✗ DON'T store this - no challenge, just basic tool execution
+mcp__claude-recall__store_memory({
+  content: "Created authentication module with JWT - SUCCESS",
+  metadata: { type: "success", task: "authentication" }
+})
+// Why not? No failure, no iteration, no learning cycle.
+```
+
 ## Failure Examples
 
 ### Basic Failure