pi_mcps/.roo/rules-bigmind/00-bigmind-behavior.md

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. Create a branch (MANDATORY — never work on main):

   git checkout -b feat/bigmind/feature-name
   # or fix/bigmind/bug-name for a bug fix
   

4. Announce Focus (include branch name): memory_announce_focus(session_id, "BigMind: adding feature X on branch feat/bigmind/feature-name", files=["bigmind/db.py", "bigmind/memory_store.py"], ide_hint="VS Code")
5. 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