소담 오브레인 (SoDam O-Brain) — AI 기억 시스템

AI와 나눈 대화에서 중요한 결정·약속을 자동으로 저장하고, 지식 그래프로 시각화하는 완전 로컬 기억 도구.

비유 한 줄: AI는 천재지만 대화가 끝나면 모든 걸 잊어버립니다. O-Brain은 그 AI 옆에 두는 자동 메모 노트예요. 중요한 말을 알아서 적어두고, 언제든 꺼내줍니다.

---

목차

1. 핵심 기능
2. 사전 준비물
3. 다운로드 방법
4. 설치 (2단계) · 업데이트하기
5. Claude Code 플러그인 방식 (선택)
6. MCP 도구 연동 (Claude Code)
7. 빠른 시작
8. 실행 · 사용 방법
9. 주요 명령어
10. 파일·데이터 위치
11. 워크플로우
12. 아키텍처 요약
13. 보안 개요 · 데이터 흐름
14. 업데이트 내용 요약
15. 문제해결 빠른 참조
16. FAQ
17. 라이선스 · 저작권 · 상업적 용도

---

핵심 기능

---

사전 준비물

Claude Code는 MCP 도구 연동·플러그인 설치 시에만 필요. 웹 대시보드는 Claude Code 없이도 사용 가능.

---

다운로드 방법

이 문서를 읽고 있다면 O-Brain 파일은 이미 내 컴퓨터에 있습니다. 프로젝트 폴더 위치만 확인하면 됩니다(현재 이 PC 기준 절대경로).

Git으로 받는 경우(개발자용):

git clone https://github.com/sodam-ai/SoDam_O-Brain.git
cd SoDam_O-Brain

이 저장소는 공개(public)라 별도 권한 없이 받을 수 있습니다. (비공개로 바뀌면 접근 권한이 필요해요.)

---

설치 (2단계)

1단계: 의존성 설치 (터미널에서)

cd \app
npm install

예시: 저장소를 C:\Tools\O-Brain에 내려받았다면 cd C:\Tools\O-Brain\app

2단계: 서버 시작

npm start

→ O-Brain 로컬 서버 ▶ http://127.0.0.1:7740 메시지가 나오면 성공.

브라우저에서 열기:

http://127.0.0.1:7740

첫 실행 시: AI 임베딩 모델(약 90 MB)을 자동 다운로드합니다. 1~3분 소요. 이후 실행부터는 즉시 시작.

업데이트하기

새 버전을 받은 뒤에는 아래 순서로 해 주세요. Windows는 실행 중인 파일을 바꿀 수 없어서 먼저 모두 끄는 것이 중요해요.

1. O-Brain 서버를 켜 둔 터미널에서 Ctrl+C로 끄고, 클로드코드 창도 모두 닫아요.
2. 새 버전을 받아요 — git으로 받았다면 git pull, 압축 파일이면 새로 받은 내용으로 덮어써요. (app/data/ 안의 내 기억은 건드리지 않아요.)
3. 터미널에서 app 폴더로 가서 npm ci를 실행해요 — 저장소의 package-lock.json에 적힌 검증된 버전 그대로 설치해요(npm install보다 안전해요). 몇 분 걸릴 수 있어요.
4. npm run selftest로 점검해요(✅가 쭉 나오고 마지막에 🎉가 나오면 정상). 이어서 npm start로 서버를 켜요.
5. 클로드코드 플러그인을 쓰고 있다면 npm run plugin:pin을 한 번 실행한 뒤, 새 클로드코드 창에서 /plugin으로 업데이트해요.
6. 브라우저에 이전에 열어 둔 O-Brain 화면이 있다면 “서버가 다시 시작된 것 같아요” 안내가 뜰 수 있어요. 그때는 화면 새로고침 버튼(또는 F5)을 누르면 돼요.

서버를 켤 때마다 기억 데이터베이스는 자동으로 백업되고 구조도 자동으로 맞춰져요. 무언가 이상하면 아래 "문제해결 빠른 참조"의 npm run restore로 되돌릴 수 있어요.

---

Claude Code 플러그인 방식 (선택)

Claude Code를 사용 중이라면 플러그인으로도 설치 가능합니다. 반드시 2단계로 나눠서 실행하세요(한 번에 설치 시도 시 “Marketplace not found” 오류):

