Patrick Plate
116 lines
5.9 KiB
Markdown
116 lines
5.9 KiB
Markdown
# 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 |
|