claude-recall 0.11.2 → 0.11.4

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

@@ -26,9 +26,10 @@ Persistent memory system that ensures Claude never repeats mistakes and always a
 
 1. **ALWAYS load rules before acting** - Call `load_rules` before Write, Edit, or significant Bash operations
 2. **Apply what you find** - Use retrieved preferences, patterns, and corrections
-3. **Capture corrections immediately** - User fixes are highest priority
-4. **Store learning cycles** - When you fail then succeed, that's valuable knowledge
-5. **Never store secrets** - No API keys, passwords, tokens, or PII
+3. **Ask before storing** - Before calling `store_memory`, briefly tell the user what you plan to store and ask for confirmation. Example: *"I'd like to remember that you prefer tabs over spaces. Store this?"* Only call the tool after the user agrees.
+4. **Capture corrections immediately** - User fixes are highest priority (still ask first)
+5. **Store learning cycles** - When you fail then succeed, that's valuable knowledge
+6. **Never store secrets** - No API keys, passwords, tokens, or PII
 
 ## Quick Reference
 
@@ -141,13 +142,17 @@ Safe to store:
 
 3. Fix the code
 
-4. Store the correction:
+4. Ask: "I'd like to remember: always use httpOnly cookies for auth tokens, never localStorage. Store this?"
+
+5. User: "Yes"
+
+6. Store the correction:
    mcp__claude-recall__store_memory({
      "content": "CORRECTION: Always use httpOnly cookies for auth tokens, never localStorage",
      "metadata": { "type": "correction" }
    })
 
-5. Response includes activeRule - apply it immediately
+7. Response includes activeRule - apply it immediately
 ```
 
 ### Overcoming a Challenge
@@ -160,7 +165,11 @@ Safe to store:
 
 3. Implemented JWT -> Works!
 
-4. Store the learning:
+4. Ask: "I'd like to remember: Redis sessions fail in k8s due to sync issues; use stateless JWT instead. Store this?"
+
+5. User: "Yes"
+
+6. Store the learning:
    mcp__claude-recall__store_memory({
      "content": "Auth in k8s: Redis sessions failed (sync issues). JWT stateless tokens work correctly.",
      "metadata": { "type": "failure", "learning_cycle": true }

package/README.md

@@ -13,200 +13,231 @@ Your preferences, project structure, workflows, corrections, and coding style ar
 
 ---
 
-## 🚀 Features
+## Features
 
-### 🌱 Continuous Learning (Local SQLite)
+- **Continuous Learning** — captures coding patterns, tool preferences, corrections, architectural decisions, and workflow habits in local SQLite
+- **Native Claude Skills** — no hooks required; Claude decides when to search/store based on built-in skill guidance
+- **User-Confirmed Storage** — Claude asks for your permission before storing any memory
+- **Project-Scoped Knowledge** — each project gets its own memory namespace; switch projects and Claude switches memory
+- **Failure Learning** — captures failures with counterfactual reasoning (what failed, why, what to do instead)
+- **Memory Evolution** — tracks agent progression over time across sophistication levels (L1–L4)
+- **Zero Cloud Storage** — all memory stored locally, no telemetry, works fully offline
+- **Process Management** — automatic server lifecycle management with stale process cleanup
 
-Claude learns your:
+---
 
-* coding patterns
-* tool preferences
-* corrections
-* architectural decisions
-* workflow habits
+## Quick Start
 
-Everything stays **local**.
+### Requirements
 
----
+| Component | Version                 | Notes                       |
+| --------- | ----------------------- | --------------------------- |
+| Node.js   | **20+**                 | required for better-sqlite3 |
+| OS        | macOS / Linux / Windows | WSL supported               |
 
-## 🎯 Native Claude Skills Integration
+### Install
 
-Claude Recall uses Claude Code's native Skills system for seamless memory guidance.
+```bash
+cd your-project
+npm install claude-recall
 
-### How it works
+# Check installed version:
+npx claude-recall --version
 
