Patrick Plate
154 lines
8.1 KiB
Markdown
154 lines
8.1 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. This gives you the full picture beyond what the task message contains. Skip this only for trivially scoped tasks (single tool call, e.g., "commit this file" or "update Jira status").
|
||
|
||
**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. Do NOT:
|
||
- Ask the user follow-up questions (put open questions in your documents instead)
|
||
- Suggest mode switches ("recommend switch to X mode")
|
||
- Enter a feedback/revision loop with the user
|
||
- Wait for GO/NO-GO decisions (that's the Orchestrator's job)
|
||
|
||
Instead: do your work → produce your artifacts → call `attempt_completion` with a summary of what was produced.
|
||
|
||
## 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
|
||
```
|
||
|
||
For PAISY/ADP domain topics — also check:
|
||
```
|
||
4. ADP Docs Wiki (adpdocs-index facts → get-page directly)
|
||
5. Confluence (search_confluence_by_cql)
|
||
6. Bitbucket PRs/commits (get_pull_request, git_log)
|
||
```
|
||
|
||
**Priority:** BigMind facts → BigMind chunks → ADP Docs Wiki → Confluence → Bitbucket → webscraper (last resort)
|
||
|
||
**FTS5 rule:** AND-matches every token. Max 3 short keywords. Long queries return 0 results.
|
||
|
||
**Never go straight to webscraper** if BigMind or Wiki MCP can answer it.
|
||
|
||
## 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 Patrick 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 |
|
||
| | `memory_request_upgrade(description, reason)` | Log desired BigMind feature |
|
||
| | `memory_list_upgrade_requests()` | See pending requests |
|
||
| | `memory_resolve_upgrade_request(id, status)` | Mark done/rejected |
|
||
| **Web UI** | `memory_open_profile()` | Open profile page in browser |
|
||
| | `memory_get_profile_url()` | Get URL for IDE built-in browser |
|
||
| **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 |
|
||
| | `memory_link_ai(username, bigmind_user)` | Link contact to their BigMind |
|
||
| **Diff** | `memory_diff_sessions(since_session_id)` | What changed since a session |
|
||
|
||
## ADP Docs Wiki
|
||
|
||
Wiki registered as `mcp://wikis/adpdocs.de.adp.com`.
|
||
|
||
**Workflow — always in this order:**
|
||
1. `memory_search_facts("topic adpdocs")` — check BigMind index first (category: `adpdocs-index`)
|
||
2. If Page ID known → `set-wiki` + `get-page "Seitentitel"` directly
|
||
3. If not known → `search-page query="..."` or `get-category-members category="..."`
|
||
4. After finding a useful page → `memory_store_fact(category="adpdocs-index", ...)` immediately
|
||
|
||
**Key categories:** `Meldeverfahren`, `Verwalterhandbuch`, `Batchabläufe`, `Client Server (CS)`, `PAISYadvanced`, `Installationshandbuch für Windows und UNIX`
|
||
|
||
**Known Page IDs in BigMind** (Facts #153–160, category `adpdocs-index`):
|
||
- Fehlercodes Batch, Meldeverfahren-Seiten (EAU/EuBP/DaBPV/DSBD/DSVV/...), Verwalterhandbuch-Seiten, Batch-Einzelaufrufe, Installation
|