{"slug": "show-hn-project-m-stop-re-explaining-project-context-between-ai-coding-tools", "title": "Show HN: Project-M – Stop re-explaining project context between AI coding tools", "summary": "A developer released Project-M, a local-first Model Context Protocol (MCP) server that compiles project state into a deterministic four-tier context store so developers can switch between Anthropic Claude Desktop, OpenAI Codex and Google Antigravity without losing context. Project-M serves a Tier 1 briefing card of under 450 tokens in under 2 milliseconds, keeps an immutable Architectural Decision Record ledger under 1,200 tokens, tracks cross-agent task handoffs, and stores raw transcripts in SQLite WAL mode with no cloud dependencies or API costs.", "body_md": "Switch between **Claude Desktop**, **OpenAI Codex**, and **Google Antigravity** without losing state.\n\nDeterministic 4-tier context compilation. Sub-2ms latency. Zero cloud dependencies.\n\n[Overview](#-overview) •\n[Architecture](#-architecture) •\n[Interactive REPL & CLI](#-developer-cli--interactive-repl) •\n[FastMCP Tools](#-fastmcp-tools-reference) •\n[Quickstart](#-quickstart) •\n[Verification](#-verification--tests)\n\nFrontier software engineering in 2026 relies on a multi-agent stack:\n\n- **Google Antigravity** for whole-repo refactoring, test harness execution, and deep agentic planning.\n- **Anthropic Claude Desktop** for high-level architectural brainstorming, formal reasoning, and PR reviews.\n- **OpenAI Codex / ChatGPT** for fast terminal scratchpads, bash script verification, and quick iterations.\n\nEvery 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.\n\n**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**.\n\n- **100% Local** : Runs on SQLite WAL mode on your machine. No accounts, no telemetry, no cloud lock-in.\n- **Zero API Costs** : No paid embedding syncs or third-party vector databases.\n- **Lossless Telemetry** : Raw conversation logs are preserved permanently in Tier 4 cold storage while models only consume compressed, high-density state cards.\n- **Clean Stdio Isolation** : MCP JSON-RPC 2.0 communication runs unpolluted over`stdout` , while branded status cards route safely to`stderr` .\n\n```\nflowchart TD\n    subgraph AI Clients [\"Frontier AI Clients\"]\n        A[\"Google Antigravity<br/>(IDE & Workspace)\"]\n        B[\"Anthropic Claude Desktop<br/>(Architectural Planner)\"]\n        C[\"OpenAI Codex / ChatGPT<br/>(Terminal & CLI)\"]\n    end\n\n    subgraph Harvesters [\"Ambient Log Harvesters\"]\n        H1[\"Antigravity Harvester<br/>JSONL Stream Reader\"]\n        H2[\"Codex Harvester<br/>Read-Only SQLite (?mode=ro)\"]\n    end\n\n    subgraph Core [\"Project-M Core Engine\"]\n        DB[(\"Storage Layer<br/>SQLite WAL Mode<br/>(.project-m/state.db)\")]\n        COMP[\"State Compiler<br/>(Lossless 4-Tier Blackboard)\"]\n        SERVER[\"FastMCP Server<br/>(JSON-RPC 2.0 over stdio)\"]\n    end\n\n    A -. writes transcript .-> H1 -->|deduplicated turns| DB\n    C -. writes session .-> H2 -->|deduplicated turns| DB\n    DB <--> COMP\n    COMP <--> SERVER\n    SERVER <==>|MCP Tools & Resources| B\n    SERVER <==>|MCP Tools & Resources| A\n    SERVER <==>|MCP Tools & Resources| C\n```\n\n| Tier | Name | Target Size | Latency | Purpose & Behavior | \n|---|---|---|---|---|\n| **Tier 1** | **Living State Card** | `< 450 tokens` | `< 2 ms` | Deterministic markdown briefing compiled via `tiktoken` . Injected automatically into every agent turn. Contains active goal, active stack, in-progress tasks, and recent ADRs. | \n| **Tier 2** | **ADR Ledger** | `< 1,200 tokens` | `< 5 ms` | Immutable record of architectural decisions ( `id` ,`title` ,`rationale` ,`status` ,`decided_by` ). Prevents agents from reversing past architectural decisions. | \n| **Tier 3** | **Task Baton Graph** | Dynamic | `< 5 ms` | Cross-agent task ownership ( `task_id` ,`status` ,`assigned_to` ,`notes` ). Coordinates handoffs between`@claude` ,`@antigravity` , and`@codex` . | \n| **Tier 4** | **Lossless Cold Storage** | Unlimited | Indexed | Exact raw session transcripts ( `transcript.jsonl` and session databases) preserved permanently with content hashes. Never sent to models directly; inspected on-demand via`get_turn()` . | \n\nInstead 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**:\n\n- **Porter Stemming (`tokenize = 'porter unicode61'`)** : Automatically matches word inflections (e.g. searching`\"connecting\"` matches`\"connect\"` ,`\"connected\"` , and`\"connection\"` ).\n- **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** .\n- **Zero-Lag Database Triggers** : Automatically updates the`conversation_turns_fts` index via C-level SQLite triggers (`AFTER INSERT` ,`AFTER DELETE` ) as turns arrive from Antigravity, Codex, or Claude.\n- **100% Offline & Free** : Instant semantic discovery over tens of thousands of past turns with zero token expenditure.\n\nProject-M features a Claude-Code-inspired terminal interface with the official **Brutalist Chevron Monogram Logo**, live hardware specs, and a rich interactive REPL.\n\n```\n   ██████╗         ██████╗       adityadebnath@Project-M(MCP)  ● REPL ACTIVE\n   ████████╗     ████████║       ──────────────────────────────────────────────\n   ██╔══████╗   ████╔══██║       Engine:     4-Tier Lossless State Compiler\n   ██║  ╚████╗ ████╔╝  ██║       Storage:    SQLite WAL (.project-m/state.db)\n   ██║   ╚████████╔╝   ██║       Clients:    Claude Desktop • Codex • Antigravity\n   ██║    ╚═══════╝    ██║       ADRs:       5 Accepted (Tier 2 Ledger)\n   ██║                 ██║       Tasks:      1 in progress (Owner: @claude)\n   ╚═╝                 ╚═╝       Telemetry:  424 raw turns recorded (Tier 4)\n                                 Invariant:  100% Local • Zero Paid APIs\n                                 Compile:    1.2ms latency (167/450 tokens)\n\n                                 ● ● ● ● ● ● ● ●\n  Type /help for commands  •  Press Tab to autocomplete  •  /exit to quit\n\nproject-m ❯\n```\n\nLaunch the interactive shell anytime with `uv run project-m` or `uv run project-m shell`:\n\n| Command | Arguments | Description | \n|---|---|---|\n| `/board` | `[--target-tokens 450]` | Renders the compiled Tier 1 State Card in real time. | \n| `/status` | — | Displays database size, WAL status, schema integrity, and active warnings. | \n| `/tasks` | — | Displays the live task backlog with owner badges. | \n| `/task` | `<id> <status> <@owner> <notes>` | Adds or updates a task baton (e.g. `/task auth-1 in_progress @claude \"OAuth2\"` ). | \n| `/decisions` | — | Lists all accepted Architectural Decision Records (ADRs). | \n| `/decide` | `<id> <title> <rationale>` | Records a binding ADR (e.g. `/decide ADR-004 \"Use SQLite WAL\" \"Zero locks\"` ). | \n| `/fetch` | — | Displays the signature Neofetch-style system and compiler specifications. | \n| `/export` | `[filename.md]` | Exports the living project state card to a portable Markdown document. | \n| `/setup` | `[all \\| claude \\| codex]` | Runs the automated one-click client installer. | \n| `/clear` | — | Clears the terminal screen. | \n| `/exit` | — | Exits the shell cleanly. | \n\nProject-M exposes 8 standard tools over Model Context Protocol:\n\n| Tool | Parameters | Description | \n|---|---|---|\n| `get_project_board` | `target_tokens: int = 450` | Returns the deterministic Tier 1 Living State Card (< 450 tokens) containing current goal, tech stack, active tasks, and recent ADRs. | \n| `record_decision` | `id, title, rationale, decided_by, status` | Posts a new Architectural Decision Record (ADR) to Tier 2. Prevents conflicting implementation paths. | \n| `update_task` | `task_id, status, assigned_to, notes` | Updates or creates a task baton in Tier 3 ( `pending` ,`in_progress` ,`completed` ). | \n| `publish_context` | `key, value, updated_by` | Updates blackboard key-values ( `current_goal` ,`active_stack` ,`milestone` ). | \n| `get_recent_context` | `limit: int = 10` | Returns recent conversation turns across all clients (Tier 4 summary). | \n| `get_turn` | `turn_id: int` | Fetches the full uncompressed raw prompt and completion payload for a specific turn. | \n| `get_project_summary` | — | Returns diagnostic telemetry: database size, decision count, task counts, and turns. | \n| `search_context` | `query: str, limit: int = 5, role: str, source: str` | Performs sub-3ms lexical search using SQLite FTS5 with Porter stemming and BM25 ranking across all historical turns. | \n\n- **macOS / Linux / Windows**\n- **Python 3.12+** (Tested up to Python 3.14.7)\n- [`uv`](https://github.com/astral-sh/uv) (Extremely fast Python package runner)\n\nIf you don't have `uv` installed yet:\n\n```\n# macOS / Linux:\ncurl -LsSf https://astral.sh/uv/install.sh | sh\n\n# Windows (PowerShell):\npowershell -ExecutionPolicy ByPass -c \"irm https://astral.sh/uv/install.ps1 | iex\"\n```\n\nYou don’t even need to clone the repository. Run this single command inside **any project directory**:\n\n```\nuvx --from git+https://github.com/adityadebnath009/Project-M.git project-m\n```\n\n`uvx` 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:\n\n```\nproject-m ❯\n```\n\nType `/board` to view the living context card, or `/help` for all commands!\n\nIf you want Project-M permanently linked with your local AI desktop assistants:\n\n```\n# 1. Clone repository & sync dependencies\ngit clone https://github.com/adityadebnath009/Project-M.git\ncd Project-M\nuv sync\n\n# 2. Run the 1-Click Auto-Installer\nuv run project-m setup all\n```\n\n**What `project-m setup all` automatically does:**\n\n1. Detects **Claude Desktop** (`claude_desktop_config.json` ),**Google Antigravity** (`mcp_config.json` ), and**Codex** (`config.toml` ).\n2. Creates timestamped safety backups (`.bak` ) of your existing configs.\n3. Injects the **Project-M FastMCP Server** over stdio.\n4. Automatically installs the **Project-M Agent Skill** (`SKILL.md` ) into your global agent directories (`~/.claude/skills` ,`~/.gemini/antigravity/skills` ,`~/.codex/skills` ).\n\n*Restart Claude Desktop or Antigravity and check the tools (🔨) menu—Project-M with all 8 tools will be active!*\n\nYou can also target a specific client:\n\n```\nuv run project-m setup -c claude\nuv run project-m setup -c antigravity\nuv run project-m setup -c codex\n```\n\nIf you want `project-m` permanently available in your shell like `git` or `docker`:\n\n```\nuv tool install git+https://github.com/adityadebnath009/Project-M.git\n```\n\nNow navigate to **any repository** on your computer and simply run:\n\n```\nproject-m          # Launch interactive Claude-Code-style REPL\nproject-m board    # Inspect compiled Tier 1 State Card (< 450 tokens)\nproject-m status   # View context health & active warnings\nproject-m fetch    # Render Neofetch specs screen\n```\n\nIf 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):\n\n```\n{\n  \"mcpServers\": {\n    \"project-m\": {\n      \"command\": \"uv\",\n      \"args\": [\n        \"run\",\n        \"--directory\",\n        \"/path/to/Project-M\",\n        \"project-m\",\n        \"run\"\n      ]\n    }\n  }\n}\n```\n\nProject-M includes an automated test suite verifying SQLite WAL concurrency, token ceiling constraints, JSONL stream parsers, FastMCP tool execution, and CLI command coverage:\n\n```\nuv run pytest -v\n============================= test session starts ==============================\nplatform darwin -- Python 3.14.7, pytest-9.2.0, pluggy-1.7.0\nrootdir: /Users/adityadebnath/Projects/Project-M(MCP)\nconfigfile: pyproject.toml\nplugins: anyio-4.16.0, asyncio-1.4.1.post1\ncollected 102 items\n\ntests/test_adapters.py ...........                                       [ 10%]\ntests/test_blackboard.py ..........                                      [ 20%]\ntests/test_claude_code.py .........                                      [ 29%]\ntests/test_cli.py ...........                                            [ 40%]\ntests/test_fts5_search.py .....                                          [ 45%]\ntests/test_multi_agent_e2e.py ......................                     [ 66%]\ntests/test_server.py .........                                           [ 75%]\ntests/test_storage.py .........................                          [100%]\n\n============================= 102 passed in 3.02s ==============================\n```\n\n**Project-M** is open-source under the [MIT License](https://github.com/adityadebnath009/Project-M/blob/main/LICENSE).", "url": "https://wpnews.pro/news/show-hn-project-m-stop-re-explaining-project-context-between-ai-coding-tools", "canonical_source": "https://github.com/adityadebnath009/Project-M", "published_at": "2026-11-19 16:33:11+00:00", "updated_at": "2026-11-19 16:46:28.811551+00:00", "lang": "en", "topics": ["ai-agents", "agent-protocols", "developer-tools", "ai-tools"], "entities": ["Project-M", "Anthropic Claude Desktop", "OpenAI Codex", "Google Antigravity", "Model Context Protocol", "FastMCP", "SQLite"], "also_reported_by": [], "takeaway": "Project-M serves a Tier 1 briefing card under 450 tokens in under 2 ms and a Tier 2 ADR ledger under 1,200 tokens in under 5 ms over MCP JSON-RPC 2.0 on stdio, keeping status output on stderr and storing state locally in SQLite WAL mode.", "recommendation": null, "alternates": {"html": "https://wpnews.pro/news/show-hn-project-m-stop-re-explaining-project-context-between-ai-coding-tools", "markdown": "https://wpnews.pro/news/show-hn-project-m-stop-re-explaining-project-context-between-ai-coding-tools.md", "text": "https://wpnews.pro/news/show-hn-project-m-stop-re-explaining-project-context-between-ai-coding-tools.txt", "jsonld": "https://wpnews.pro/news/show-hn-project-m-stop-re-explaining-project-context-between-ai-coding-tools.jsonld"}}