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.