Arra Memory Lab

신뢰할 수 있는 AI 메모리의 기반이 되는 계약(contract)을 학습하기 위한 독립형 단일 사용자 Cloudflare 랩입니다: 권위 있는 소스(authoritative sources), 재구축 가능한 임베딩(rebuildable embeddings), 증거 기반 관찰(evidence-backed observations), 검사 가능한 하이브리드 검색(inspectable hybrid recall), 경계가 있는 추적(bounded traces), 그리고 변경 전 미리보기(preview-before-mutation) 작업을 다룹니다.

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

이 랩이 보여주는 것

• 권위 계층(Authority tiers): 메모리는 권위가 있으며, 청크/임베딩과 관찰은 파생된 것입니다.

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

• 증거 계보(Evidence lineage): 관찰은 원본 메모리 ID, 개정 버전, 해시를 유지합니다.

• 안전한 변경(Safe mutation): forget과 rebuild는 먼저 드라이런(dry-run)을 수행하며, forget 확인은 정확한 미리보기 스냅샷에 바인딩되고, 확인된 rebuild 작업은 범위가 제한됩니다.

• 데이터 최소화(Data minimization): 최신 100개의 검색 추적에는 운영 메타데이터만 포함되며, 쿼리나 메모리 내용은 절대 포함되지 않습니다.

• 추적 연계 검색(Trace-linked recall): 추적 저장이 성공하면 검색은 traceId를 반환합니다. 순위 결과 스냅샷에는 메모리 ID, 순위/점수 출처, 원본 개정 버전, 원본 해시만 보존됩니다.

• 명시적 대체(Explicit supersession): supersedesMemoryId는 쓰기 시점에 한 번만 해석되어 불변의 ID/개정 버전/해시 스냅샷으로 변환됩니다. 시간적 그래프를 추론하지 않습니다.

• 소규모 출처(Small provenance): project, sourcePath, createdBy는 구조화된 필드이며, Oracle 정체성은 oracle-<name> 태그로 유지됩니다. retrospective와 cheatsheet는 일급 메모리 종류입니다.

추적의 queryHash는 익명화가 아닌 상관관계 핸들입니다. 특히 낮은 엔트로피 쿼리의 경우 더욱 그렇습니다. 따라서 원시 쿼리와 메모리 내용은 생략되지만 추적 접근은 계속 보호됩니다.

Related MCP server: Ghostkeep

릴리스 정체성

package.json은 랩의 방콕 CalVer에 대한 단일 정보 소스입니다: YY.M.D-alpha.HMM, 여기서 HMM = 시간 × 100 + 분이며 Asia/Bangkok 기준입니다. 빌드는 해당 문자열만 공개 클라이언트에 주입합니다. /api/info, MCP initialize, lab_info 도구, UI 푸터는 모두 동일한 값을 보고합니다.

npm run version:next   # preview the next available Bangkok minute
npm run version:bump   # update package.json + package-lock.json, no commit/tag
npm run version:check  # fail if format or lock metadata drift

bump 명령은 같은 분 내 재사용, 시계 롤백, 알 수 없는 플래그, 그리고 기존 arra-memory-lab-v* 태그보다 최신이 아닌 CalVer을 거부합니다.

이는 의도적으로 프로덕션 정체성 또는 테넌시 설계가 아닙니다. 비공개 웹 API는 하나의 소유자 베어러 시크릿을 사용합니다. 원격 MCP 경로는 OAuth 2.1, S256 PKCE, 동적 클라이언트 등록(DCR), 만료되는 액세스 토큰, 리프레시 토큰을 사용하여 Claude.ai 및 기타 웹 MCP 클라이언트가 소유자 암호를 저장하지 않고도 연결할 수 있게 합니다. 테넌트, 큐, ANN 인덱스, 자율 통합은 계속 보류 상태입니다.

데이터 흐름 및 개인정보 보호 경계

• 메모리 생성은 D1 소스 쓰기가 성공한 후 최선 노력(best-effort) 방식으로 임베딩을 시도합니다.

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

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

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

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

Cloudflare 계정 정책과 위협 모델이 이 처리를 명시적으로 허용하지 않는 한 합성 데이터 또는 비민감 데이터를 사용하십시오. 로컬 개발에서도 Workers AI 바인딩은 원격 서비스에 접근하며 사용량이 발생할 수 있습니다.

배포

1. 위의 Deploy to Cloudflare를 클릭하고 저장소 배포를 승인합니다.

2. Cloudflare 배포 양식에서 LAB_ACCESS_TOKEN을 입력하라는 메시지가 표시됩니다. 긴 임의 값(예: openssl rand -hex 32로 생성된 값)을 제공하십시오. Cloudflare는 이를 시크릿 바인딩으로 저장합니다. 동일한 값이 브라우저 API를 잠금 해제하고 새 OAuth 클라이언트를 승인하지만, OAuth 클라이언트는 이 값을 절대 받지 않습니다.

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

체크아웃된 릴리스의 경우 wrangler.jsonc의 플레이스홀더 ID를 편집하지 마십시오. 릴리스 헬퍼는 먼저 빌드와 테스트를 수행하고, arra-memory-lab라는 이름의 D1 데이터베이스 하나와 arra-memory-lab-oauth라는 이름의 KV 네임스페이스 하나를 정확히 확인한 다음, 해당 ID를 모드 0600 임시 구성에만 쓰고, 마이그레이션을 적용한 후 동일한 불변 빌드를 배포합니다:

npm run deploy:dry-run
npm run deploy

