@colbymchenry/cmem 0.2.37 → 0.5.2

package/.claude-plugin/plugin.json

@@ -0,0 +1,17 @@
+{
+  "name": "cmem",
+  "version": "0.4.0",
+  "description": "Self-learning memory for Claude Code. Never lose a conversation.",
+  "author": {
+    "name": "Colby McHenry",
+    "url": "https://github.com/colbymchenry"
+  },
+  "homepage": "https://github.com/colbymchenry/cmem",
+  "repository": "https://github.com/colbymchenry/cmem",
+  "license": "MIT",
+  "keywords": ["memory", "learning", "sessions", "knowledge"],
+  "commands": "../commands/",
+  "skills": "../skills/",
+  "hooks": "../hooks/hooks.json",
+  "mcpServers": "../.mcp.json"
+}

package/.mcp.json

@@ -0,0 +1,11 @@
+{
+  "mcpServers": {
+    "cmem": {
+      "command": "node",
+      "args": ["dist/mcp/server.js"],
+      "env": {
+        "CMEM_DATA_DIR": "~/.cmem"
+      }
+    }
+  }
+}

package/README.md

@@ -2,11 +2,11 @@
 
 # 🧠 cmem
 
-### Your Claude Code Conversations, Remembered Forever
+### Self-Learning Memory for Claude Code
 
-**Don't just explore your code or folders—explore your conversations, or pick up where you left off.**
+**Never lose a conversation. Claude learns from every session.**
 
