SoupNet-oss

Soup.net 是 AI 代理的共享记忆。你使用的代理会在判断发生时记录你的判断，然后在你的下一次会话、不同的工具或加入项目的协作者的代理中把它们带回来。配方书会自己构建。

存储单元是一个配方：一个结构化的、有证据支持的判断——“作为 [角色] 在 [目标] 上工作，我偏好 [X]，因为 [原因]”，加上逐字引用的支持性引文。代理通过配方检查来使用它：一种语义搜索，其唯一副作用是追加。你的代理用当前关于你品味的假设进行搜索，得到你之前的决定及其证据，而这个假设本身就成为未来代理可以找到的痕迹。没有任何东西会被覆盖，每次检查都会让下一次更聪明——蚂蚁用来强化信息素轨迹的同一机制（stigmergy）。

为什么

AI 代理自己完成越来越大块的工作，而你从不只运行一个。每个新会话都是一个全新的代理，每个工具又是另一个，协作者也带来他们自己的。每个都需要你的答案，分别地，从头开始。稀缺资源是你。

大多数代理记忆存储事实和对话状态，在一个供应商的生态内。Soup.net 存储判断本身，以及限定它的上下文和证据，它与你同在——可移植到 Claude Code、ChatGPT、Gemini 或你的团队内部编写的自定义代理。过去的决定作为上下文而非指令回来：你的代理会权衡它们与当前任务，而不是重放过时的事实。

因为每次检查都会留下一个带日期的、仅追加的痕迹，你也免费获得可观测性：一个可检查的日志，记录你的代理代表你行使的判断。随着代理在检查之间运行时间越来越长，这份记录让你保持在驾驶座上。

Soup.net 是用自己的工作流开发的。构建它的 AI 代理在工作的同时，将设计决策配方检查到维护者的语料库中——因此系统的设计历史存在于系统中，扩展它的代理会检索塑造它们正在修改的代码的判断。

配方地图是人类观察该语料库增长的方式：配方按语义相似性聚类，投影到你选择的任意两个概念轴上。

Related MCP server: memmd-mcp

现场数据

2026 年年中，一项现场评估在维护者的真实工作上运行——两个项目，协调器代理生成子代理群，每个代理都被告知在判断时刻进行检查，并自我报告每次检查对它做了什么。诚实的范围：一个开发者，一个 3 个月的语料库上的 3 天反馈窗口，所有 Claude 家族代理。观察性的，不是基准。

• 在 64 个不同的代理会话中进行了 178 次检查，在一个可连接的日志中。

• 68% 的检查确认了先前的决定，因此代理继续工作而不是打断人类。

• 约 4.5% 的检查改变了代理的行动。按设计罕见——但那个尾部是价值集中的地方：最强的案例是一个代理的“放弃这个索引”的测量但错误的结论被人类质疑、重新测试、反转，并永久记录，这样未来的代理就不会重新推导它。

• 12 个审计的高影响案例中有 12 个在原始语料库中成立；没有一个被反驳。

• 成本：每次检查返回约 1–3 KB 的上下文，一个 4–6 KB 的会话简报，0.15–0.36 秒的热检查延迟。

已知的失败模式，来自同一评估：自我报告从未说过“不”（把每个百分比都视为上限）；一个年轻的语料库在大约 1/10 的检查中返回空结果（那是播种，不是失败）；批量结束会话的检查大多检索代理自己的新鲜痕迹。在判断时刻检查，而不是在闭幕式上。还有一个诚实的差距：纯 URL 路径已测试可与 ChatGPT（网页）、Gemini 和 Claude 一起工作——但到目前为止，每个仪器化的现场行都来自 Claude Code 中的 Claude 家族代理，因此跨供应商的有效性数字还不存在。如果你从另一个工具运行它，你就在生成第一批真实数据。

试试

• 托管 — 免费，对新注册开放：soup.net。该网站为你使用的任何代理生成一键简报，从纯网页聊天机器人到完整的 MCP 客户端。在 claude.ai 上，从 Connectors Directory 列表 一键连接（所有计划，包括免费版）。

  网页聊天机器人路径是一流的界面，不是后备方案：没有 MCP 的代理通过生成的链接参与——配方检查是代理构造或人类点击的 URL。已测试可与 ChatGPT（网页）、Gemini 和 Claude 一起工作，包括免费层级。

