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:

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

5.9 KiB Raw Blame History Unescape Escape