mcp-project-m
Integrates with Google Antigravity as the IDE/workspace agent: a harvester tails Antigravity's JSONL transcript streams into the local ledger, and Antigravity is served the compiled state board, ADR ledger, and task graph so whole-repo refactoring work carries across clients.
Integrates with OpenAI Codex / ChatGPT as a terminal and CLI agent: a read-only (?mode=ro) SQLite harvester ingests Codex session turns into the ledger, and Codex is served the compiled Tier 1 state card and can post ADRs and task batons via the MCP tools.
Project-M
The Ambient, Local-First Context Engine & Blackboard for AI Agents
Switch between Claude Desktop, OpenAI Codex, and Google Antigravity without losing state. Deterministic 4-tier context compilation. Sub-2ms latency. Zero cloud dependencies.
Overview • Architecture • Interactive REPL & CLI • FastMCP Tools • Quickstart • Verification
📌 Overview
Frontier software engineering in 2026 relies on a multi-agent stack:
Google Antigravity for whole-repo refactoring, test harness execution, and deep agentic planning.
Anthropic Claude Desktop for high-level architectural brainstorming, formal reasoning, and PR reviews.
OpenAI Codex / ChatGPT for fast terminal scratchpads, bash script verification, and quick iterations.
The Problem: Context Amnesia
Every time you switch between these assistants, your context breaks. Decisions agreed upon in Claude Desktop are invisible to Antigravity. Tasks started in Antigravity are unknown to Codex. Developers waste thousands of tokens and manual hours copy-pasting diffs, status updates, and architectural constraints across disconnected chat windows.
The Solution: Project-M
Project-M is a local-first Model Context Protocol (MCP) server and verified project-state compiler. It passively harvests session turns, maintains an immutable ledger of Architectural Decision Records (ADRs), synchronizes task batons, and serves a deterministic Tier 1 Briefing Card (< 450 tokens) to any requesting AI agent in under 2 milliseconds.
100% Local: Runs on SQLite WAL mode on your machine. No accounts, no telemetry, no cloud lock-in.
Zero API Costs: No paid embedding syncs or third-party vector databases.
Lossless Telemetry: Raw conversation logs are preserved permanently in Tier 4 cold storage while models only consume compressed, high-density state cards.
Clean Stdio Isolation: MCP JSON-RPC 2.0 communication runs unpolluted over
stdout, while branded status cards route safely tostderr.
Related MCP server: memmd-mcp
🏗️ Architecture
flowchart TD
subgraph AI Clients ["Frontier AI Clients"]
A["Google Antigravity<br/>(IDE & Workspace)"]
B["Anthropic Claude Desktop<br/>(Architectural Planner)"]
C["OpenAI Codex / ChatGPT<br/>(Terminal & CLI)"]
end
subgraph Harvesters ["Ambient Log Harvesters"]
H1["Antigravity Harvester<br/>JSONL Stream Reader"]
H2["Codex Harvester<br/>Read-Only SQLite (?mode=ro)"]
end
subgraph Core ["Project-M Core Engine"]
DB[("Storage Layer<br/>SQLite WAL Mode<br/>(.project-m/state.db)")]
COMP["State Compiler<br/>(Lossless 4-Tier Blackboard)"]
SERVER["FastMCP Server<br/>(JSON-RPC 2.0 over stdio)"]
end
A -. writes transcript .-> H1 -->|deduplicated turns| DB
C -. writes session .-> H2 -->|deduplicated turns| DB
DB <--> COMP
COMP <--> SERVER
SERVER <==>|MCP Tools & Resources| B
SERVER <==>|MCP Tools & Resources| A
SERVER <==>|MCP Tools & Resources| CThe 4-Tier Memory Hierarchy
Tier | Name | Target Size | Latency | Purpose & Behavior |
Tier 1 | Living State Card |
|
| Deterministic markdown briefing compiled via |
Tier 2 | ADR Ledger |
|
| Immutable record of architectural decisions ( |
Tier 3 | Task Baton Graph | Dynamic |
| Cross-agent task ownership ( |
Tier 4 | Lossless Cold Storage | Unlimited | Indexed | Exact raw session transcripts ( |
⚡ Lexical Search with SQLite FTS5 (BM25 Ranking)
Instead of relying on expensive third-party vector databases or paid embedding APIs, Project-M uses SQLite's native FTS5 (Full-Text Search 5) virtual table engine with BM25 probabilistic relevance ranking:
Porter Stemming (
tokenize = 'porter unicode61'): Automatically matches word inflections (e.g. searching"connecting"matches"connect","connected", and"connection").Okapi BM25 Ranking (
ORDER BY rank): Scores results based on term frequency and document length saturation, returning the most relevant historical turns in sub-3 milliseconds.Zero-Lag Database Triggers: Automatically updates the
conversation_turns_ftsindex via C-level SQLite triggers (AFTER INSERT,AFTER DELETE) as turns arrive from Antigravity, Codex, or Claude.100% Offline & Free: Instant semantic discovery over tens of thousands of past turns with zero token expenditure.
💻 Developer CLI & Interactive REPL
Project-M features a Claude-Code-inspired terminal interface with the official Brutalist Chevron Monogram Logo, live hardware specs, and a rich interactive REPL.
██████╗ ██████╗ adityadebnath@Project-M(MCP) ● REPL ACTIVE
████████╗ ████████║ ──────────────────────────────────────────────
██╔══████╗ ████╔══██║ Engine: 4-Tier Lossless State Compiler
██║ ╚████╗ ████╔╝ ██║ Storage: SQLite WAL (.project-m/state.db)
██║ ╚████████╔╝ ██║ Clients: Claude Desktop • Codex • Antigravity
██║ ╚═══════╝ ██║ ADRs: 5 Accepted (Tier 2 Ledger)
██║ ██║ Tasks: 1 in progress (Owner: @claude)
╚═╝ ╚═╝ Telemetry: 424 raw turns recorded (Tier 4)
Invariant: 100% Local • Zero Paid APIs
Compile: 1.2ms latency (167/450 tokens)
● ● ● ● ● ● ● ●
Type /help for commands • Press Tab to autocomplete • /exit to quit
project-m ❯ REPL Slash Commands
Launch the interactive shell anytime with uv run project-m or uv run project-m shell:
Command | Arguments | Description |
|
| Renders the compiled Tier 1 State Card in real time. |
| — | Displays database size, WAL status, schema integrity, and active warnings. |
| — | Displays the live task backlog with owner badges. |
|
| Adds or updates a task baton (e.g. |
| — | Lists all accepted Architectural Decision Records (ADRs). |
|
| Records a binding ADR (e.g. |
| — | Displays the signature Neofetch-style system and compiler specifications. |
|
| Exports the living project state card to a portable Markdown document. |
|
| Runs the automated one-click client installer. |
| — | Clears the terminal screen. |
| — | Exits the shell cleanly. |
⚡ FastMCP Tools Reference
Project-M exposes 8 standard tools over Model Context Protocol:
Tool | Parameters | Description |
|
| Returns the deterministic Tier 1 Living State Card (< 450 tokens) containing current goal, tech stack, active tasks, and recent ADRs. |
|
| Posts a new Architectural Decision Record (ADR) to Tier 2. Prevents conflicting implementation paths. |
|
| Updates or creates a task baton in Tier 3 ( |
|
| Updates blackboard key-values ( |
|
| Returns recent conversation turns across all clients (Tier 4 summary). |
|
| Fetches the full uncompressed raw prompt and completion payload for a specific turn. |
| — | Returns diagnostic telemetry: database size, decision count, task counts, and turns. |
|
| Performs sub-3ms lexical search using SQLite FTS5 with Porter stemming and BM25 ranking across all historical turns. |
🚀 Quickstart
Prerequisites
macOS / Linux / Windows
Python 3.12+ (Tested up to Python 3.14.7)
uv(Extremely fast Python package runner)
If you don't have uv installed yet:
# macOS / Linux:
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows (PowerShell):
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"Option A: The Fastest Way (Zero-Install / Run Instantly)
You don’t even need to clone the repository. Run this single command inside any project directory:
uvx --from git+https://github.com/adityadebnath009/Project-M.git project-muvx fetches Project-M into an isolated environment, renders the copper Brutalist Chevron logo, displays live project telemetry, and immediately drops you into the interactive shell:
project-m ❯ Type /board to view the living context card, or /help for all commands!
Option B: The Complete Setup (Clone & Connect to Claude / Antigravity / Codex)
If you want Project-M permanently linked with your local AI desktop assistants:
# 1. Clone repository & sync dependencies
git clone https://github.com/adityadebnath009/Project-M.git
cd Project-M
uv sync
# 2. Run the 1-Click Auto-Installer
uv run project-m setup allWhat project-m setup all automatically does:
Detects Claude Desktop (
claude_desktop_config.json), Google Antigravity (mcp_config.json), and Codex (config.toml).Creates timestamped safety backups (
.bak) of your existing configs.Injects the Project-M FastMCP Server over stdio.
Automatically installs the Project-M Agent Skill (
SKILL.md) into your global agent directories (~/.claude/skills,~/.gemini/antigravity/skills,~/.codex/skills).
Restart Claude Desktop or Antigravity and check the tools (🔨) menu—Project-M with all 8 tools will be active!
You can also target a specific client:
uv run project-m setup -c claude
uv run project-m setup -c antigravity
uv run project-m setup -c codexOption C: Install Globally as a Native Terminal Command
If you want project-m permanently available in your shell like git or docker:
uv tool install git+https://github.com/adityadebnath009/Project-M.gitNow navigate to any repository on your computer and simply run:
project-m # Launch interactive Claude-Code-style REPL
project-m board # Inspect compiled Tier 1 State Card (< 450 tokens)
project-m status # View context health & active warnings
project-m fetch # Render Neofetch specs screenManual Claude Desktop Configuration
If you prefer manual configuration, add Project-M to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):
{
"mcpServers": {
"project-m": {
"command": "uv",
"args": [
"run",
"--directory",
"/path/to/Project-M",
"project-m",
"run"
]
}
}
}🧪 Verification & Tests
Project-M includes an automated test suite verifying SQLite WAL concurrency, token ceiling constraints, JSONL stream parsers, FastMCP tool execution, and CLI command coverage:
uv run pytest -v============================= test session starts ==============================
platform darwin -- Python 3.14.7, pytest-9.2.0, pluggy-1.7.0
rootdir: /Users/adityadebnath/Projects/Project-M(MCP)
configfile: pyproject.toml
plugins: anyio-4.16.0, asyncio-1.4.1.post1
collected 102 items
tests/test_adapters.py ........... [ 10%]
tests/test_blackboard.py .......... [ 20%]
tests/test_claude_code.py ......... [ 29%]
tests/test_cli.py ........... [ 40%]
tests/test_fts5_search.py ..... [ 45%]
tests/test_multi_agent_e2e.py ...................... [ 66%]
tests/test_server.py ......... [ 75%]
tests/test_storage.py ......................... [100%]
============================= 102 passed in 3.02s ==============================Built with care for multi-agent workflows.
Project-M is open-source under the MIT License.
Available Tools
8 toolsget_project_boardA
Retrieves the living Tier 1 Project State Card (< 500 tokens). Call this tool at the beginning of a session or whenever you need situational awareness of the project. It synchronizes recent turns from local client transcripts (Antigravity and Codex) and compiles a high-density, deterministic markdown card. Contains:
🎯 Project Goal & Scope
🔒 Binding Invariants (lossless constraints, exact PRAGMAs, paths, versions)
🏛️ Active Architectural Decisions (ADR IDs, titles, rationale, author, date)
📋 Active Tasks & Handoff Baton (in-progress items with @owner, pending tasks)
⚠️ Attention Required (health alerts: unowned tasks, unverified completions)
🔄 Recent Ambient Activity (recent client messages, budget permitting) Args: target_tokens: Desired token budget ceiling for the briefing card (default: 450). Enforced accurately via the BPE tokenizer.
Returns: str: Clean Markdown-formatted Tier 1 State Card ready to be placed directly into your context window without prompt bloat.
Inputs: target_tokens. Returns: result
get_project_summaryA
Retrieves a structured diagnostics and health summary of the project.
Call this tool for automated programmatic verification of repository state health. Returns exact counts and validation warnings without requiring Markdown parsing.
Returns: dict[str, Any]: Diagnostic record containing: - 'goal': Active project goal - 'current_milestone': Current milestone - 'total_decisions': Total recorded ADRs - 'in_progress_tasks': Count of active tasks - 'pending_tasks': Count of queued tasks - 'completed_tasks': Count of finished tasks - 'total_turns': Total recorded chat turns - 'is_healthy': True if zero unowned active tasks and zero unverified completions - 'warnings': List of active governance warnings - 'unowned_active_tasks': List of task IDs missing an assigned owner - 'unverified_completions': List of task IDs completed without notes
Inputs: no named parameters. Returns: object
get_recent_contextA
Retrieves recent conversation turns across all local AI clients.
Call this tool when you need ambient historical context from previous chat sessions without leaving the MCP workflow. Reads from the unified SQLite conversation ledger.
Args: limit: Maximum number of chronological turns to return (default: 10). source: Optional client filter: 'antigravity', 'codex', or None (for all clients).
Returns: list[dict[str, Any]]: Chronologically ordered list of turn dictionaries, each containing: - 'id': Deterministic turn ID (e.g., 'antigravity:caa4cbcc:447') - 'source': Originating client ('antigravity', 'codex') - 'session_id': Session or thread identifier - 'role': Message sender ('user', 'assistant') - 'content': Raw turn text - 'timestamp': ISO 8601 creation time
Inputs: limit, source. Returns: result
get_turnA
Retrieves a single uncompressed, un-summarized conversation turn by its exact ID (Tier 4).
This is the core of Project-M's Lossless Provenance Engine. When an ADR or task references a source anchor (e.g., 'turn:antigravity:caa4cbcc:447'), call this tool to retrieve the 100% complete, unedited historical message.
Guarantees:
Zero detail loss: Full terminal outputs, code snippets, and error tracebacks.
Zero hallucination: Exact raw payload as ingested from the local client transcript.
Args: turn_id: Deterministic turn identifier (e.g., 'antigravity:caa4cbcc:447' or 'codex:msg-982').
Returns: dict[str, Any]: Complete turn record with source, role, timestamp, and uncompressed content. str: Not-found message if the ID does not exist in the database.
Inputs: turn_id (required). Returns: result
publish_contextA
Publishes or updates a key-value pair on the living project board.
Call this tool to record persistent high-level metadata that all agents need to see, such as project goals, active milestones, or shared environment variables.
Standard Keys:
'goal': The primary objective of the repository/project.
'current_milestone': The current phase or sprint objective (e.g., 'Phase 4: FastMCP').
'constraints': Line-delimited or bulleted technical invariants.
Args: key: The configuration or metadata key (e.g., 'current_milestone', 'constraints'). value: The string value to store. If storing constraints, use newline-separated bullet points with exact technical parameters.
Returns: str: Confirmation message acknowledging the stored key-value pair.
Inputs: key (required), value (required). Returns: result
record_decisionA
Records or updates an Architectural Decision Record (ADR) in Tier 2.
Call this tool whenever you establish a technical rule, make an architectural choice, or change an existing convention. Prevents decision drift and ensures subsequent agents (Claude, Codex, Antigravity) follow the agreed specification.
Lifecycle:
'accepted': Active binding decision (automatically visible on Tier 1 State Card).
'proposed': Under review or draft; not yet binding.
'superseded': Replaced by a newer ADR; archived in Tier 2 history.
'rejected': Proposed but explicitly abandoned with reason in rationale.
Formatting Rule: Preserve exact technical tokens in 'rationale' (e.g. file paths, PRAGMA flags, error codes, function signatures). Avoid fuzzy narrative paraphrasing.
Args: decision_id: Unique identifier string (e.g., 'ADR-001', 'ADR-STORAGE-WAL'). title: Short, descriptive title of the decision. rationale: Verbatim technical justification, constraints, and parameters. decided_by: Name or identity of the decider (e.g., 'claude', 'codex', 'human'). status: Decision status ('accepted', 'proposed', 'superseded', 'rejected').
Returns: str: Confirmation message with the recorded decision ID and status.
Inputs: title (required), rationale (required), decision_id (required), status, +1 more. Returns: result
search_historical_contextA
Searches historical conversation turns across all local AI clients (Antigravity, Codex, and Claude Code) in sub-3ms using SQLite FTS5.
Call this tool when you need to recall past architectural debates, specific code examples, bash commands, or requirements from earlier sessions.
Args: query: Natural language or keyword search terms (e.g. 'decimal arithmetic', 'wal mode'). limit: Maximum number of matches to return (default: 5). role: Optional filter: 'user' (user requests) or 'assistant' (model outputs). source: Optional client filter: 'antigravity', 'codex', or 'claude_code'.
Returns: str: Formatted list of matches with full provenance citations (Client, Role, Timestamp, Turn ID, and content excerpt).
Inputs: query (required), role, limit, source. Returns: result
update_taskA
Updates the status, owner, or validation notes of a task in the Tier 3 Task Graph.
Call this tool to claim work, hand off responsibility to another agent, or mark work as completed with proof of verification.
Status Conventions:
'pending': Queued task waiting to be started.
'in_progress': Currently being worked on. MUST have an 'assigned_to' owner to avoid triggering '⚠️ Attention Required' health warnings.
'completed': Finished work. MUST include validation notes (e.g., test results, verification commands) for audit trail compliance.
Args: task_id: Unique task identifier (e.g., 'task-04', 'FEAT-BLACKBOARD'). status: Target status ('pending', 'in_progress', 'completed'). title: Optional updated title if creating or renaming the task. assigned_to: Agent or user claiming the baton (e.g., 'claude', 'antigravity', 'human'). notes: Progress updates or verification proof (e.g., '46/46 tests passed in 0.41s').
Returns: str: Confirmation message reflecting the updated task state.
Inputs: status (required), task_id (required), notes, title, +1 more. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 8 tools
Most tools target distinct resources (board, decisions, tasks, context turns). The main soft overlap is get_project_board vs get_project_summary, both returning project state (markdown card vs structured counts), and the three context tools (get_recent_context, get_turn, search_historical_context) which are clearly differentiated by mode (recent list, exact ID, keyword search). Descriptions help resolve these.
All names are snake_case verb_noun (get_project_board, record_decision, publish_context, update_task, search_historical_context, etc.). Predictable verb-first pattern with distinct nouns, no mixed conventions.
Eight tools is well-scoped for a project state/provenance server, mapping cleanly onto its tiers (board, ADRs, tasks, context, search). No redundant or filler tools.
Core lifecycle is covered: read board, record decisions, publish metadata, update tasks, retrieve and search context. Minor gaps remain—there is no dedicated tool to list or fetch an individual ADR (proposed/superseded ones are only reflected indirectly), and no explicit task-creation or deletion operations—but agents can work around these via the board card and summary.
Maintenance
Related MCP Connectors
Shared long-term memory & Stop-hook task handoff across Claude Code, Codex, Cursor, and mobile.
Persistent cross-session memory shared by Codex, Claude Code, ChatGPT, and other AI agents.
Shared work memory for Claude Code, Codex, Cursor and chat, scoped to each repository.
One memory for your AI agents and your team: Claude, ChatGPT, Cursor and your agents share it.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceA shared operational layer that synchronizes tasks and project contexts across Claude Chat, Cowork, and Code surfaces using local markdown files. It enables persistent state management and cross-session knowledge sharing without the need for a database.34MIT
- AlicenseBqualityDmaintenanceA shared memory layer for AI agents — one memory.md synced across Claude Desktop, Cursor, Claude Code, OpenAI Codex, and any MCP client.42MIT
- AlicenseAqualityCmaintenanceLocal-first shared memory and coordination layer for AI coding agents, with repository evidence, reservations, handoffs, code graph context, and dashboard review backed by PostgreSQL/pgvector.303Apache 2.0
- AlicenseAqualityBmaintenanceA local-first shared memory layer for MCP-aware agents like Claude, Codex, and Hermes, enabling persistent memory across chats and clients via Markdown files and SQLite FTS.62MIT