pi_mcps/mcp/bigmind

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

# 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):

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

# 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 for full architectural details.