claude-recall 0.8.4 → 0.8.6

package/.claude/CLAUDE.md

@@ -1,407 +1,14 @@
-# Claude Recall - Skills Integration
+# Claude Recall - Memory-First Development
 
-**Note**: Claude Recall now uses Claude Code Skills for better memory management.
-See [.claude/skills/memory-management/SKILL.md](./.claude/skills/memory-management/SKILL.md) for details.
+This project uses Claude Code Skills for memory management.
 
----
+**Primary Documentation:** [SKILL.md](./skills/memory-management/SKILL.md)
 
-# Claude Recall - Memory-First Development with Learning Loop
+The skill provides:
+- Memory search workflow (search before acting)
+- Automatic failure capture with counterfactual reasoning
+- Project scoping (universal vs project-specific)
+- DevOps pattern priority (Priority 0 - highest)
+- Privacy & security guidelines
 
-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 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
-
-### 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 meaningful outcomes** for future learning:
-
-**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"):
-```
-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: "Tried session-based auth (failed), switched to JWT tokens (SUCCESS) - JWT works better for stateless API",
-  metadata: { type: "success", task: "authentication", learning_cycle: 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
-
-## Intelligence & Evolution (v0.7.0+)
-
-### Automatic Failure Learning
-
-Claude Recall now **automatically captures failures with counterfactual reasoning**:
-- **What failed**: The approach or action that didn't work
-- **Why it failed**: Root cause analysis (file not found, permission denied, etc.)
-- **What should be done instead**: Counterfactual suggestion (the right approach)
-- **Preventative checks**: Steps to prevent the failure from recurring
-
-**No manual storage needed** - failures are auto-detected from:
-- Error messages and exceptions
-- User corrections ("That didn't work", "Failed", "Error")
-
-### Sophistication Tracking
-
-Every memory is **automatically classified by sophistication level**:
-- **L1 Procedural**: Basic tool use, simple actions
-- **L2 Self-Reflection**: Error checking, corrections, learning from failures
-- **L3 Adaptive**: Systematic workflows, devops patterns
-- **L4 Compositional**: Multi-constraint reasoning, complex decision-making
-
-View your agent's evolution: `npx claude-recall evolution`
-
-### New CLI Commands (v0.7.0+)
-
-**View memory evolution metrics:**
-```bash
-npx claude-recall evolution                    # Last 30 days
-npx claude-recall evolution --days 60          # Last 60 days
-npx claude-recall evolution --project my-app   # Filter by project
-```
-
-Shows:
-- Progression score (0-100)
-- Sophistication breakdown (L1-L4 percentages)
-- Confidence trends (improving/stable/declining)
-- Failure rate trends (improving/stable/worsening)
-
-**View failure memories with counterfactual learning:**
-```bash
-npx claude-recall failures                     # Last 10 failures
-npx claude-recall failures --limit 20          # Show 20 most recent
-npx claude-recall failures --project my-app    # Filter by project
-```
-
-Shows:
-- What failed and why
-- What should have been done instead
-- Preventative checks to avoid recurrence
-- Alternative approaches to consider
-
-## 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. ✗ DO NOT store success - this was just applying a known preference
-   No challenge overcome, no learning cycle.
-```
-
-### 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)
-
-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"
-
-**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")
-- 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
-
-**DO NOT store:**
-- Trivial successes (file creation, simple tool execution)
-- First-try successes with no challenges
-- Actions that just followed existing preferences
-
-## 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
-
-## Project Scoping (v0.7.2+)
-
-Claude Recall now supports **project-specific memory isolation** to keep universal preferences separate from project-specific information.
-
-### Three Memory Scopes
-
-1. **Universal** (`scope='universal'`): Available in all projects
-   - User says: "Remember everywhere: I prefer TypeScript with strict mode"
-   - Stored as universal memory, accessible from any project
-
-2. **Project** (`scope='project'`): Only available in current project
-   - User says: "For this project, we use PostgreSQL"
-   - Stored with project_id, only accessible from this project
-
-3. **Unscoped** (`scope=null`, default): Available everywhere (backward compatible)
-   - User says: "I prefer Jest for testing"
-   - Stored without scope, works like v0.7.1 and earlier
-
-### Auto-Detection
-
-When storing memories, the system automatically detects scope from user language:
-
-**Universal indicators**:
-- "remember everywhere"
-- "for all projects"
-- "globally"
-- "always use"
-
-**Project indicators**:
-- "for this project"
-- "project-specific"
-- "only here"
-- "in this project"
-
-**Default**: If no indicator, memory is unscoped (available everywhere)
-
-### How Search Works
-
-**Default behavior** (project + universal):
-```
-mcp__claude-recall__search("database")
-```
-Returns: Current project memories + universal memories + unscoped memories
-
-**Global search** (all projects):
-```
-mcp__claude-recall__search("database", filters: { globalSearch: true })
-```
-Returns: All memories from all projects
-
-### CLI Usage
-
-```bash
-# Current project stats
-npx claude-recall stats
-
-# Global stats (all projects)
-npx claude-recall stats --global
-
-# Search current project
-npx claude-recall search "database"
-
-# Search specific project
-npx claude-recall search "database" --project my-app
-
-# Search all projects
-npx claude-recall search "database" --global
-```
-
-### Use Cases
-
-**Universal memories**: Preferences that apply across all your work
-- Coding style: "Always use TypeScript with strict mode"
-- Tools: "Prefer Jest for testing"
-- Conventions: "Name files with kebab-case"
-
-**Project memories**: Project-specific details
-- Database: "This project uses PostgreSQL"
-- API: "Base URL is https://api.example.com"
-- Build: "Run npm run build:prod for production"
-
-## 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!
+For project architecture and development commands, see [CLAUDE.md](../CLAUDE.md) in the project root.

