Arra Memory Lab

신뢰할 수 있는 AI 메모리를 뒷받침하는 계약(contracts)을 학습하기 위한 독립형, 단일 사용자 Cloudflare 랩입니다: 권위 있는 소스(authoritative source), 재구성 가능한 임베딩(rebuildable embedding), 증거 기반 관찰(evidence-backed observation), 검사 가능한 하이브리드 검색(inspectable hybrid recall), 범위가 제한된 트레이스(bounded trace), 그리고 변경 전 미리보기(preview-before-mutation) 작업을 다룹니다.

이 배포는 단일 Worker를 생성하고, wrangler.jsonc에 따라 D1 데이터베이스를 자동으로 프로비저닝하며, 배포 스크립트를 통해 포함된 마이그레이션을 실행합니다. Workers AI는 768차원의 @cf/google/embeddinggemma-300m 임베딩을 제공합니다.

이 랩이 보여주는 것

• Authority tiers: 메모리는 권위를 가지며, 청크/임베딩과 관찰(observations)은 프라이머리로부터 파생됩니다.

• Honest recall: 모든 검색은 요청된 모드(yquire 모드), 실제 적용된 모드, 성능 저하(degradation), 순위 출처(rank provenance)를 보고합니다.

• Evidence lineage: 관찰은 원본 메모리 ID, 개정 번호, 해시를 유지합니다.

• 안전한 변경: forget과 rebuild는 먼저 건건히 실행(dry-run)되며, forget 확인은 정확히 동일한 미리보기 스냅샷에 바인딩되고, 확인된 rebuild 지YM도 제한됩니다.

• 데이터 최소화: 최신 100개의 검색 traces에는 운영 관련 메타데이터만 포함되며, 쿼리나 메모리 콘텐츠는 절대 포함되지 않습니다.

trace queryHash는 상관관계 처리 핸들이지, 익명화가 아닙니다. 특히 낮은 엔트로피 쿼리에서 더욱 그렇습니다. 따라서 원본 쿼리와 메모리 콘텐츠가 빠져 있음에도 불구하고 trace 접근은 계속 보호됩니다.

여기에는 의도적으로 프로덕션 수준의 식별/테넌시(tenancy) 디자인이 적용되지 않습니다. 하나의 bearer 토큰을 사용하며, 토큰이 없으면 보호 접근이 폐쇄적으로 실패(fails closed)합니다. OAuth/DCR, 테넌트, 대기열, ANN 인덱스, 자율 통합은 후속 과제로 남겨 두었습니다.

데이터 흐름 및 프라이버시 경계

• 메모리 생성은 먼저 D1 소혁 쓰기가 성공한 뒤 베스트에포트(best-effort) 방식의 임베딩을 시도합니다.

• 의미/하이브리드 검색은 쿼리 텍스트를 Workers AI에 보냅니다.

• 확인된 rebuild는 선택한 메모리의 제목/내용 청크를 Workers AI로 보내고 파생 벡터를 D1에 기록합니다.

• 키워드 검색과 rebuild 미리보기는 Workers AI를 호출하지 않습니다.

• D1은 권위 있는 텍스트와 파생된 청크 텍스트/벡터를 저장하며, 검색 추적은 쿼리 해시와 운영 메타데이터만 저장합니다.

합성 데이터 또는 비민감 데이터를 사용하세요. 특별히 Cloudflare 계정 정책과 위협 모델이 해당 처리를 명시적으로 허용하지 않는 경우에는 더욱 그래야 합니다. 로컬 개발에서도 Workers AI 바인딩은 원격 서비스에 접근하며 요금이 발생할 수 있습니다.

배포

1. 위의 Deploy to Cloudflare 버튼을 클릭하고 리포지토리 배포를 승인하세요.

