Newshot

Show HN:Project-M – 为AI编程代理打造的本地共享内存

Translation(model translation, not the source's own text)

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 1Living State Card< 450 tokens< 2 ms通过 tiktoken 编译的确定性 markdown 简报。自动注入到每个 agent 轮次中。包含当前目标、当前技术栈、进行中的任务以及最近的 ADR。
Tier 2ADR Ledger< 1,200 tokens< 5 ms架构决策的不可变记录( id , title , rationale , status , decided_by )。防止 agent 推翻过去的架构决策。
Tier 3Task Baton Graph动态< 5 ms跨 agent 的任务归属( task_id , status , assigned_to , notes )。协调 @claude 、 @antigravity 与 @codex 之间的交接。
Tier 4Lossless 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_boardtarget_tokens: int = 450返回确定性的 Tier 1 Living State Card(< 450 token),包含当前目标、技术栈、活动任务和最近的 ADR。
record_decisionid, title, rationale, decided_by, status向 Tier 2 发布新的架构决策记录(ADR)。防止冲突的实现路径。
update_tasktask_id, status, assigned_to, notes在 Tier 3 中更新或创建任务接力棒( pending 、 in_progress 、 completed )。
publish_contextkey, value, updated_by更新黑板键值( current_goal 、 active_stack 、 milestone )。
get_recent_contextlimit: int = 10返回所有客户端最近的对话轮次(Tier 4 摘要)。
get_turnturn_id: int获取特定轮次的完整未压缩原始提示与补全负载。
get_project_summary—返回诊断遥测:数据库大小、决策数、任务计数和轮次数。
search_contextquery: str, limit: int = 5, role: str, source: str使用 SQLite FTS5 执行低于 3ms 的词法搜索,支持 Porter 词干提取和 BM25 排序,跨所有历史轮次。

🚀 快速开始

前置条件

  • 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 的开源项目。

The translation is machine-generated and individual terms may be off. Nothing is rewritten or cut; the original is authoritative.

Published by HN AI
This site only summarises and aggregates; copyright stays with the original author. Headlines and summaries follow the source — where they differ, the original wins.
Read the original ↗