Patrick Plate
dabdda167f
- Extract all wiki content from create_wiki_pages.py into docs/wiki/pages/*.md - Add docs/wiki/deploy_wiki.sh: copies pages to wiki/ repo, commits, pushes - Add /wiki/ to .gitignore (anchored — does not affect docs/wiki/) - 12 pages: Home, MCP-Servers-Overview, mcp-image-gen, ComfyUI-Setup, mcp-webscraper (8 tools incl. search_hint), BigMind (schema v8), Development-Conventions, Java-Projects, Java-wellmann-shop, Java-mss-failsafe, Java-Architecture, _Sidebar - Workflow: edit docs/wiki/pages/*.md → ./docs/wiki/deploy_wiki.sh
126 lines
4.6 KiB
Markdown
126 lines
4.6 KiB
Markdown
# 🧠 BigMind — Persistent AI Memory
|
|
|
|
|
|
|
|
**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)`
|