Project-M
面向 AI Agent 的环境感知、本地优先上下文引擎与黑板
在 Claude Desktop、OpenAI Codex 和 Google Antigravity 之间切换而不丢失状态。确定性的 4 层上下文编译。低于 2ms 的延迟。零云端依赖。
概览 • 架构 • 交互式 REPL 与 CLI • FastMCP 工具 • 快速开始 • 验证
📌 概览
2026 年的前沿软件工程依赖于多 Agent 技术栈:
- Google Antigravity 用于全仓库重构、测试框架执行和深度 Agent 规划。
- Anthropic Claude Desktop 用于高层架构头脑风暴、形式化推理和 PR 评审。
- OpenAI Codex / ChatGPT 用于快速终端草稿、bash 脚本验证和快速迭代。
问题:上下文失忆
每次在这些助手之间切换时,你的上下文就会断裂。在 Claude Desktop 中达成的决定对 Antigravity 不可见。在 Antigravity 中开始的任务对 Codex 一无所知。开发者在互不相通的聊天窗口之间复制粘贴 diff、状态更新和架构约束,浪费了数千 token 和大量手动工时。
解决方案:Project-M
Project-M 是一个本地优先的 Model Context Protocol (MCP) 服务器和经过验证的项目状态编译器。它被动采集会话轮次,维护一份不可变的架构决策记录 (ADR) 账本,同步任务接力棒,并在 2 毫秒内为任何请求的 AI Agent 提供确定性的第 1 层简报卡(少于 450 token)。
- 100% 本地:在你的机器上以 SQLite WAL 模式运行。无账户、无遥测、无云端锁定。
- 零 API 成本:无需付费嵌入同步,也无需第三方向量数据库。
- 无损遥测:原始对话日志永久保存在第 4 层冷存储中,而模型只消费压缩后的高密度状态卡。
- 干净的 Stdio 隔离:MCP JSON-RPC 2.0 通信通过 stdout 无污染地运行,而品牌化状态卡则安全地路由到 stderr。
🏗️ 架构
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
4 层记忆层级
| 层级 | 名称 | 目标大小 | 延迟 | 用途与行为 |
|---|---|---|---|---|
| Tier 1 | Living State Card | < 450 tokens | < 2 ms | 通过 tiktoken 编译的确定性 markdown 简报。自动注入到每个 agent 轮次中。包含当前目标、当前技术栈、进行中的任务以及最近的 ADR。 |
| Tier 2 | ADR Ledger | < 1,200 tokens | < 5 ms | 架构决策的不可变记录( id , title , rationale , status , decided_by )。防止 agent 推翻过去的架构决策。 |
| Tier 3 | Task Baton Graph | 动态 | < 5 ms | 跨 agent 的任务归属( task_id , status , assigned_to , notes )。协调 @claude 、 @antigravity 与 @codex 之间的交接。 |
| Tier 4 | Lossless Cold Storage | 无限制 | 已索引 | 精确的原始会话记录( transcript.jsonl 与会话数据库)通过内容哈希永久保存。永不直接发送给模型;通过 get_turn() 按需检查。 |
⚡ 基于 SQLite FTS5 的词法搜索(BM25 排序)
Project-M 不依赖昂贵的第三方向量数据库或付费 embedding API,而是使用 SQLite 原生 FTS5(Full-Text Search 5)虚拟表引擎,并配合 BM25 概率相关性排序:
- Porter Stemming(tokenize = 'porter unicode61'):自动匹配词形变化(例如搜索 "connecting" 会匹配 "connect"、"connected" 和 "connection")。
- Okapi BM25 Ranking(ORDER BY rank):基于词频与文档长度饱和度为结果打分,在 3 毫秒以内返回最相关的历史轮次。
- 零延迟数据库触发器:随着轮次从 Antigravity、Codex 或 Claude 到达,通过 C 层 SQLite 触发器(AFTER INSERT、AFTER DELETE)自动更新 conversation_turns_fts 索引。
- 100% 离线且免费:在数万条历史轮次上实现即时语义发现,零 token 消耗。
💻 开发者 CLI 与交互式 REPL
Project-M 提供受 Claude Code 启发的终端界面,配有官方 Brutalist Chevron Monogram Logo、实时硬件规格以及功能丰富的交互式 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 斜杠命令
随时使用 uv run project-m 或 uv run project-m shell 启动交互式 shell:
| 命令 | 参数 | 描述 |
|---|---|---|
| /board | [--target-tokens 450] | 实时渲染编译后的 Tier 1 State Card。 |
| /status | — | 显示数据库大小、WAL 状态、模式完整性和活动警告。 |
| /tasks | — | 显示带有负责人徽章的实时任务待办列表。 |
| /task | <id> <status> <@owner> <notes> | 添加或更新任务接力棒(例如 /task auth-1 in_progress @claude "OAuth2" )。 |
| /decisions | — | 列出所有已接受的架构决策记录(ADR)。 |
| /decide | <id> <title> <rationale> | 记录一条具有约束力的 ADR(例如 /decide ADR-004 "Use SQLite WAL" "Zero locks" )。 |
| /fetch | — | 显示标志性的 Neofetch 风格系统与编译器规格。 |
| /export | [filename.md] | 将动态项目状态卡导出为可移植的 Markdown 文档。 |
| /setup | [all │ claude │ codex] | 运行自动化一键客户端安装程序。 |
| /clear | — | 清空终端屏幕。 |
| /exit | — | 干净退出 shell。 |
⚡ FastMCP 工具参考
Project-M 通过 Model Context Protocol 暴露 8 个标准工具:
| 工具 | 参数 | 描述 |
|---|---|---|
| get_project_board | target_tokens: int = 450 | 返回确定性的 Tier 1 Living State Card(< 450 token),包含当前目标、技术栈、活动任务和最近的 ADR。 |
| record_decision | id, title, rationale, decided_by, status | 向 Tier 2 发布新的架构决策记录(ADR)。防止冲突的实现路径。 |
| update_task | task_id, status, assigned_to, notes | 在 Tier 3 中更新或创建任务接力棒( pending 、 in_progress 、 completed )。 |
| publish_context | key, value, updated_by | 更新黑板键值( current_goal 、 active_stack 、 milestone )。 |
| get_recent_context | limit: int = 10 | 返回所有客户端最近的对话轮次(Tier 4 摘要)。 |
| get_turn | turn_id: int | 获取特定轮次的完整未压缩原始提示与补全负载。 |
| get_project_summary | — | 返回诊断遥测:数据库大小、决策数、任务计数和轮次数。 |
| search_context | query: str, limit: int = 5, role: str, source: str | 使用 SQLite FTS5 执行低于 3ms 的词法搜索,支持 Porter 词干提取和 BM25 排序,跨所有历史轮次。 |
🚀 快速开始
前置条件
- macOS / Linux / Windows
- Python 3.12+(已测试至 Python 3.14.7)
- uv(极快的 Python 包运行器)
如果你尚未安装 uv:
# 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"
选项 A:最快方式(零安装 / 立即运行)
你甚至不需要克隆仓库。在任意项目目录内运行这一条命令:
uvx --from git+https://github.com/adityadebnath009/Project-M.git project-m
uvx 会将 Project-M 获取到隔离环境中,渲染铜色 Brutalist Chevron 标志,显示实时项目遥测,并立即将你带入交互式 shell:
输入 /board 查看动态上下文卡片,或输入 /help 查看所有命令!
选项 B:完整安装(克隆并连接 Claude / Antigravity / Codex)
如果你希望 Project-M 与本地 AI 桌面助手永久关联:
# 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
project-m setup all 自动执行的操作:
- 检测 Claude Desktop(claude_desktop_config.json)、Google Antigravity(mcp_config.json)和 Codex(config.toml)。
- 为你现有的配置创建带时间戳的安全备份(.bak)。
- 通过 stdio 注入 Project-M FastMCP Server。
- 自动将 Project-M Agent Skill(SKILL.md)安装到你的全局 agent 目录(~/.claude/skills、~/.gemini/antigravity/skills、~/.codex/skills)。
重启 Claude Desktop 或 Antigravity,然后查看工具(🔨)菜单——Project-M 和全部 8 个工具将处于激活状态!
你也可以指定某个特定客户端:
uv run project-m setup -c claude
uv run project-m setup -c antigravity
uv run project-m setup -c codex
选项 C:作为原生终端命令全局安装
如果你希望 project-m 像 git 或 docker 一样在 shell 中永久可用:
uv tool install git+https://github.com/adityadebnath009/Project-M.git
现在导航到你电脑上的任意仓库,直接运行:
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
手动配置 Claude Desktop
如果你偏好手动配置,请将 Project-M 添加到 ~/Library/Application Support/Claude/claude_desktop_config.json(macOS)或 %APPDATA%\Claude\claude_desktop_config.json(Windows):
{
"mcpServers": {
"project-m": {
"command": "uv",
"args": [
"run",
"--directory",
"/path/to/Project-M",
"project-m",
"run"
]
}
}
}
🧪 验证与测试
Project-M 包含一套自动化测试,用于验证 SQLite WAL 并发、token 上限约束、JSONL 流解析器、FastMCP 工具执行以及 CLI 命令覆盖:
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 ==============================
为多智能体工作流精心打造。
Project-M 是基于 MIT License 的开源项目。