Skip to main content
Glama
yinshaojun001

ProjectBrain

by yinshaojun001
OverviewSchemaRelated ServersScoreDiscussions
Python
Local

ProjectBrain 是一个本地项目认知层，帮助 AI 编程智能体在修改代码前理解项目背景。

它将代码结构事实与人工经验转化为任务范围的制品，供 AI 智能体使用：

  • Context Pack：与当前任务相关的文件、符号、流程、风险和人工注释。

  • Impact Analysis：某次变更可能影响的文件、符号、调用链、依赖、测试和审查风险。

  • Git Diff Impact：基于 Git 变更文件的本地变更影响分析。

  • Project Brain：从 Codex 会话中自动提取知识单元，支持人工确认与检索。

ProjectBrain 不是代码搜索 UI，不是通用 RAG 聊天机器人，也不会自动修改代码。

状态

原型 / 本地 MVP。

当前能力：

  • CodeGraph SQLite 适配器

  • ProjectBrain JSON Schema 模型与校验

  • Context Pack 构建器

  • Impact Analysis 构建器

  • 基于 Git 变更文件的 Git diff 影响分析

  • 智能体友好的紧凑输出格式

  • 本地经验声明（claim）创作

  • JSON 文件本地运行时

  • 本地 stdio MCP 服务器

  • Project Brain 知识单元存储与管理

  • 可选 FastAPI API 与暗色系 Brain Explorer UI

  • 合成公开演示数据 examples/payment-mini/

Related MCP server: roam-code

快速上手

使用 Homebrew 安装：

brew tap yinshaojun001/projectbrain https://github.com/yinshaojun001/projectbrain
brew trust yinshaojun001/projectbrain
brew install projectbrain
projectbrain doctor
codex-brain --help

或从源码安装：

python3 -m venv .venv
.venv/bin/python -m pip install -e .
.venv/bin/projectbrain doctor

运行测试：

python3 -m unittest discover -s tests

与自己的项目配合使用

一条命令初始化项目：

projectbrain --store-root ~/.projectbrain-work setup /path/to/my/project \
  --id my_project

setup 会运行 CodeGraph 索引、导入 ProjectBrain 事实、执行 Context Pack 冒烟测试，并提示安装 MCP 服务器到 Codex CLI、Claude Code、Cursor、Trae 等支持的智能体。

生成 Context Pack：

projectbrain context my_project "解释结算入口" --format agent

生成 Impact Analysis：

projectbrain impact my_project "修改结算合约" \
  --changed-file src/settlement/SettlementService.java

projectbrain impact-diff my_project "审查暂存变更" --staged --format agent

添加人工经验声明：

projectbrain claim add my_project \
  --id exp_checkout \
  --applies-to checkout \
  --risk high \
  --review-state approved \
  --claim-type HUMAN_CONFIRMED \
  --statement "结账校验变更需要兼容性审查。"

Brain Explorer（知识管理）

启动本地 API 服务后，在浏览器打开：

http://127.0.0.1:8000/ui/projects/<project_id>/brain

可以：

  • 浏览已确认的知识单元（按类型分组）

  • 审核待确认的 AI 提取候选知识

  • 手动添加知识

  • 搜索项目知识库

通过 CLI 管理知识：

projectbrain brain propose /path/to/my/project --type constraint --statement "退款手续费需单独入账。"
projectbrain brain candidates /path/to/my/project
projectbrain brain confirm-candidate /path/to/my/project <candidate_id>

codex-brain：带项目记忆的 Codex

codex-brain 以显式子进程方式启动 Codex CLI，并初始化项目本地 Brain 存储：

cd /path/to/my/project
codex-brain

# 冒烟测试：
codex-brain --project . --no-ui --no-extract --codex-command "true"

项目本地 Brain 数据存储在：

<project>/.projectbrain/brain/
  knowledge_units.jsonl
  memory_candidates.jsonl
  conversations.jsonl

可选 FastAPI 服务器

python3 -m venv .venv
.venv/bin/python -m pip install -e '.[api]'

PYTHONPATH=apps/api:packages/adapters:packages/runtime:packages/schema \
.venv/bin/uvicorn projectbrain_api.main:app --reload

访问 http://127.0.0.1:8000/ui/projects 打开暗色系 Brain Explorer UI。

JSON API 路由：

GET    /health
POST   /api/v1/projects/import
GET    /api/v1/projects
POST   /api/v1/projects/{project_id}/context-pack
POST   /api/v1/projects/{project_id}/impact-analysis
POST   /api/v1/projects/{project_id}/impact-analysis/git-diff
GET    /api/v1/projects/{project_id}/policy

本地 MCP 服务器

projectbrain --store-root /absolute/path/to/.projectbrain mcp serve

本地 stdio 子进程，不开放网络端口，不上传源码。详见 MCP 使用说明。

在 MCP 工具调用中使用 output_format: "agent" 获取紧凑的智能体友好输出。

本地输出控制，在项目根目录添加 .projectbrain-policy.json：

{
  "deny_paths": ["private/**"],
  "output_limits": { "max_items_per_section": 8 },
  "include_source_snippets": false
}

仓库结构

apps/
  api/projectbrain_api/   可选 FastAPI API 与 UI
packages/
  adapters/               CodeGraph 适配器与制品构建器
  runtime/                本地 JSON 运行时与仓库抽象
  schema/                 数据类 Schema 与校验
examples/payment-mini/    合成公开演示数据
tests/                    单元与 API 测试
docs/                     设计与实现文档

设计文档

文档

说明

设计文档

产品定位、架构、组件、API 与路线图

域模型

项目认知域模型与界限上下文

MVP 架构

本地 MVP 架构、服务边界与验收标准

MCP 使用说明

本地 stdio MCP 服务器使用与隐私边界

中文快速上手

本地安装、演示、MCP、声明与策略的中文教程

路线图

  • 增加类型化 API 请求/响应模型

  • 增加 OpenAPI 快照测试

  • 增加更丰富的 Git diff 符号匹配

  • 增加数据库后端仓库实现

  • 增加更多语言适配器

许可证

MIT

Install Server
A
license - permissive license
B
quality
B
maintenance

How are these scores calculated?

Maintenance

–Maintainers
–Response time
–Release cycle
–Releases (12mo)
Commit activity

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Tools

View all tools

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/yinshaojun001/projectbrain'

If you have feedback or need assistance with the MCP directory API, please join our Discord server