HutchDB

HutchDB

为 AI Agent 打造的数据库。无需 Schema、SQL 或结构。
一个结构化工作区，Claude Code、Codex、Cursor、Hermes、Claw、Grokbot 和其他 MCP 客户端都可以共同读取和更新。开源。

什么是 HutchDB？

HutchDB Core 是一个无头、单用户 MCP 服务，让你运行的每个 Agent 都能使用相同的持久化结构化数据。连接 Claude Code、Codex、Cursor、VS Code 或其他 MCP 客户端，即可跨会话存储、查询和更新共享记录集合。

集合使用无需预定义 Schema 的 Postgres JSONB，支持全文搜索、可选验证和视图定义。没有仪表板、没有登录页面，也不需要繁琐的 OAuth 流程——只有一个 MCP 端点和一个由你掌控的 Postgres 数据库。

此仓库是开源引擎。如果你希望用户和 Agent 在同一个可视化工作区中协作，HutchDB Cloud 提供网页视图、已发布页面、社交登录和组织共享。请参阅下文的 Core 与 Cloud 对比。

可以用它做什么？

Agent 工作数据的默认存放位置通常是 Markdown 文件：TODO.md、笔记目录，或写满文字的记忆文件。这适用于一个 Agent 给自己记笔记。但只要你想进行筛选（“列出严重程度高于 2 的未修复 Bug”）、汇总（“按阶段统计管道价值”），或让两个 Agent 同时更新同一列表而不互相覆盖，就会遇到问题。

HutchDB 将相同信息保存为真实记录：每条记录都可单独寻址、可查询，并且支持多个 Agent 同时安全地读取和更新。因此，只要 Agent 生成或使用的结构化数据需要在一次聊天结束后继续保留，HutchDB 就能派上用场。人们常用它来处理以下场景：

不断积累的研究。 客户访谈、竞争对手分析、抓取的商品列表、文献综述。每次会话都会向集合中添加记录；之后的任何会话都可以查询整个集合。

“把这五个竞争对手的定价页面保存到 competitor-pricing，然后告诉我与上个月相比有哪些变化。”

原本需要用电子表格维护的追踪列表。 Bug 报告、内容日历、求职申请、库存、阅读清单。与电子表格的区别在于：Agent 可以在任务进行中查询和更新记录。

“将此 Bug 以 high 严重程度记录到 bug-reports，然后列出所有仍未关闭的条目。”

由多个 Agent 交接处理的工作流。 一个 Agent 收集记录，另一个处理记录，第三个汇报结果。每条记录上的状态字段会标记其在工作流中的进度，因此无需在工具之间复制数据。

“提取所有状态为 new 的 leads 记录，逐条补充信息，并将状态设为 ready-for-outreach。”

长期项目的工作状态。 决策、待解决问题和待办事项在上下文窗口关闭后仍可查询。新会话可以先询问之前的进展，而不必重新听取简报。

“我们上周对定价页面做了什么决定？还有哪些问题尚未解决？”

可重复使用的操作手册。 为定期执行的任务（每周报告、发布检查清单、内容制作）保存说明、输入和当前状态，让任何 Agent 都能接手执行。

“运行 weekly-metrics 操作手册，并将结果保存到 weekly-reports。”

这些场景都无需预先设计架构：集合会在首次写入时自动创建，记录则可采用任意 JSON 格式。从“把这个保存到 HutchDB”开始，然后就能通过任何已连接的 Agent 查询相同记录。

快速开始

注意：完整文档请访问 hutchdb.com。

1. 克隆并启动（Docker）：

   git clone https://github.com/ExpeditedProjects/hutchdb
   cd hutchdb
   docker compose up
   

   Core 会迁移数据库，并在端口 3000 上启动。单例用户和个人组织会在首次请求时按需创建——无需执行种子数据步骤。

2. 限制访问（可选，但在非本地主机环境下建议启用）——启动前设置 API 密钥，要求每次 MCP 调用都携带 bearer token：

   export HUTCH_API_KEY="$(openssl rand -hex 32)"
   

   如果未设置，所有请求都会被信任——在本地主机上没问题，但不适用于公开主机。

