vibeship-mind 3.0.2

Context graph memory system for AI coding assistants

Mind

Mind gives Claude a mind - not just memory across sessions, but focus within them. It remembers what worked, what didn't, and what it's supposed to be building.

When you're vibe coding with Claude, it forgets everything between sessions. What you decided, what broke, what worked - gone. Even worse, in long sessions it starts suggesting the same failed fixes over and over.

Mind fixes both problems with two-layer memory:

• MEMORY.md - Long-term memory across sessions
• SESSION.md - Short-term focus within a session

---

Why Mind?

3 steps. Install, init, connect. Done.

Fully automated. Memory just works - no commands required:

• Claude writes memories as it works
• Session gaps auto-detected (30 min)
• Learnings auto-promoted to long-term memory
• Context auto-injected into CLAUDE.md
• Reminders auto-surface when due or when keywords match

Optional tools are there when you want them, but the core memory flow runs hands-free.

Two-layer memory:

• Cross-session recall (MEMORY.md)
• Within-session focus (SESSION.md)

Zero friction. Claude writes to files, MCP reads them lazily. No database, no cloud, no sync issues.

Human-readable. Plain .md files you can open, edit, or git-track anytime.

Open source. See exactly how it works. No black box.

---

Ready to Give Claude a Mind?

3 steps. Zero friction.

1. Install Mind

pip install vibeship-mind

To upgrade to the latest version:

pip install vibeship-mind --upgrade

2. Initialize in your project

Open a terminal in your project folder, then run:

python -m mind init

3. Connect to Claude Code

Copy and paste this to Claude:

Add Mind MCP server to my config. Use command "python" with args ["-m", "mind", "mcp"]

Claude will set it up for you. Restart Claude Code after, and Mind will work automatically.

Manual setup (if you prefer)

Add to your MCP config file:

Mac/Linux: ~/.claude.json Windows: %USERPROFILE%\.claude.json

{
  "mcpServers": {
    "mind": {
      "command": "python",
      "args": ["-m", "mind", "mcp"]
    }
  }
}

Save the file, then restart Claude Code.

---

Alternative: Install from source

git clone https://github.com/vibeforge1111/vibeship-mind.git
cd vibeship-mind
uv sync
uv run mind init

MCP config for source install:

{
  "mcpServers": {
    "mind": {
      "command": "uv",
      "args": ["--directory", "/path/to/vibeship-mind", "run", "mind", "mcp"]
    }
  }
}

---

What's New in 3.0.0 (v3)

Mind v3 adds a semantic context graph that runs alongside your existing MEMORY.md:

• Real Semantic Search - Uses sentence-transformers (all-MiniLM-L6-v2) for meaning-based retrieval
• Entity Extraction - Automatically detects files, functions, and concepts from conversations
• Decision Tracking - Structured storage with reasoning, alternatives, and confidence scores
• Query Expansion - Searches find related content even with different wording
• Cross-Encoder Reranking - Results ranked by actual relevance, not just keyword match
• Pattern Detection - Learns your preferences, habits, and blind spots over time
• 874 Tests - Comprehensive coverage for production stability

Upgrading from v2

Step 1: Upgrade

pip install vibeship-mind --upgrade

Step 2: Done. That's it - migration is automatic.

When you use Mind after upgrading, it automatically:

• Detects your existing MEMORY.md
• Migrates all content to v3 structured tables
• Preserves everything - no data loss

Both systems stay in sync - every mind_log() writes to both v2 and v3.

.mind/
├── MEMORY.md          ← v2 (still works, human-readable)
├── SESSION.md         ← v2 (session tracking)
└── v3/
    └── graph/         ← v3 (LanceDB vector database)
        ├── memories.lance
        ├── decisions.lance
        ├── entities.lance
        └── ...

Optional: View Your Migrated Data

# See migration stats
mind migrate .

# Generate human-readable views
mind generate-views .

This creates DECISIONS.md, PATTERNS.md, and POLICIES.md in your .mind/ folder.

If Migration Didn't Run (edge cases)

mind migrate . --force

---

What's New in 2.3.0

• Logging Levels - Choose Efficient/Balanced/Detailed modes to control what gets logged
• Usage-Based Retention - Memories decay if unused, stay relevant if accessed frequently
• 413 Tests - Comprehensive test coverage for stability

To upgrade to the newest version: pip install vibeship-mind --upgrade

Previous (2.2.0)

• Semantic Search - mind_search() uses TF-IDF similarity, not just keywords
• Loop Detection - Warns when you're about to repeat a rejected approach
• Smart Promotion - Deduplicates memories, links related entries
• Memory <-> Session Flow - Relevant memories surface when logging blockers

---

MCP Tools (12 total)

Core:

Tool	What it does
mind_recall()	Load session context - CALL FIRST every session
mind_log(msg, type)	Log to session or memory (routes by type)

Type routing for mind_log():

