생각·메모·할일·링크를 원자(atom) 단위로 쪼개 주제(theme) 로 분류하는 세컨드 브레인. 원자마다 주제는 하나만 달고, 주제·원자 사이의 숨은 연결은 임베딩 유사도로 계산해 드러낸다 — 흩어진 기록 사이의 다리가 자동으로 보인다.
- 저장소: PostgreSQL 16 + pgvector (관계형 테이블 + 벡터 임베딩 검색)
- API + 웹: Express 5 (
apps/api, 정적 웹apps/web동봉) - 적재 인터페이스: 텔레그램 봇(원자 분해·분류를 LLM이 수행) + 원격 MCP (아래)
- 인증: 유저별 격리. 텔레그램 sender_id → userId 매핑, 모든 데이터 쿼리에 userId 강제 주입.
themes— 주제. 정체성 =(user_id, name). PARA(project/area/resource/archive) 분류와starred보유.atoms— 원자(지식·할일·이벤트).title/summary/body/source/kind/status/날짜 등. 지식 임베딩은embedding vector(384)컬럼(부가, NULL 허용).atom_theme— 원자↔주제 연결(원자당 1개). 주제 간 다리는 이 테이블이 아니라 임베딩 유사도 엣지(graph-edges.mjs)로 계산한다.- 임베딩: 384차원. 2026-06-11 부터 Gemini
text-embedding-004사용(초기 e5-small에서 전환). 하이브리드 검색(hybrid.mjs)으로 키워드 + 벡터를 병합. - 그 외: 인증/신원(
users/sessions/magic_tokens/api_tokens), 캘린더·가민 연동, 운동(workout_sessions/exercise_*/routines), 다이어그램, 브리핑, 가입 요청, 블로그 포스트 등.
Chaos는 원격 HTTP MCP 서버를 노출한다. 어느 머신의 Claude Code든 Bearer 토큰으로 인증하면 chaos를 양방향(컨텍스트 읽기 + 카오스식 적재)으로 쓸 수 있다.
토큰은 텔레그램 신뢰 채널(봇과의 대화)에서만 발급된다 — 봇에게 "MCP 토큰 발급해줘" 라고 하면 본인 텔레그램 ID로 90일짜리 Bearer 토큰을 1회 응답으로 받는다. (서버는 토큰의 SHA-256 해시만 저장하고 평문은 재조회 불가. 분실 시 재발급.)
내부적으로는 loopback 신뢰 채널 엔드포인트(
POST /api/auth/mcp-token,x-internal-secret+x-telegram-id헤더)로만 발급된다. 외부(nginx 경유)는X-Forwarded-For가 붙어 차단되므로 남의 토큰을 만들 수 없다.
받은 토큰으로 원격 머신에서 한 번 실행:
claude mcp add --transport http chaos \
https://jongdeug.duckdns.org/chaos/mcp \
--header "Authorization: Bearer <YOUR_TOKEN>"
⚠️ 공개 엔드포인트 경로는 루트/mcp가 아니라/chaos/mcp다 (nginx가 chaos를/chaos/prefix로 서빙).
| 툴 | 방향 | 설명 |
|---|---|---|
list_themes |
읽기 | 모든 주제 + 집계(총/열림/완료/폐기)·미리보기 |
get_theme_items |
읽기 | 한 주제의 원자 + 출처(포인트 묶음) 상세 |
list_open_actions |
읽기 | 미완료(open) 할일 원자 전체 |
weekly_insights |
읽기 | 최근 7일 요약: 총량·최다주제·다리·휴면주제·최강연결 |
capture_memo |
쓰기 | 원문(raw) + 분해된 원자(atoms)를 적재 |
capture_source |
쓰기 | 외부 자료를 "출처 1개 + 포인트 묶음"으로 적재 |
적재 규칙(원자 분해·kind/status·theme/PARA 분류)은 chaos_capture_guide 프롬프트에 내장돼 있어, 쓰기 전에 참고하면 된다.
봇에게 "MCP 토큰 목록 / 폐기" 로 조회·폐기할 수 있다 (GET /api/auth/mcp-token/list, POST /api/auth/mcp-token/revoke — 둘 다 신뢰 채널 전용). 목록은 메타(label·생성/만료일·폐기여부)만 반환하고 평문/해시는 절대 노출하지 않는다.
- 데이터 단일 소스:
apps/api/src/chaos-data.mjs(PostgreSQL) — 지식 데이터 작업의 SQL을 한 곳에 모아 MCP 툴(mcp-server.mjs)과 HTTP 엔드포인트(api.mjs)가 공유한다(중복 쿼리 없음). 스키마는schema.sql, 부팅 시ensureSchema()로 멱등 적용. - 유저 격리: 요청별 userId를
AsyncLocalStorage로 주입 → 모든 데이터 쿼리에 userId 강제. 정체성 테이블(User/Session/MagicToken/ApiToken)만 비격리 쿼리 사용. - MCP 전송: Streamable HTTP, stateless JSON 모드(
sessionIdGenerator: undefined+enableJsonResponse: true). 인증 미들웨어mcpBearerAuth는 토큰 해시 조회·검증 후 userId를 ALS에 주입한다. - 바인딩: API + 웹은
127.0.0.1:3001에만 바인딩되고 외부 노출은 nginx가/chaos/prefix로 프록시(prefix는 업스트림 전달 시 제거).