• 自托管 — MIT 许可，刻意简单的技术栈（Postgres 17 + pgvector、Hono、React）。核心检查路径上服务器不运行 LLM：代理在它们已经运行的地方进行推理；服务器做存储和向量搜索。（可选的高级功能——默认关闭，按用户选择加入——使用一次服务器端 LLM 调用；见 docs/planning/premium-llm-features.md。）嵌入默认使用 Google 的 Gemini API（AI Studio 密钥 可用；一个确定性的存根提供者覆盖开发和测试，零 API 调用），但自托管者可以完全本地运行它们，无需密钥——在进程内 CPU 上，或针对任何本地 /v1/embeddings 服务器（下面的 本地 / 离线嵌入）。然后 Gemini 仅用于可选的高级功能。快速开始如下。无论哪种方式，你的语料库都可以导出为单个 JSON 文件（GET /auth/me/export，已登录）——并导入回来：POST /import 接受该文件作为原始请求体（仅限已登录的人类），因此语料库可以在实例之间移动、从备份恢复或重建为新的配方书。默认情况下，导入会创建一个新的配方书（用 ?book_name= 命名）；传递 ?book=<slug|id> 导入到现有的。重新导入你自己的语料库是幂等的（精确 ID 更新——重新上传会跳过已经落地的）；导入一个 ID 属于实例上其他人的语料库会生成新的 ID 并报告旧→新映射，所以它是一个可移植性工具，不是字节相同的恢复（一行甚至可以没有 ID 就导入）。导入通过内容寻址的向量缓存异步重新嵌入，因此实例之前嵌入过的文本零提供者调用——而删除账户会保留该共享缓存，所以重新配置相同的语料库保持免费。

将支持 MCP 的代理指向托管服务，一行即可：

claude mcp add --transport http soupnet https://mcp.soup.net/mcp --header "Authorization: Bearer YOUR_KEY"

了解更多

• docs/benchmarks.md — 跨 PERMA、SWE-Lancer 和 π-Bench 的受控基准结果（摘要 + 每个基准的详细页面），补充上面的现场数据

• docs/design-thinking.md — 产品愿景、用户原型、配方检查场景

• docs/architecture/overview.md — 系统拓扑、三个代理表面、数据模型概览

• docs/architecture/ranking-engine.md — check_recipe 排名引擎：目标、逐阶段流水线、扩展点和假设寄存器

• docs/planning/pivot-search-as-logging.md — 搜索即日志的转变（决策历史）

• docs/engineering-principles.md — 支配每个设计选择的 13 条原则

• docs/backlog.md — 当前工作队列；已完成项在 docs/backlog-completed.md

• docs/adr/ — 带日期和状态行的架构决策

• docs/testing-plan.md、docs/workflows/security.md — 测试和审计如何工作

每个文档的顶部部分都说明其目的以及它与附近文档的区别。如果你添加新文档，也这样做——并链接到本节。

快速开始

cp .env.example .env
# Edit .env: set JWT_SECRET (openssl rand -hex 32), DEV_USERNAME, DEV_PASSWORD.
# GEMINI_API_KEY is optional locally — leave EMBEDDINGS_PROVIDER=stub for tests.

docker compose up --build -d    # postgres + backend (with in-process embedding worker) + mailpit
npm run dev:frontend            # Vite SPA on :5273 (separate terminal)

打开 http://localhost:5273 — 登录，生成一个配方检查链接，然后开始检查配方。

用于本地开发的 Mailpit Web UI：http://localhost:8625

本地 / 离线嵌入

语义搜索需要一个嵌入提供者，由 EMBEDDINGS_PROVIDER 在整个进程中选定。默认（gemini）调用 Google；stub 为开发/测试返回确定性的假向量。另外两个提供者让自托管者运行真正的语义搜索，无需外部 API 和密钥：

• local — 通过 @huggingface/transformers 的进程内 CPU 模型（默认 bge-small-en-v1.5）。设置 EMBEDDINGS_PROVIDER=local 即可——模型（约 23 MB）下载一次。摩擦最小；适合试驾和 CI。

• openai-compatible — 指向任何本地 OpenAI 风格的 /v1/embeddings 服务器，因此你可以通过已经运行的工具提供更强的模型：

  EMBEDDINGS_PROVIDER=openai-compatible
  EMBEDDINGS_BASE_URL=http://localhost:8080/v1   # llama.cpp: llama-server -m <model>.gguf --embedding --pooling mean
  EMBEDDINGS_MODEL=<the id the server reports>
  # EMBEDDINGS_API_KEY=...                        # optional bearer, if your server requires one

  LM Studio（http://localhost:1234/v1）、Ollama（ollama pull nomic-embed-text → http://localhost:11434/v1）和 Hugging Face TEI 的工作方式相同——任何 /v1/embeddings 端点。如果 Soup.net 在自己的容器中运行，localhost 指的是容器：使用 host.docker.internal 或主机 IP。

