claude-recall 0.8.3 → 0.8.5

package/README.md

@@ -15,216 +15,238 @@ Your preferences, project structure, workflows, corrections, and coding style ar
 
 ## 🚀 Features
 
-### **🌱 Continuous Learning (Local SQLite)**
+### 🌱 Continuous Learning (Local SQLite)
 
-* Learns your coding patterns, tool preferences, and corrections
-* Stores and evolves them in a local SQLite database
-* Claud Code automatically searches memory before performing actions
+Claude learns your:
 
-### **⚡ Realtime Memory Intelligence (PubNub Event Bus)**
+* coding patterns
+* tool preferences
+* corrections
+* architectural decisions
+* workflow habits
 
-Claude Recall uses a lightweight, metadata-only PubNub layer to enable **instant, asynchronous memory processing**:
+Everything stays **local**.
 
-* Hooks publish tool events and prompt metadata to PubNub channels
-* Memory Agent subscribes in real time
-* Processes events without blocking Claude
-* Suggests relevant memories back to Claude Code
+---
 
-This gives hooks **sub-10ms execution**, compared to 50–500ms with synchronous CLI pipelines.
+## ⚡ Realtime Memory Intelligence (PubNub Event Bus)
 
-> **No user text, code, or memory content is ever sent over PubNub.**
-> Only small metadata packets — tool names, file paths, event types, heartbeat signals.
+Claude Recall uses a lightweight, metadata-only PubNub layer to provide **instant, asynchronous memory intelligence**.
 
-### **📂 Project-Scoped Knowledge**
+### What PubNub enables
 
-Each project gets its own memory context:
+* **Hooks become <10ms**
+  Instead of slow, blocking MCP or CLI calls (50–500ms), hooks now publish a tiny packet and return instantly.
 
-* architecture
-* conventions
-* decisions
-* constraints
-* mistakes + corrections
-* coding preferences
-* tech stack
+* **The Memory Agent works in the background**
+  The Agent subscribes to PubNub channels, processes events in real time, updates memory, and sends suggestions back to Claude without slowing anything down.
 
-Switch projects → Claude switches memory.
+* **Claude stays fast and responsive**
+  Even under heavy editing or repeated tool runs.
 
-### **🔌 Zero Cloud Storage**
+### What PubNub actually carries (metadata-only)
 
-* All memory stays local
-* SQLite database in `~/.claude-recall/`
-* No telemetry
-* No remote sync
-* PubNub carries **ephemeral metadata only**
+* tool name
+* file path
+* event type
+* prompt token counts (no text)
+* memory suggestion IDs
+* Agent heartbeat
 
-### **💻 Claude Code–Native Integration**
+### What PubNub does *not* carry
 
-* MCP server automatically detected
-* Realtime memory suggestions
-* High-quality planning via Python hooks
-* Automatic search-before-edit behavior
+🚫 code
+🚫 conversation text
+🚫 file contents
+🚫 memory content
+🚫 embeddings
+🚫 prompts
+🚫 anything sensitive
+
+PubNub is **not** storage — it is a realtime coordination channel.
 
 ---
 
-## ⚡ Quick Start
+## 💬 Why use PubNub at all?
 
-### **Requirements**
+Developers often ask this. Here's the clear answer:
 
-| Component | Version                 | Notes                                 |
-| --------- | ----------------------- | ------------------------------------- |
-| Node.js   | **20+**                 | required for better-sqlite3           |
-| Python    | **3.x**                 | required for Claude Code hook scripts |
-| PubNub    | included via npm        | metadata-only usage                   |
-| OS        | macOS / Linux / Windows | WSL supported                         |
+### ✔ **Persistent memory doesn't require PubNub**
 
----
+The core idea (Claude remembering preferences and project knowledge) could be implemented with:
 
-### **Install (recommended: per project)**
+* direct MCP calls
+* local HTTP server
+* sockets / pipes
+* a local queue
+* synchronous CLI calls
 
-```bash
-cd your-project
-npm install claude-recall
-```
+### ✔ **But PubNub gives a dramatically better UX**
 
-Restart **Claude Code**.
+Without PubNub:
 
----
+* hooks block while waiting for the Memory Agent to finish
+* every file write/edit stalls Claude
+* the editor feels sluggish
+* memory suggestions arrive too late to help
+* cross-platform performance varies wildly
 
-### **Verify it's working**
+With PubNub:
 
-In Claude Code:
+* hooks return in **6–10ms**
+* memory is processed asynchronously
+* Claude gets suggestions in real time
+* no need to bundle/maintain a local broker
+* works the same on macOS, Windows, Linux, WSL
 
-> "Search my memories for preferences."
+### ✔ **Local-first design is preserved**
 
-Claude should call:
+PubNub only transmits metadata — no user content ever leaves your machine.
 
-```
-mcp__claude-recall__search
-```
+### ✔ **Implementation detail, not a hard dependency**
 
-If results appear → Claude Recall is active.
+In the future the event bus can be swapped (local-only transport, WebSockets, NATS, etc.).
+PubNub is simply the fastest path to a great developer experience today.
 
 ---
 
-## 🧠 How It Works
+## 📂 Project-Scoped Knowledge
 
-Claude Recall consists of **three integrated systems**:
+Each project gets its own memory namespace:
 
----
+* architecture
+* tech stack
+* conventions
+* past decisions
+* known pitfalls
+* previous fixes
+* preferences unique to that codebase
 
-### **1. The Memory Engine (SQLite, local)**
+Switch projects → Claude switches memory.
 
-Stores:
+---
 
-* preferences
-* project knowledge
-* coding style
-* corrections
-* workflow patterns
-* successes & failures
+## 🔌 Zero Cloud Storage
 
