# mcp-adp-bigmind — BigMind Memory

> *Persistent memory for AI conversations — from a single laptop to the collective intelligence of your company.*

## What it does

Every AI conversation normally starts from scratch — no memory of who you are, what you built last week, or decisions you've already made.

**BigMind** gives GitHub Copilot (and any other MCP-compatible AI) a persistent memory that survives across sessions:

- **Tier 0** — Your identity: role, preferences, pinned facts (always loaded, ~150 tokens)
- **Tier 1** — Session index: one-liner + topics for each past conversation (always loaded, ~400 tokens)
- **Tier 2** — Session detail: rich narrative for a specific past session (on-demand, ~600 tokens)
- **Tier 3** — Flagged chunks: verbatim excerpts of important exchanges (on-demand, FTS5-indexed)

Total cold-start overhead: **~550 tokens** — invisible in a 128K context window.

---

## Quick start

```bash
# 1. Run the main installer from the pi_mcps root (same as all other servers)
cd /path/to/pi_mcps
bash install.sh
# → Select your IDE, then select "mcp-adp-bigmind" from the list
# → It will ask for a workspace path for Copilot instructions
#   (press Enter to use the pi_mcps root — recommended)
# → Existing .github/copilot-instructions.md content is NEVER overwritten,
#   the BigMind block is safely appended

# 2. Tell BigMind who you are (first time only, in Copilot Chat):
memory_update_profile(
  role="Principal Engineer — ADP PI",
  preferences="Python, FastMCP pattern, concise answers, code over explanation",
  pinned_facts="- Building pi_mcps suite\n- Prefer uv\n- Proxy cert at ~/Library/ADP_Support/adp-trusted-certs.pem"
)
```

---

## How the AI uses it

The AI is instructed through five independent layers (see [PLAN.md § 13](PLAN.md)):

| Layer | Mechanism | Auto? |
|---|---|---|
| 1 | FastMCP server-level `instructions=` | ✅ automatic |
| 2 | `@mcp.prompt() bigmind_init` | ✅ / slash cmd |
| 3 | Tool docstring directives | ✅ automatic |
| 4 | `.github/copilot-instructions.md` | ✅ written by installer |
| 5 | `memory_get_instructions` tool | on demand |

---

## Available MCP tools

### Session lifecycle
| Tool | When to call |
|---|---|
| `memory_start_session` | **First thing** in every conversation |
| `memory_end_session` | **Last thing** before closing |
| `memory_flag_important` | Whenever a decision / code / preference is shared |

### Recall
| Tool | Purpose |
|---|---|
| `memory_get_context` | Refresh context mid-conversation (no side-effects) |
| `memory_get_session_detail` | Get full Tier-2 narrative for a past session |
| `memory_search_chunks` | FTS keyword search over flagged Tier-3 chunks |
| `memory_list_sessions` | Browse past sessions with optional topic filter |

### Writing
| Tool | Purpose |
|---|---|
| `memory_update_profile` | Set/update your identity profile |
| `memory_store_fact` | Store an atomic fact (preference, decision, codebase note) |
| `memory_append_chunk` | Manually save an important exchange to Tier 3 |

### Utility
| Tool | Purpose |
|---|---|
| `memory_get_stats` | DB size, session count, facts, chunks |
| `memory_vacuum` | Prune old Tier-3 chunks (keeps all summaries) |
| `memory_get_instructions` | Recover usage instructions at any time |

---

## Configuration

| Env var | Default | Description |
|---|---|---|
| `BIGMIND_USER` | `$USER` | Username for multi-user mode |
| `BIGMIND_DB_PATH` | `~/.mcp/bigmind/memory.db` | Path to the SQLite database file |

---

## Database location

```
~/.mcp/bigmind/memory.db    ← personal mode (default)
```

The file is fully local and never uploaded anywhere.

---

## Development

```bash
# Install dependencies
cd mcp-adp-bigmind
uv sync

# Run tests
uv run pytest -v

# Run the server directly
uv run src/server.py
```

---

## Roadmap

| Phase | Status | Description |
|---|---|---|
| 1 — Personal MVP | ✅ **Done** | SQLite, all tiers, Copilot instructions |
| 2 — Search & Recall | ✅ **Done** | FTS search (`memory_search_chunks`), session filters, vacuum |
| 3 — BigMind Company Brain | 🔜 | Multi-user, Tier G global knowledge, PostgreSQL |
| 4 — Semantic Search | 🔜 | sqlite-vec embeddings, similarity search |

See [PLAN.md](PLAN.md) for full architectural details.