2. Cloudflare 배포 폼에서 LAB_ACCESS_TOKEN을 입력하도록 요청합니다. 긴 랜덤 값(예: openssl rand -hex 32로 생성)을 입력하세요. Cloudflare는 이 값을 secret 바인딩으로 저장합니다.

3. 배포합니다. 리포지토리의 배포 스크립트는 Worker를 빌드하고 게시하기 전에 D1 마이그레이션을 자동으로 적용합니다.

4. Worker URL을 여세요. 토큰을 한 번만 입력하면 됩니다. 브라우저는 그 토큰을 sessionStorage에만 저장하므로, 브라우저 세션을 종료하면 지워집니다.

만약 배포 폼 또는 자동 마이그레이션 단계에 수동 복구가 필요하면, 다음 CLI 대체 수단을 사용하세요.

printf '%s' 'replace-with-a-long-random-token' | npx wrangler secret put LAB_ACCESS_TOKEN
npx wrangler d1 migrations apply DB --remote

API와 /mcp는 Authorization: Bearer $LAB_ACCESS_TOKEN을 요구합니다. 공개된 것은 GET /api/info뿐이며, 이는 아키텍처/기능 정도만 공개할 뿐 말뭉치 콘텐츠는 공개하지 않습니다. LAB_ACCESS_TOKEN이 없으면 보호된 접근은 차단 실패(fail closed)합니다.

왜 원클릭 배포에 D1인가요?

D1을 사용하는 이유는 Cloudflare의 배포 흐름이 D1을 자동으로 프로비저닝하고 바인딩하여, 이 랩의 진짜에 가까운 원클릭경험을 가능하게 하기 때문입니다. 물론 특정 벤더(provider)에 결합되는 트레이드오프가 있습니다. 이 버전은 이식 가능한 데이터베이스 계층이나 Turso/libSQL 배포를 어떻게 하는지 보여줍니다. 이것은 집중된 Cloudflare 랩에 적합한 선택이며, 일률적인 프로덕션 권장 사항은 아닙니다.

Local development

Node.js를 이용한 설치/빌드/실행, Bun을 이용한 테스트/체크 스크립트, 그리고 Workers AI를 위한 Cloudflare 계정이 필요합니다. Worker와 D1을 로컬에서 실행하더라도 AI 바인딩은 원격으로 남아 있기 때문에 Wrangler가 경고를 표시합니다.

cd labs/arra-memory-lab
npm install
cp .env.example .dev.vars
# Set LAB_ACCESS_TOKEN in .dev.vars
npx wrangler d1 migrations apply DB --local
npm run dev

품질 검사:

npm run typecheck
npm test
npm run build
# or all three:
npm run check

주요창 훅은 dist/에서 .env* 및 .dev.vars* 파일을 제거합니다. 이는 로컬 아티팩트에 대한 심층 방어입니다. Wrangler의 배포 매니페스트는 이러한 개발 파일을 업로드하지 않습니다.

HTTP 예제

export LAB_URL='https://arra-memory-lab.<account>.workers.dev'
export LAB_ACCESS_TOKEN='your-long-random-token'
export AUTH="Authorization: Bearer $LAB_ACCESS_TOKEN"

# Public capability disclosure
curl "$LAB_URL/api/info"

# Create an authoritative memory (indexing is best effort)
curl -X POST "$LAB_URL/api/memories" -H "$AUTH" -H 'Content-Type: application/json' \
  -d '{"title":"Prefer explicit authority","content":"Memories are sources; embeddings are projections.","kind":"decision","tags":["architecture"]}'

# Hybrid recall exposes requested/effective modes and rank provenance
curl -X POST "$LAB_URL/api/search" -H "$AUTH" -H 'Content-Type: application/json' \
  -d '{"query":"Which data is authoritative?","mode":"hybrid","limit":8}'

# Preview a forget and retain the returned expected* fields
curl -X POST "$LAB_URL/api/memories/MEMORY_ID/forget" -H "$AUTH" -H 'Content-Type: application/json' \
  -d '{"confirm":false}'