-Memory is structured, versioned, and evolves over time.
+* All memory stored locally in SQLite
+* No cloud sync
+* No telemetry
+* PubNub carries **ephemeral metadata only**
+* Entire system works offline (except realtime coordination)
 
 ---
 
-### **2. The Realtime Event Bus (PubNub)**
+## 💻 Claude Code–Native Integration
+
+Claude Recall integrates tightly via:
 
-A lightweight, metadata-only communication layer enabling **non-blocking hooks** and **fast memory updates**.
+* MCP server (search, store, evolve)
+* pre-action hooks
+* planning hooks
+* post-action hooks
+* PubNub event subscriber (Memory Agent)
 
-**Why PubNub?**
+Claude automatically searches memory before writing or editing files.
 
-* Hooks complete in <10ms
-* Memory Agent processes events asynchronously
-* Claude stays fast and responsive
-* Zero waiting on the MCP server
-* No user data transmitted
+---
 
-**Channels used:**
+## ⚡ Quick Start
 
-| Channel                 | Purpose                  | Payload (metadata only) |
-| ----------------------- | ------------------------ | ----------------------- |
-| `claude-tool-events`    | tool invocation metadata | tool name, file path    |
-| `claude-prompt-stream`  | prompt chunk events      | token counts, not text  |
-| `claude-memory-context` | memory suggestions       | memory IDs, confidence  |
-| `claude-presence`       | heartbeat & lifecycle    | agent online/offline    |
+### Requirements
 
-**Privacy guarantee:**
-No code, file contents, conversation text, or memory content is ever transmitted.
-Only minimal metadata.
+| Component | Version                 | Notes                          |
+| --------- | ----------------------- | ------------------------------ |
+| Node.js   | **20+**                 | required for better-sqlite3    |
+| Python    | **3.x**                 | required for Claude Code hooks |
+| PubNub    | included via npm        | metadata only                  |
+| OS        | macOS / Linux / Windows | WSL supported                  |
 
 ---
 
-### **3. Claude Code Hook System**
+### Install (per project)
+
+```bash
+cd your-project
+npm install claude-recall
+```
 
-Hooks enforce high-quality behavior:
+Restart **Claude Code**.
 
-**Pre-action:**
+---
 
-* Search memory
-* Provide context
-* Adjust plan
+### Verify it's working
 
-**Post-action:**
+In Claude Code:
 
-* Capture new learnings
-* Update or evolve memories
-* Suggest improvements through PubNub
+> "Search my memories."
 
-**Planning hook:**
+Claude should call:
 
-* High-quality reasoning
-* Structured decision making
-* Leverages stored knowledge
+```
+mcp__claude-recall__search
+```
+
+If results appear → You're ready.
 
 ---
 
-## 📚 Full Documentation
+## 🧠 How It Works (High-Level)
+
+Claude Recall consists of:
+
+### 1. Local Memory Engine (SQLite)
+
+Stores and evolves preferences, patterns, decisions, corrections.
+
+### 2. Realtime Event Bus (PubNub)
+
+Makes hooks fast and enables the Memory Agent to work asynchronously.
+
+### 3. Memory Agent
 
-Detailed docs live in the `docs/` folder:
-
-| Topic                      | File                      |
-| -------------------------- | ------------------------- |
-| Installation               | `docs/installation.md`    |
-| 5-minute Quickstart        | `docs/quickstart.md`      |
-| Architecture (with PubNub) | `docs/architecture.md`    |
-| The Learning Loop          | `docs/learning-loop.md`   |
-| Memory Types               | `docs/memory-types.md`    |
-| CLI Reference              | `docs/cli.md`             |
-| Hooks Documentation        | `docs/hooks.md`           |
-| Project Scoping            | `docs/project-scoping.md` |
-| Troubleshooting            | `docs/troubleshooting.md` |
-| Security & Privacy         | `docs/security.md`        |
-| FAQ                        | `docs/faq.md`             |
+Subscribes to PubNub, updates memory, sends suggestions to Claude.
+
+### 4. Claude Code Hooks
+
+Inject memory pre-action, perform structured planning, capture post-action learnings.
 
 ---
 
 ## 🔐 Security & Privacy
 
-Claude Recall is a **local-first**, privacy-focused system.
+Claude Recall is built for local-first workflows:
 
-* All memory stored locally in SQLite
-* PubNub used only for ephemeral event metadata
-* No user data, code, or conversation text leaves your machine
-* No cloud sync
-* No telemetry
-* You control your entire memory set
-* Easy export/inspect/delete through CLI
+* SQLite memory never leaves your machine
+* PubNub sends metadata only
+* No storage of PubNub messages
+* No prompts, code, or memory content is transmitted
+* Full transparency via CLI (`list`, `inspect`, `export`)
 
-Full security notes: `docs/security.md`.
+Full details in `/docs/security.md`.
 
 ---
 
-## 🛠 Development
+## 📚 Full Documentation
+
+All docs in `/docs`:
 
-PRs welcome — see `CONTRIBUTING.md` (optional).
-Local development uses the Memory Agent + PubNub + SQLite.
+* Installation
+* Quickstart
+* Architecture
+* Learning Loop
+* Memory Types
+* CLI Reference
+* Hooks
+* Project Scoping
+* Troubleshooting
+* Security
+* FAQ
 
 ---
 
-## ❤️ Community
+## 🛠 Development & Contributions
 
-Issues and feedback are welcome.
-Claude Recall is evolving rapidly — your input shapes it.
+PRs welcome — Claude Recall is open to contributors.
 
 ---
 

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.3",
+  "version": "0.8.5",
   "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": {