-**Semantic search • Organize by project • Favorite conversations • 100% local**
+**Semantic search • Auto-synthesis • Knowledge injection • Web GUI • 100% local**
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Node.js](https://img.shields.io/badge/Node.js-18+-green.svg)](https://nodejs.org/)
@@ -25,9 +25,35 @@ npx @colbymchenry/cmem
 
 ---
 
-Ever closed your terminal and lost that perfect Claude conversation? The one where you finally figured out that tricky bug, or designed that elegant architecture?
+## Stop Writing Markdown Files
 
-**cmem** gives Claude Code a long-term memory. Every conversation is automatically saved, indexed, and searchable—so you (and Claude) can pick up right where you left off.
+Everyone tries to solve Claude's memory problem the same way: **manually writing markdown files**. `CLAUDE.md`, `ARCHITECTURE.md`, decision logs, convention docs...
+
+It's tedious. It's incomplete. And you forget to update them.
+
+**cmem takes a different approach.** Instead of *you* documenting everything, cmem watches your conversations and *automatically* extracts the knowledge Claude needs. Architecture decisions, bug patterns, project conventions, anti-patterns—all captured naturally as you work.
+
+Think of it like giving Claude a **notebook for each project**. Every conversation adds notes. When Claude needs to answer a question, it semantically searches this organized, efficient knowledge base—finding exactly the right context without you lifting a finger.
+
+> **Traditional approach:** You manually write docs → Claude reads them → Docs aren't detailed enough so Claude explores anyway → You forget to update → Outdated docs lead to bad suggestions
+>
+> **cmem approach:** You just code → cmem learns from every session → Knowledge stays current and detailed → Claude gives informed answers instantly
+
+---
+
+## What is cmem?
+
+**cmem** is a self-learning memory system for Claude Code. It:
+
+1. **Backs up every conversation** — Never lose work, even if Claude clears storage
+2. **Learns from your sessions** — Auto-extracts lessons about your projects
+3. **Injects relevant knowledge** — Claude starts each conversation with context about your codebase
+4. **Searches your history** — Find past conversations by meaning, not keywords
+5. **Rename and favorite sessions** - Never lose those valuable sessions between you and Claude
+6. **View all sessions by project** - Organized chat sessions by what project you were working on
+7. **Web GUI** — Manage learned knowledge through a beautiful interface
+
+---
 
 ### MCP Integration
 
@@ -51,20 +77,68 @@ Ever closed your terminal and lost that perfect Claude conversation? The one whe
 
 ![Open all sessions in current directory](https://github.com/user-attachments/assets/3783343c-815c-47ba-a6da-fb96cb25ee1b)
 
+---
+
+## Web GUI
+
+Manage your learned knowledge through a clean web interface.
+
+![GUI](https://github.com/user-attachments/assets/70f0d89b-6e1e-4f3e-bada-185197d226e8)
+
+```bash
+cmem gui
+```
+
+**Features:**
+- Browse all lessons by project and category
+- Edit, archive, or delete lessons
+- View confidence scores and usage stats
+- Create lessons manually
+- Filter by category (architecture, bugs, conventions, etc.)
+
+## Features
+
+### 📚 Self-Learning Knowledge Base
+
+cmem automatically extracts reusable lessons from your conversations:
+- **Architecture decisions** and their rationale
+- **Anti-patterns** — what NOT to do and why
+- **Bug patterns** — common issues and root causes
+- **Project conventions** — code style, naming, organization
+- **Dependency knowledge** — library quirks, version issues
+- **Domain knowledge** — business logic, requirements
+
+<img width="848" height="348" alt="PNG image" src="https://github.com/user-attachments/assets/f3abd9b0-0efa-4da8-a668-cb8d7532b24c" />
+
+These lessons are automatically surfaced when relevant to your current task
+
+### 🔍 Semantic Search
 
-## Why cmem?
+Find conversations by meaning, not keywords. "That React hooks discussion" or "the database migration plan" just works.
 
-🧠 **Sub-Agent Summarization** — When Claude needs context from past sessions, cmem spawns a separate Claude instance to read and synthesize—keeping your main conversation context clean. Just like Explore agents, but for your conversation history.
+### 🤖 Claude Remembers
 
-🔍 **Semantic Search** — Find conversations by meaning, not keywords. "That React hooks discussion" or "the database migration plan" just works.
+Via MCP integration, Claude can search your past conversations and learned knowledge:
+- "What did we decide about auth last week?"
+- "How do we handle errors in this project?"
+- "What's the convention for API endpoints?"
 
-🤖 **Claude Can Remember** — Via MCP integration, Claude can search your past conversations. "What did we decide about auth last week?" Finally, context that persists.
+### 💾 Automatic Backup
 
-🔄 **Automatic Sync** — A background daemon watches your Claude Code sessions and keeps everything indexed in real-time.
+Every conversation is backed up to `~/.cmem/backups/`. Even if Claude Code clears its storage, cmem restores your sessions instantly.
 
-💾 **Never Lost** — Every conversation is automatically backed up. Even if Claude Code clears its storage, cmem restores your sessions instantly when you resume them.
+### 🪝 Hook-Based Integration
 
-📦 **100% Local & Private** — Everything runs on your machine. No cloud services, no API keys, no external servers. Just SQLite + local AI embeddings.
+cmem integrates with Claude Code via hooks (no background daemon):
+- **UserPromptSubmit** — Injects relevant lessons before Claude responds
+- **Stop/PreCompact** — Syncs and backs up sessions automatically
+
+### 📦 100% Local & Private
+
+Everything runs on your machine:
+- SQLite database with vector embeddings
+- Local AI embeddings (nomic-embed-text-v1.5)
+- No cloud services, no API keys required
 
 ## Quick Start
 
@@ -75,16 +149,16 @@ npx @colbymchenry/cmem
 The setup wizard will:
 1. Install `cmem` globally
 2. Download the embedding model (~130MB, one-time)
-3. Optionally set up auto-sync on login (macOS)
-4. Configure MCP server in `~/.claude.json` + permissions in `~/.claude/settings.json`
+3. Configure MCP server in Claude Code
+4. Set up hooks for automatic sync and learning
+5. Clean up any old daemon from previous versions
 
-That's it. Your conversations are now being remembered.
+**Upgrading?** Just run the same command — it handles everything automatically.
 
 ## Requirements
 
 - **Node.js 18+**
-
-No other dependencies. The AI embedding model downloads automatically on first use and runs entirely in Node.js.
+- **Claude Code CLI** (for synthesis features)
 
 ## Usage
 
@@ -92,78 +166,68 @@ No other dependencies. The AI embedding model downloads automatically on first u
 cmem                    # Browse sessions in beautiful TUI
 cmem --local            # Browse sessions from current folder only
 cmem search "query"     # Semantic search across all conversations
-cmem watch              # Start the sync daemon
+cmem synthesize         # Extract lessons from queued sessions
+cmem gui                # Launch web-based lesson management UI
 cmem stats              # See what's stored
 ```
 
-## How It Works
+## MCP Tools
 
-```
-Claude Code sessions → cmem watch daemon → SQLite + Vector DB
-                                                ↓
-                              Claude Code ← MCP Server ← Semantic Search
-```
+Claude Code gains these abilities:
+
+| Tool | Description |
+|------|-------------|
+| `search_and_summarize` | AI-synthesized answers from past sessions |
+| `search_sessions` | Find sessions by semantic similarity |
+| `search_lessons` | Find learned knowledge for current project |
+| `save_lesson` | Manually save important knowledge |
+| `validate_lesson` | Mark a lesson as helpful (boosts confidence) |
+| `reject_lesson` | Mark a lesson as wrong (reduces confidence) |
+| `list_lessons` | Browse all lessons for a project |
+| `list_sessions` | Browse recent sessions |
+| `get_session` | Retrieve full conversation history |
 
-1. **Watch**: The daemon monitors `~/.claude/` for new/changed sessions
-2. **Index**: Conversations are parsed and embedded locally using `nomic-embed-text-v1.5`
-3. **Search**: Query by meaning using vector similarity
-4. **Remember**: Claude can access past conversations via MCP tools
+## How It Works
 
-### Background Daemon
+### Knowledge Injection (Hooks)
 
-The `cmem watch` daemon runs in the background and automatically syncs your Claude Code sessions:
+When you send a prompt to Claude:
 
-- **With daemon installed**: Sessions sync automatically whenever you use Claude Code
-- **Without daemon**: Run `cmem watch` manually, or sessions sync when you open the TUI
+1. **UserPromptSubmit hook** triggers
+2. cmem searches for relevant lessons
+3. Matching lessons are injected as `<project_knowledge>`
+4. Claude sees this context before responding
 
-On macOS, you can install the daemon to start automatically on login:
-```bash
-cmem install    # Enable auto-start
-cmem uninstall  # Disable auto-start
-```
+### Session Sync (Hooks)
 
-## MCP Tools
+When a session ends or compacts:
 
-Once configured, Claude Code gains these abilities:
+1. **Stop/PreCompact hook** triggers
+2. cmem parses and indexes the session
+3. Session is backed up to `~/.cmem/backups/`
+4. Session is queued for lesson extraction
 
-| Tool | What it does |
-|------|--------------|
-| `search_and_summarize` | **The star feature** — Ask a question, get an AI-synthesized answer from past sessions |
-| `search_sessions` | Find sessions by semantic similarity |
-| `list_sessions` | Browse recent sessions |
-| `get_session` | Retrieve full conversation history |
-| `get_session_context` | Get context to continue a past conversation |
+### Lesson Synthesis
 
-### How `search_and_summarize` Works
+Sessions in the queue are processed by the synthesis engine:
 
+```bash
+cmem synthesize        # Process pending sessions
+cmem synthesize -s     # Show queue status
 ```
-Main Claude Session                          cmem MCP Server
-       │                                            │
-       │  "What did we decide about auth?"          │
-       ├───────────────────────────────────────────►│
-       │                                            │
-       │                                   ┌────────┴────────┐
-       │                                   │ 1. Vector search │
-       │                                   │ 2. Find sessions │
-       │                                   │ 3. Read content  │
-       │                                   └────────┬────────┘
-       │                                            │
-       │                                   ┌────────┴────────┐
-       │                                   │ Spawn Claude CLI │
-       │                                   │ (sub-agent)      │
-       │                                   │                  │
-       │                                   │ Reads sessions,  │
-       │                                   │ synthesizes      │
-       │                                   │ answer           │
-       │                                   └────────┬────────┘
-       │                                            │
-       │  "Based on your Jan 15 session, you       │
-       │   decided to use JWT with refresh..."      │
-       │◄───────────────────────────────────────────┤
-       │                                            │
-```
 
-This keeps your main context clean—only the concise summary comes back, not the raw session content. Uses Haiku by default for speed, configurable to Sonnet or Opus.
+The synthesis engine uses Claude (via CLI) to analyze sessions and extract reusable lessons.
+
+## Lesson Confidence System
+
+Each lesson has a confidence score (0-100%):
+
+- **Synthesized lessons** start at 30-70% based on evidence
+- **Manual lessons** start at 60%
+- **Validation** boosts confidence by 10%
+- **Rejection** reduces confidence by 20%
+- **Very low confidence** lessons are auto-archived
+- **Unused lessons** decay over time
 
 ## Commands
 
@@ -175,28 +239,12 @@ This keeps your main context clean—only the concise summary comes back, not th
 | `cmem search <query>` | Semantic search |
 | `cmem list` | List all sessions |
 | `cmem restore <id>` | Output session context |
-| `cmem watch` | Start sync daemon |
-| `cmem install` | Auto-start daemon on login (macOS) |
-| `cmem uninstall` | Remove auto-start |
+| `cmem synthesize` | Extract lessons from queue |
+| `cmem synthesize -s` | Show synthesis queue status |
+| `cmem gui` | Launch web-based lesson management UI |
 | `cmem stats` | Storage statistics |
 | `cmem mcp` | Start MCP server |
 
-## TUI Views
-
-### Global Tab
-All your sessions in one place, smart-sorted into three tiers:
-1. **Starred sessions** — Your favorites, sorted by message count
-2. **Named sessions** — Custom-named conversations, sorted by message count
-3. **Everything else** — Sorted by message count
-
-Press `s` to star/unstar a session.
-
-### Projects Tab
-Browse sessions organized by project folder.
-- Press `Enter` to drill into a project's sessions
-- Press `s` to enter **sort mode** — use `↑/↓` to reorder, `Enter` to confirm
-- Custom project order is persisted
-
 ## TUI Keyboard Shortcuts
 
 | Key | Action |
@@ -215,18 +263,52 @@ Browse sessions organized by project folder.
 ## Data Storage
 
 All data is stored locally in `~/.cmem/`:
-- `sessions.db` — SQLite database with vector embeddings
-- `models/` — Downloaded embedding model (~130MB)
-- `backups/` — Full copies of all conversation JSONLs (auto-restored if Claude deletes them)
 
-Claude Code sessions are read from `~/.claude/`.
+```
+~/.cmem/
+├── sessions.db      # SQLite database (sessions, lessons, embeddings)
+├── models/          # Downloaded embedding model (~130MB)
+└── backups/         # Full copies of all conversation JSONLs
+```
+
+## Plugin Architecture
+
+cmem is designed as a Claude Code plugin:
+
+```
+.claude-plugin/
+├── plugin.json      # Plugin manifest
+commands/
+├── cmem.md          # /cmem slash command
+skills/
+└── memory-search/
+    └── SKILL.md     # Memory search skill
+hooks/
+└── hooks.json       # UserPromptSubmit, Stop, PreCompact hooks
+.mcp.json            # MCP server configuration
+```
 
 ## Tech Stack
 
 - **SQLite** + **sqlite-vec** — Embedded vector database
-- **transformers.js** + **nomic-embed-text-v1.5** — Local AI embeddings (768 dimensions, runs in Node.js)
+- **transformers.js** + **nomic-embed-text-v1.5** — Local AI embeddings
 - **ink** — Beautiful terminal UI (React for CLI)
+- **React** + **Vite** + **Tailwind** — Web GUI
 - **MCP** — Model Context Protocol for Claude integration
+- **Claude Code Hooks** — Event-driven integration (no daemon)
+
+## Upgrading from Previous Versions
+
+If you're upgrading from a version that used the background daemon:
+
+```bash
+npx @colbymchenry/cmem
+```
+
+The setup wizard will:
+- Automatically stop and remove the old daemon
+- Configure the new hook-based system
+- Your existing sessions and data are preserved
 
 ## License
 
@@ -235,6 +317,6 @@ MIT
 ---
 
 <p align="center">
-  <b>Stop losing your best conversations.</b><br>
+  <b>Stop losing your best conversations. Start learning from them.</b><br>
   <code>npx @colbymchenry/cmem</code>
 </p>

package/commands/cmem.md

@@ -0,0 +1,8 @@
+---
+description: Browse and manage Claude Code memory
+disable-model-invocation: true
+---
+
+Launch the CMEM terminal interface to browse sessions and manage learned knowledge.
+
+Execute: !node ${CLAUDE_PLUGIN_ROOT}/dist/cli.js $ARGUMENTS