Claude Mind 🧠

Give Claude persistent memory across sessions. Zero setup. Automatic updates. Team-ready.

Why This Exists

Problem: Claude forgets your project between sessions. You repeat yourself constantly.

Solution: Self-bootstrapping memory that extracts knowledge from your existing code.

Quick Start (60 seconds)

# 1. Bootstrap - collect project context
npx claude-mind

# 2. In Claude Code - let Claude analyze your project
/mind:init

# 3. That's it! Memory is active.
# Claude now remembers your project context automatically.

What Just Happened?

✅ Collected your package.json, README.md, and git history ✅ Created .claude/memory/context/ with raw project files ✅ Created memory-bank/ for team collaboration ✅ Claude will analyze and create your personal memory ✅ Two-tier memory system ready: personal + team

🎯 Dual-Memory System

Claude Mind uses a two-tier memory architecture:

Personal Memory (.claude/memory/)

• 🔒 Private: Gitignored, stays on your machine
• 📝 Purpose: Your notes, experiments, work-in-progress
• 🚀 Fast: Update anytime without team coordination
• 💡 Freedom: Try ideas without affecting team

Team Memory (memory-bank/)

• 🤝 Shared: Committed to git, entire team sees it
• 📚 Official: Authoritative architecture and decisions
• 🔍 Reviewed: Changes go through PR process
• 📖 Onboarding: New developers get instant context

How They Work Together

# You run /mind:init
# Claude reads: memory-bank/ (team) + project files
# Claude creates: .claude/memory/ (your personal understanding)

# You implement a feature
/mind:impl Add authentication

# Claude reads BOTH memories:
# - memory-bank/ for team patterns
# - .claude/memory/ for your current work

# Share your discovery with team
/mind:promote patterns --section "Auth Pattern"
# Creates PR with memory-bank/ update
# Team reviews and approves

Best of Both Worlds

| Need | Solution | |------|----------| | Quick personal notes | Use .claude/memory/ (no commit needed) | | Share architecture decision | Use /mind:promote decisions | | Onboard new developer | They get memory-bank/ via git clone | | Experiment with ideas | Try in .claude/memory/, promote if successful | | Team alignment | Review memory-bank/ changes in PRs |

See It In Action

Before Mind:

You: "Add authentication"
Claude: "What type of auth? What's your stack? What's your current setup?"
You: *explains everything again* 😫

After Mind:

You: "Add authentication"
Claude: *reads memory* "I see you're using Next.js 14 with Prisma.
I'll add NextAuth.js to match your existing pattern..." ✨

How It Works

LLM-First Architecture: Unlike tools that use hardcoded parsing, we let Claude do what it does best - understand your code semantically.

Step 1: Bootstrap (JavaScript)

npx claude-mind

• Collects raw project files (package.json, README, etc.)
• Captures git history and project structure
• No parsing, no assumptions - just gathers facts

