토큰(tokens), 디코딩(decoding), 그리고 Supermemory를 살아있는 공장으로 변모시켜 상호작용 가능한 3D 교육용 앱을 어떻게 구축했는지 — 그리고 왜 메모리가 부가 기능이 아닌 중추(spine)인지에 대하여.

요약 (TL;DR)

Token Factory는 Next.js와 React Three Fiber를 사용한 웹 앱으로, 대규모 언어 모델(LLM)이 텍스트를 생성하는 과정을 산업용 방을 통과하는 물리적인 "토큰 큐브(token cubes)"로 애니메이션화하여 교육합니다: 토크나이저(tokenizer), 임베딩(embeddings), 로짓(logits), 소프트맥스(softmax), 온도(temperature), top-k, top-p, 샘플링(sampling), 컨텍스트 윈도우(context window), KV 캐시(KV cache), 투기적 디코딩(speculative decoding) 등이 포함되며, 생성 _전_에 크리스탈을 회상하고 생성 _후_에 대화를 저장하는 Supermemory 금고가 양 끝을 받치고 있습니다.

Repo: github.com/harishkotra/token-factory

npx supermemory local          # :6767 포트에서 필수 메모리 레이어 실행
npm install && cp .env.example .env.local
# SUPERMEMORY_API_KEY=sm_... 설정
...

1. 우리가 해결하고자 했던 문제

LLM 추론(inference)에 대한 대부분의 설명은 다음 중 하나입니다:

1. 수학의 벽 — 로짓(logits), 소프트맥스(softmax), 핵 샘플링(nucleus sampling) 등이 공식으로만 나열됨,
2. 블랙박스 채팅 UI — 텍스트 박스, 스피너(spinner), 그리고 문단뿐임.

둘 다 _직관(intuition)_을 길러주지는 못합니다. 온도는 분포가 평평해지는 것을 직접 보기 전까지는 추상적으로 느껴집니다. Top-p는 확률 버킷이 채워지다 멈추는 것을 관찰하기 전까지는 어렵습니다. 메모리 레이어는 크리스탈이 금고에서 컨텍스트 컨베이어(context conveyor)로 날아오기 전까지는 "마케팅이 가미된 RAG"처럼 들릴 뿐입니다.

우리는 다음과 같은 것에 더 가까운 것을 원했습니다:

• Factorio (관찰할 수 있는 시스템)
• Brilliant.org (상호작용을 통한 학습)
• Apple 온보딩 (움직임이 설명을 대신함)

…여기에 중요한 기술적 관점을 더하자면: 현대의 에이전트(agents)는 단순한 디코더(decoders)가 아니라, 메모리가 증강된 시스템(memory-augmented systems)입니다. 따라서 Supermemory Local (localhost:6767)은 선택적인 플러그인이 아닙니다. 이것은 제품의 핵심 인프라입니다.

2. 제품 프레이밍

엘리베이터 피치

보이지 않는 수학 대신, 모든 토큰은 AI 공장을 통과하는 물리적인 큐브가 됩니다. 사용자는 AI에 대해 읽는 것이 아니라, 그것이 일어나는 과정을 지켜봅니다. 그리고 이 공장은 기억합니다.

핵심 루프 (항상 실행) (Core loop (always))

사용자 프롬프트 (User prompt)
  → Supermemory 검색 + 프로필 (Supermemory search + profile)
  → 풍부해진 컨텍스트 (Enriched context) (메모리 / 프로필 / 프롬프트 큐브)
...

프로덕션 UX에는 "메모리 비활성화" 토글이 없습니다. 디코딩 노브(Decoding knobs) (온도 (temperature), top-k/p, KV 캐시 (KV cache), 투기적 디코딩 (speculative))는 결코 꺼지지 않는 메모리 중추 (memory spine) 위에 위치합니다.

3. 상위 수준 아키텍처 (High-level architecture)

┌─────────────────────────────────────────────────────────────────┐
│  브라우저 (Browser) (Next.js App Router)                         │
│                                                                  │
...

왜 이렇게 분리했는가? (Why this split?)

실패 정책 (Failure policy)은 의도적이며 엄격합니다:

• API 키 누락 → 설정 오류 (misconfigured) 게이트
• Supermemory 다운 → 연결 끊김 (disconnected) 게이트; 시작 비활성화
• 실행 중 회상 (Recall) 실패 → 중단 (abort) (가짜 성공 없음)
• 투어 모드 (Tour mode)는 오직 **카메라 전용 (camera-only)**으로만 존재하며, 비생성형 (non-generative)으로 표시됨

