Patrick Plate
155d56e8e8
- Move bigmind/ -> mcp/bigmind/ - Move webscraper/ -> mcp/webscraper/ - Move mss-failsafe/ -> java/mss-failsafe/ - Move Wellmann-Shop/ -> java/wellmann-shop/ (normalize to kebab-case) - Add .roo/ IDE config files to tracking - Add plans/REPO_STRATEGY.md (monorepo strategy document) - Expand .gitignore: Java/Maven, Node/TS, coverage, uv.lock - Rewrite README.md as navigation index - Update .roo/mcp.json webscraper path to mcp/webscraper/
135 lines
4.2 KiB
Markdown
135 lines
4.2 KiB
Markdown
# 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.
|
|
|