비공개 /api/* 경로는 Authorization: Bearer $LAB_ACCESS_TOKEN을 요구합니다. /mcp는 랩의 OAuth 제공자가 발급한 액세스 토큰만 허용하며, 소유자 시크릿 자체는 여기서 거부됩니다. OAuth 검색, DCR, 토큰 교환, 승인 UI는 /.well-known/*, /oauth/*, /authorize 아래에 있습니다. GET /api/info만 공개 애플리케이션 콘텐츠입니다. LAB_ACCESS_TOKEN이 없으면 비공개 API 접근과 OAuth 승인은 실패 시 잠금(fail closed)됩니다.

동의 응답은 의도적으로 CSP form-action을 생략합니다. 실제 MCP 호스트가 사용하는 임베디드 OAuth 브라우저는 정확한 출처 허용 목록이 있어도 제출이 차단되었습니다. 양식 대상은 고정된 상대 경로 /authorize입니다. base-uri 'none'은 기본 대상 재작성을 방지하고, 모든 DCR 파생 필드는 HTML 이스케이프되며, POST 경로는 OAuth 제공자가 검증하고 리디렉션을 완료하기 전에 PKCE/스코프/클라이언트 상태를 다시 파싱합니다. 이는 측정된 호환성 경계이지 일반적인 CSP 권장 사항이 아닙니다.

원클릭 배포에 D1을 사용하는 이유는?

Cloudflare의 배포 흐름이 D1을 자동으로 프로비저닝하고 바인딩할 수 있어 이 랩을 진정한 원클릭에 가깝게 유지할 수 있기 때문에 D1을 사용합니다. 이는 의도적인 제공자 결합입니다. 이 버전은 휴대용 데이터베이스 계층이나 Turso/libSQL 배포를 보여주지 않습니다. 이는 집중된 Cloudflare 랩에는 허용 가능하지만, 일반적인 프로덕션 권장 사항은 아닙니다.

로컬 개발

설치/빌드/배포에는 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

postbuild 훅은 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":"retrospective","tags":["architecture"],"project":"github.com/soul-brews-studio/claude-ai-mcp-poc","sourcePath":"ψ/memory/retrospectives/example.md","createdBy":"rrr","oracleName":"neo","supersedesMemoryId":"OPTIONAL_EXISTING_MEMORY_ID"}'

# 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","project":"github.com/soul-brews-studio/claude-ai-mcp-poc","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, trace_list, trace_get.

lab_info는 유효한 토큰에 대해 항상 제공됩니다. memory:read는 recall, memory_stats, trace_list, trace_get을 제어하고, memory:write는 remember, observe, forget, rebuild_index를 제어합니다. 스코프 검사는 리프레시 토큰 다운스코핑을 포함하여 모든 무상태 요청에서 래핑 해제된 액세스 토큰 스코프를 사용합니다.

구현은 @modelcontextprotocol/server@2.0.0을 고정하고 Cloudflare Agents createMcpHandler 래퍼를 사용합니다. "SDK v2"와 "프로토콜 버전"은 별개의 축입니다. 엔드포인트는 최신 2026-07-28 요청을 처리하고 2025년대 initialize 흐름을 무상태 호환 경로로 유지합니다. 어느 경로도 Mcp-Session-Id를 생성하지 않습니다. 모든 요청은 새 서버 인스턴스를 받습니다. 증명 매트릭스는 docs/mcp-v2-stateless.md를 참조하십시오.

MCP 클라이언트 연결 또는 재로드

npm run mcp:connect -- codex "$LAB_URL/mcp" arra-memory-lab
# or Claude Code:
npm run mcp:connect -- claude "$LAB_URL/mcp" arra-memory-lab

헬퍼는 URL을 등록하고 클라이언트의 OAuth 로그인을 시작합니다. 다시 실행하면 등록/로그인 경로가 새로 고쳐집니다. Claude.ai의 경우 Settings → Connectors → Add custom connector를 열고 https://…/mcp만 입력한 다음 Connect를 클릭하고 승인 페이지에서 랩 암호를 입력합니다.

Bearer 대 OAuth

측정된 결정과 정리된 증명은 docs/provenance-oauth-report.md를 참조하십시오.

실패 계약

• 권위 있는 메모리 쓰기는 임베딩 실패에도 생존합니다.

• 하이브리드 검색은 임베딩 제공자 실패 시에만 성능이 저하되며 그 이유를 보고합니다.

• 명시적 의미론적 검색은 의미론적 추론을 사용할 수 없으면 오류를 반환합니다.

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

• 추적 쓰기 실패는 성공적인 검색을 변경하거나 원래 오류를 가리지 않습니다.

• 완료된 추적, 순위 결과 링크, 보존 정리는 하나의 D1 배치에서 시도됩니다. 추적 저장은 검색에 대해 실패 안전(fail-safe) 상태를 유지합니다.

• 메모리를 잊어도 과거 추적 결과 또는 대체 스냅샷은 지워지지 않습니다. 추적 정리는 순위 링크에 연쇄적으로 적용됩니다.

• Rebuild는 파생 청크를 교체하기 전에 원본 개정 버전/해시를 다시 확인합니다.

• Forget 확인은 미리보기가 반환한 개정 버전, 해시, 청크 수, 관찰 수를 요구합니다. 오래된 확인은 HTTP 409 / stale_preview로 실패합니다.

현재 런타임 경계는 CONTRACT.md, UI 시스템은 DESIGN.md를 참조하십시오.

주요 플랫폼 참고 자료

• Cloudflare 배포 버튼 및 자동 리소스 프로비저닝

• Cloudflare D1 바인딩 구성

• Cloudflare Workers AI 바인딩

• 원격 MCP용 Cloudflare OAuth 제공자

• Anthropic 원격 MCP 커넥터 인증

• EmbeddingGemma 300M 모델 계약

• Cloudflare D1과 Drizzle ORM