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:

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:

memory_search_facts("topic adpdocs") — check BigMind index first (category: adpdocs-index)
If Page ID known → set-wiki + get-page "Seitentitel" directly
If not known → search-page query="..." or get-category-members category="..."
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

8.1 KiB Raw Blame History Unescape Escape