3. 连接你的 Agent。 对于 Claude Code，请将以下内容添加到 MCP 配置中：

   {
     "mcpServers": {
       "hutch": {
         "type": "http",
         "url": "http://localhost:3000/api/mcp",
         "headers": {
           "Authorization": "Bearer YOUR_HUTCH_API_KEY"
         }
       }
     }
   }
   

   Cursor、Codex 和 VS Code 接受相同格式的 HTTP MCP 服务——url 和 bearer 标头都相同。

4. 开始使用。 集合会在首次写入时自动创建——无需进行任何设置。直接告诉你的 Agent：

   “把这些发布任务保存到 HutchDB。” “上周我们保存了哪些关于定价研究的内容？” “查询 bug-reports 集合，找出提到超时的内容。”

5. 验证端点（可选）：

   curl -X POST http://localhost:3000/api/mcp \
     -H "Authorization: Bearer $HUTCH_API_KEY" \
     -H "Content-Type: application/json" \
     -H "Accept: application/json, text/event-stream" \
     -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'
   

   你应该能看到 hutch_* 工具列表（集合、记录、架构、视图）。

git clone https://github.com/ExpeditedProjects/hutchdb
cd hutchdb
npm install
cp .env.local.example .env.local
# Required: HUTCH_DATABASE_URL
# Optional: HUTCH_API_KEY
npm run db:migrate
npm run dev

Claude Code 连接到本地 Core 实例的典型会话：

You:    Save each of these customer interviews as a record — tag the ones
        that mention pricing.

Agent:  Stored 9 records in `customer-interviews`, 4 tagged "pricing".

You:    (a week later) Which interviewees complained about onboarding?

Agent:  Querying `customer-interviews`... 3 records match: Dana R.,
        Marcus T., and the anonymous Feb 12 call.

记录以任意 JSON 格式存储在 Postgres JSONB 中，可通过包含过滤器、Mongo 风格的运算符（$gt、$in、$exists、$contains，等等）和全文搜索进行查询；如需强制执行结构，也可选择使用架构。需要迁移数据时，可将集合导出为 CSV 或 JSON，也可从中导入。

HutchDB Core 与 HutchDB Cloud

Core 刻意保持精简。如果你需要产品层，请运行 HutchDB Cloud——或者分叉 Core 并构建自己的产品。

claude.ai 需要 OAuth。 Core 不包含 OAuth 授权服务，因此无法开箱即用地将 Core 实例添加到 claude.ai（Web）。Claude Code、Cursor、Codex 和 VS Code 都支持静态 bearer token，可正常使用。

架构

• Next.js App Router — 一个静态落地页、一个 MCP 路由（/api/mcp）、一个 REST 种子路由（/api/v1/collections）。其余内容均已删除。
• Drizzle + Postgres — 每个集合都有自己的 JSONB 文档表；热点字段会自动成为索引列，其他所有字段均通过包含运算符和全文搜索查询。升级使用按集合存储之前的数据库：在运行 db:migrate 后，运行一次 npm run storage:cutover。
• MCP 服务 — 集合工具（包括各集合统计信息）、记录工具（存储/查询/搜索/更新/删除/状态/转换，以及 CSV/JSON 导出和导入）、架构工具（描述/推断/更新）和视图工具。查询支持过滤运算符（$gt/$gte/$lt/$lte/$ne/$in/$nin/$exists/$contains）、字段投影，以及 count/min/max/distinct/sum/avg 聚合。
• 身份验证接缝（src/lib/auth/seam.ts）— 身份验证逻辑的唯一所在：设置 HUTCH_API_KEY 时检查 bearer 密钥，否则使用单例上下文。
• 单例引导（src/lib/auth/singleton.ts）— 一个用户、一个个人组织，在首次请求时延迟创建。

贡献

• 发现了 Bug？ 请附上复现步骤提交问题。
• 想改进 Core？ 欢迎提交 PR——贡献者需签署 CLA，以便维护者将其双重授权给 HutchDB Cloud。请参阅 CONTRIBUTING.md 和 CLA.md。
• 反馈或想法？ 请通过问题联系我们；告诉我们你正在构建什么。

npm test          # vitest
npm run smoke     # end-to-end smoke test against a running instance:
                  #   SMOKE_BASE_URL=http://localhost:3000 npm run smoke
                  #   (keyed mode: add SMOKE_API_KEY=...)

许可证

AGPL v3。