/plugin marketplace add \plugin
/plugin install o-brain@o-brain-local

예시: /plugin marketplace add C:\Tools\O-Brain\plugin

⚠️ 설치(또는 업데이트) 전에 한 번만: /plugin으로 설치하면 플러그인 파일이 Claude Code의 캐시 폴더로 복사돼서 옆에 app 폴더가 없어집니다. 그래서 설치·업데이트 전에 터미널에서 app 폴더로 가서 npm run plugin:pin을 한 번 실행해 O-Brain 위치를 등록해 주세요(내 사용자 폴더의 .obrain/root 파일에 위치 한 줄이 저장됩니다). 등록하지 않으면 대화를 시작할 때 “app 폴더를 찾지 못했어요” 안내가 나오며, 그때 같은 명령을 실행하면 됩니다.

설치 후 Claude Code 재시작 → 슬래시 명령어 사용 가능:

---

MCP 도구 연동 (Claude Code)

Claude Code settings.json에 등록하면 대화 중 기억을 바로 저장·검색할 수 있습니다:

{
  "mcpServers": {
    "o-brain": {
      "command": "node",
      "args": ["C:/절대경로/app/src/mcp-server.mjs"]
    }
  }
}

경로는 절대 경로, 슬래시(/) 사용 — 백슬래시(\) 쓰면 오작동할 수 있습니다.

사용 가능한 MCP 도구: save_memory, search_memory, get_memory, get_related, get_timeline, add_relation, list_categories

---

빠른 시작

1. npm install (최초 1회) → npm start
2. 브라우저에서 http://127.0.0.1:7740 열기
3. (Claude Code 사용자) 평소처럼 대화 중 또렷한 결정 문장을 말하고 /clear → 자동 저장
4. 화면 우측 상단 ⚙ 설정에서 목록 개수·그래프 노드 개수 등을 취향대로 조절

---

실행 · 사용 방법

실행

# app 폴더에서 실행
npm start                              # 서버 시작 (기본 포트 7740)
$env:OBRAIN_PORT=7741; npm start       # 포트를 바꿔서 시작 (PowerShell)

서버 종료: 터미널에서 Ctrl + C.

사용 — 웹 대시보드 (5개 탭)

화면 미리보기

아래는 예제(합성 더미) 데이터로 채운 실제 화면입니다 — 실제 개인 기억이 아닙니다.

그래프 뷰 — 2D/3D 지식그래프 (빨강 점선=모순됨, 초록 실선=뒷받침)

개요 탭 — 통계·분포

목록 탭 — 카드 목록 + 상세 패널

타임라인 탭 — 시간순 기억

설정 탭 — 5개 조절 항목

데이터 화면 — 내보내기 · 가져오기 · 백업

헤더 오른쪽의 ⬇ 버튼(또는 Ctrl+K → “데이터 관리”)으로 엽니다. 위에서부터 내보내기 · 가져오기 · 백업 세 칸이에요.

① 내보내기 — 기억을 파일로 꺼내요(원본은 그대로 남아요).

범위는 전체 / 지금 목록에 불러온 것 / 목록에서 고른 것 / 프로젝트 하나만 중에서 고릅니다. "폴더 경로 빼기"는 기본으로 켜져 있어요(남에게 보여줄 때 안전합니다. 내 다른 PC로 옮길 때는 끄세요). "내려받기"는 브라우저 다운로드 폴더로, "이 PC 폴더에 저장"은 app/data/export/에 저장하고 위치를 알려 줍니다. 압축(.gz) 옵션도 있어요.

② 가져오기 — 파일에서 기억을 들여와요.

1. 파일을 끌어다 놓거나 “파일 고르기” — JSON·JSON Lines·CSV·TSV·마크다운·텍스트, 그리고 이걸 .gz로 압축한 것(최대 5MB · 5,000건). 엑셀 .xlsx는 "다른 이름으로 저장 → CSV UTF-8"로 바꿔 올려 주세요. 한글 윈도우 CSV(CP949)도 읽어요.
2. 미리보기 — 새로 들어올 기억, 이미 있어서 건너뛸 것, 읽지 못한 줄, 시크릿이 가려진 기억을 먼저 보여 줘요. 이 단계에서는 아무것도 저장되지 않아요.
3. "가져오기"를 누르면 먼저 지금 기억을 자동 백업하고 저장해요(진행 바 표시. 중간에 멈추면 아무것도 저장되지 않아요).
4. 끝난 뒤 **30분 안에는 “되돌리기”**로 방금 가져온 것만 지울 수 있어요.

