SoupNet-oss

Soup.net은 AI 에이전트를 위한 공유 메모리입니다. 당신과 함께 작업하는 에이전트들은 판단이 일어나는 순간 그 판단을 기록하고, 다음 세션, 다른 도구, 또는 프로젝트에 합류하는 협력자의 에이전트에게 다시 가져옵니다. 레시피 북은 스스로 만들어집니다.

저장 단위는 레시피입니다. 하나의 판단 호출이 구조화되고 증거가 뒷받침된 형태로 기록됩니다 — "[역할]로서 [목표]를 작업하면서, [이유]를 위해 [X]를 선호합니다" — 그리고 그대로 인용된 지원 문구가 함께합니다. 에이전트는 레시피 체크를 통해 이를 사용합니다. 유일한 부수 효과가 추가(append)인 의미론적 검색입니다. 에이전트는 당신의 취향에 대한 현재 가설로 검색하고, 증거와 함께 이전 결정을 돌려받으며, 그 가설 자체가 미래 에이전트가 찾을 수 있는 추적 기록이 됩니다. 어떤 것도 덮어쓰지 않으며, 모든 체크는 다음 체크를 더 똑똑하게 만듭니다 — 개미가 페로몬 흔적을 강화하는 것과 같은 메커니즘(스티그머지)입니다.

왜

AI 에이전트는 스스로 점점 더 큰 작업을 완수하며, 당신은 하나만 실행하지 않습니다. 모든 새 세션은 새로운 에이전트이고, 모든 도구는 또 다른 에이전트이며, 협력자들은 자신의 에이전트를 가져옵니다. 각각은 당신의 답을 별도로, 처음부터 필요로 합니다. 부족한 자원은 바로 당신입니다.

대부분의 에이전트 메모리는 한 공급업체의 생태계 안에서 사실과 대화 상태를 저장합니다. Soup.net은 판단 호출 자체를, 그 범위를 정하는 맥락과 증거와 함께 저장하며, 당신과 함께 이동합니다 — Claude Code, ChatGPT, Gemini, 또는 팀이 사내에서 만든 커스텀 에이전트에 이식 가능합니다. 과거 결정은 지시가 아닌 맥락으로 돌아옵니다. 에이전트는 낡은 사실을 재생하는 대신 현재 작업에 비추어 이를 저울질합니다.

모든 체크는 날짜가 있는 추가 전용 추적을 남기므로, 관찰 가능성도 무료로 얻을 수 있습니다. 에이전트가 당신을 대신해 행사한 판단의 검사 가능한 로그 하나가 생깁니다. 에이전트가 체크인 사이에 더 오래 실행될수록, 그 기록이 당신을 운전석에 앉혀 두는 것입니다.

Soup.net은 자체 워크플로로 개발됩니다. 이를 구축하는 AI 에이전트들은 작업하면서 설계 결정을 레시피 체크로 유지 관리자의 코퍼스에 기록합니다. 따라서 시스템의 설계 역사가 시스템 안에 살아 있고, 시스템을 확장하는 에이전트는 자신이 변경하는 코드를 형성한 판단 호출을 검색합니다.

레시피 맵은 인간이 그 코퍼스가 성장하는 것을 지켜보는 방법입니다. 레시피는 의미론적 유사성으로 클러스터링되어, 선택한 두 개념 축에 투영됩니다.

Related MCP server: memmd-mcp

현장 데이터

2026년 중반, 유지 관리자의 실제 작업에 대한 현장 평가가 실행되었습니다. 두 프로젝트, 하위 에이전트 함대를 생성하는 코디네이터 에이전트, 모든 에이전트가 판단 순간에 체크하고 각 체크가 자신에게 무엇을 했는지 자체 보고하도록 지시받았습니다. 솔직한 범위: 개발자 1명, 3개월 코퍼스에 대한 3일 피드백 창, 모든 Claude 계열 에이전트. 관찰적이며 벤치마크가 아닙니다.

• 64개의 개별 에이전트 세션에서 178개의 체크가 하나의 결합 가능한 로그에 기록되었습니다.

• 체크의 68%가 이전 결정을 확인하여 에이전트가 인간을 방해하는 대신 계속 작업했습니다.

• 체크의 약 4.5%가 에이전트의 행동을 변경했습니다. 설계상 드물지만, 그 꼬리 부분에 가치가 집중됩니다. 가장 강력한 사례는 측정되었지만 잘못된 "이 인덱스 삭제" 결론이 인간에 의해 도전받고, 재테스트되고, 뒤집혀 영구히 기록되어 미래 에이전트가 다시 도출하지 못하게 한 것입니다.

• 감사된 고영향 사례 12건 중 12건이 원시 코퍼스에 대해 유지되었으며, 어떤 것도 모순되지 않았습니다.

• 비용: 체크당 반환된 컨텍스트 약 1–3KB, 세션 브리핑 4–6KB, 웜 체크 지연 시간 0.15–0.36초.

