MemCTX
Autonomous Session Memory & Context Handoff for Claude Code Never repeat yourself. Your AI pair programmer, now with world-class memory.
🚀 Quick Start • ✨ Features • 🏗️ Architecture • 💻 CLI Commands
⚡ The Problem vs The Solution
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.
| 😫 Without MemCTX | ✨ With MemCTX |
|---|---|
| ❌ Repeating Context every session | ✅ Automatic Injection of critical context |
| ❌ Lost History when closing terminal | ✅ Persistent Graph of all past decisions |
| ❌ Manual Notes for handoffs | ✅ AI Handoffs indicating where to start next |
| ❌ Unnoticed Tech Debt accumulation | ✅ Telemetry & Metrics tracking Tech Debt |
✨ Key Features
🧠 World-Class Memory
Automatically captures every Claude Code session, extracting gamification metrics like Aha! moments, Divergence, and Flow State.🤖 Explicit AI Handoffs
Claude analyzes each session and passes it on. The next session gets explicitSTART HERE markers, Open Rabbit Holes, Tech Debt, and Architectural Drift.
🏗️ Knowledge Graph Architecture
Unifies your context into a persistent graph database. Extracts complex file-function relationships in a single optimized pass.📊 Beautiful React Dashboard
Modern, responsive UI visualizing session telemetry, tool usage, and your node/edge graph layout in seconds.⚡ Incremental Snapshots & Privacy-First
Long sessions are safely chunked via hybrid 10-turn / 5-minute triggers. Everything runs locally via SQLite. The global daemon operates efficiently out of the way on port 9999.🚀 Quick Start
1. Installation
# Strongly recommended
pnpm add -g memctx
# Alternatives
npm install -g memctx
yarn global add memctx
2. Setup (30 seconds)
memctx install # Registers Claude Code hooks
memctx start # Boots the backend daemon
memctx open # Opens your dashboard
You're all set! MemCTX is now silently backing up and injecting context behind the scenes. Start a session by running
claude.
🏗️ How It Works
graph LR
A[Claude Code CLI] -->|Hooks| B["MemCTX Daemon (Port 9999)"]
B -->|Persist| C[("SQLite DB")]
B -->|Graph & Stats| D["Anthropic Analysis"]
D -->|Rich Context| C
C -->|Serve| E["React UI Dashboard"]
B -->|Explicit Handoff Payload| A
style A fill:#3b82f6,color:#fff,stroke:#fff
style B fill:#10b981,color:#fff,stroke:#fff
style C fill:#f59e0b,color:#fff,stroke:#fff
style D fill:#8b5cf6,color:#fff,stroke:#fff
style E fill:#ef4444,color:#fff,stroke:#fff
- Initialization:
memctx startboots the local daemon. - Seamless Hooks: MemCTX injects directly into Claude Code via
~/.claude/settings.json. - Session Start: MemCTX computes past context, open tech debt, and immediate next steps, piping it directly into Claude's System Prompt via the
SessionStarthook. - Live Telemetry: A background worker monitors streams via a hybrid 10-turn or 5-minute snapshot strategy.
- Session Extraction: MemCTX analyzes gamified session stats (Aha! moments, tech debt, flow states).
- Dashboard Visualization: Review your timeline, metrics, and architecture maps in a beautiful React SPA!
💻 CLI Reference
| Command | Description |
|---|---|
memctx install |
Install hooks and start daemon |
memctx start |
Boot the background worker daemon |
memctx stop |
Stop the background worker daemon |
memctx status |
Show daemon status and SQLite health |
memctx open |
Open the React dashboard in your browser |
memctx search <Q> |
Search sessions directly from the terminal |
memctx export |
Export all sessions to clean Markdown files |
memctx uninstall |
Remove all hooks and gracefully stop daemon |
🔧 Configuration
While MemCTX typically runs instantly out of the box, you can fine-tune it in http://localhost:9999/settings or via environment variables:
export ANTHROPIC_API_KEY="sk-ant-..." # Required for rich summaries
export ANTHROPIC_BASE_URL="..." # Support for proxies like 9router
export MEMCTX_PORT=8080 # Custom Daemon Port (Default: 9999)
export MEMCTX_DB_PATH="/path/to/db.sqlite" # Custom DB path
⭐ Star us on GitHub — it motivates us a lot!
💡 Open Source & Community
MemCTX is built by and for the developer community. We heartily welcome contributions and feedback!
MIT Licensed • Made with ❤️ by Fahad Aziz Qureshi