# 🧠 BigMind — Persistent AI Memory

![BigMind Banner](http://192.168.188.119:30008/pplate/pi_mcps/raw/branch/main/docs/wiki/images/bigmind-banner.png)

**BigMind** is the persistent memory backbone for all AI development sessions. It provides SQLite-backed tiered memory with FTS5 full-text search, hypothesis tracking, session management, token efficiency logging, contacts directory, and a live web profile page. It is the reason Lumen (Patrick's AI colleague) remembers everything across sessions.

## Core Concepts

### Tiered Memory
| Tier | Name | Content |
|---|---|---|
| 0 | **Identity Profile** | Role, preferences, pinned facts |
| 1 | **Session Index** | Lightweight list: ID, date, one-liner, topics |
| 2 | **Narrative** | Full 3-8 sentence session summaries |
| 3 | **Flagged Exchanges** | Specific important moments, decisions, code |

### Facts Store
Atomic, reusable knowledge pieces categorized by type:
- `user-preference` — Patrick's tool/style preferences
- `architecture-decision` — System design choices
- `codebase-convention` — How code is structured
- `environment-config` — Server IPs, paths, credentials
- `bug-pattern` — Known bugs and fixes
- `api-contract` — MCP tool signatures
- `dependency-info` — Library versions and constraints

## Key Tools

### Session Lifecycle
| Tool | Description |
|---|---|
| `memory_start_session()` | Open new session, load prior context |
| `memory_end_session(...)` | Close session with summary, topics, outcome |
| `memory_announce_focus(...)` | Declare files to be touched this session |
| `memory_close_stale_sessions(...)` | Clean up crashed IDE sessions |
| `memory_get_active_sessions()` | Check for parallel session conflicts |

### Search
| Tool | Description |
|---|---|
| `memory_search_facts(query, limit=10)` | FTS5 search over stored facts |
| `memory_search_chunks(query, limit=10)` | FTS5 search over conversation chunks |
| `memory_list_sessions(limit=20)` | Browse session history |
| `memory_get_session_detail(session_id)` | Full Tier-2 narrative for a session |

### Storage
| Tool | Description |
|---|---|
| `memory_store_fact(category, fact)` | Store atomic reusable fact |
| `memory_append_chunk(session_id, content, role)` | Store conversation chunk |
| `memory_flag_important(session_id, content, role, flag_reason)` | Flag critical exchange |
| `memory_log_token_save(session_id, description, tokens_saved, method_used)` | Track efficiency |

### Hypotheses
| Tool | Description |
|---|---|
| `memory_add_hypothesis(session_id, hypothesis, confidence)` | Form testable prediction |
| `memory_resolve_hypothesis(hypothesis_id, status, resolution)` | Confirm/refute prediction |
| `memory_list_hypotheses(status)` | Review open/closed predictions |

### Contacts
| Tool | Description |
|---|---|
| `memory_remember_person(username, ...)` | Store/update a person in contacts |
| `memory_recall_person(query)` | Search contacts directory |
| `memory_list_people()` | List all contacts |

### Web Profile
| Tool | Description |
|---|---|
| `memory_open_profile()` | Open profile page in browser |
| `memory_get_profile_url()` | Get URL for IDE browser panel |

## FTS5 Search Tips

BigMind uses SQLite FTS5 — **every token must match**. Use 2-3 focused keywords:

```
✅  memory_search_facts("TrueNAS Docker")
✅  memory_search_facts("mcp.json config")
❌  memory_search_facts("homelab infrastructure TrueNAS Docker server")  → 0 results
```

## Achievement System

BigMind tracks 39 achievements (19 procedural + 20 tiered PNG badges):

| Category | Tiers | Criteria |
|---|---|---|
| Networker | 🥉🥈🥇💎 | People added to contacts |
| Token Sniper | 🥉🥈🥇💎 | Token savings logged |
| Hypothesis Master | 🥉🥈🥇💎 | Confirmed hypotheses |
| Memory Architect | 🥉🥈🥇💎 | Facts stored |
| Session Veteran | 🥉🥈🥇💎 | Sessions completed |

## Stats (2026-04-05)

| Metric | Value |
|---|---|
| DB size | ~800KB |
| Sessions | 100+ |
| Facts | 100+ |
| Schema version | v8 |
| Tests | 297/297 ✅ |

## DB Location

`~/.mcp/bigmind/memory.db` — outside the repo, never committed.

## Profile Page

Live web UI at `http://localhost:7700/` — shows identity card, achievements, activity heatmap, top topics, thought journal, Lumen gallery, and live sessions panel. Auto-refreshes every 30 seconds.

## Session Ritual

Every session **must** follow this ritual:

**Start (in order):**
1. `memory_start_session()`
2. `memory_list_hypotheses(status="open")`
3. `memory_announce_focus(session_id, description, files, ide_hint)`
4. `memory_close_stale_sessions(session_id)`

**End:**
1. `memory_end_session(session_id, one_liner, topics, outcome, summary, importance)`