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

�� 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

1. Initialization: memctx start boots the local daemon.
2. Seamless Hooks: MemCTX injects directly into Claude Code via ~/.claude/settings.json.
3. Session Start: MemCTX computes past context, open tech debt, and immediate next steps, piping it directly into Claude's System Prompt via the SessionStart hook.
4. Live Telemetry: A background worker monitors streams via a hybrid 10-turn or 5-minute snapshot strategy.
5. Session Extraction: MemCTX analyzes gamified session stats (Aha! moments, tech debt, flow states).
6. 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