两个注意事项。 每个部署一个嵌入提供者——来自不同模型的向量位于不同的语义空间中，永远不会混合，因此切换提供者或模型意味着重新嵌入语料库（搜索会安全失败到空结果，直到你这样做）。而且模型的原生维度必须 ≤ 3072（或支持 MRL）。在底层，小于 3072 的向量被零填充到现有的 halfvec(3072) 列中，这对余弦来说是可证明的无损——设计、数学和退出标准在 ADR-0023 和 docs/planning/local-embedding-provider.md 中。

仓库布局

这是整个仓库的定位图。带有自己 README（或在其顶部文档中说明目的）的子目录承载细节；此图链接到它们。

apps/backend       Hono HTTP server (port 3101) — auth, REST API, /check recipe page,
                   remote MCP endpoint (/mcp), plus in-process pg-boss embedding consumers
                   (src/embedding-worker/). See ADR-0020, ADR-0021.
apps/frontend      Vite React SPA (port 5273) — dashboard, recipe map, admin pages
apps/mcp-server    Stdio MCP server (bundled as soupnet.mcpb for Claude Desktop)

packages/db        Drizzle schema + migrations — single claimnet schema, single source of truth
packages/domain    Business logic, ranking rules, shared agent-facing copy (no I/O)
packages/contracts Zod schemas + OpenAPI registry (mostly pre-pivot shapes; new routes inline-validate)
packages/client-sdk REST API client wrapper
packages/api-client Auto-generated React Query hooks (regenerated from contracts)
packages/config    Shared tsconfig, ESLint config

docs/              Top level: design-thinking.md, engineering-principles.md, testing-plan.md,
                   backlog.md + backlog-completed.md (the cross-session work queue)
docs/adr/          Architecture decision records — dated, with status lines
docs/architecture/ How the code works: overview, search algorithms, data model (generated)
docs/planning/     Validated proposals ready (or nearly ready) to implement
docs/rough-notes/  Dated working notes, meant to rot — see its README for the contract
                   and the fidelity ladder (rough-notes → planning → adopted docs/ADRs)
docs/workflows/    Repeatable processes (security audit cycle, etc.)
docs/connectors/   Connector-facing docs (claude.ai directory submission material)
docs/legal/        Privacy policy + ToS source material

scripts/           Dev/ops one-offs: test-ci-local.mjs (the canonical gate), cleanup,
                   data-model doc generation, QA harnesses

MCP 设置

主要路径是通过 Streamable HTTP 的远程 MCP（无状态，ADR-0021）。将你的代理指向后端的 /mcp 端点，使用 API 密钥作为 Bearer 令牌——无论你是本地运行（http://localhost:3101/mcp）还是针对部署的实例（https://mcp.soup.net/mcp），工作方式相同。

两条凭证路径，一个端点。 API 密钥 Bearer（见下文）适合开发者工具，粘贴密钥是自然操作。聊天式客户端——claude.ai、ChatGPT Developer Mode、Mistral Le Chat、Perplexity——通过 OAuth 2.1 连接到同一个 /mcp URL：服务器实现了 RFC 8414 元数据（/.well-known/oauth-authorization-server 和 /oauth-protected-resource）、动态客户端注册（RFC 7591，POST /oauth/register）、带逐食谱书同意页面的 PKCE-S256 授权，以及刷新令牌轮换（apps/backend/src/routes/oauth.ts）。在 claude.ai 上，Soup.net 是 Anthropic Connectors Directory 中列出的连接器——从 claude.ai/directory/soupnet 一键连接，适用于包括 Free 在内的所有 Claude 套餐。各客户端的逐步指南：docs/connectors/index.md（渲染于 soup.net/info/connect）。

1. 生成 API 密钥 — 登录 SPA，打开 API keys，创建每日密钥或限定范围密钥，复制原始值。

2. 添加服务器。 在 Claude Code 中只需一行：

claude mcp add --transport http soupnet http://localhost:3101/mcp --header "Authorization: Bearer YOUR_KEY"

