# BigMind Tools Reference

## Lifecycle (Session Management)
| Tool | Description | When to Use |
|------|-------------|-------------|
| `memory_start_session()` | Open new session, load context | First action every conversation |
| `memory_end_session(session_id, one_liner, topics, outcome, summary, importance=5)` | Close session with summary | Last action before closing |
| `memory_close_stale_sessions(session_id)` | Close all open sessions except current | Session start if multiple open |
| `memory_announce_focus(session_id, description, files, ide_hint)` | Declare session focus + files | Before editing files |
| `memory_get_active_sessions()` | List open sessions + focus/files | Check for conflicts |

## Search (Find Past Context)
| Tool | Description | When to Use |
|------|-------------|-------------|
| `memory_search_facts(query, limit=10)` | FTS5 search across stored facts | Reusable knowledge (preferences, codebase) |
| `memory_search_chunks(query, limit=10)` | FTS5 search across conversation chunks | Past decisions, code reviews |
| `memory_get_session_detail(session_id)` | Full Tier-2 narrative for past session | When Tier-1 index shows relevant session |
| `memory_list_sessions(limit=20, topics_filter)` | List past sessions | Browse history by topic/date |

## Storage (Save Knowledge)
| Tool | Description | When to Use |
|------|-------------|-------------|
| `memory_store_fact(category, fact, confidence=1.0)` | Store atomic reusable fact | New preferences, decisions, infrastructure |
| `memory_append_chunk(session_id, content, role, flag_reason)` | Append conversation chunk | Important exchanges (decisions, code) |
| `memory_flag_important(session_id, content, role, flag_reason)` | Flag exchange as Tier-3 memory | Significant decisions, code changes |
| `memory_log_token_save(session_id, description, tokens_saved, method_used)` | Log token efficiency savings | When using memory/CLI instead of full files |

## Hypotheses (Predictive Thinking)
| Tool | Description | When to Use |
|------|-------------|-------------|
| `memory_add_hypothesis(session_id, hypothesis, confidence=0.7)` | Form prediction/hypothesis | Before analysis, debugging, planning |
| `memory_resolve_hypothesis(hypothesis_id, status, resolution)` | Close hypothesis | When outcome known (confirmed/refuted) |
| `memory_list_hypotheses(status)` | List open/closed hypotheses | Review predictions |

## Maintenance (Health & Upgrades)
| Tool | Description | When to Use |
|------|-------------|-------------|
| `memory_get_stats()` | DB statistics (sessions, facts, chunks) | Monitor growth |
| `memory_health_check(stale_days=30)` | Diagnostic: stale facts, orphaned sessions | Monthly maintenance |
| `memory_vacuum(older_than_days=90)` | Prune old chunks | Keep DB lean |
| `memory_deprecate_fact(fact_id, reason)` | Mark fact as outdated | When knowledge changes |
| `memory_request_upgrade(session_id, description, reason, priority, certainty=0.7)` | Log feature request | Hit limitation, need new capability |
| `memory_get_instructions()` | Full BigMind usage guide | When unsure how to use memory

## Web UI (Profile & Monitoring)
| Tool | Description | When to Use |
|------|-------------|-------------|
| `memory_open_profile()` | Open profile page in browser | View stats, sessions, achievements |
| `memory_get_profile_url()` | Get profile URL for IDE browser | Quick access without leaving IDE