• SESSION.md: experience, blocker, assumption, rejected
• MEMORY.md: decision, learning, problem, progress
• SELF_IMPROVE.md: feedback, preference, blind_spot, skill
• Special: reinforce (boosts pattern confidence)

Reading:

Tool	What it does
mind_session()	Check current session state
mind_search(query)	Semantic search past memories
mind_status()	Check memory health
mind_reminders()	List pending reminders

Actions:

Tool	What it does
mind_blocker(desc)	Log blocker + auto-search memory for solutions
mind_remind(msg, when)	Set reminder - time or context-based
mind_reminder_done(index)	Mark a reminder as done
mind_edges(intent)	Check for gotchas before risky code
mind_checkpoint()	Force process pending memories
mind_add_global_edge()	Add cross-project gotcha

---

How It Works

Long-term (MEMORY.md): Permanent knowledge - decisions, learnings, problems, progress. mind_recall() loads this as context each session.

Short-term (SESSION.md): Working memory buffer:

• Experience - Raw moments, thoughts, what's happening
• Blockers - Things stopping progress
• Rejected - What didn't work and why
• Assumptions - What you're assuming true

When a new session starts (30 min gap), valuable items get promoted from SESSION.md to MEMORY.md automatically.

See docs/HOW_IT_WORKS.md for the full architecture.

---

Reminders

Mind supports two types of reminders:

Time-based:

• "tomorrow", "in 3 days", "next session", "2025-12-20"

Context-based:

• "when I mention auth" - triggers when relevant keywords come up
• "when we work on database" - Claude sees keywords and surfaces reminder naturally

Example: "Remind me to check the security audit when we work on auth"

Reminders are stored in .mind/REMINDERS.md and shown in mind_recall() output.

---

Initialize Mind in Any Project

Open a terminal in your project folder and run:

python -m mind init

That's it! This creates .mind/MEMORY.md and .mind/SESSION.md.

---

Quick Commands

# Check if everything is working
python -m mind doctor

# See what Mind extracted from your notes
python -m mind parse

# Check project status
python -m mind status

# List all registered projects
python -m mind list

---

Useful Prompts for Claude

Copy-paste these prompts to Claude to get the most out of Mind:

1. Check Health

Check Mind's health and tell me if anything needs attention

2. View Session State

Show me my current session state - what have we tried and what's blocked?

3. Review Decisions

What decisions have we made in this project?

4. Search Memories

Search my memories for anything related to [topic]

5. Find Gotchas

What gotchas or learnings do we have about [topic]?

6. Log a Decision

Log this as a decision: [your decision and reasoning]

7. Set Time Reminder

Remind me to [task] tomorrow

8. Set Context Reminder

Remind me to [task] when we work on [feature]

9. List Reminders

Show me all my pending reminders

10. Complete Reminder

Mark reminder [number] as done

11. Check Progress

What were we working on? Check the session

12. Log Failed Approach

Log that we tried [approach] and it didn't work because [reason]

13. Review Assumptions

What assumptions are we making right now?

14. Log a Learning

Log this learning: [what you discovered]

15. Log a Blocker

I'm stuck on [problem] - log it and search for solutions

16. Check for Gotchas Before Coding

Before I implement [feature], check for any gotchas

17. Force Memory Sync

Force process any pending memories now

18. Add Project Gotcha

Add this as a project gotcha: [issue and workaround]

19. Upgrade Mind

Help me upgrade Mind to the latest version

Then run: pip install vibeship-mind --upgrade

20. Initialize New Project

Initialize Mind in [project path]

Then run: python -m mind init /path/to/project

---

The Problem This Solves

Across sessions:

• "What did we decide yesterday?" -> Forgotten
• "What gotchas did we hit?" -> Re-discovered every time

Within sessions:

• "Didn't we already try that?" -> Suggests same failed fix 3 times
• "What are we building again?" -> Drifts into rabbit holes

Mind fixes both. Two layers of memory, zero friction.

---

File Structure

your-project/
├── .mind/
│   ├── MEMORY.md     <- Long-term memory (persists)
│   ├── SESSION.md    <- Short-term focus (cleared each session)
│   ├── REMINDERS.md  <- Time and context-based reminders
│   ├── config.json   <- Feature flags for experiments
│   └── state.json    <- Timestamps for session detection
└── CLAUDE.md         <- Mind injects context here

---

Troubleshooting

Problem	Fix
"Command not found"	Use python -m mind instead of just mind
Nothing being captured	Use keywords: decided, problem, learned, gotcha
Claude repeating mistakes	Tell Claude: "Check SESSION.md" or "Add to Rejected Approaches"
Need to check health	Run python -m mind doctor

---

Documentation

• Architecture - Technical deep-dive, design principles
• How It Works - Visual diagrams explaining the system
• MCP Tools - Full tool reference with parameters

---

License

Apache 2.0 - See LICENSE for details.

---

Built by @meta_alchemist

A vibeship.co ecosystem project