任何 HTTP-MCP 客户端都使用同样的三个事实，无论其配置模式如何命名：

{
  "mcpServers": {
    "soupnet": {
      "type": "http",
      "url": "http://localhost:3101/mcp",
      "headers": { "Authorization": "Bearer YOUR_KEY" }
    }
  }
}

各客户端的配置块（Codex、VS Code、Google Antigravity、通过 mcp-remote 或 apps/mcp-server/ 中 stdio 服务器的 Claude Desktop）位于 /docs/mcp-setup 指南中——由你自己的实例提供，或从仪表盘访问时托管并预填你的密钥。一个常青页面，而非分叉副本。

3. 重启客户端（或在 Claude Code 中运行 /mcp）以加载新服务器。可用工具：check_recipe、get_briefing、list_my_recipe_books、update_recipe_book_description。

工具契约是只读 + 仅追加。没有更新或删除接口，因此一个困惑的（或被提示注入的）代理可以添加痕迹，但永远无法销毁或重写记录——如果你以安全态势评估 MCP 服务器，这一点值得了解。

开发

前置条件： Node 24 LTS、npm ≥ 10、Docker

通过 Docker 启动一切：

docker compose up --build -d    # postgres + backend + worker
npm run dev:frontend             # Vite dev server (separate terminal)

或在本地以热重载方式运行后端：

docker compose up -d postgres    # just the database
npm run build:packages           # build internal packages
source .env && npm run dev:backend   # Hono with tsx watch on :3101
npm run dev:frontend             # Vite on :5273

数据库迁移：

cd packages/db
npx drizzle-kit generate         # generate migration from schema changes
# migrations auto-apply at backend startup

测试

npx vitest run                    # all tests (.env auto-loaded by vitest config)
npx vitest watch                  # watch mode
npm run test:ci                   # clean reproduction of CI (fresh DB on :5534, no Gemini)

集成测试会访问正在运行的 Docker 后端，因此请保持 docker compose up -d 处于活动状态。

集成测试会在实时数据库中创建测试数据（使用 @test.local 邮箱的用户，位于他们自己的食谱书中）。测试痕迹按食谱书限定范围，不会出现在你的个人搜索结果中。要清理累积的测试数据：

npx tsx scripts/cleanup-test-data.ts           # clean up
npx tsx scripts/cleanup-test-data.ts --status  # just show counts

有关覆盖预期和测试类别的说明，请参阅 docs/testing-plan.md。

公开版与托管版

这是开源代码库。托管版的部署细节——Terraform、运维手册、AWS 拓扑——存放在一个单独的私有配套仓库中，因为它们特定于某一运营商的基础设施选择，不具有普遍适用性。

判断内容是否属于本仓库的标准： 自托管者在自己基础设施上运行这套技术栈时是否需要这些内容？如果需要，就放在这里。如果特定于某个托管部署，就不放。

该应用与部署无关——只需要带 pgvector 的 Postgres 17 和 .env.example 中的环境变量。也与容器平台无关：本地用 Docker Compose，生产环境用任何其他平台（Kubernetes、ECS、Fly、Hetzner）。

关键规则

• 路由处理器或 React 组件中不写业务逻辑——使用 services

• 绝不直接修改数据库——始终使用 Drizzle 迁移

• 类型专用导入使用 import type { ... }；使用 unknown 而非 any

• 参见 docs/engineering-principles.md

背后的人

Soup.net 的很大一部分——代码、文档、本 README 的部分内容——由 AI 代理编写。所有这些都由一个可验证的人类指导、审查并负责：Andy Forest，一位拥有 30 年经验的系统架构师和开发者。近期工作：Scratch Foundation 的 AI 平台架构师；运营 Steamlabs 十年，这是一家加拿大非营利组织，为 850,000+ 名青少年学习者带来了动手 AI 教育；合著者 Make: AI Robots（O'Reilly，已译成日文）；LiteLLM 贡献者。

Soup.net 的存在是因为他运行大量代理，并希望自己的判断能在它们之间存续。本 README 所描述的问责模式——代理做工作，人类为之负责——正是本仓库自身的构建方式。

许可证与商标

本仓库中的代码和文档根据 MIT License 授权。

Soup.net 名称、徽标、字标和品牌插画资产标识 soup.net 上的托管服务，不在 MIT 授权范围内。可以自由分叉代码、自托管、在此基础上构建——但请以你自己的名称和品牌呈现你的公共实例。