Project Brain

项目大脑

LLM编码会话的持久长期记忆。带有BM25搜索、MCP服务器和Claude Code集成的胖索引知识文件。

问题

LLMs在两次会议之间会忘记一切。上下文窗口是有限的（约20万个令牌），只能追加，而且很昂贵。随意打开文件会浪费代币。过去会议的知识丢失了。

解决方案

Project Brain为你的法学硕士提供了一个持久的记忆系统：

• 脂肪指数 --摘要足够丰富，无需打开即可回答“我需要这个文件吗？”
• 键入的知识文件 --规范、代码、规则、学习、日志、重置——每个都有明确的角色
• BM25搜索 --在上下文窗口外查找相关知识
• 会话切换 --结构化状态捕获，以便下一个会话从您停止的地方继续
• MCP服务器 --将大脑搜索/直接阅读作为工具

快速开始

1.克隆并安装

git clone https://github.com/jkmack000/project-brain.git
cd project-brain
uv sync

2.在项目中初始化大脑

cd /path/to/your/project
uv run /path/to/project-brain/project-brain/brain.py init "My Project"

这创建了一个 project-brain/ 目录中包含所有脚手架、模板和一个空的INDEX-MASTER.md。

3.注册MCP服务器（克劳德代码）

claude mcp add brain -- uv --directory /path/to/project-brain/project-brain run brain-mcp-server.py

4.复制Claude Code集成文件

将这些复制到您的项目中 .claude/ 目录：

cp -r /path/to/project-brain/.claude/rules/ /path/to/your/project/.claude/rules/
cp -r /path/to/project-brain/.claude/skills/ /path/to/your/project/.claude/skills/
cp -r /path/to/project-brain/.claude/agents/ /path/to/your/project/.claude/agents/
cp /path/to/project-brain/.claude/settings.local.json /path/to/your/project/.claude/settings.local.json
cp /path/to/project-brain/CLAUDE.md /path/to/your/project/CLAUDE.md

5.启动Claude Code会话

在项目目录中打开Claude Code。SessionStart挂钩将触发，规则将加载，技能将可用：

• /brain-search --无需打开文件即可搜索知识
• /brain-deposit [TYPE] [desc] --通过重复检查来积累新知识
• /brain-handoff --在结束前捕获会话状态
• /brain-status --检查大脑健康

CLI命令

uv run brain.py init "Project Name"              # Scaffold a new brain
uv run brain.py search "query"                    # BM25 search over fat indexes
uv run brain.py status                            # File counts, orphans, health
uv run brain.py deposit --type LEARN --tags "x,y" # Add a knowledge file
uv run brain.py recall "task description"         # Generate a RESET context package
uv run brain.py ingest "source.md"                # Extract knowledge from a document
uv run brain.py reindex                           # Rebuild content hash manifest

运作原理

脂肪指数

每个大脑文件在index-MASTER.md中都有一个脂肪索引条目：

### LEARN-005
- **Type:** LEARN
- **File:** learnings/LEARN-005_api-rate-limits.md
- **Tags:** api, rate-limit, gotcha
- **Links:** CODE-003, SPEC-002
- **Summary:** Production API enforces 100 req/min per key. Bulk operations
  need request batching with exponential backoff. Discovered during load testing.
- **Known issues:** None open

LLM首先读取索引，识别它实际需要的1-3个文件，然后只打开这些文件。没有投机文件打开，没有浪费的代币。

会话工作流

Session 1 (SEARCH — disposable):
  Load INDEX-MASTER.md → search → identify needed files → generate RESET file

Session 2 (WORK — efficient):
  Load RESET file + listed files → 170K+ tokens free for actual work

文件类型

完整设置指南

这一切都是新的吗？看 入门——从零到工作大脑 了解涵盖安装、设置、摄取和工作示例的完整演练。

建筑

看 规范-000 完整的方法论。

需求

• Python 3.12+
• 紫外线 （推荐）或pip
• Claude Code（用于钩子、规则、技能和MCP集成）

许可证

麻省理工学院