package/docs/faq.md

@@ -221,6 +221,9 @@ Project-specific keys ensure:
 - no cross-project leakage
 - clean agent shutdown
 
+**Recommended**: Create your own free keys for production:
+[Create PubNub Keys](https://www.pubnub.com/how-to/admin-portal-create-keys/)
+
 ---
 
 ## What if I want to reset everything?

package/docs/installation.md

@@ -37,6 +37,10 @@ Then restart **Claude Code**.
 
 Claude will automatically detect the MCP server and begin using persistent memory.
 
+Installation creates `.claude/skills/memory-management/` with:
+- SKILL.md (main skill definition)
+- references/ (examples, patterns, troubleshooting)
+
 ---
 
 ## Global Install (Not Recommended)

package/docs/project-scoping.md

@@ -19,6 +19,17 @@ This enables:
 
 ---
 
+## Automatic Memory Scoping
+
+Claude Recall automatically manages memory scope:
+- **Universal memories** (coding style, tool preferences) → reused across all projects
+- **Project memories** (database configs, APIs) → isolated per project
+
+System auto-detects from language ("remember everywhere" vs "for this project").
+No user configuration needed.
+
+---
+
 ## Presence Channel
 
 Memory Agent publishes heartbeats:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-recall",
-  "version": "0.8.4",
+  "version": "0.8.6",
   "description": "Persistent memory for Claude Code with fire-and-forget PubNub architecture, automatic capture, failure learning, and project scoping via MCP server",
   "main": "dist/index.js",
   "bin": {

package/docs/architecture.md

@@ -1,160 +0,0 @@
-# Architecture Overview
-
-Claude Recall consists of three integrated subsystems:
-
-1. **Local Memory Engine (SQLite)**
-2. **Realtime Event Bus (PubNub)**
-3. **Claude Code Hooks + MCP Server**
-
-Together, they form a fast, private, adaptive memory layer for Claude.
-
----
-
-# 1. Local Memory Engine (SQLite)
-
-All persistent knowledge is stored locally:
-
-- preferences
-- workflow patterns
-- project architecture
-- mistakes + corrections
-- reasoning heuristics
-- coding standards
-- naming conventions
-
-The database:
-- is located at `~/.claude-recall/memories.db`
-- is indexed for fast semantic search
-- uses structured, typed memory records
-- prunes & evolves data over time
-
-The Memory Engine guarantees:
-- **zero cloud storage**
-- **full user control**
-- **review, edit, export, delete**
-
----
-
-# 2. Realtime Event Bus (PubNub)
-
-PubNub enables Claude Recall's **low-latency, non-blocking architecture**.
-
-### Why PubNub?
-
-Claude Code hooks run inside time-sensitive workflows.
-Traditional synchronous CLI calls were slow (50–500ms).
-PubNub reduces them to **sub-10ms**.
-
-### What PubNub Transmits
-Only *lightweight metadata*, for example:
-
-- tool name
-- file path
-- event type
-- prompt token counts (never text)
-- memory suggestion IDs
-- agent lifecycle heartbeat
-
-### What PubNub Does *NOT* Transmit
-- code
-- conversation text
-- memory contents
-- embeddings
-- prompts
-- project data
-- file contents
-
-PubNub is a **coordination mechanism**, not storage and not transport of user content.
-
-### Event Flow
-
-```
-Claude Code Hook
-↓ publish (metadata only)
-PubNub Channel
-↓ subscribe
-Memory Agent
-↓ analyze
-Memory Engine (SQLite)
-↓ suggestions
-PubNub Channel
-↓ subscribe
-Claude Code
-```
-
-### Channels Used
-
-| Channel | Purpose |
-|---------|---------|
-| `claude-tool-events` | File write/edit events from hooks |
-| `claude-prompt-stream` | Prompt token metadata |
-| `claude-memory-context` | Contextual memory suggestions |
-| `claude-presence` | Agent heartbeat & lifecycle |
-
-### Architecture Benefits
-- Hooks are instantaneous
-- Memory is processed asynchronously
-- Claude remains responsive
-- Multiple events can be buffered in parallel
-- Agent can evolve memory without blocking anything
-
----
-
-# 3. Claude Code Hooks + MCP Server
-
-Claude Recall integrates deeply with Claude Code:
-
-### Pre-Action Hook
-- Fired before Claude writes or edits files
-- Publishes event metadata
-- Requests relevant memories
-- Injects memory into planning
-
-### Planning Hook
-- Performs advanced reasoning
-- Uses previous memories
-- Returns structured plan
-- Reduces hallucination & mistakes
-
-### Post-Action Hook
-- Captures new knowledge
-- Classifies memory type
-- Publishes metadata via PubNub
-- Evolves memory asynchronously
-
-### MCP Server
-Handles:
-- semantic search
-- memory retrieval
-- memory creation/updating
-- project registration
-- skills activation
-
----
-
-# Summary Diagram
-
-```
-        ┌──────────────┐
-        │  Claude Code │
-        └───────┬──────┘
-                │ Hooks
-                ▼
-      ┌─────────────────────┐
-      │   PubNub Event Bus  │
-      └───────┬────────────┘
-              │ metadata only
-              ▼
-    ┌───────────────────────┐
-    │  Memory Agent (Local) │
-    └───────┬──────────────┘
-            │
-            ▼
- ┌─────────────────────────────┐
- │   SQLite Memory Engine      │
- └─────────────────────────────┘
-```
-
----
-
-Next: Learn about the [Learning Loop](learning-loop.md).