4. 기술 스택 (Tech stack)

클론(cloning)하려는 분들을 위한 중요한 Tailwind 참고 사항: Tailwind v4가 바이너리 디렉토리를 자동 스캔하게 두지 마세요. .supermemory/data 아래에 있는 Supermemory의 로컬 DB는 스캔될 경우 잘못된 CSS를 생성할 수 있습니다. 우리는 globals.css에서 소스를 제한합니다:

@import "tailwindcss";

@source not "../../../.supermemory";
...

5. 팩토리 룸 (Factory rooms) (각 모드가 가르치는 것)

각 룸에는 스테이지 크롬(stage chrome)에 표시되는 짧은 설명이 있습니다. 디자인 규칙은 다음과 같습니다: 한 문장으로 작성하며, 절대 문단으로 만들지 말 것.

유휴 상태(Idle)의 룸에서도 **데모 큐브/소품 (demo cubes/props)**을 보여주어 탐색 시 빈 바닥에 착륙하지 않도록 합니다. 실행 중에는 깜빡임과 비용을 줄이기 위해 활성 룸 ± 인접 룸만 무거운 콘텐츠를 마운트(mount)합니다.

6. 메모리 계층: 인프라로서의 Supermemory (Memory layer: Supermemory as infrastructure)

클라이언트 설정 (Client configuration)

// src/lib/supermemory/client.ts (개념적 코드)
import Supermemory from "supermemory";

...

우리가 구현하는 작업 (Operations we implement)

// 개념적 MemoryService 인터페이스
checkHealth()           // documents.list({ limit: 1 }) + latency
ensureSeeded()          // 멱등성(idempotent)을 가진 customId 시드 (Phaser, tokens, …)
...

메모리 시딩 (Seed memories)

첫 성공적인 연결 시, 다음과 같은 의미론적 시드(semantic seeds)를 upsert 합니다:

• Phaser는 2D HTML5 게임 프레임워크입니다.
• 토큰(Tokens)은 텍스트의 하위 단어 조각(subword pieces)입니다.
• 온도(Temperature)는 무작위성(randomness)을 제어합니다.
• KV 캐시(KV cache)는 자기회귀적 추론(autoregressive inference) 속도를 높입니다.

따라서 **“Phaser에 대해 알려줘”**와 같은 데모는 하드코딩된 오프라인 배열을 진실의 원천(source of truth)으로 사용하는 대신, 실제 검색 점수(search scores)를 타격합니다.

API 라우트 (API routes)

키(Keys)는 브라우저로 전송되지 않으며, 클라이언트는 동일 출처(same-origin)의 Next.js 라우트와만 통신합니다.

7. 생성 오케스트레이션 (Generation orchestration)

이 경험의 핵심은 factory store의 runGeneration()입니다. 이는 room, phase, candidates, generated[]를 진행시키며, 카메라와 3D 장면이 따라올 수 있도록 sleep을 포함한 시간 기반 상태 머신(timed state machine) 역할을 합니다.

의사 코드(Pseudocode):

