Skip to main content
Glama

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.

Tests Python Protocol Storage Latency License

Reviewed by HOL Guard M8ven Score

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 to stderr.


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| C

The 4-Tier Memory Hierarchy

Tier

Name

Target Size

Latency

Purpose & Behavior

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.

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.

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.

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().

⚡ 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_fts index 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

/board

[--target-tokens 450]

Renders the compiled Tier 1 State Card in real time.

/status

—

Displays database size, WAL status, schema integrity, and active warnings.

/tasks

—

Displays the live task backlog with owner badges.

/task

<id> <status> <@owner> <notes>

Adds or updates a task baton (e.g. /task auth-1 in_progress @claude "OAuth2").

/decisions

—

Lists all accepted Architectural Decision Records (ADRs).

/decide

<id> <title> <rationale>

Records a binding ADR (e.g. /decide ADR-004 "Use SQLite WAL" "Zero locks").

/fetch

—

Displays the signature Neofetch-style system and compiler specifications.

/export

[filename.md]

Exports the living project state card to a portable Markdown document.

/setup

[all | claude | codex]

Runs the automated one-click client installer.

/clear

—

Clears the terminal screen.

/exit

—

Exits the shell cleanly.


⚡ FastMCP Tools Reference

Project-M exposes 8 standard tools over Model Context Protocol:

Tool

Parameters

Description

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.

record_decision

id, title, rationale, decided_by, status

Posts a new Architectural Decision Record (ADR) to Tier 2. Prevents conflicting implementation paths.

update_task

task_id, status, assigned_to, notes

Updates or creates a task baton in Tier 3 (pending, in_progress, completed).

publish_context

key, value, updated_by

Updates blackboard key-values (current_goal, active_stack, milestone).

get_recent_context

limit: int = 10

Returns recent conversation turns across all clients (Tier 4 summary).

get_turn

turn_id: int

Fetches the full uncompressed raw prompt and completion payload for a specific turn.

get_project_summary

—

Returns diagnostic telemetry: database size, decision count, task counts, and turns.

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.


🚀 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-m

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:

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 all

What project-m setup all automatically does:

  1. Detects Claude Desktop (claude_desktop_config.json), Google Antigravity (mcp_config.json), and Codex (config.toml).

  2. Creates timestamped safety backups (.bak) of your existing configs.

  3. Injects the Project-M FastMCP Server over stdio.

  4. 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 codex

Option 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.git

Now 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 screen

Manual 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 tools
get_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

    A4.1/5.0

    Scored across 8 tools

    Disambiguation4/5

    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.

    Naming Consistency5/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      A 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.
      34
      MIT
    • A
      license
      B
      quality
      D
      maintenance
      A shared memory layer for AI agents — one memory.md synced across Claude Desktop, Cursor, Claude Code, OpenAI Codex, and any MCP client.
      4
      2
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      A 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.
      6
      2
      MIT