Step 2: Analysis (Claude's Intelligence)

/mind:init  # in Claude Code

• Claude reads collected files
• Analyzes framework, architecture, patterns
• Creates memory files with deep understanding
• Works with ANY framework - even ones that don't exist yet!

Benefits of LLM-Based Approach

• ✅ Future-proof - Works with new frameworks automatically
• ✅ Accurate - Semantic analysis, not regex matching
• ✅ Maintainable - No hardcoded framework lists
• ✅ Smart - Claude understands context and relationships

Installation

npx claude-mind

That's it! Then run /mind:init in Claude Code.

Supported Project Types

ALL of them! Because Claude analyzes your project semantically, it works with:

• ✅ Any language - JavaScript, Python, Rust, Go, Java, C++, etc.
• ✅ Any framework - Next.js, Django, Svelte, Astro, even custom frameworks
• ✅ Any structure - Monorepos, microservices, libraries, CLIs
• ✅ Future frameworks - Works with tools that don't exist yet

No hardcoded framework detection = No maintenance burden

Planning & Implementation Workflows (New in v1.1)

Planning Mode: /mind:plan

Research and plan features before implementing. Perfect for complex features or exploring different approaches.

/mind:plan Build a real-time notification system

What happens:

1. 📋 RESEARCH: Claude reads memory and analyzes your request
2. 🎯 ANALYZE: Breaks down requirements, constraints, and impact
3. 📖 PLAN: Creates multiple implementation approaches with pros/cons
4. 💡 RECOMMEND: Suggests best approach with detailed rationale
5. 📝 SAVE: Optionally saves plan for team review and future reference

When to use:

• Complex features requiring careful planning
• Exploring different architectural approaches
• Creating documentation for team discussion
• Understanding impact before making changes

Example:

You: /mind:plan Migrate authentication from sessions to JWT

Claude:
📋 RESEARCH: Express.js app, currently using express-session...
🎯 ANALYZE: Breaking down migration requirements...
📖 PLAN:
    Approach 1: Gradual migration (Recommended)
      ✓ Zero downtime
      ✓ Supports both auth methods during transition
      ✗ More complex implementation

    Approach 2: Direct replacement
      ✓ Simpler code
      ✗ Requires maintenance window

💡 RECOMMEND: Approach 1 - Gradual migration
    Rationale: Your active.md shows production users...

📝 Save this plan? yes
✅ Plan saved to .claude/memory/plans/2025-10-12-jwt-migration.md

Implementation Workflow: /mind:impl

Implement features with full project context awareness through an intelligent 4-phase workflow.

/mind:impl Add user authentication with JWT

What happens automatically:

1. 📖 PLAN: Claude reads your memory, analyzes the request, and creates an implementation plan
2. 🔧 ACT: Implements the feature following your project's patterns
3. 📝 DOCUMENT: Updates memory files automatically (active.md, patterns.md, decisions.md)
4. ✅ VALIDATE: Reviews implementation, suggests next steps

Key Features:

• ✨ Zero configuration - Just describe what you want in natural language
• 🧠 Memory-aware - Reads all project context before implementing
• 🎯 Auto-detection - Figures out type (frontend/backend), complexity, and focus areas
• 📝 Auto-documentation - Updates memory files so future work builds on this
• 🔄 Adaptive - Simple changes are fast, complex changes get proper planning

Example:

You: /mind:impl Optimize database query performance

Claude:
📖 PLAN: Reading memory... Detected Backend + Performance focus
        Creating optimization plan... [shows plan]
        Proceed? yes

🔧 ACT: [implements optimizations with progress bar]
📝 DOCUMENT: [updates active.md, patterns.md automatically]
✅ VALIDATE: 3 files optimized, 40% faster queries, tests passing
        Next: Add query caching, monitor production performance

Sharing Knowledge: /mind:promote

Share your personal discoveries with the team through reviewed PRs.

/mind:promote brief --commit --pr

What happens:

1. 📖 Reads your personal memory
2. 📝 Shows diff with team memory
3. 🚀 Copies to memory-bank/
4. 📦 Creates git commit
5. 🔀 Opens PR for team review

What to promote:

• ✅ Architectural decisions
• ✅ Discovered patterns
• ✅ Implementation plans
• ✅ Project insights

What to keep personal:

• ❌ Work-in-progress notes
• ❌ Experiments
• ❌ Personal task tracking

Recommended Workflows

Solo Developer:

/mind:impl [feature]     # Work fast, personal memory only
# Optionally promote discoveries:
/mind:promote patterns --commit

Team - Complex Feature:

/mind:plan [feature]    # Research in personal memory
/mind:promote plans/2025-10-12-feature.md --pr  # Share for discussion
# Team reviews plan in PR
/mind:impl [feature]     # Implement after approval

Team - Quick Feature:

/mind:impl [feature]     # Implement with team patterns
# Promote if you discover something reusable:
/mind:promote patterns --section "New Pattern"

Documentation

• 📖 Getting Started Guide - 5-minute tutorial
• 🏗️ Architecture Deep Dive - How it works
• 🤝 Contributing Guide - How to contribute

FAQ

Q: Does this work with any project? A: Yes! Claude analyzes your project semantically, so it works with ANY language, framework, or structure - even custom ones.

Q: What about privacy? A: All memory stored locally in your repo as text files. Nothing sent to external services.

Q: Do I need to update this when my stack changes? A: No! Just run /mind:sync and Claude will detect the changes automatically.

Q: How much token overhead? A: ~5-10% increase, but saves 30-50% by eliminating repeated explanations. Net benefit: 20-40% token reduction.

Q: Team collaboration? A: Yes! Dual-memory system:

• Personal memory (.claude/memory/) - Gitignored, your private notes
• Team memory (memory-bank/) - Committed to git, shared knowledge
• Use /mind:promote to share your discoveries with the team
• Team memory reviewed via PRs, no external services needed

Q: How is this different from Cline Memory Bank? A: Cline requires manual file creation. We bootstrap automatically AND use Claude's intelligence instead of hardcoded parsing.

Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

Roadmap

• [x] v1.0 - LLM-first architecture with semantic analysis
• [x] v1.1 - Intelligent implementation workflow (/mind:impl)
• [ ] v2.0 - Auto-sync hooks and enhanced context optimization

License

MIT - See LICENSE

Acknowledgments

Inspired by:

• Cline Memory Bank - Memory system concept
• SuperClaude Framework - Multi-phase workflow patterns

Adapted for Claude Code with self-bootstrapping and intelligent automation.

Built with ❤️ for the Claude Code community