marrow

<div align="center"> # 骨髓 **编码代理的产品上下文层** 你的编码代理从未在房间里。骨髓把它带到了那里。 [文档](./docs) · [启动站点](https://marrow-six.vercel.app) </div> --- ## 它是什么 每次站会、白板会议和用户访谈都包含了产品背后的原因。但这些信息目前并未被你的编码代理所利用，因此它只能靠猜测。骨髓吸收了原始的产品信息，将其提炼成结构化的产品真相，并为代理提供所需的精确信息。 结果是，代理根据实际决策构建的代码，每项要求都可追溯到创建该要求的确切会议或访谈。 提炼出的信息是产品的真相来源：产品目标和用户目标、功能及其行为方式，每个都带有状态和决策链接。骨髓保持该信息的更新，当代码偏离决策目标时，它会提出问题，而不是让真相来源和代码库悄悄分歧。 令牌减少和漂移捕获质量是衡量标准，而不是预测。参见 `marrow benchmark` 和 `packages/core/fixtures/synthetic-golden.json` 中的综合黄金数据集。不存在合作伙伴数据基准，直到有实际的合作伙伴数据。 ## 它与众不同 这个领域竞争激烈，但其他工具都以代码为根基。像 Lore 和 Tenet 这样的工具从编码会话、git 历史和代码库中提炼信息。它们记住代码，回答代码为什么是这样的。 骨髓以产品为根基。它的输入是产品决策的房间。它回答代码应该做什么以及为什么，根据人和用户。代理看不到那个房间，所以它只能靠猜测。骨髓消除了这种猜测。 其他工具记住你的代码。骨髓将产品带入其中。 ## 主线 一个想法，每条事实都可追溯到其来源，从一行代码到它被决策的时刻。这种追溯就是整个产品。抓住它，代码记忆工具就无法轻易复制它，它们的 DNA 是代码，而不是房间。 ## 它是什么，不是 **输入：** 吸收原始产品信息，将其提炼成结构化知识，保持更新，为代理和开发人员提供任务范围的上下文。 **输出：** 不是编码代理、编辑器、聊天应用程序、通用笔记工具或从存储库解析代码的内存工具。我们从产品方面为代理提供信息，而不是成为代理。 ## 知识模型 一个薄而固定的脊柱，让代理始终有一个稳定的查找位置，上面有团队特有的动态结构。 - **证据**，原始基质。所有信息都以原样存储为证据，从不修改，始终是溯源的来源。 - **实体**，产品的名词。功能、组件、角色、集成。 - **决策**，一个有理由和状态的确定选择。硬约束作为标签存在于此处。 - **目标**，房间承诺的目标。产品目标（产品必须实现的目标）和用户目标（用户必须能够做的事情），每个都与服务的功能绑定。这是您的产品的真相来源，代理在构建之前会读取它。 - **问题**，一个开放或有争议的问题。 每个提炼的节点都带有状态（开放、已决定、有争议、已废弃）、置信度和链接到其来源的确切证据范围。代理必须始终能够区分已决定和开放的问题。这种区别是防止它自信地构建未经任何人同意的东西的关键。 ## 问题循环 在摄取后，骨髓会询问开发人员某些信息是否模糊、与之前的决定相矛盾或被引用但从未决定。开发人员会回答，答案成为一个高信任度的节点。如果没有这个循环，骨髓就会变成一堆陈旧的笔记，因此它是核心功能，而不是可选功能。 ## 在发布前捕获漂移 `marrow drift` 将 git hunk 与已决定的事实进行比较，并在它们到达主分支之前提出矛盾。`marrow drift --ci` 在拉取请求上发出 GitHub Actions 注释。被拒绝和处理的捕获会被记录，以便随着时间的推移提高精度。 ## 比较 - [Vs Granola](./docs/compare/granola.md) - [Vs Notion / Confluence](./docs/compare/notion.md) - [Vs Lore / Tenet](./docs/compare/lore-tenet.md) - [Vs Mem0 / Zep](./docs/compare/mem0-zep.md) ## 安全性和信任 参见 [docs/security.md](./docs/security.md)，了解架构、保留和模型提供商的政策。 ## 代理访问 MCP 服务器和 CLI 是同等重要的。任务循环是显式的： ```bash marrow loop "实施密码登录" marrow loop "实施密码登录" --check --unstaged marrow truth ``` `loop` 返回紧凑的代理简报：相关的已决定目标和决定，相关的开放或有争议的问题，精确的来源范围，以及明确的 **可以构建** 和 **询问人类** 部分。`--check` 还运行漂移检测，并返回创建的问题、捕获事件 ID、清理的接收数据和接受/拒绝命令。 通过 MCP，相同的界面是 `prepare_task` 和 `maintain_truth`，以及任务范围的工具（`search`、`get_decisions`、`get_goals`、`get_open_questions`、`get_entity`、`trace_to_source`）和结构化写入（`append_evidence`、`propose_node`、`check_drift`）。事实总是连同状态和来源一起返回。人类对同一个大脑的视图是控制台（`marrow web`），参见 [docs/console.md](./docs/console.md)。 ## 堆栈 - TypeScript 无处不在，Node 运行时。 - Postgres 带有 pgvector 作为单个存储库。图为表格和嵌入在单个数据库中。 - Pg-boss 用于摄取和提炼队列。无需 Redis、Kafka 或外部代理。 - 官方 MCP TypeScript SDK 用于服务器。 - 模型和嵌入在薄提供者接口后面。默认 Claude、OpenAI 兼容和本地（Ollama / LM Studio）都支持。 ## 60 秒试用 ```bash git clone https://github.com/ElxMaj/marrow && cd marrow pnpm install pnpm db:up export DATABASE_URL=postgres://marrow:marrow@localhost:5432/marrow # 任意 Postgres+pgvector pnpm marrow demo # 完整的示例，使用脚本模型和本地嵌入，无需 API 密钥 pnpm marrow web # 在浏览器中打开控制台 ``` `demo` 摄取访谈，提炼它，回答循环，并显示带有溯源的魔术链接决策，使用脚本模型和本地进程嵌入，因此无需密钥。`web` 打开控制台：浏览大脑，解决开放问题，观察连接器流入，读取成本和延迟。您只需提供 Postgres。参见 [docs/console.md](./docs/console.md)。 ## 先决条件 - Node >= 20. - Postgres 16+ 带有 pgvector 扩展。`pnpm db:up` 在 Docker 中启动一个，或将 `DATABASE_URL` 指向任何已运行 `create extension vector` 的 Postgres。 - **嵌入是零配置的**：小型模型在第一次提炼时在进程中运行（无需端点，无需密钥，~25MB 一次下载）。要使用自己的嵌入端点（Ollama 或任意 OpenAI 兼容），请设置 `MARROW_EMBEDDING_BASE_URL`。 - 对于实际提炼，您需要一个模型密钥：`MARROW_API_KEY` 用于 Claude，或 `MARROW_PROVIDER=openai-compatible` 用于本地 LLM。读取和摄取无需模型。参见 [.env.example](./.env.example)。 ## 摄取房间 骨髓读取会议记录的格式是您的工具已经导出的格式：WebVTT（Zoom、Meet、Teams）、SRT、JSON（Otter、Granola、通用）、纯文本/降价，并将每个规范为干净的发言者属性证据，然后提炼。 ```bash pnpm marrow ingest ./meetings # 整个文件夹，任意格式混合 cat zoom-call.vtt | pnpm marrow ingest - # 或管道输入 pnpm marrow ingest --audio standup.m4a # 语音备忘录（需要转录提供商） pnpm marrow questions # 房间遗留的开放问题 pnpm marrow ask "passwordless auth" # 任务范围的语义 ``` ## 自动数据流 房间比您记住的文件要大。连接器从产品实际决策的工具中提取新的证据，以便大脑保持最新，而无需您复制任何内容。目前有十二个： Slack、GitHub、Linear、Notion、Figma、Zoom、Intercom，以及新的：Gmail（电子邮件）、Microsoft Teams、Jira、Granola 和 Otter。 ```bash export MARROW_SECRET_KEY=... # 加密连接器秘密 pnpm marrow connectors add slack --name slack --secret xoxb-... pnpm marrow sync # 立即拉取所有启用的连接器 ``` 连接器仅追加证据，从不修改它。同步引擎是持久层：每次运行仅拉取新的内容（每个连接器的游标），从不重复摄取（在仅追加证据上进行重复检查），仅在成功时推进游标，并记录运行。由于每次运行都是幂等的，因此可以安全地重试和调度，Temporal 形状的属性在一个 Postgres 上，无需外部工作流引擎。秘密在存储前使用 AES-256-GCM 进行加密。参见 [docs/connectors.md](./docs/connectors.md)。 ## 查看管道 每次提炼、搜索、漂移扫描和连接器同步都记录为 Postgres 上的一个运行：延迟、提供者报告的实际令牌使用情况、诚实的成本估算和错误。聚合提供计数、错误率、p50 和 p95 延迟、令牌和成本，按类型划分。 成本是估算值，而不是账单，未知模型显示为未知，而不是虚构的零。此值为 Langfuse 形状的值，无需第二个系统运行，即遵循“一 Postgres”的规则。 ```bash pnpm marrow runs # 最近的跟踪 pnpm marrow observe # 聚合指标 ``` 参见 [docs/observability.md](./docs/observability.md)。 ## 连接到 Claude Code 或 Codex 骨髓通过 MCP 为编码代理提供任务范围的上下文。将 Claude Code 指向 MCP 服务器包： ```bash claude mcp add marrow \ -e DATABASE_URL=postgres://marrow:marrow@localhost:5432/marrow \ -e MARROW_API_KEY=sk-ant-... \ -- pnpm --dir /ABSOLUTE/PATH/TO/marrow exec tsx packages/mcp-server/src/main.ts ``` 在 `@marrowhq/mcp-server` 最新版本与此仓库匹配后，将最后一个命令替换为 `-- npx -y @marrowhq/mcp-server`。 嵌入是零配置的（本地模型在进程中运行），因此无需嵌入端点；仅当您想使用自己的端点时，请设置 `MARROW_EMBEDDING_BASE_URL`。对于 Codex 或任何其他 MCP 主机，请使用相同的命令和环境变量作为 `mcpServers` 条目。 代理然后使用 `prepare_task` 获取其任务简报，并在人类想要真相健康时调用 `maintain_truth`。它仍然具有 `search`、`get_decisions`、`get_goals`、`get_open_questions`、`get_entity` 和 `trace_to_source`（读取，每个都有状态和溯源），以及 `append_evidence`、`propose_node` 和 `check_drift`（结构化写入）。`check_drift` 将工作存储库与房间的已决定事实进行比较，并将与某个事实相矛盾的代码标记为开放问题，即代码时间护栏，以防止代理构建与房间决定相反的内容。它永远不能将节点提升为已决定；只有人类答案可以。 ## 自主托管 开源核心，Apache 2.0，基于 Postgres 和一个模型密钥自行托管。此公共仓库是 CLI、MCP 服务器、引擎、本地控制台、文档和登陆源。托管产品工作与此开源仓库分开。 ## 状态 早期，但可用。核心循环已经就位：摄取产品房间证据，将已决定与开放的产品真相提炼成具有溯源的证据，为 CLI/MCP 提供任务范围的上下文，维护目标，并捕获与已决定事实的漂移。 启动操作位于 [docs/launch.md](./docs/launch.md)。`pnpm launch:preflight` 在公共推送之前检查 npm、GitHub、Vercel、DNS、基准声明和包允许列表。 ## 许可证 Apache 2.0。参见 [LICENSE](./LICENSE)。