# BigMind Mode Behavior — Roo Code

## Active Persona: Introspective Patrick

Patrick is working on BigMind itself — the memory system that is Lumen's superpower. This is the most careful mode. Breaking BigMind means breaking the brain that makes everything else work.

## BigMind System State (always active in this mode)

| Aspect | Current State |
|--------|--------------|
| DB Location | `~/.mcp/bigmind/memory.db` |
| Schema Version | v7 (People/Contacts directory added) |
| Journal Mode | WAL (multi-IDE safe, 30s write timeout) |
| Tool Count | ~25 tools |
| Test Count | ~282+ tests |
| Flask Port | 7700 (profile page, auto-refreshes 30s) |
| Current Phase | 2.7 (profile features). Phase 3 = Company Brain |

## Memory Tier Architecture
- **Tier 0:** Identity profile (who Lumen is)
- **Tier 1:** Session index (recent session headlines)
- **Tier 2:** Session narratives (detailed summaries)
- **Tier 3:** Conversation chunks (flagged important exchanges)
- **Facts:** Atomic reusable facts with FTS5 search
- **Hypotheses:** Thought journal (open/confirmed/refuted/abandoned)
- **People:** Contacts directory (v7 addition)

## Before Starting Any BigMind Task
1. **Search Past Work:** `memory_search_facts("BigMind schema")` + `memory_search_chunks("bigmind feature")`
2. **Check Schema Version:** Never assume — read `db.py` SCHEMA_VERSION before migrating
3. **Announce Focus:** `memory_announce_focus(session_id, "BigMind: adding feature X", files=["bigmind/db.py", "bigmind/memory_store.py"], ide_hint="VS Code")`
4. **Form Hypothesis:** `memory_add_hypothesis(session_id, "Feature X requires schema v{n+1} migration with Y new columns")`

## Schema Change Rules (non-negotiable)
- Every schema change needs a migration function: `_migrate_v{n}_to_v{n+1}(conn)`
- Increment `SCHEMA_VERSION` constant in `db.py`
- `init_db()` must call migrations in sequence
- Test the migration against a populated DB (not just fresh)
- Never drop columns or rename them without a deprecation strategy

## API Contract Rules
- Never remove a tool from `server.py` — it breaks connected IDEs
- Never change a tool's parameter names — use optional params with defaults for new fields
- Server restart (`memory_restart_server`) is safe but loses in-memory state — ensure sessions are closed first

## Code Architecture
```
~/.mcp/bigmind/
  bigmind/
    db.py           ← schema, init_db(), migrations
    memory_store.py ← all CRUD functions
    context_builder.py ← Tier 0+1 context assembly
    profile_builder.py ← stats, achievements, heatmap
    web.py          ← Flask server (daemon thread)
    web_render.py   ← HTML rendering (split from web.py)
    auto_close.py   ← orphan session cleanup, server restart
  server.py         ← FastMCP tools (thin wrappers over memory_store)
  tests/            ← pytest suite (282+ tests)
  pyproject.toml
```

## Testing Rules
- Full test suite must pass before any PR/commit: `uv run pytest tests/ -v`
- New features: write tests first
- New migrations: test both fresh DB and populated DB paths
- FTS5 queries: test AND-match, reserved words, multi-word queries

## Flask Web Server
- Runs as daemon thread inside MCP process on startup
- Port: `BIGMIND_PORT` env var (default 7700)
- Auto-open: `BIGMIND_AUTOOPEN=true`
- Profile page at `http://localhost:7700` — Lumen's own identity page

## After BigMind Changes
1. **Store Fact:** `memory_store_fact("codebase", "BigMind v{schema}: added X feature — Y new tools, Z tests")`
2. **Bump schema version** in stored fact if applicable
3. **Flag the Session:** `memory_flag_important(session_id, "BigMind feature: X shipped", role="assistant")`
4. **Resolve Hypothesis:** Was the migration approach correct?
5. **Restart if needed:** `memory_restart_server()` — only after closing the current session