memctx 1.0.0 → 1.0.2

package/README.md

@@ -1,227 +1,484 @@
-# ClaudeContext
+<div align="center">
 
-> Autonomous session memory for Claude Code
+# 🧠 MemCTX
 
-ClaudeContext automatically captures, analyzes, and summarizes your Claude Code sessions, providing intelligent context injection and a beautiful dashboard to track your development history.
+### Autonomous Session Memory for Claude Code
 
-## Features
+*Never lose context. Never repeat yourself. Your AI pair programmer, now with perfect memory.*
 
-- 🧠 **Automatic Session Tracking** - Captures every Claude Code session automatically
-- 🤖 **AI-Powered Summaries** - Generates structured summaries with what you did, next steps, and gotchas
-- 📊 **Beautiful Dashboard** - Modern UI to browse sessions, search history, and view metrics
-- 🔍 **Full-Text Search** - Search across all your sessions and conversations
-- 📈 **Live Monitoring** - Real-time view of active sessions
-- 🎯 **Smart Context Injection** - Automatically injects relevant session history into new sessions
-- 🏷️ **Tags & Bookmarks** - Organize sessions with tags and bookmarks
-- 📝 **Session Notes** - Add custom notes to any session
-- 🌓 **Dark/Light Theme** - Beautiful themes for any preference
+[![npm version](https://img.shields.io/npm/v/memctx.svg?style=for-the-badge&logo=npm&color=CB3837)](https://www.npmjs.com/package/memctx)
+[![npm downloads](https://img.shields.io/npm/dm/memctx.svg?style=for-the-badge&logo=npm&color=CB3837)](https://www.npmjs.com/package/memctx)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=for-the-badge)](https://opensource.org/licenses/MIT)
+[![Node Version](https://img.shields.io/node/v/memctx.svg?style=for-the-badge&logo=node.js&color=339933)](https://nodejs.org)
 
-## Installation
+[🚀 Quick Start](#-quick-start) • [📖 Documentation](#-documentation) • [✨ Features](#-features) • [🎯 Demo](#-demo) • [💬 Community](#-community)
+
+<img src="https://raw.githubusercontent.com/bbhunterpk-ux/memctx/main/assets/hero.png" alt="MemCTX Dashboard" width="800" />
+
+</div>
+
+---
+
+## 🎯 What is MemCTX?
+
+MemCTX transforms Claude Code into a **context-aware development companion** by automatically capturing, analyzing, and intelligently injecting your development history. Think of it as giving Claude a **photographic memory** of your entire project journey.
+
+<table>
+<tr>
+<td width="50%">
+
+### 😫 Before MemCTX
+- ❌ Repeat context every session
+- ❌ Lost conversation history
+- ❌ Manual session notes
+- ❌ Forgotten decisions
+- ❌ Context switching overhead
+
+</td>
+<td width="50%">
+
+### ✨ With MemCTX
+- ✅ Automatic context injection
+- ✅ Searchable session history
+- ✅ AI-powered summaries
+- ✅ Decision tracking
+- ✅ Seamless continuity
+
+</td>
+</tr>
+</table>
+
+---
+
+## ✨ Features
+
+<table>
+<tr>
+<td width="33%" align="center">
+
+### 🧠 Smart Memory
+Automatically captures every Claude Code session with full context preservation
+
+</td>
+<td width="33%" align="center">
+
+### 🤖 AI Summaries
+Claude analyzes each session and generates structured summaries with key insights
+
+</td>
+<td width="33%" align="center">
+
+### 📊 Beautiful Dashboard
+Modern, responsive UI to browse, search, and analyze your development history
+
+</td>
+</tr>
+<tr>
+<td width="33%" align="center">
+
+### 🔍 Full-Text Search
+Lightning-fast search across all sessions, conversations, and code snippets
+
+</td>
+<td width="33%" align="center">
+
+### 📈 Live Monitoring
+Real-time view of active sessions with WebSocket updates
+
+</td>
+<td width="33%" align="center">
+
+### 🎯 Context Injection
+Automatically injects relevant history into new sessions for perfect continuity
+
+</td>
+</tr>
+<tr>
+<td width="33%" align="center">
+
+### 🏷️ Tags & Bookmarks
+Organize sessions with custom tags and bookmark important moments
+
+</td>
+<td width="33%" align="center">
+
+### 📝 Session Notes
+Add custom notes and annotations to any session
+
+</td>
+<td width="33%" align="center">
+
+### 🌓 Dark/Light Theme
+Beautiful themes that adapt to your preference
+
+</td>
+</tr>
+</table>
+
+---
+
+## 🚀 Quick Start
+
+<details open>
+<summary><b>📦 Installation</b></summary>
 
 ```bash
 # Install globally with npm
-npm install -g claudectx
+npm install -g memctx
 
-# Or with pnpm
-pnpm add -g claudectx
+# Or with pnpm (recommended)
+pnpm add -g memctx
 
 # Or with yarn
-yarn global add claudectx
+yarn global add memctx
 ```
 
-## Quick Start
+</details>
+
+<details open>
+<summary><b>⚡ Setup (30 seconds)</b></summary>
 
 ```bash
-# Install and setup hooks
-claudectx install
+# 1. Install and configure hooks
+memctx install
 
-# Start the service
-claudectx start
+# 2. Start the service
+memctx start
 
-# Open the dashboard
-claudectx open
+# 3. Open the dashboard
+memctx open
 ```
 
-That's it! ClaudeContext will now automatically capture all your Claude Code sessions.
+**That's it!** MemCTX is now capturing your Claude Code sessions automatically. 🎉
 
-## Requirements
+</details>
 
-- **Node.js** 18.0.0 or higher
-- **Claude Code** CLI installed
-- **Build tools** for native dependencies:
-  - Linux: `build-essential`, `python3`
-  - macOS: Xcode Command Line Tools
-  - Windows: Visual Studio Build Tools
-
-## Configuration
+<details>
+<summary><b>🔧 Configuration</b></summary>
 
 ### Settings Dashboard (Recommended)
 
-The easiest way to configure ClaudeContext is through the Settings page in the dashboard:
-
-1. Open `http://localhost:9999/settings`
-2. Configure your preferences:
-   - **API Provider**: Direct (Anthropic) or Proxy (9router, etc.)
-   - **API Key**: Your Anthropic or proxy API key
-   - **Base URL**: Custom proxy endpoint (if using proxy)
-   - **Model**: Choose Claude Opus, Sonnet, Haiku, or AWS default
-   - **Disable Summaries**: Toggle to save API costs
-3. Click "Save Settings"
-4. Restart worker: `claudectx restart`
+Open `http://localhost:9999/settings` and configure:
 
-Settings are saved to `~/.claudectx/settings.json` and persist across restarts.
+- **API Provider**: Direct (Anthropic) or Proxy (9router, etc.)
+- **API Key**: Your Anthropic or proxy API key
+- **Model**: Choose Claude Opus, Sonnet, Haiku, or AWS default
+- **Disable Summaries**: Toggle to save API costs
 
 ### Environment Variables (Alternative)
 
-You can also configure via environment variables:
-
 ```bash
 # Required for AI summaries
 export ANTHROPIC_API_KEY="sk-ant-..."
 
-# Optional: Use proxy (like 9router)
+# Optional: Use proxy
 export ANTHROPIC_BASE_URL="https://your-proxy.com/v1"
 
 # Optional: Custom port (default: 9999)
-export CLAUDECTX_PORT=8080
+export MEMCTX_PORT=8080
 
 # Optional: Custom database location
-export CLAUDECTX_DB_PATH="/path/to/db.sqlite"
-
-# Optional: Number of sessions to inject (default: 3)
-export CLAUDECTX_CONTEXT_SESSIONS=5
+export MEMCTX_DB_PATH="/path/to/db.sqlite"
 ```
 
-**Configuration Priority:** Settings Dashboard > Environment Variables > Defaults
+</details>
 
-### Configuration Files
+---
 
-ClaudeContext stores its data in `~/.claudectx/`:
+## 💻 CLI Commands
+
+<table>
+<tr>
+<th width="30%">Command</th>
+<th width="70%">Description</th>
+</tr>
+<tr>
+<td><code>memctx install</code></td>
+<td>Install hooks and start daemon</td>
+</tr>
+<tr>
+<td><code>memctx start</code></td>
+<td>Start the worker daemon</td>
+</tr>
+<tr>
+<td><code>memctx stop</code></td>
+<td>Stop the worker daemon</td>
+</tr>
+<tr>
+<td><code>memctx restart</code></td>
+<td>Restart the worker daemon</td>
+</tr>
+<tr>
+<td><code>memctx status</code></td>
+<td>Show daemon status and health check</td>
+</tr>
+<tr>
+<td><code>memctx open</code></td>
+<td>Open dashboard in browser</td>
+</tr>
+<tr>
+<td><code>memctx search &lt;query&gt;</code></td>
+<td>Search sessions from terminal</td>
+</tr>
+<tr>
+<td><code>memctx export</code></td>
+<td>Export all sessions as markdown</td>
+</tr>
+<tr>
+<td><code>memctx config</code></td>
+<td>Show configuration</td>
+</tr>
+<tr>
+<td><code>memctx uninstall</code></td>
+<td>Remove hooks and stop daemon</td>
+</tr>
+</table>
 
-```
-~/.claudectx/
-├── db.sqlite          # Session database
-├── settings.json      # User preferences (API key, model, etc.)
-├── hooks/             # Claude Code hooks
-└── logs/              # Service logs
-```
+---
 
-## CLI Commands
+## 🎯 Demo
 
-```bash
-# Installation & Setup
-claudectx install      # Install hooks and start daemon
-claudectx uninstall    # Remove hooks and stop daemon
-
-# Service Management
-claudectx start        # Start the worker daemon
-claudectx stop         # Stop the worker daemon
-claudectx restart      # Restart the worker daemon
-claudectx status       # Show daemon status and health
-
-# Usage
-claudectx open         # Open dashboard in browser
-claudectx search <query>  # Search sessions from terminal
-claudectx export       # Export all sessions as markdown
-claudectx config       # Show configuration
-
-# Options
---port <number>        # Set custom port
---api-key <key>        # Set Anthropic API key
---sessions <number>    # Number of sessions to inject
+<div align="center">
+
+### Dashboard Overview
+
+<img src="https://raw.githubusercontent.com/bbhunterpk-ux/memctx/main/assets/dashboard.png" alt="Dashboard" width="800" />
+
+### Session Details
+
+<img src="https://raw.githubusercontent.com/bbhunterpk-ux/memctx/main/assets/session-detail.png" alt="Session Detail" width="800" />
+
+### Search & Filter
+
+<img src="https://raw.githubusercontent.com/bbhunterpk-ux/memctx/main/assets/search.png" alt="Search" width="800" />
+
+</div>
+
+---
+
+## 🏗️ How It Works
+
+```mermaid
+graph LR
+    A[Claude Code CLI] -->|Hooks| B[MemCTX Worker]
+    B -->|Store| C[SQLite Database]
+    B -->|Summarize| D[Anthropic API]
+    D -->|AI Summary| C
+    C -->|Serve| E[React Dashboard]
+    B -->|Inject Context| F[CLAUDE.md]
+    F -->|Auto-load| A
+    
+    style A fill:#4A90E2
+    style B fill:#50C878
+    style C fill:#FFB347
+    style D fill:#9B59B6
+    style E fill:#E74C3C
+    style F fill:#3498DB
 ```
 
-## Dashboard
+<details>
+<summary><b>📋 Detailed Flow</b></summary>
+
+1. **Session Start**: Claude Code session begins → `session-start` hook fires
+2. **Capture**: MemCTX worker creates session record in SQLite
+3. **Observe**: Every tool use is captured via `post-tool-use` hook
+4. **End**: Session ends → `stop` hook fires
+5. **Summarize**: Worker sends transcript to Claude for AI analysis
+6. **Store**: Summary stored in database
+7. **Inject**: Next session auto-loads relevant context from `CLAUDE.md`
+8. **Browse**: View everything in the beautiful dashboard
+
+</details>
+
+---
+
+## 📖 Documentation
+
+<table>
+<tr>
+<td width="50%">
+
+### 📚 For Users
+- [Installation Guide](https://memctx.dev/docs/installation)
+- [Configuration](https://memctx.dev/docs/configuration)
+- [CLI Reference](https://memctx.dev/docs/cli)
+- [Dashboard Guide](https://memctx.dev/docs/dashboard)
+- [Troubleshooting](https://memctx.dev/docs/troubleshooting)
+
+</td>
+<td width="50%">
 
-Access the dashboard at `http://localhost:9999` (or your custom port).
+### 🛠️ For Developers
+- [Architecture](https://memctx.dev/docs/architecture)
+- [API Reference](https://memctx.dev/docs/api)
+- [Contributing Guide](https://github.com/bbhunterpk-ux/memctx/blob/main/CONTRIBUTING.md)
+- [Development Setup](https://memctx.dev/docs/development)
+- [Plugin System](https://memctx.dev/docs/plugins)
 
-### Pages
+</td>
+</tr>
+</table>
 
-- **Projects** - View all projects and their sessions
-- **Search** - Full-text search across all sessions
-- **Live** - Real-time monitoring of active sessions
-- **Metrics** - System performance and statistics
-- **Logs** - View service logs
-- **Settings** - Configure API provider, model, and preferences
+---
+
+## 🔧 Requirements
+
+<table>
+<tr>
+<td width="50%">
 
-### Features
+### System Requirements
+- **Node.js**: 18.0.0 or higher
+- **Claude Code**: CLI installed
+- **OS**: Linux, macOS, or Windows (WSL)
 
-- **Session Details** - View full conversation history, summaries, and observations
-- **Tags** - Create and assign tags to organize sessions
-- **Bookmarks** - Mark important sessions for quick access
-- **Notes** - Add custom notes to any session
-- **Archive** - Archive old sessions to declutter
-- **Export** - Export sessions as markdown or screenshots
-- **Keyboard Shortcuts** - Press `?` to see all shortcuts
+</td>
+<td width="50%">
 
-## How It Works
+### Build Tools (for installation)
+- **Linux**: `build-essential`, `python3`
+- **macOS**: Xcode Command Line Tools
+- **Windows**: Visual Studio Build Tools
 
-1. **Hooks** - ClaudeContext registers hooks in `~/.claude/settings.json` that trigger on session events
-2. **Worker** - A background service captures session data and stores it in SQLite
-3. **AI Summarization** - When a session ends, Claude analyzes it and generates a structured summary
-4. **Context Injection** - On new sessions, relevant history is automatically injected into `CLAUDE.md`
-5. **Dashboard** - A React app provides a beautiful interface to browse and search your history
+</td>
+</tr>
+</table>
 
-## Architecture
+<details>
+<summary><b>🔨 Installing Build Tools</b></summary>
 
+**Linux (Ubuntu/Debian):**
+```bash
+sudo apt install build-essential python3
 ```
-┌─────────────────┐
-│  Claude Code    │
-│   (CLI/IDE)     │
-└────────┬────────┘
-         │ hooks
-         ▼
-┌─────────────────┐
-│ ClaudeContext   │
-│    Worker       │◄──── WebSocket ────┐
-│  (Node.js)      │                    │
-└────────┬────────┘                    │
-         │                             │
-         ▼                             │
-┌─────────────────┐          ┌────────┴────────┐
-│   SQLite DB     │          │   Dashboard     │
-│  (Sessions)     │          │   (React)       │
-└─────────────────┘          └─────────────────┘
+
+**macOS:**
+```bash
+xcode-select --install
 ```
 
-## Troubleshooting
+**Windows:**
+Install [Visual Studio Build Tools](https://visualstudio.microsoft.com/downloads/#build-tools-for-visual-studio-2022)
+
+</details>
+
+---
+
+## 🎨 Dashboard Features
+
+<table>
+<tr>
+<td width="33%" align="center">
+
+### 📊 Projects View
+Browse all projects and their sessions organized by directory
+
+</td>
+<td width="33%" align="center">
+
+### 🔍 Search
+Full-text search with filters, tags, and date ranges
+
+</td>
+<td width="33%" align="center">
 
-### Service won't start
+### 📈 Live Monitor
+Real-time view of active sessions with WebSocket updates
+
+</td>
+</tr>
+<tr>
+<td width="33%" align="center">
+
+### 📝 Session Details
+View full conversation history, summaries, and observations
+
+</td>
+<td width="33%" align="center">
+
+### 🏷️ Tags & Notes
+Organize with custom tags and add notes to sessions
+
+</td>
+<td width="33%" align="center">
+
+### 📊 Metrics
+System performance, API usage, and statistics
+
+</td>
+</tr>
+<tr>
+<td width="33%" align="center">
+
+### 🌓 Themes
+Beautiful dark and light themes
+
+</td>
+<td width="33%" align="center">
+
+### ⌨️ Shortcuts
+Keyboard shortcuts for power users (press `?`)
+
+</td>
+<td width="33%" align="center">
+
+### 📤 Export
+Export sessions as markdown or screenshots
+
+</td>
+</tr>
+</table>
+
+---
+
+## 🚨 Troubleshooting
+
+<details>
+<summary><b>Service won't start</b></summary>
 
 ```bash
 # Check if port is in use
 lsof -i :9999
 
 # Check logs
-tail -f /tmp/claudectx.log
+tail -f /tmp/memctx.log
 
 # Restart service
-claudectx restart
+memctx restart
 ```
 
-### Hooks not working
+</details>
+
+<details>
+<summary><b>Hooks not working</b></summary>
 
 ```bash
 # Verify hooks are registered
-cat ~/.claude/settings.json | grep claudectx
+cat ~/.claude/settings.json | grep memctx
 
 # Reinstall hooks
-claudectx uninstall
-claudectx install
+memctx uninstall
+memctx install
 ```
 
-### SQLite compilation errors
+</details>
+
+<details>
+<summary><b>SQLite compilation errors</b></summary>
 
 ```bash
 # Rebuild native modules
 npm rebuild better-sqlite3
 
 # Or reinstall
-npm uninstall -g claudectx
-npm install -g claudectx
+npm uninstall -g memctx
+npm install -g memctx
 ```
 
-### AI summaries not working
+</details>
+
+<details>
+<summary><b>AI summaries not working</b></summary>
 
 ```bash
 # Check API key is set
@@ -230,16 +487,49 @@ echo $ANTHROPIC_API_KEY
 # Set API key
 export ANTHROPIC_API_KEY="sk-ant-..."
 
-# Restart service
-claudectx restart
+# Or configure in dashboard
+memctx open
+# Navigate to Settings
 ```
 
-## Development
+</details>
+
+---
+
+## 🤝 Contributing
+
+We love contributions! MemCTX is open source and community-driven.
+
+<table>
+<tr>
+<td width="33%" align="center">
+
+### 🐛 Report Bugs
+[Open an issue](https://github.com/bbhunterpk-ux/memctx/issues/new?template=bug_report.md)
+
+</td>
+<td width="33%" align="center">
+
+### 💡 Request Features
+[Suggest a feature](https://github.com/bbhunterpk-ux/memctx/issues/new?template=feature_request.md)
+
+</td>
+<td width="33%" align="center">
+
+### 🔧 Submit PRs
+[Contributing Guide](https://github.com/bbhunterpk-ux/memctx/blob/main/CONTRIBUTING.md)
+
+</td>
+</tr>
+</table>
+
+<details>
+<summary><b>Development Setup</b></summary>
 
 ```bash
 # Clone repository
-git clone https://github.com/yourusername/claudectx.git
-cd claudectx
+git clone https://github.com/bbhunterpk-ux/memctx.git
+cd memctx
 
 # Install dependencies
 pnpm install
@@ -251,39 +541,176 @@ pnpm run build
 npm link
 
 # Test
-claudectx install
-claudectx start
+memctx install
+memctx start
 ```
 
-## Contributing
+</details>
+
+---
+
+## 💬 Community
+
+<div align="center">
 
-Contributions are welcome! Please:
+[![GitHub Discussions](https://img.shields.io/badge/GitHub-Discussions-181717?style=for-the-badge&logo=github)](https://github.com/bbhunterpk-ux/memctx/discussions)
+[![Discord](https://img.shields.io/badge/Discord-Join%20Us-5865F2?style=for-the-badge&logo=discord&logoColor=white)](https://discord.gg/memctx)
+[![Twitter](https://img.shields.io/badge/Twitter-Follow-1DA1F2?style=for-the-badge&logo=twitter&logoColor=white)](https://twitter.com/memctx)
 
-1. Fork the repository
-2. Create a feature branch
-3. Make your changes
-4. Add tests if applicable
-5. Submit a pull request
+</div>
 
-## License
+- **GitHub Discussions**: Ask questions, share ideas
+- **Discord**: Real-time chat with the community
+- **Twitter**: Follow for updates and tips
 
-MIT © 2026
+---
 
-## Support
+## 📊 Stats
 
-- **Issues**: [GitHub Issues](https://github.com/yourusername/claudectx/issues)
-- **Discussions**: [GitHub Discussions](https://github.com/yourusername/claudectx/discussions)
-- **Email**: your.email@example.com
+<div align="center">
 
-## Acknowledgments
+![GitHub stars](https://img.shields.io/github/stars/bbhunterpk-ux/memctx?style=social)
+![GitHub forks](https://img.shields.io/github/forks/bbhunterpk-ux/memctx?style=social)
+![GitHub watchers](https://img.shields.io/github/watchers/bbhunterpk-ux/memctx?style=social)
 
-Built with:
-- [Claude](https://claude.ai) - AI assistant by Anthropic
-- [Express](https://expressjs.com/) - Web framework
-- [SQLite](https://www.sqlite.org/) - Database
-- [React](https://react.dev/) - UI framework
-- [Vite](https://vitejs.dev/) - Build tool
+</div>
 
 ---
 
-Made with ❤️ for the Claude Code community
+## 🗺️ Roadmap
+
+<table>
+<tr>
+<th width="33%">✅ v1.0 (Current)</th>
+<th width="33%">🚧 v1.1 (Next)</th>
+<th width="33%">🔮 v2.0 (Future)</th>
+</tr>
+<tr>
+<td valign="top">
+
+- [x] Session capture
+- [x] AI summaries
+- [x] Dashboard UI
+- [x] Search & filter
+- [x] Tags & bookmarks
+- [x] Export functionality
+
+</td>
+<td valign="top">
+
+- [ ] Team collaboration
+- [ ] Cloud sync
+- [ ] VS Code extension
+- [ ] Advanced analytics
+- [ ] Custom plugins
+- [ ] API webhooks
+
+</td>
+<td valign="top">
+
+- [ ] Multi-user support
+- [ ] Enterprise features
+- [ ] Advanced AI insights
+- [ ] Integration marketplace
+- [ ] Mobile app
+- [ ] Self-hosted option
+
+</td>
+</tr>
+</table>
+
+---
+
+## 📄 License
+
+MemCTX is [MIT licensed](LICENSE).
+
+```
+MIT License
+
+Copyright (c) 2026 Fahad Aziz Qureshi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+```
+
+---
+
+## 🙏 Acknowledgments
+
+Built with ❤️ using:
+
+<div align="center">
+
+[![Claude](https://img.shields.io/badge/Claude-AI%20Assistant-8A2BE2?style=for-the-badge)](https://claude.ai)
+[![Express](https://img.shields.io/badge/Express-Web%20Framework-000000?style=for-the-badge&logo=express)](https://expressjs.com)
+[![React](https://img.shields.io/badge/React-UI%20Framework-61DAFB?style=for-the-badge&logo=react&logoColor=black)](https://react.dev)
+[![SQLite](https://img.shields.io/badge/SQLite-Database-003B57?style=for-the-badge&logo=sqlite)](https://sqlite.org)
+[![Vite](https://img.shields.io/badge/Vite-Build%20Tool-646CFF?style=for-the-badge&logo=vite&logoColor=white)](https://vitejs.dev)
+
+</div>
+
+Special thanks to:
+- [Anthropic](https://anthropic.com) for Claude AI
+- The Claude Code community
+- All our contributors and users
+
+---
+
+## 📞 Support
+
+<table>
+<tr>
+<td width="50%" align="center">
+
+### 📧 Email
+[info@memctx.dev](mailto:info@memctx.dev)
+
+</td>
+<td width="50%" align="center">
+
+### 🌐 Website
+[memctx.dev](https://memctx.dev)
+
+</td>
+</tr>
+<tr>
+<td width="50%" align="center">
+
+### 🐛 Issues
+[GitHub Issues](https://github.com/bbhunterpk-ux/memctx/issues)
+
+</td>
+<td width="50%" align="center">
+
+### 💬 Discussions
+[GitHub Discussions](https://github.com/bbhunterpk-ux/memctx/discussions)
+
+</td>
+</tr>
+</table>
+
+---
+
+<div align="center">
+
+### ⭐ Star us on GitHub — it motivates us a lot!
+
+[![Star History Chart](https://api.star-history.com/svg?repos=bbhunterpk-ux/memctx&type=Date)](https://star-history.com/#bbhunterpk-ux/memctx&Date)
+
+---
+
+**Made with ❤️ by [Fahad Aziz Qureshi](https://memctx.dev)**
+
+*Empowering developers with perfect AI memory*
+
+[⬆ Back to Top](#-memctx)
+
+</div>

package/dist/installer/hooks-settings.json

@@ -0,0 +1,72 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ~/.claudectx/hooks/session-start.js",
+            "timeout": 5000
+          }
+        ]
+      }
+    ],
+    "SessionEnd": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ~/.claudectx/hooks/session-end.js",
+            "timeout": 3000
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ~/.claudectx/hooks/post-tool-use.js",
+            "timeout": 2000
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ~/.claudectx/hooks/user-prompt-submit.js",
+            "timeout": 2000
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ~/.claudectx/hooks/stop.js",
+            "timeout": 2000
+          }
+        ]
+      }
+    ],
+    "PreCompact": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ~/.claudectx/hooks/pre-compact.js",
+            "timeout": 5000
+          }
+        ]
+      }
+    ]
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "memctx",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Autonomous session memory for Claude Code - automatically captures, analyzes, and summarizes your development sessions",
   "author": "Fahad Aziz Qureshi <info@memctx.dev> (https://memctx.dev)",
   "license": "MIT",
@@ -42,7 +42,7 @@
     "dev": "NODE_NO_WARNINGS=1 tsx watch src/index.ts",
     "dev:dashboard": "cd dashboard && vite --port $PORT",
     "build": "pnpm run build:worker && pnpm run build:dashboard",
-    "build:worker": "tsc -p tsconfig.worker.json",
+    "build:worker": "tsc -p tsconfig.worker.json && cp -r installer/hooks-settings.json dist/installer/ && cp -r src/hooks/*.js dist/src/hooks/ 2>/dev/null || true",
     "build:dashboard": "cd dashboard && pnpm install && pnpm vite build",
     "start": "node dist/index.js",
     "typecheck": "tsc -p tsconfig.json --noEmit"

package/dist/src/db/migrations/001_add_memory_tables.sql

@@ -1,149 +0,0 @@
--- Migration: Add Memory System Tables
--- Date: 2026-04-03
--- Description: Extends ClaudeContext with preferences, knowledge, patterns, tasks, and contacts
-
--- User preferences
-CREATE TABLE IF NOT EXISTS preferences (
-  id INTEGER PRIMARY KEY AUTOINCREMENT,
-  category TEXT NOT NULL,  -- communication_style, coding, workflow, testing
-  key TEXT NOT NULL,
-  value TEXT NOT NULL,
-  confidence REAL DEFAULT 1.0,  -- 0-1 confidence score
-  source_session_id TEXT,
-  created_at INTEGER DEFAULT (unixepoch()),
-  updated_at INTEGER DEFAULT (unixepoch()),
-  UNIQUE(category, key),
-  FOREIGN KEY (source_session_id) REFERENCES sessions(id)
-);
-
-CREATE INDEX IF NOT EXISTS idx_preferences_category ON preferences(category);
-CREATE INDEX IF NOT EXISTS idx_preferences_updated ON preferences(updated_at DESC);
-
--- Relationships/Contacts
-CREATE TABLE IF NOT EXISTS contacts (
-  id TEXT PRIMARY KEY,
-  name TEXT NOT NULL,
-  type TEXT NOT NULL,  -- person, team, organization
-  role TEXT,
-  email TEXT,
-  metadata TEXT,  -- JSON for additional fields
-  created_at INTEGER DEFAULT (unixepoch()),
-  updated_at INTEGER DEFAULT (unixepoch())
-);
-
-CREATE INDEX IF NOT EXISTS idx_contacts_type ON contacts(type);
-CREATE INDEX IF NOT EXISTS idx_contacts_name ON contacts(name);
-
--- Interaction history
-CREATE TABLE IF NOT EXISTS interactions (
-  id INTEGER PRIMARY KEY AUTOINCREMENT,
-  contact_id TEXT NOT NULL,
-  session_id TEXT,
-  interaction_type TEXT,  -- mentioned, collaborated, discussed, reviewed
-  context TEXT,
-  created_at INTEGER DEFAULT (unixepoch()),
-  FOREIGN KEY (contact_id) REFERENCES contacts(id) ON DELETE CASCADE,
-  FOREIGN KEY (session_id) REFERENCES sessions(id) ON DELETE SET NULL
-);
-
-CREATE INDEX IF NOT EXISTS idx_interactions_contact ON interactions(contact_id);
-CREATE INDEX IF NOT EXISTS idx_interactions_session ON interactions(session_id);
-CREATE INDEX IF NOT EXISTS idx_interactions_created ON interactions(created_at DESC);
-
--- Domain knowledge
-CREATE TABLE IF NOT EXISTS knowledge_items (
-  id TEXT PRIMARY KEY,
-  category TEXT NOT NULL,  -- technology, business, architecture, debugging
-  topic TEXT NOT NULL,
-  content TEXT NOT NULL,
-  confidence REAL DEFAULT 0.5,  -- 0-1 confidence score
-  source_session_id TEXT,
-  last_accessed_at INTEGER,
-  access_count INTEGER DEFAULT 0,
-  created_at INTEGER DEFAULT (unixepoch()),
-  updated_at INTEGER DEFAULT (unixepoch()),
-  FOREIGN KEY (source_session_id) REFERENCES sessions(id) ON DELETE SET NULL
-);
-
-CREATE INDEX IF NOT EXISTS idx_knowledge_category ON knowledge_items(category);
-CREATE INDEX IF NOT EXISTS idx_knowledge_topic ON knowledge_items(topic);
-CREATE INDEX IF NOT EXISTS idx_knowledge_confidence ON knowledge_items(confidence DESC);
-CREATE INDEX IF NOT EXISTS idx_knowledge_accessed ON knowledge_items(last_accessed_at DESC);
-
--- Full-text search for knowledge
-CREATE VIRTUAL TABLE IF NOT EXISTS knowledge_fts USING fts5(
-  topic, content,
-  content=knowledge_items,
-  content_rowid=rowid
-);
-
--- Triggers to keep FTS in sync
-CREATE TRIGGER IF NOT EXISTS knowledge_fts_insert AFTER INSERT ON knowledge_items BEGIN
-  INSERT INTO knowledge_fts(rowid, topic, content) VALUES (new.rowid, new.topic, new.content);
-END;
-
-CREATE TRIGGER IF NOT EXISTS knowledge_fts_delete AFTER DELETE ON knowledge_items BEGIN
-  DELETE FROM knowledge_fts WHERE rowid = old.rowid;
-END;
-
-CREATE TRIGGER IF NOT EXISTS knowledge_fts_update AFTER UPDATE ON knowledge_items BEGIN
-  DELETE FROM knowledge_fts WHERE rowid = old.rowid;
-  INSERT INTO knowledge_fts(rowid, topic, content) VALUES (new.rowid, new.topic, new.content);
-END;
-
--- Learned patterns
-CREATE TABLE IF NOT EXISTS learned_patterns (
-  id TEXT PRIMARY KEY,
-  pattern_type TEXT NOT NULL,  -- debugging, problem_solving, code_pattern, workflow
-  title TEXT NOT NULL,
-  description TEXT NOT NULL,
-  example TEXT,
-  success_count INTEGER DEFAULT 0,
-  failure_count INTEGER DEFAULT 0,
-  last_used_at INTEGER,
-  created_at INTEGER DEFAULT (unixepoch()),
-  updated_at INTEGER DEFAULT (unixepoch())
-);
-
-CREATE INDEX IF NOT EXISTS idx_patterns_type ON learned_patterns(pattern_type);
-CREATE INDEX IF NOT EXISTS idx_patterns_success ON learned_patterns(success_count DESC);
-CREATE INDEX IF NOT EXISTS idx_patterns_used ON learned_patterns(last_used_at DESC);
-
--- Pending tasks
-CREATE TABLE IF NOT EXISTS tasks (
-  id TEXT PRIMARY KEY,
-  title TEXT NOT NULL,
-  description TEXT,
-  status TEXT DEFAULT 'pending',  -- pending, in_progress, completed, blocked, cancelled
-  priority TEXT DEFAULT 'medium',  -- low, medium, high, urgent
-  project_id TEXT,
-  tags TEXT,  -- JSON array
-  created_session_id TEXT,
-  completed_session_id TEXT,
-  due_date INTEGER,
-  created_at INTEGER DEFAULT (unixepoch()),
-  updated_at INTEGER DEFAULT (unixepoch()),
-  completed_at INTEGER,
-  FOREIGN KEY (project_id) REFERENCES projects(id) ON DELETE CASCADE,
-  FOREIGN KEY (created_session_id) REFERENCES sessions(id) ON DELETE SET NULL,
-  FOREIGN KEY (completed_session_id) REFERENCES sessions(id) ON DELETE SET NULL
-);
-
-CREATE INDEX IF NOT EXISTS idx_tasks_status ON tasks(status);
-CREATE INDEX IF NOT EXISTS idx_tasks_priority ON tasks(priority);
-CREATE INDEX IF NOT EXISTS idx_tasks_project ON tasks(project_id);
-CREATE INDEX IF NOT EXISTS idx_tasks_created ON tasks(created_at DESC);
-
--- Memory metadata (for tracking memory health)
-CREATE TABLE IF NOT EXISTS memory_metadata (
-  key TEXT PRIMARY KEY,
-  value TEXT NOT NULL,
-  updated_at INTEGER DEFAULT (unixepoch())
-);
-
--- Insert initial metadata
-INSERT OR IGNORE INTO memory_metadata (key, value) VALUES
-  ('schema_version', '1'),
-  ('memory_enabled', 'true'),
-  ('last_consolidation', '0'),
-  ('total_memories', '0');

package/dist/src/db/migrations/002_add_project_id_to_memory.sql

@@ -1,25 +0,0 @@
--- Migration: Add project_id to memory tables
--- Date: 2026-04-03
--- Description: Make memory project-specific instead of global
-
--- Add project_id to preferences
-ALTER TABLE preferences ADD COLUMN project_id TEXT REFERENCES projects(id);
-CREATE INDEX IF NOT EXISTS idx_preferences_project ON preferences(project_id);
-
--- Add project_id to knowledge_items
-ALTER TABLE knowledge_items ADD COLUMN project_id TEXT REFERENCES projects(id);
-CREATE INDEX IF NOT EXISTS idx_knowledge_project ON knowledge_items(project_id);
-
--- Add project_id to learned_patterns
-ALTER TABLE learned_patterns ADD COLUMN project_id TEXT REFERENCES projects(id);
-CREATE INDEX IF NOT EXISTS idx_patterns_project ON learned_patterns(project_id);
-
--- Add project_id to contacts
-ALTER TABLE contacts ADD COLUMN project_id TEXT REFERENCES projects(id);
-CREATE INDEX IF NOT EXISTS idx_contacts_project ON contacts(project_id);
-
--- Update existing test data with project_id
-UPDATE preferences SET project_id = 'c6d8edec13ba353f' WHERE project_id IS NULL;
-UPDATE knowledge_items SET project_id = 'c6d8edec13ba353f' WHERE project_id IS NULL;
-UPDATE learned_patterns SET project_id = 'c6d8edec13ba353f' WHERE project_id IS NULL;
-UPDATE contacts SET project_id = 'c6d8edec13ba353f' WHERE project_id IS NULL;

package/dist/src/db/migrations/003_enhance_sessions_schema.sql

@@ -1,27 +0,0 @@
--- Migration 003: Enhance Sessions Schema for v2.0
--- Adds 7 new columns for enhanced summarization and 5 performance indexes
-
--- Add new columns to sessions table
-ALTER TABLE sessions ADD COLUMN summary_mood TEXT;
-ALTER TABLE sessions ADD COLUMN summary_complexity TEXT;
-ALTER TABLE sessions ADD COLUMN summary_blockers TEXT;
-ALTER TABLE sessions ADD COLUMN summary_resolved TEXT;
-ALTER TABLE sessions ADD COLUMN summary_key_insight TEXT;
-ALTER TABLE sessions ADD COLUMN duration_seconds INTEGER;
-ALTER TABLE sessions ADD COLUMN embedding_summary TEXT;
-
--- Create performance indexes
-CREATE INDEX IF NOT EXISTS idx_sessions_project_ended
-  ON sessions(project_id, ended_at DESC);
-
-CREATE INDEX IF NOT EXISTS idx_sessions_status_project
-  ON sessions(status, project_id);
-
-CREATE INDEX IF NOT EXISTS idx_sessions_started
-  ON sessions(started_at DESC);
-
-CREATE INDEX IF NOT EXISTS idx_observations_session_type
-  ON observations(session_id, event_type);
-
-CREATE INDEX IF NOT EXISTS idx_observations_project_created
-  ON observations(project_id, created_at DESC);

package/dist/src/db/migrations/004_add_bookmarks.sql

@@ -1,5 +0,0 @@
--- Add is_bookmarked column to sessions table
-ALTER TABLE sessions ADD COLUMN is_bookmarked INTEGER DEFAULT 0;
-
--- Create index for faster bookmark queries
-CREATE INDEX IF NOT EXISTS idx_sessions_bookmarked ON sessions(is_bookmarked, project_id);

package/dist/src/db/migrations/005_add_tags.sql

@@ -1,21 +0,0 @@
--- Add tags table and session_tags junction table
-CREATE TABLE IF NOT EXISTS tags (
-  id INTEGER PRIMARY KEY AUTOINCREMENT,
-  project_id TEXT NOT NULL REFERENCES projects(id),
-  name TEXT NOT NULL,
-  color TEXT,
-  created_at INTEGER NOT NULL DEFAULT (unixepoch()),
-  UNIQUE(project_id, name)
-);
-
-CREATE TABLE IF NOT EXISTS session_tags (
-  session_id TEXT NOT NULL REFERENCES sessions(id) ON DELETE CASCADE,
-  tag_id INTEGER NOT NULL REFERENCES tags(id) ON DELETE CASCADE,
-  created_at INTEGER NOT NULL DEFAULT (unixepoch()),
-  PRIMARY KEY (session_id, tag_id)
-);
-
--- Create indexes for faster queries
-CREATE INDEX IF NOT EXISTS idx_tags_project ON tags(project_id);
-CREATE INDEX IF NOT EXISTS idx_session_tags_session ON session_tags(session_id);
-CREATE INDEX IF NOT EXISTS idx_session_tags_tag ON session_tags(tag_id);

package/dist/src/db/migrations/006_add_notes.sql

@@ -1,2 +0,0 @@
--- Add notes column to sessions table
-ALTER TABLE sessions ADD COLUMN notes TEXT;

package/dist/src/db/migrations/007_add_archived.sql

@@ -1,2 +0,0 @@
--- Add is_archived column to sessions table
-ALTER TABLE sessions ADD COLUMN is_archived INTEGER DEFAULT 0;

package/dist/src/services/auto-summarizer.d.ts

@@ -1,5 +0,0 @@
-/**
- * Auto-summarizer: Finds completed sessions without summaries and queues them
- * This handles cases where SessionEnd hook doesn't fire
- */
-export declare function startAutoSummarizer(): void;

package/dist/src/services/auto-summarizer.js

@@ -1,50 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.startAutoSummarizer = startAutoSummarizer;
-const queries_1 = require("../db/queries");
-const summarization_queue_1 = require("./summarization-queue");
-const logger_1 = require("./logger");
-const CHECK_INTERVAL = 2 * 60 * 1000; // Check every 2 minutes
-/**
- * Auto-summarizer: Finds completed sessions without summaries and queues them
- * This handles cases where SessionEnd hook doesn't fire
- */
-function startAutoSummarizer() {
-    setInterval(() => {
-        try {
-            console.log('[AutoSummarizer] Checking for unsummarized sessions...');
-            // Find completed sessions without summaries
-            const allSessions = queries_1.queries.getSessions({ limit: 1000 });
-            let queued = 0;
-            for (const session of allSessions) {
-                // Skip if:
-                // - Session is still active
-                // - No transcript path
-                // - Already has a summary
-                if (session.status === 'active')
-                    continue;
-                if (!session.transcript_path)
-                    continue;
-                if (session.summary_title)
-                    continue;
-                console.log(`[AutoSummarizer] Found unsummarized session: ${session.id.slice(0, 8)}`);
-                summarization_queue_1.summarizationQueue.enqueue({
-                    sessionId: session.id,
-                    transcriptPath: session.transcript_path,
-                    projectId: session.project_id,
-                    priority: 'low'
-                });
-                queued++;
-            }
-            if (queued > 0) {
-                console.log(`[AutoSummarizer] Queued ${queued} sessions for summarization`);
-                logger_1.logger.info('AutoSummarizer', `Queued ${queued} unsummarized sessions`);
-            }
-        }
-        catch (err) {
-            console.error('[AutoSummarizer] Error:', err);
-        }
-    }, CHECK_INTERVAL);
-    console.log('[AutoSummarizer] Started (checks every 2 minutes)');
-}
-//# sourceMappingURL=auto-summarizer.js.map

package/dist/src/services/auto-summarizer.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"auto-summarizer.js","sourceRoot":"","sources":["../../../src/services/auto-summarizer.ts"],"names":[],"mappings":";;AAUA,kDAuCC;AAjDD,2CAAuC;AACvC,+DAA0D;AAC1D,qCAAiC;AAEjC,MAAM,cAAc,GAAG,CAAC,GAAG,EAAE,GAAG,IAAI,CAAA,CAAC,wBAAwB;AAE7D;;;GAGG;AACH,SAAgB,mBAAmB;IACjC,WAAW,CAAC,GAAG,EAAE;QACf,IAAI,CAAC;YACH,OAAO,CAAC,GAAG,CAAC,wDAAwD,CAAC,CAAA;YAErE,4CAA4C;YAC5C,MAAM,WAAW,GAAG,iBAAO,CAAC,WAAW,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAA;YAExD,IAAI,MAAM,GAAG,CAAC,CAAA;YACd,KAAK,MAAM,OAAO,IAAI,WAAW,EAAE,CAAC;gBAClC,WAAW;gBACX,4BAA4B;gBAC5B,uBAAuB;gBACvB,0BAA0B;gBAC1B,IAAI,OAAO,CAAC,MAAM,KAAK,QAAQ;oBAAE,SAAQ;gBACzC,IAAI,CAAC,OAAO,CAAC,eAAe;oBAAE,SAAQ;gBACtC,IAAI,OAAO,CAAC,aAAa;oBAAE,SAAQ;gBAEnC,OAAO,CAAC,GAAG,CAAC,gDAAgD,OAAO,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,CAAA;gBAErF,wCAAkB,CAAC,OAAO,CAAC;oBACzB,SAAS,EAAE,OAAO,CAAC,EAAE;oBACrB,cAAc,EAAE,OAAO,CAAC,eAAe;oBACvC,SAAS,EAAE,OAAO,CAAC,UAAU;oBAC7B,QAAQ,EAAE,KAAK;iBAChB,CAAC,CAAA;gBACF,MAAM,EAAE,CAAA;YACV,CAAC;YAED,IAAI,MAAM,GAAG,CAAC,EAAE,CAAC;gBACf,OAAO,CAAC,GAAG,CAAC,2BAA2B,MAAM,6BAA6B,CAAC,CAAA;gBAC3E,eAAM,CAAC,IAAI,CAAC,gBAAgB,EAAE,UAAU,MAAM,wBAAwB,CAAC,CAAA;YACzE,CAAC;QACH,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,OAAO,CAAC,KAAK,CAAC,yBAAyB,EAAE,GAAG,CAAC,CAAA;QAC/C,CAAC;IACH,CAAC,EAAE,cAAc,CAAC,CAAA;IAElB,OAAO,CAAC,GAAG,CAAC,mDAAmD,CAAC,CAAA;AAClE,CAAC"}