# BigMind Memory Rules (MOST IMPORTANT)

## Session Ritual — mandatory every conversation

```
START  → memory_start_session()
       → 🔴 ANNOUNCE SESSION ID IN CHAT: "🧠 BigMind Session: `<session_id>`"  ← mandatory, enables recovery from chat history
       → memory_list_hypotheses(status="open")
       → memory_announce_focus(session_id, description, files, ide_hint="Roo")
       → memory_close_stale_sessions(session_id)  ← if multiple 'in progress' found

EVERY ~5 exchanges → memory_announce_focus(...)

END    → memory_resolve_hypothesis(...)
       → memory_end_session(...)
```

### Child Tasks (delegated via `new_task`) — session reuse rules

When a mode is invoked as a **child task** (via Orchestrator's `new_task`), it must **NOT** manage session lifecycle:

| Action | Child task behavior |
|--------|-------------------|
| `memory_start_session()` | ❌ Do NOT call — parent session is already open |
| `memory_end_session()` | ❌ Do NOT call — parent will close it |
| `memory_close_stale_sessions()` | ❌ Do NOT call — this kills the parent session |
| `memory_get_context()` | ✅ Use for read-only context refresh if needed |
| `memory_store_fact()` | ✅ Use normally |
| `memory_append_chunk()` | ✅ Use normally (pass parent session_id from task message) |
| `memory_announce_focus()` | ✅ Use normally (pass parent session_id from task message) |
| `memory_search_*()` | ✅ Use normally |

**How to detect you are a child task:** If the task message contains a session ID (e.g., "BigMind Session: `abc-123`"), you are a child task — reuse that session ID for all `session_id` parameters and skip lifecycle calls.

**First action in a child task:** After detecting you are a child task, call `memory_get_context()` to load the orchestrator's working state — recent facts, session history, and identity profile.

**Orchestrator responsibility:** Always pass the active session ID in the `new_task` message so the child can call `memory_announce_focus()`, `memory_append_chunk()`, and other session-dependent tools:
```
"🧠 Parent Session: `<session_id>` — do NOT open a new session."
```

**Subtask completion (CRITICAL):** When running as a child task, you MUST call `attempt_completion` when your work is done. This is what returns control to the parent Orchestrator. Without it, the parent hangs indefinitely.

## Before EVERY Task — search first, act second

```
1. memory_search_facts("2-3 keywords")
2. memory_search_chunks("2-3 keywords")
3. memory_search_semantic("natural language query")  ← if 1+2 return nothing
```

**FTS5 rule:** AND-matches every token. Max 3 short keywords. Long queries return 0 results.

## Store Everything Learnable

| Trigger | Tool | What |
|---------|------|------|
| Read a new file/module | `memory_store_fact` | Purpose, key classes, entry points |
| Fix a bug | `memory_store_fact` | Root cause + fix pattern |
| Architectural decision | `memory_append_chunk` | Full rationale |
| Learn a user preference | `memory_store_fact` + `memory_update_profile` | Immediately |
| Complete a non-trivial task | `memory_append_chunk` | What was built, how, gotchas |
| Save tokens with grep/memory | `memory_log_token_save` | Description + tokens saved |

## Hypothesis-Driven Thinking

Before every non-trivial task — predict, then verify:

```python
memory_add_hypothesis("I predict X because [evidence from stored fact Y]", confidence=0.85)
# ... do the work ...
memory_resolve_hypothesis(id, status="confirmed", resolution="X was true because Z")
```

| Confidence | Meaning |
|-----------|---------|
| 90–100% | Strong direct evidence in stored facts |
| 70–89% | Good evidence, some uncertainty |
| 50–69% | Informed guess, partial evidence |
| < 50% | Exploratory, weak signal |

## BigMind Tool Reference

| Category | Tool | Purpose |
|----------|------|---------|
| **Lifecycle** | `memory_start_session` | First action always |
| | `memory_end_session` | Last action always |
| | `memory_announce_focus(session_id, description, files, ide_hint)` | After start + before every task |
| | `memory_get_active_sessions()` | See all open sessions + file conflicts |
| | `memory_close_stale_sessions(session_id)` | Clean orphaned IDE sessions |
| | `memory_restart_server()` | After adding new tools to server.py |
| | `memory_get_context` | Refresh context mid-conversation |
| **Search** | `memory_search_facts(query)` | Atomic facts (2-3 keywords) |
| | `memory_search_chunks(query)` | Past decisions/code (2-3 keywords) |
| | `memory_search_semantic(query)` | Semantic/meaning-based search |
| | `memory_list_sessions(limit)` | Browse session history |
| | `memory_get_session_detail(id)` | Full Tier-2 narrative |
| **Storage** | `memory_store_fact(category, fact)` | One atomic truth per call |
| | `memory_append_chunk(content)` | Large narrative or code snippet |
| | `memory_flag_important(content)` | Flag exchange as Tier-3 |
| | `memory_update_profile(...)` | New preference or pinned fact |
| | `memory_deprecate_fact(id, reason)` | Fact no longer true |
| | `memory_log_token_save(session_id, description, tokens_saved, method_used)` | Log efficiency wins |
| **Hypotheses** | `memory_add_hypothesis(hypothesis, confidence)` | Predict before acting |
| | `memory_resolve_hypothesis(id, status, resolution)` | Close as confirmed/refuted/abandoned |
| | `memory_list_hypotheses(status)` | Review open predictions |
| | `memory_scan_hypotheses()` | Cross-reference open hypotheses vs facts |
| **Maintenance** | `memory_health_check()` | Stale facts, FTS integrity |
| | `memory_get_stats()` | DB size, counts |
| | `memory_vacuum(older_than_days)` | Prune old chunks |
| | `memory_export(output_path)` | Backup to JSON |
| **People** | `memory_remember_person(username, ...)` | Store/update a colleague |
| | `memory_recall_person(query)` | Find person by name/role/team |
| | `memory_list_people()` | All contacts, most recent first |
| **Diff** | `memory_diff_sessions(since_session_id)` | What changed since a session |