⚠️ 외부에서 받은 파일은 기억 속 문장이 AI에게 지시처럼 섞일 수 있어서, 기본으로 **“검토 필요”(신뢰도 40%)**로 들어오고 새 대화에 자동으로 불러오지 않아요. 기억을 열어 내용을 확인하고 저장하면 정식 기억이 됩니다. 내가 직접 만든 파일(이 화면에서 내보낸 JSON 등)이면 “믿을 수 있는 파일” 체크를 켜세요 — 파일에 적힌 출처·신뢰도를 그대로 씁니다. 비밀번호·API 키로 보이는 부분은 가져올 때도 자동으로 가려져요.

③ 백업 — 사고에 대비한 사본이에요.

• 자동: 서버를 켤 때, 그리고 기억을 지우기·합치기·가져오기 직전에 만들어져요. 종류별로 따로 보관해요(서버 시작 7개 · 위험 작업 직전 7개).
• 직접: “지금 백업 만들기”(.db, 10개까지)와 “이식용 백업”(.json.gz, 10개까지 — 다른 PC로 옮길 때 새 PC의 "가져오기"에 올려요). 직접 만든 백업은 자동 백업에 밀려나지 않아요.
• 목록에는 종류·날짜·용량·기억 건수·"열어서 확인함 ✔"이 보이고, 내려받기로 파일을 따로(USB·클라우드) 보관할 수 있어요.
• 되돌리기는 화면이 아니라 터미널에서 해요(열려 있는 데이터 파일을 덮어쓰면 망가질 수 있어서입니다). 서버·클로드코드 창을 모두 닫고 app 폴더에서 npm run restore → 번호 선택 → yes. 지금 데이터는 먼저 자동 백업되고, 원래 파일은 지워지지 않고 옆에 남아요.

---

주요 명령어

# app/ 폴더에서 실행
npm start          # 서버 시작 (포트 7740)
npm run selftest   # 자가 진단
npm run backup     # 수동 백업(.db)
npm run backup -- --portable   # 이식용 백업(.json.gz, 다른 PC로 옮길 때)
npm run restore    # 백업으로 되돌리기(서버·클로드코드 창을 모두 닫고 실행)
npm run status     # DB 상태 조회(마지막 자동 저장 성공 여부·의미검색 상태 포함)
npm run reindex    # 의미검색용 정보가 빠진 기억 채우기(의미검색이 멈췄던 뒤에)
npm run plugin:pin # /plugin 설치용 위치 등록(플러그인 설치·업데이트 전 1회)
npm run seed       # 예제 데이터 입력 (테스트용)

---

파일·데이터 위치

⚠️ 멈추고 확인: app/data 폴더(기억 DB)를 삭제·이동·덮어쓰기 하기 전에는 먼저 npm run backup으로 백업하세요. 지운 기억은 되돌릴 수 없습니다. OneDrive 같은 클라우드 동기화 폴더 안에서는 DB가 깨질 수 있으니 쓰지 마세요.

환경 변수 (app/.env.local)

---

워크플로우

일반 사용자(웹 UI 중심): 아침에 npm start → 어제 기억 확인 → 작업 중 중요 결정 직접 입력 → 저녁에 관계 연결·정리.

Claude Code 사용자(MCP/플러그인): 대화 중 결정을 말하고 /clear로 세션 종료 → 자동 저장 → 가끔 /o-brain:open으로 화면 확인 → /o-brain:backup으로 주기적 백업.

---

아키텍처 요약

[Claude Code / 브라우저]
        ↓
[Express 서버 127.0.0.1:7740]
        ↓
[보안 필터] → [임베딩(로컬 AI)] → [SQLite DB]
                                    ├── FTS5 (키워드 검색)
                                    └── sqlite-vec (벡터 검색)