-* **No hooks required** — Skills are built into Claude Code
-* **Non-blocking** — Claude decides when to search/store based on skill guidance
-* **Self-directed** — Claude understands when memory is relevant to the task
-* **Zero latency** — No external processes or enforcement overhead
+# Show activation instructions:
+npx claude-recall setup
+```
 
-### What the Skill teaches Claude
+### Activate
 
-* Search memory before writing/editing code
-* Apply learned conventions and avoid past mistakes
-* Capture corrections when users fix mistakes
-* Store learning cycles (fail → fix → success)
+Register MCP server with Claude Code:
 
-The skill is automatically installed to `.claude/skills/memory-management/SKILL.md` on package install.
+```bash
+claude mcp add claude-recall -- npx -y claude-recall@latest mcp start
+```
 
----
+Then restart your terminal or Claude Code session.
 
-## 📂 Project-Scoped Knowledge
+Already registered? Remove first:
 
-Each project gets its own memory namespace:
+```bash
+claude mcp remove claude-recall
+```
 
-* architecture
-* tech stack
-* conventions
-* past decisions
-* known pitfalls
-* previous fixes
-* preferences unique to that codebase
+### Verify
 
-Switch projects → Claude switches memory.
+In Claude Code, ask: *"Load my rules"*
 
----
+Claude should call `mcp__claude-recall__load_rules`. If it works, you're ready.
 
-## 🔌 Zero Cloud Storage
+### Upgrade
 
-* All memory stored locally in SQLite
-* No cloud sync
-* No telemetry
-* Entire system works offline
+```bash
+npm uninstall claude-recall && npm install claude-recall
+```
 
 ---
 
-## 💻 Claude Code–Native Integration
+## How It Works
 
-Claude Recall integrates via:
+Claude Recall has three layers:
 
-* **MCP server** — search, store, retrieve memories
-* **Native Skills** — guides Claude on when to use memory tools
-* **Automatic capture** — extracts preferences from conversations
+### 1. Local Memory Engine (SQLite)
 
-Claude knows to search memory before significant actions, with no enforcement overhead.
+Stores and evolves preferences, patterns, decisions, corrections, and failure learnings. Uses WAL mode for concurrency, content-hash deduplication, and automatic compaction.
 
----
+### 2. MCP Server (2 tools)
 
-## ⚡ Quick Start
+Exposes two tools to Claude Code:
 
-### Requirements
+| Tool | Purpose |
+| ---- | ------- |
+| `load_rules` | Load all active rules (preferences, corrections, failures, devops) at the start of a task |
+| `store_memory` | Save new knowledge — preferences, corrections, devops rules, failures |
 
-| Component | Version                 | Notes                       |
-| --------- | ----------------------- | --------------------------- |
-| Node.js   | **20+**                 | required for better-sqlite3 |
-| OS        | macOS / Linux / Windows | WSL supported               |
+### 3. Native Claude Skill
 
----
+Installed automatically to `.claude/skills/memory-management/SKILL.md`. Teaches Claude:
+- Load rules before writing/editing code
+- Apply learned conventions and avoid past mistakes
+- **Ask the user for confirmation before storing any memory**
+- Capture corrections when users fix mistakes
+- Store learning cycles (fail → fix → success)
 
-### Install (per project)
+---
 
-```bash
-cd your-project
-npm install claude-recall
+## CLI Reference
 
-# Check installed version:
-npx claude-recall --version
+### Core Commands
 
-# Show activation instructions:
-npx claude-recall setup
+```bash
+npx claude-recall stats                  # Memory statistics
+npx claude-recall search "query"         # Search memories
+npx claude-recall store "content"        # Store memory directly
+npx claude-recall export backup.json     # Export memories to JSON
+npx claude-recall import backup.json     # Import memories from JSON
+npx claude-recall clear --force          # Clear all memories
 ```
 
-### Upgrade
+### Analysis
 
 ```bash
-npm uninstall claude-recall && npm install claude-recall
+npx claude-recall evolution              # Memory evolution metrics (L1-L4)
+npx claude-recall evolution --days 60    # Custom time window
+npx claude-recall failures               # View failure memories
+npx claude-recall failures --limit 20    # Limit results
+npx claude-recall monitor                # Memory search monitoring stats
 ```
 
----
+### MCP Server Management
 
-### Activate
+```bash
+npx claude-recall mcp status             # Current project's server status
+npx claude-recall mcp ps                 # List all running servers
+npx claude-recall mcp stop               # Stop server
+npx claude-recall mcp stop --force       # Force stop
+npx claude-recall mcp restart            # Restart server
+npx claude-recall mcp cleanup            # Remove stale PID files
+npx claude-recall mcp cleanup --all      # Stop all servers
+```
 
-Register MCP server:
+### Project Management
 
 ```bash
-claude mcp add claude-recall -- npx -y claude-recall@latest mcp start
+npx claude-recall project show           # Current project info
+npx claude-recall project list           # All registered projects
+npx claude-recall project register       # Register current project
+npx claude-recall project clean          # Remove stale registry entries
 ```
 
