🧠 Memorizable

AI-assisted feature memory system for development projects

Captures and summarizes Claude Code interactions to track project features, key points, and rules.

✨ Features

• 🤖 Automatic Claude Code Integration - Seamlessly captures AI conversations
• 📝 Smart Summarization - Uses OpenAI to extract features and key insights
• 🎯 Project Memory - Maintains up-to-date MEMORY.md with project state
• ⚡ Real-time Processing - Processes messages as you work
• 🔧 Configurable - Customizable message thresholds and file paths
• 🚀 Zero Friction - Set up once, works automatically

🚀 Quick Start

1. Install globally

npm install -g memorizable

2. Start the server

memorizable server
# 🌐 Server running on http://localhost:3001

3. Set up your project

cd your-awesome-project
memorizable setup --project-name "my-app" --openai-key "sk-your-key-here"
# ✅ Hooks configured! Start using Claude Code.

4. Start coding with Claude!

Your conversations are now automatically captured and summarized! 🎉

📋 Commands

🖥️ memorizable server

Start the Memorizable server (required for message capture)

memorizable server
# Options:
#   --port        Server port (default: 3001)
#   --data-dir    Data directory path

⚙️ memorizable setup

Configure hooks for your project

memorizable setup --project-name "my-project" --openai-key "sk-..."

# 📝 Options:
#   --project-name    Unique name for your project (required)
#   --openai-key      OpenAI API key for summarization (required)  
#   --memory-path     Path to memory file (default: ./MEMORY.md)
#   --max-messages    Messages before summarization (default: 10)

📊 memorizable status

Check current configuration and message count

memorizable status
# Shows:
# ✅ Project: my-awesome-app
# 📝 Messages: 7/10 (3 until next summary)
# 📄 Memory file: ./MEMORY.md  
# 🔧 Config: .memorizable/config.json

🔄 memorizable summarize

Manually trigger summarization

memorizable summarize
# 🤖 Analyzing 8 messages...
# ✅ Memory updated: ./MEMORY.md

🗑️ memorizable remove

Remove hooks from your project

memorizable remove
# 🧹 Hooks removed from Claude Code configuration

🧩 How It Works

graph TD
    A[👨‍💻 You chat with Claude Code] --> B[🎣 Hooks capture messages]
    B --> C[📨 Send to Memorizable server]
    C --> D{📊 Reached message limit?}
    D -->|No| E[💾 Store message]
    D -->|Yes| F[🤖 AI Summarization]
    F --> G[📝 Update MEMORY.md]
    G --> H[🗑️ Clear message buffer]

Loading

1. 🎣 Message Capture: Claude Code hooks automatically capture all conversations
2. 🧮 Smart Counting: Only counts user messages (excludes tool calls) for clean summaries
3. 🤖 AI Summarization: After N messages, OpenAI analyzes and extracts:
   • 🎯 Project overview
   • 🏗️ Technical architecture
   • 💡 Key insights
   • ✨ Feature requirements
4. 📄 Memory Update: Intelligently updates your MEMORY.md file

📄 Memory File Structure

Your MEMORY.md maintains project knowledge in a clean format:

# 🎯 Project Overview
Brief description of your project and its goals

# 🏗️ Technical Architecture/Framework  
Technical stack, architecture decisions, and implementation details

# 💡 Key Items
- Important decisions and patterns
- Technical insights and learnings
- Development guidelines

# ✨ Features (Product Requirements)
- 🔐 User Authentication: Secure login system with JWT
- 📊 Dashboard: Real-time analytics and reporting
- 🔄 Data Sync: Background synchronization with external APIs

⚙️ Configuration

Configuration lives in .memorizable/config.json:

{
  "projectName": "my-awesome-app",
  "openaiApiKey": "sk-...", 
  "userMemoryPath": "./MEMORY.md",
  "maxMessagesBeforeSummary": 10
}

🛠️ Development

# Clone the repository
git clone https://github.com/AlexKlim/memorizable.git
cd memorizable

# Install dependencies
npm install

# Build TypeScript
npm run build

# Run in development mode
npm run dev

# Link for local testing
npm link

🐛 Troubleshooting

🚫 Server not starting

• Check if port 3001 is available: lsof -i :3001
• Ensure Node.js 16+ is installed: node --version
• Try a different port: memorizable server --port 3002

📵 Messages not being captured

• Verify server is running: memorizable server
• Check hooks installation: memorizable status
• Look at debug logs: /tmp/memorizable-debug.log
• Restart Claude Code after setup

🔄 Summarization not triggering

• Only user messages count (tool calls are excluded)
• Check message count: memorizable status
• Verify OpenAI API key: memorizable status
• Manually trigger: memorizable summarize

📝 Memory file not updating

• Verify file path in config: memorizable status
• Check write permissions on memory file
• Look for server errors in logs

🏗️ Architecture

• 🖥️ Server: Express.js server handling message storage and processing
• 🎣 Hooks: Claude Code integration for conversation capture
• 💾 Storage: JSON-based message storage in memorizable-data/
• 🤖 AI Engine: OpenAI GPT-4 for intelligent conversation analysis
• 📝 Memory Management: Smart Markdown file updates with conflict resolution

📋 Requirements

• Node.js 16 or higher
• npm or yarn package manager
• OpenAI API key for summarization features
• Claude Code for AI-assisted development

📄 License

MIT © Alex Klim

🤝 Contributing

Contributions welcome! Please read our contributing guidelines first.

---

Made with ❤️ for better AI-assisted development

Report Bug • Request Feature • Documentation