기술 스택: Node.js ES Modules · Express.js v5 · SQLite (better-sqlite3) · sqlite-vec · @huggingface/transformers (all-MiniLM-L6-v2) · force-graph / 3d-force-graph · @modelcontextprotocol/sdk

---

보안 개요 · 데이터 흐름

• 서버는 127.0.0.1(내 PC 전용)에만 바인딩 — 외부 기기에서 접근 불가
• 기억 저장 전 API 키·비밀번호 자동 제거 (redact.mjs 처리) — GitHub·Slack·Stripe 토큰, JWT, DB 주소 속 비밀번호, “비밀번호는 …” 같은 한글 표현까지 가립니다. 다만 모든 비밀번호를 막는다고 보장하지는 않습니다(키워드 없이 적힌 임의 문자열이나 숫자·기호가 없는 비밀번호는 못 잡을 수 있음) — 민감한 값은 애초에 대화에 쓰지 않는 것이 가장 안전합니다
• 서버는 허용한 주소(127.0.0.1·localhost + 서버 포트)로 온 요청만 받습니다 — 악성 웹페이지가 브라우저를 속여 내 PC의 서버를 읽게 하는 “DNS 리바인딩” 공격을 막습니다(2026-10-20)
• 의미검색 모델을 못 쓰는 상황이 생기면 화면 위에 경고 배너가 뜨고, 기억은 저장하되 키워드 검색으로 계속 동작합니다(조용히 엉뚱한 결과를 내지 않음)
• 서버 실행마다 새로운 로컬 API 토큰 자동 생성 (crypto.randomBytes)
• data/, .env.local, *.sqlite는 .gitignore에 포함 — Git에 절대 올라가지 않음
• 외부 클라우드 통신 없음. 임베딩 모델도 완전 로컬 실행
• 입력값 검증: 잘못된 id·범위 밖 숫자·CORS 미허용 출처는 서버가 400/403/404로 안전하게 거부(실측 확인됨)
• 예상치 못한 서버 오류(예: 깨진 형식의 요청)가 나도 내부 파일 경로·오류 스택 정보는 절대 화면에 노출되지 않음 — 안전한 안내 문구만 표시, 상세 기록은 서버 로그에만 남음(2026-07-27 전역 에러 핸들러 추가)
• 여러 Claude Code 창을 동시에 열어도 데이터가 안전하게 처리됨(2026-09-11 실측 검증: 동시 생성·동시 수정 다수 실행 후에도 손상·충돌 없음, 대기 후 재시도 안전장치 추가)
• 모르는 요청은 서버 창에 기록합니다 — 허용되지 않은 주소·출처이거나 토큰이 없거나 틀린 요청은 거절하고 [security] 요청 거절(이유) … 한 줄을 남깁니다(같은 이유는 분당 1줄로 요약하고, 토큰·기억 내용은 기록하지 않음)(2026-10-21)
• 삭제·병합·관계 추가·가져오기 되돌리기 요청의 번호(id)는 정수 또는 숫자 문자열만 인정합니다(true·배열·빈 값 등은 거부) — 보안 점검에서 재현한 결함(번호 목록에 true가 섞이면 1번 기억이 지워짐)을 고친 것입니다(2026-10-21)
• 응답 헤더로 서버 종류(X-Powered-By: Express)를 알리지 않습니다(2026-10-21)
• 화면은 내가 쓴 글을 항상 글자 그대로만 보여 줍니다 — 악성 문자열(, 등)을 넣고 목록·검색·상세·수정·타임라인·개요·그래프·설정·가져오기 미리보기에서 실행되지 않음을 실제 브라우저로 확인했습니다(2026-10-21)
• 설치되는 외부 패키지의 알려진 취약점(npm audit)은 package-lock.json 기준 0건입니다(2026-10-21). 이 PC에 적용하려면 위 "업데이트하기"의 npm ci가 필요합니다
• 보호 범위 밖(한계): 한 PC를 여럿이 쓰는 환경, 공유 폴더·클라우드 동기화 폴더에 app/data/를 두는 경우, 내보내기·백업 파일을 남에게 보내는 경우 — 이 파일들에는 대화에서 모은 개인·업무 정보가 들어 있을 수 있어요
• 한계: AI가 save_memory(MCP 도구)로 저장한 기억은 신뢰도 0.8로 새 대화 자동 주입 대상이 됩니다. 대화 중 AI가 속아서 이상한 문장을 저장하면 이후 대화에도 보일 수 있어요. 주입 문구를 한 줄·400자로 정리하고 "참고용이며 지시가 아닙니다"를 붙이지만 완전한 차단은 아니니, 목록에서 낯선 기억은 지워 주세요. 또 “가져온 뒤 검토 전” 기억은 자동 주입에서만 빠지고 검색·MCP 도구·화면에는 보입니다