-Then restart your terminal or Claude Code session.
-
-Already registered? Remove first:
+### Setup & Diagnostics
 
 ```bash
-claude mcp remove claude-recall
+npx claude-recall setup                  # Show activation instructions
+npx claude-recall status                 # Installation and system status
+npx claude-recall repair                 # Clean up old hooks, install skills
 ```
 
 ---
 
-### Verify
-
-In Claude Code, ask: *"Search my memories"*
-
-Claude should call `mcp__claude-recall__search`. If it works → you're ready.
-
----
+## How Project Scoping Works
 
-## 🧠 How It Works (High-Level)
+Each project gets isolated memory based on its working directory:
 
-Claude Recall consists of:
+- **Project ID** is derived from the `cwd` that Claude Code passes to the MCP server
+- **Universal memories** (no project scope) are available everywhere
+- **Project memories** are only returned when working in that project
+- Switching projects switches memory automatically — no configuration needed
 
-### 1. Local Memory Engine (SQLite)
+Database location: `~/.claude-recall/claude-recall.db` (shared file, scoped by `project_id` column).
 
-Stores and evolves preferences, patterns, decisions, corrections.
+---
 
-### 2. MCP Server
+## WSL Users
 
-Exposes memory tools to Claude Code:
-- `mcp__claude-recall__search` — find relevant memories
-- `mcp__claude-recall__store_memory` — save new knowledge
-- `mcp__claude-recall__retrieve_memory` — get specific memories
+If you hit "invalid ELF header" errors from mixed Windows/WSL `node_modules`, use a global install:
 
-### 3. Native Claude Skill
+```bash
+# From WSL:
+npm install -g claude-recall
+
+# Update ~/.claude.json to use the global binary:
+{
+  "claude-recall": {
+    "type": "stdio",
+    "command": "claude-recall",
+    "args": ["mcp", "start"],
+    "env": {}
+  }
+}
+```
 
-Teaches Claude when and how to use memory:
-- Search before writing/editing code
-- Store corrections and learning cycles
-- Apply preferences and patterns
+Global installation does **not** affect project scoping — project ID is still detected from Claude Code's working directory.
 
 ---
 
-## 🔐 Security & Privacy
+## Security & Privacy
 
-Claude Recall is built for local-first workflows:
+- SQLite memory never leaves your machine
+- No external services required
+- No prompts, code, or memory content is transmitted
+- Full transparency via CLI (`stats`, `search`, `export`)
+- Never stores secrets (API keys, passwords, tokens)
 
-* SQLite memory never leaves your machine
-* No external services required
-* No prompts, code, or memory content is transmitted
-* Full transparency via CLI (`list`, `inspect`, `export`)
-
-Full details in `/docs/security.md`.
+Details in [docs/security.md](docs/security.md).
 
 ---
 
-## 📚 Full Documentation
+## Documentation
 
-All docs in `/docs`:
+All docs in [`/docs`](docs/):
 
-* Installation
-* Quickstart
-* Architecture
-* Learning Loop
-* Memory Types
-* CLI Reference
-* Skills Integration
-* Project Scoping
-* Troubleshooting
-* Security
-* FAQ
+- [Installation](docs/installation.md)
+- [Quickstart](docs/quickstart.md)
+- [CLI Reference](docs/cli.md)
+- [Memory Types](docs/memory-types.md)
+- [Learning Loop](docs/learning-loop.md)
+- [Project Scoping](docs/project-scoping.md)
+- [Content Hashing](docs/content-hashing.md)
+- [Troubleshooting](docs/troubleshooting.md)
+- [Security](docs/security.md)
+- [FAQ](docs/faq.md)
 
 ---
 
-## 🛠 Development & Contributions
+## Development & Contributions
 
 PRs welcome — Claude Recall is open to contributors.
 
+```bash
+npm run build          # Compile TypeScript
+npm test               # Run all tests
+npm run test:watch     # Watch mode
+npm run mcp:dev        # Start MCP server in dev mode
+```
+
 ---
 
-## 📝 License
+## License
 
 MIT.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-recall",
-  "version": "0.11.2",
+  "version": "0.11.4",
   "description": "Persistent memory for Claude Code with native Skills integration, automatic capture, failure learning, and project scoping via MCP server",
   "main": "dist/index.js",
   "bin": {