# Confirm only that exact preview. A changed source/impact returns 409 stale_preview.
curl -X POST "$LAB_URL/api/memories/MEMORY_ID/forget" -H "$AUTH" -H 'Content-Type: application/json' \
  -d '{"confirm":true,"expectedRevision":1,"expectedHash":"COPY_FROM_PREVIEW","expectedChunks":0,"expectedObservationCount":0}'

# Preview a bounded rebuild; confirmed work is capped at 10 memories / 256 chunks
curl -X POST "$LAB_URL/api/index/rebuild" -H "$AUTH" -H 'Content-Type: application/json' \
  -d '{"confirm":false}'

MCP

앱은 /mcp 경로에서 상태 비저장(stateless) Streamable HTTP MCP를 제공하며, 다음 도구들이 있습니다:

lab_info, remember, recall, observe, forget, rebuild_index, memory_stats.

구현은 @modelcontextprotocol/server@2.0.0의 핀 고정 버전을 사용하며, Cloudflare Agents의 createMcpHandler 래퍼를 이용합니다. "SDK v2"와 "protocol submission"은 별개의 축입니다. 끝은 최신 버전인 2026-07-28 요청을 제공하고, 2025 다양한 initialize 플로우는 무상태 호환 레인(stateless compatibility lane)을 유지합니다. 어느 쪽 래인도 Mcp-Session-Id를 만들지 않습니다. 모든 요청은 새로운 서버 인스턴스를 받습니다. 증거 제공 매트릭스는 docs/mcp-v2-stateless.md를 참조하세요.

curl을 사용한 MCP 엔드포인트 확인

curl -X POST "$LAB_URL/mcp" \
  -H "$AUTH" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"1.0"}}}'

MCP 클라이언트 구성

Streamable HTTP 서버를 지원하는 클라이언트의 경우:

{
  "mcpServers": {
    "arra-memory-lab": {
      "type": "http",
      "url": "https://arra-memory-lab.<account>.workers.dev/mcp",
      "headers": {
        "Authorization": "Bearer ${LAB_ACCESS_TOKEN}"
      }
    }
  }
}

클라이언트가 헤더의 환경 변수를 대체하지 못하면, 자격증명 토클을 하드코딩하는 대신 비밀 관리자를 사용하세요. 정확한 구성 래퍼는 MCP 클라이언트마다 다르지만, 엔드포인트와 bearer 헤더는 동일합니다.

실패 계약

• 원본 메모리 절안 쓰기는 임베딩 실패에도 살아남습니다.

• 하이브리드 검색은 임베딩 제공자(provider) 실패에서만 그리드가 낮아지며, 그 사유를 보고합니다.

• 명시적 semantic 검색은 의미 추론(semantic inference)이 불가능하면 오류를 반환합니다.

• 데이터베이스/벡터 오류는 AI 폴백으로 오분류되지 않습니다.

• 실패하는 트레이스는 성공한 소음을 튕기거나, 원본 오류를 가리지 않습니다. (hmm the original pr:"Trace-write failures never modify a successful recall nor mask its original error." I'll present이 오류를 가Didn't realize preserving exact wording could be tricky; translate appropriately.)

• rebuild는 계파/청크를 교체하기 전에 원본 개정 번호와 해시를 다시 확인합니다.

• forget 확인 시 미리보기가 반여한 개정 번호, 해시, 청크 개수, 관찰 개수를 함께 제시해야 합니다. 만료된 확인은 HTTP 409 / stale_preview로 실패합니다.

CONTRACT.md의 번경 불가 v1 경계와 DESIGN.md의 UI 시스템을 참조하세요.

주요 플랫폼 참조

• Cloudflare Deploy buttons and automation provisioning

• Cloudflare D1 binding configuration

• Cloudflare Workers AI bindings

• EmbeddingGemma 300M model contract

• Drizzle ORM with D1