async function runGeneration() {
  await ensureSupermemoryConnected(); // 그렇지 않으면 중단 + 게이트

...

왜 “답변 플래너(answer planner)”가 필요한가?

초기 프로토타입은 순수하게 장난감 수준의 어휘(toy vocabulary)에서 샘플링했습니다. 그 결과 다음과 같은 저장소 항목이 생성되었습니다:

robot accept of reject token token

카오스 모드(chaos mode)에는 귀엽지만, 데모용으로는 끔찍합니다. **답변 플래너(answer planner)**는 Supermemory의 상위 히트(또는 휴리스틱)를 토큰 시퀀스로 변환하는 한편, factory는 여전히 로짓(logits) → 필터링(filters) → 샘플링(sampling) 과정을 보여줍니다. 계획된 토큰은 가장 높은 로짓을 가진 후보(highest-logit candidate)로 주입되어, UI 학습 효과를 유지하면서 응답(Response) 패널의 가독성을 확보합니다.

// src/lib/answer-planner.ts (발췌)
export function planAnswerTokens(
  prompt: string,
...

소프트맥스 (Softmax) (교육적 핵심)

export function applySoftmax(cubes: TokenCube[], temperature: number) {
  const T = Math.max(0.05, temperature);
  const scaled = cubes.map((c) => c.logit / T);
...

그 후 Top-k 및 top-p가 레이저 게이트(laser gate)와 버킷 애니메이션(bucket animations)을 위한 alive 플래그를 가지치기(prune)합니다.

8. 3D 및 UX 엔지니어링 노트

컨테인드 스테이지 (Contained stage)

초기 버전은 전체 화면(full-bleed) Canvas 위에 전체 뷰포트 절대 HUD를 사용했습니다. 결과적으로 텍스트가 겹치고, "AI가 응답 중입니다"라는 문구를 읽을 수 없었으며, 카메라가 14개의 룸(room)을 통해 텔레포트할 때 혼란스러운 깜빡임이 발생했습니다.

현재 레이아웃:

┌ 상단 바 (로고, 연결, 도움말) ───────────────────┐
│  컨테인드 3D 스테이지 (둥근 프레임)               │
│  + 스테이지 크롬 (StageChrome) (모드 설명, 줌, 룸 레일) │
...

카메라 및 줌 (Camera & zoom)

OrbitControls가 카메라를 제어합니다. 룸 변경 및 stageZoom은 매 프레임마다 스크롤 줌(scroll zoom)과 충돌하는 대신, 한 번에 **대상 + 거리(target + distance)**를 설정합니다 (효과 중심):

// 개념적 카메라 업데이트
const look = new THREE.Vector3(...meta.lookAt);
const baseCam = new THREE.Vector3(...meta.camera);
...

버튼: 확대 (stageZoom /= 1.2), 축소 (*= 1.2), 초기화 (1). 스크롤은 여전히 OrbitControls를 통해 작동합니다.

연결 UX (Connection UX)

ConnectionGate는 Supermemory가 정상 상태가 될 때까지 경험을 차단하며, npx supermemory local 및 .env.local을 위한 복사-붙여넣기 단계를 제공합니다. 연결 배지에는 실시간 지연 시간(예: Supermemory · live · 37ms)이 표시됩니다.

9. 프로젝트 레이아웃 (탐색용)

src/
  app/api/{health,memory,memory/search,seed,profile}/
  components/
...

10. 의도적으로 하지 않은 것들

• 신뢰할 수 있는 원천(source of truth)으로서의 조용한 오프라인 메모리 저장소 미사용 — 데모는 반드시 Supermemory를 실행해야 합니다.
• 팩토리 경로(factory path)를 위한 호스팅된 LLM 요구 사항 미포함 — 해커톤 데모를 (로컬 SM을 제외하고) 오프라인 친화적으로 유지하고 교육적 목적에 집중할 수 있게 합니다.
• UI 내의 방대한 문서화 지양 — 도움말 서랍(Help drawer)과 한 줄짜리 모드 설명(mode blurbs)만 제공합니다.

향후 방향은 명확합니다: 동일한 시각적 디코드 경로(visual decode path)와 Supermemory 중추(spine)를 유지하면서, 답변 플래너(answer planner)를 실제 모델 API로 교체하는 것입니다.

11. 직접 시도해 보세요

git clone https://github.com/harishkotra/token-factory.git
cd token-factory
npx supermemory local          # sm_ 키 복사
...

권장되는 첫 실행 단계:

1. Supermemory · live가 실행될 때까지 기다립니다.
2. 프롬프트(Prompt) 입력: Tell me about Phaser
3. Vault(금고) 관찰 → 컨텍스트(context) 색상 확인 (amber 메모리 / violet 프로필 / cyan 프롬프트) → 디코드된 룸(rooms) 확인
4. Answer(답변) 패널 읽기
5. Vault(금고) 열기 — 새로운 에피소드 크리스탈(episodic crystal) 확인

12. 맺음말

Token Factory는 **AI를 위한 시스템 문해력 (systems literacy)**이 우리가 게임이나 제품 디자인에서 사용하는 것과 동일한 시각적 언어를 필요로 한다는 믿음에 기반한 프로젝트입니다. 만약 학생이 온도가 창의성에 미치는 영향을 30초 만에 체감하고, 메모리 크리스탈이 컨텍스트 컨베이어(context conveyor)에 합류하는 것을 본다면, 우리는 단순히 해커톤 데모를 출시한 것을 넘어, 보이지 않는 파이프라인을 직접 걸어 다닐 수 있는 공간으로 만든 것입니다.

카메라를 비출 수 있는 무언가를 만드세요. 그리고 그것이 기억할 수 있게 만드세요.

코드 및 상세 정보: https://www.dailybuild.xyz/project/196-token-factory