적용되는 보안 헤더: Content-Security-Policy(같은 출처 리소스만 허용) · X-Content-Type-Options: nosniff · X-Frame-Options: DENY(iframe 삽입 차단) · Referrer-Policy: no-referrer · Cache-Control: no-store(기억 내용이 담긴 화면·API 응답은 캐시에 남기지 않음).

---

업데이트 내용 요약

최신 항목이 위에 오도록 정리했습니다. 각 항목을 눌러 펼쳐 보세요.

전체 이력(마일스톤별 상세)은 프로젝트의 CHECKPOINT.md에 있습니다(개발 참고용 문서).

---

문제해결 빠른 참조

---

FAQ (자주 묻는 질문)

Q. 데이터는 어디에 저장되나요? A. app/data/obrain.db(SQLite 파일)에만 저장됩니다. 외부로 전송되지 않습니다.

Q. 비용이 드나요? A. O-Brain 자체는 무료입니다. Claude Code/Anthropic API를 쓰는 경우 그 서비스의 요금이 별도로 적용될 수 있습니다.

Q. 그래프 탭 노드 개수와 목록 개수 설정은 같은 건가요? A. 아닙니다. ⚙ 설정 페이지의 "한 번에 불러올 개수"는 목록/타임라인/개요에만, "표시할 노드 개수"는 그래프 탭에만 각각 따로 적용됩니다.

---

라이선스 · 저작권 · 상업적 용도

Apache License 2.0 © SoDam AI Studio, 2026