같은 평가에서 알려진 실패 모드: 자체 보고는 한 번도 "아니오"라고 말하지 않았습니다(모든 백분율을 상한으로 취급). 어린 코퍼스는 체크 10건 중 약 1건에서 아무것도 반환하지 않습니다(이는 시딩이지 실패가 아닙니다). 그리고 일괄 처리된 세션 종료 체크는 대부분 에이전트 자신의 새로운 추적을 검색합니다. 판단 순간에 체크하세요. 마무리 의식이 아니라. 그리고 한 가지 솔직한 공백: 일반 URL 경로는 ChatGPT(웹), Gemini, Claude에서 작동하는 것으로 테스트되었지만, 지금까지 계측된 현장 행은 모두 Claude Code의 Claude 계열 에이전트에서 나왔습니다. 따라서 공급업체 간 효과성 수치는 아직 존재하지 않습니다. 다른 하네스에서 실행한다면, 당신이 첫 번째 실제 데이터를 생성하는 것입니다.

사용해 보기

• 호스팅 — 무료이며 신규 가입에 열려 있습니다: soup.net. 이 사이트는 웹 전용 챗봇부터 전체 MCP 클라이언트까지, 사용하는 모든 에이전트에 대한 원클릭 브리핑을 생성합니다. claude.ai에서는 커넥터 디렉토리 목록에서 원클릭으로 연결할 수 있습니다(무료 플랜 포함 모든 플랜).

  웹 챗봇 경로는 일급 인터페이스이지 폴백이 아닙니다. 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 없이 도착해도 가져올 수 있습니다). 가져오기는 콘텐츠 주소 지정 벡터 캐시를 통해 비동기적으로 재임베딩하므로, 인스턴스가 이전에 임베딩한 텍스트는 공급자 호출 비용이 0입니다. 계정 삭제는 공유 캐시를 보존하므로 동일한 코퍼스를 다시 프로비저닝해도 무료로 유지됩니다.

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 웹 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를 통한 Claude Desktop 또는 apps/mcp-server/의 stdio 서버)은 /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를 참조하세요.

공개 버전 vs 호스팅 버전

이것은 오픈소스 코드베이스입니다. 호스팅 버전의 배포 세부 사항 — Terraform, 운영 런북, AWS 토폴로지 — 은 단일 운영자의 인프라 선택에 특화되어 있고 일반적으로 유용하지 않기 때문에 별도의 비공개 동반 리포지토리에 있습니다.

이 리포지토리에 속하는지 테스트하는 기준: 자체 호스팅 사용자가 자신의 인프라에서 이 스택을 실행할 때 이 콘텐츠가 필요한가? 그렇다면 여기에 있습니다. 특정 호스팅 배포에만 해당된다면 여기에 없습니다.

애플리케이션은 배포 방식에 구애받지 않습니다 — pgvector가 포함된 Postgres 17과 .env.example의 환경 변수만 필요합니다. 컨테이너 플랫폼에도 구애받지 않습니다: 로컬에서는 Docker Compose, 프로덕션에서는 다른 모든 것(Kubernetes, ECS, Fly, Hetzner).

핵심 규칙

• 라우트 핸들러나 React 컴포넌트에 비즈니스 로직을 넣지 마세요 — 서비스를 사용하세요

• 직접 DB를 수정하지 마세요 — 항상 Drizzle 마이그레이션을 사용하세요

• 타입 전용 임포트에는 import type { ... }를 사용하고, any 대신 unknown을 사용하세요

• docs/engineering-principles.md 참조

이 프로젝트의 배후에 있는 사람

Soup.net의 상당 부분 — 코드, 문서, 이 README의 일부 — 은 AI 에이전트가 작성했습니다. 모든 것은 한 명의 검증 가능한 인간이 지시하고, 검토하고, 책임을 집니다: Andy Forest, 30년 경력의 시스템 아키텍트이자 개발자. 최근 작업: Scratch Foundation의 AI 플랫폼 아키텍트; 85만 명 이상의 어린 학습자에게 실습형 AI 교육을 제공한 캐나다 비영리 단체 Steamlabs를 10년간 운영; Make: AI Robots(O'Reilly, 일본어로 번역됨) 공동 저자; LiteLLM 기여자.

Soup.net은 그가 많은 에이전트를 운영하면서 자신의 판단이 에이전트들 사이에서 유지되기를 원했기 때문에 존재합니다. 이 README가 설명하는 책임 모델 — 에이전트가 작업을 수행하고, 인간이 그에 대해 책임을 진다 — 은 바로 이 리포지토리 자체가 구축된 방식입니다.

라이선스 및 상표

이 리포지토리의 코드와 문서는 MIT License에 따라 라이선스가 부여됩니다.

Soup.net 이름, 로고, 워드마크 및 브랜드 일러스트레이션 자산은 soup.net의 호스팅 서비스를 식별하며 MIT 허가의 적용을 받지 않습니다. 코드를 포크하고, 자체 호스팅하고, 자유롭게 구축하세요 — 단, 공개 인스턴스는 자신의 이름과 브랜딩으로 제공하세요.