🧠 MemCTX

Autonomous Session Memory for Claude Code

Never lose context. Never repeat yourself. Your AI pair programmer, now with perfect memory.

🚀 Quick Start • 📖 Documentation • ✨ Features • 🎯 Demo • 💬 Community

🎯 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.

😫 Before MemCTX

❌ Repeat context every session
❌ Lost conversation history
❌ Manual session notes
❌ Forgotten decisions
❌ Context switching overhead

✨ With MemCTX

✅ Automatic context injection
✅ Searchable session history
✅ AI-powered summaries
✅ Decision tracking
✅ Seamless continuity

✨ Features

🧠 Smart Memory

Automatically captures every Claude Code session with full context preservation

🤖 AI Summaries

Claude analyzes each session and generates structured summaries with key insights

📊 Beautiful Dashboard

Modern, responsive UI to browse, search, and analyze your development history

🔍 Full-Text Search

Lightning-fast search across all sessions, conversations, and code snippets

📈 Live Monitoring

Real-time view of active sessions with WebSocket updates

🎯 Context Injection

Automatically injects relevant history into new sessions for perfect continuity

🏷️ Tags & Bookmarks

Organize sessions with custom tags and bookmark important moments

📝 Session Notes

Add custom notes and annotations to any session

🌓 Dark/Light Theme

Beautiful themes that adapt to your preference

🚀 Quick Start

📦 Installation

# Install globally with npm
npm install -g memctx

# Or with pnpm (recommended)
pnpm add -g memctx

# Or with yarn
yarn global add memctx

Current Version: 1.0.4 | Node Required: >=18.0.0

⚡ Setup (30 seconds)

# 1. Install and configure hooks
memctx install

# 2. Start the service
memctx start

# 3. Open the dashboard
memctx open

That's it! 🎉 MemCTX is now capturing your Claude Code sessions automatically.

🔧 Configuration

Settings Dashboard (Recommended)

Open http://localhost:9999/settings and configure:

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)

# Required for AI summaries
export ANTHROPIC_API_KEY="sk-ant-..."

# Optional: Use proxy
export ANTHROPIC_BASE_URL="https://your-proxy.com/v1"

# Optional: Custom port (default: 9999)
export MEMCTX_PORT=8080

# Optional: Custom database location
export MEMCTX_DB_PATH="/path/to/db.sqlite"

💻 CLI Commands

Command	Description
`memctx install`	Install hooks and start daemon
`memctx start`	Start the worker daemon
`memctx stop`	Stop the worker daemon
`memctx restart`	Restart the worker daemon
`memctx status`	Show daemon status and health check
`memctx open`	Open dashboard in browser
`memctx search <query>`	Search sessions from terminal
`memctx export`	Export all sessions as markdown
`memctx config`	Show configuration
`memctx uninstall`	Remove hooks and stop daemon

🎯 Demo

Dashboard Overview

Session Details

Search & Filter

🏗️ How It Works

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

📋 Detailed Flow

Session Start: Claude Code session begins → session-start hook fires
Capture: MemCTX worker creates session record in SQLite
Observe: Every tool use is captured via post-tool-use hook
End: Session ends → stop hook fires
Summarize: Worker sends transcript to Claude for AI analysis
Store: Summary stored in database
Inject: Next session auto-loads relevant context from CLAUDE.md
Browse: View everything in the beautiful dashboard

📖 Documentation

📚 Complete Documentation →

📚 For Users

🛠️ For Developers

🔧 Requirements

System Requirements

Node.js: 18.0.0 or higher
Claude Code: CLI installed
OS: Linux, macOS, or Windows (WSL)

Build Tools (for installation)

Linux: build-essential, python3
macOS: Xcode Command Line Tools
Windows: Visual Studio Build Tools

🔨 Installing Build Tools

Linux (Ubuntu/Debian):

sudo apt install build-essential python3

macOS:

xcode-select --install

Windows:
Install Visual Studio Build Tools

🎨 Dashboard Features

📊 Projects View

Browse all projects and their sessions organized by directory

🔍 Search

Full-text search with filters, tags, and date ranges

📈 Live Monitor

Real-time view of active sessions with WebSocket updates

📝 Session Details

View full conversation history, summaries, and observations

🏷️ Tags & Notes

Organize with custom tags and add notes to sessions

📊 Metrics

System performance, API usage, and statistics

🌓 Themes

Beautiful dark and light themes

⌨️ Shortcuts

Keyboard shortcuts for power users (press ?)

📤 Export

Export sessions as markdown or screenshots

🚨 Troubleshooting

Service won't start

# Check if port is in use
lsof -i :9999

# Check logs
tail -f /tmp/memctx.log

# Restart service
memctx restart

Hooks not working

# Verify hooks are registered
cat ~/.claude/settings.json | grep memctx

# Reinstall hooks
memctx uninstall
memctx install

SQLite compilation errors

# Rebuild native modules
npm rebuild better-sqlite3

# Or reinstall
npm uninstall -g memctx
npm install -g memctx

AI summaries not working

# Check API key is set
echo $ANTHROPIC_API_KEY

# Set API key
export ANTHROPIC_API_KEY="sk-ant-..."

# Or configure in dashboard
memctx open
# Navigate to Settings

🤝 Contributing

We love contributions! MemCTX is open source and community-driven.

Development Setup

# Clone repository
git clone https://github.com/bbhunterpk-ux/memctx.git
cd memctx

# Install dependencies
pnpm install

# Build
pnpm run build

# Link locally
npm link

# Test
memctx install
memctx start

💬 Community

💬 GitHub Discussions

Ask questions, share ideas

💭 Discord

Real-time chat with the community

🐦 Twitter

Follow for updates and tips

📊 Stats

🗺️ Roadmap

✅ v1.0 (Current)	🚧 v1.1 (Next)	🔮 v2.0 (Future)
Session capture AI summaries Dashboard UI Search & filter Tags & bookmarks Export functionality	Team collaboration Cloud sync VS Code extension Advanced analytics Custom plugins API webhooks	Multi-user support Enterprise features Advanced AI insights Integration marketplace Mobile app Self-hosted option

📄 License

MemCTX is MIT licensed.

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:

Special thanks to:

🤖 Anthropic

For Claude AI

👥 Community

The Claude Code community

🙌 Contributors

All our contributors and users

📞 Support

📧 Email

[email protected]

🌐 Website

memctx.dev

🐛 Issues

GitHub Issues

💬 Discussions

GitHub Discussions

⭐ Star us on GitHub — it motivates us a lot!

Made with ❤️ by Fahad Aziz Qureshi

Empowering developers with perfect AI memory

⬆ Back to Top