• 설치할 때 함께 깔리는 외부 패키지 213개 전부(2026-10-21, 각 패키지의 license 표기 전수 조사)에 라이선스가 적혀 있고 대부분 허용형입니다(MIT 151 · ISC 27 · BSD 19 · Apache-2.0 7 외). GPL·AGPL 계열은 0건입니다. 직접 쓰는 라이브러리(better-sqlite3, sqlite-vec, @huggingface/transformers, force-graph, 3d-force-graph, express, @modelcontextprotocol/sdk)와 로컬 AI 모델(all-MiniLM-L6-v2, Apache-2.0)도 모두 허용형(MIT/Apache-2.0)입니다. 다만 함께 깔리는 이미지 처리 도구(sharp)의 Windows용 바이너리(@img/sharp-win32-x64)는 LGPL-3.0 라이브러리 여러 개와 MPL-1.1(cairo) 을 묶어 둔 것이라 약한 카피레프트 조건이 붙습니다. O-Brain은 이미지 처리를 쓰지 않고, 이 바이너리를 저장소에 싣지도 않으며(설치할 때 npm이 내려받음), 고쳐 쓰지도 않으므로 개인·내부 사용에는 보통 지장이 없습니다. 다만 node_modules를 묶어 재배포하거나 고객사에 납품하기 전에는 전문가 확인을 권장합니다(이 문서는 법률 자문이 아닙니다). 자세한 목록은 NOTICE 파일에 있습니다.
• Claude Code/Anthropic API로 만든 산출물(대화 결과)의 소유권: Anthropic 상업 이용약관 원문 기준으로 산출물은 사용자 소유이며, 대화 내용은 Anthropic의 모델 학습에 쓰이지 않습니다(anthropic.com/legal/commercial-terms 원문 확인, 2026-08-10). 다만 요금제·세부 사용 정책은 계정마다 다를 수 있으니 정확한 내용은 그 약관 원문에서 직접 확인하시기 바랍니다 — 이건 O-Brain이 아니라 Anthropic이 정하는 부분입니다.
• “Claude”, “Anthropic”, “Codex”, "OpenAI"는 각 회사의 상표입니다. O-Brain은 이들과 공식 제휴·인증 관계가 없고, 로고나 브랜드 이미지를 사용하지 않습니다. ("Claude Code와 함께 작동함"이라는 설명은 가능하지만, 공식 인증 제품처럼 보이게 하지 않습니다.)
• 제품명 "O-Brain"은 개인 프로젝트의 작업명입니다. 정식 상표 등록 여부는 확인되지 않았으므로, 이 이름으로 상표를 출원하거나 상업적으로 크게 내세우기 전에는 별도로 공식 상표 데이터베이스를 확인하는 것을 권장합니다.
• AI 생성 콘텐츠 확인 의무: 이 프로젝트의 코드·문서(설계 문서 포함)는 AI가 생성에 관여했습니다. 이 프로젝트를 실제로 배포·재배포·판매·회사/고객사 납품 등 상업적으로 활용하시기 전에는, 포함된 AI 생성 코드·문서·이미지에 대해 저작권 귀속·출처·상업적 이용 가능 여부·기존 저작물과의 유사성(특히 코드 조각)을 사용자가 직접 최종 확인하시기 바랍니다 — 이 프로젝트가 그 확인을 대신 보증하지 않습니다.
• 재배포할 때 지킬 것(Apache-2.0 요약): ① LICENSE 사본을 함께 줍니다 ② 내가 고친 파일에는 "고쳤다"고 표시합니다 ③ 원래의 저작권·특허·상표·출처 고지를 지우지 않습니다 ④ NOTICE의 내용을 유지합니다. 이 요약은 이해를 돕기 위한 것이고, 정확한 조건은 LICENSE 원문이 기준입니다.
• 라이선스가 주지 않는 것: 저작권·라이선스 고지를 지우는 것, "SoDam AI Studio"나 “O-Brain” 이름을 제휴·보증처럼 쓰는 것(Apache-2.0은 상표 사용권을 주지 않습니다), 타인의 상표·로고를 쓰는 것.
• 처음 실행할 때 인터넷이 필요한 부분: 임베딩 모델(Xenova/all-MiniLM-L6-v2, 약 90MB)을 Hugging Face에서 한 번 내려받습니다(Apache-2.0, 2026-10-21 공개 정보로 확인). 그 뒤 기억 저장·검색·화면은 내 PC 안에서만 동작합니다.
• 내보내기·백업·가져오기 파일: 내보낸 파일과 백업에는 클로드코드 대화에서 모은 개인·고객사·업무 정보가 그대로 들어갈 수 있습니다. 메신저·메일·클라우드·저장소에 올리면 외부에 공개된 것으로 보고, 올리기 전에 내용을 확인하세요(O-Brain은 파일을 어디로도 자동 전송하지 않습니다). 반대로 남이 만든 파일을 가져올 때 그 안의 글에 대한 저작권·개인정보 책임은 가져오는 사람에게 있습니다.
• 직접 확인해야 하는 것: Claude·Anthropic 등 AI 서비스의 요금제·이용 정책·약관(O-Brain과 별개), 모델 사용 정책, 외부 서비스 약관, 폰트·이미지·아이콘을 새로 넣을 때 그 라이선스. 지금 화면은 시스템 글꼴과 직접 그린 인라인 SVG만 쓰고 외부 폰트·이미지·CDN이 없습니다(2026-10-21 전수 검색). 문서의 스크린샷에는 합성 데모 기억만 담겨 있습니다.
• 법무·전문가 검토가 필요한 것: ① LGPL·MPL 바이너리가 든 node_modules의 재배포·납품 ② “O-Brain” 이름의 상표 ③ AI가 만든 코드·문서의 저작권 귀속과 유사 저작물 여부 ④ 면책·책임 제한 문구의 법적 효력 ⑤ Anthropic 약관의 “경쟁 제품” 조항이 내 사용에 해당하는지.
• 이 README·라이선스 안내는 법률 자문이 아닙니다. 계약·납품·재배포 등 실제 상업적 활용을 계획 중이라면, 위 내용을 참고 자료로만 쓰고 필요 시 변호사 등 전문가의 확인을 받으시기 바랍니다.
• 라이선스 전문: LICENSE 파일 · 의존성 고지 전문: NOTICE 파일

---

이 문서와 README.html의 내용은 동일합니다. 영문판: README.en.md