소담 오브레인 (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 [저장소 주소]
cd [폴더명]

저장소가 비공개(private)일 경우 접근 권한이 필요합니다.

설치 (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분 소요. 이후 실행부터는 즉시 시작.

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

설치 후 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개 탭)

주요 명령어

# app/ 폴더에서 실행
npm start          # 서버 시작 (포트 7740)
npm run selftest   # 자가 진단
npm run backup     # 수동 백업
npm run status     # DB 상태 조회
npm run seed       # 예제 데이터 입력 (테스트용)

파일·데이터 위치

환경 변수 (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 처리)
• 서버 실행마다 새로운 로컬 API 토큰 자동 생성 (crypto.randomBytes)
• data/, .env.local, *.sqlite는 .gitignore에 포함 — Git에 절대 올라가지 않음
• 외부 클라우드 통신 없음. 임베딩 모델도 완전 로컬 실행
• 입력값 검증: 잘못된 id·범위 밖 숫자·CORS 미허용 출처는 서버가 400/403/404로 안전하게 거부(실측 확인됨)
• 예상치 못한 서버 오류(예: 깨진 형식의 요청)가 나도 내부 파일 경로·오류 스택 정보는 절대 화면에 노출되지 않음 — 안전한 안내 문구만 표시, 상세 기록은 서버 로그에만 남음(2026-07-27 전역 에러 핸들러 추가)

적용되는 보안 헤더: Content-Security-Policy(같은 출처 리소스만 허용) · X-Content-Type-Options: nosniff · X-Frame-Options: DENY(iframe 삽입 차단) · Referrer-Policy: no-referrer.

업데이트 내용 요약

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

• 세션을 다시 열면, 하던 얘기와 관련된 기억을 먼저 보여줌: 지금까지는 클로드코드 세션을 재개할 때 항상 "최근 것·중요한 것" 순으로만 기억을 자동으로 불러왔습니다. 이제는 직전에 무슨 대화를 하고 있었는지를 함께 살펴서, 그 주제와 관련 있는 기억을 우선으로 불러옵니다(예: "버튼 색상" 얘기를 하다 재개하면 버튼 관련 결정이 먼저 뜸). 완전히 새로 시작하는 세션은 아직 참고할 대화가 없으니 기존 방식(최근·중요순) 그대로입니다.
• 그래프가 단순해졌을 때 안내 문구 추가: 기억이 많이 쌓이면(1,500건 이상) 그래프가 느려지지 않도록 자동으로 "같은 종류끼리만 연결"하는 단순한 방식으로 바뀌는데, 지금까지는 이 사실이 화면에 전혀 안내되지 않았습니다. 이제 그래프 화면 하단에 "유형별 연결(유사도 생략)" 문구와 함께, 왜 이렇게 됐는지·노이즈나 중복 기억을 정리하면 어떻게 다시 정밀한 연결로 돌아오는지 설명이 함께 표시됩니다.
• "#"으로 시작하는 문장이 통째로 사라지던 문제 수정: 지금까지는 사용자가 "# 이렇게 하자"처럼 문장 앞에 "#"을 붙이면, 실제로 중요한 지시였어도 문서 제목으로 오인해 통째로 저장 후보에서 빠지는 문제가 있었습니다. 이제는 "#" 표시만 떼어내고 나머지 문장은 평소처럼 정상적으로 저장 여부를 판단합니다.
• 자동 저장 시 시스템 로그가 섞여드는 문제 방지: 클로드코드가 로컬 명령을 실행한 결과 문구가 사용자의 실제 발화가 아닌데도 저장 후보로 검토되던 지점을 발견해 걸러내도록 보강했습니다(실제로 잘못 저장된 사례는 없었지만, 방어가 완전하지 않았던 부분을 미리 막았습니다).

• 완전일치 중복 기억 일괄 정리: 개요 탭 중복 정리 화면에, 내용이 완전히 똑같은 기억 쌍이 여러 건일 때 하나하나 확인하지 않고 "완전일치만 전부 한번에 정리" 버튼 한 번으로 모두 정리할 수 있는 기능을 추가했습니다(기존의 건별 확인·병합 방식과 별개로 추가된 것이라 기존 방식도 그대로 남아있습니다). 삭제 전 자동 백업 + 10초 되돌리기는 기존 기능과 동일하게 적용됩니다.
• 대용량 대화 기록 크래시 방지: 클로드코드 세션 기록이 아주 커지는 극단적인 경우(약 900MB 이상) 자동 저장 과정이 통째로 멈춰버릴 수 있던 문제를 발견해, 최근 20MB 분량만 읽어 처리하도록 수정했습니다. 평소 사용에는 영향이 없습니다(대부분의 세션 기록은 이 크기보다 훨씬 작습니다).
• 오류 메시지 정보노출 점검: 백업 생성이 실패하는 드문 상황을 재현해 점검한 결과, 오류 메시지에 서버 내부의 폴더 절대경로가 그대로 노출되던 지점 3곳(중복 정리·일괄 삭제 관련 화면)을 발견해 즉시 차단했습니다. 이제 이런 상황에서도 사용자 화면에는 안전한 안내 문구만 표시됩니다.
• 의존성(부품 라이브러리) 보안 재점검: 외부 라이브러리 취약점을 다시 점검(npm audit)해 새로 발견된 고위험 3건(ip-address)을 안전하게 자동 수정했습니다. 남은 고위험 4건(sharp·adm-zip, AI 임베딩 라이브러리 경유)은 아직 상위 배포판에 수정이 없어 그대로인데, 코드를 직접 확인한 결과 O-Brain은 텍스트만 다루고 이 취약점과 관련된 이미지 처리 기능 자체를 쓰지 않아 실제 위험은 낮은 것으로 확인했습니다.
• 자동 테스트 배터리 확대: 정상 흐름·잘못된 입력·경계값·인증 실패·악성 요청 등 23가지 상황을 자동으로 점검하는 테스트를 새로 작성해 전부 통과를 확인했습니다.

• 백업 목록에서 원하는 백업 고르기: ⚙ 설정 화면의 백업 목록에서 되돌리고 싶은 백업을 클릭해 선택하면, 아래 수동 복원 안내가 그 백업 파일 이름으로 정확히 채워지고 "파일 이름 복사" 버튼도 함께 나타나 여러 단계를 옮겨 적다 실수할 위험을 줄였습니다. (버튼 한 번으로 자동 복원하는 기능은 데이터 안전을 위해 만들지 않았습니다 — 파일 교체는 여전히 안내를 따라 직접 하는 방식입니다.)
• 오류 메시지 보안 점검: 형식이 깨진 요청(예: 손상된 데이터 전송)을 서버에 보내는 극히 드문 상황을 실제로 재현해 점검한 결과, 서버 내부의 파일 경로나 오류 상세 정보가 응답에 노출될 수 있는 지점을 발견해 즉시 차단했습니다. 이제 이런 상황에서도 사용자에게는 안전한 안내 문구만 전달되고, 문제 진단에 필요한 상세 기록은 서버 로그 파일에만 남습니다.
• 의존성(부품 라이브러리) 보안 점검: 프로젝트가 사용하는 외부 라이브러리의 알려진 보안 취약점을 점검(npm audit)해 9건 중 3건을 해결했습니다(위험도 "높음" 5건→4건, "중간" 4건→2건으로 감소, 기존 코드와 호환되는 안전한 범위 내에서만 자동 업데이트). 남은 6건(높음 4·중간 2)은 이 프로젝트가 실제로 그 코드 경로를 쓰지 않는다는 것을 직접 코드로 확인했습니다. 검색·저장에 쓰이는 SQL 처리, 화면 표시 시 악성 스크립트 방어 코드도 함께 재점검했습니다.

• 노이즈 기억 필터 + 일괄 정리: 클로드코드 세션 요약이나 대화 인용문(예: "Claude:", 표, 헤더)이 실수로 기억으로 잘못 저장되는 경우를 목록 탭에서 골라 확인할 수 있는 필터 추가. "전체 선택" 버튼으로 필터링된 것을 한 번에 선택해 정리(자동 삭제 아님 — 사람이 확인 후 삭제, 10초 되돌리기 지원).
• 자동 저장·자동 불러오기 방어: 앞으로 저장되는 기억에서 이런 노이즈가 덜 섞이도록 저장 규칙을 정밀화하고, 다음 대화 시작 시 자동으로 불러오는 기억에서도 기존에 저장돼 있던 노이즈가 다시 섞여 들어오지 않도록 방어 추가.
• 관계 제안 큐: 개요 탭에서 다른 기억과 연결이 없는 기억을 하나씩 보여주고, 비슷한 기억을 추천 — 연결할지·건너뛸지는 사람이 직접 결정(관계 종류를 AI가 자동으로 추측하지 않음).
• 전체 백업 내보내기: 헤더의 내보내기 메뉴에 "JSON 전체 백업"·"마크다운 전체 백업" 항목 추가. 기존 내보내기(화면에 지금 보이는 것만, 최대 500건)와 달리 지금까지 모은 기억 전체를 관계 정보까지 포함해 파일로 저장.
• 범위(전역/프로젝트) 필터 결함 수정: 목록·검색·그래프 어디서도 "전역"/"프로젝트" 범위 필터가 실제로는 정확히 작동하지 않던 결함을 발견해 수정(전역 선택 시 프로젝트 기억까지 섞여 보이거나, 프로젝트 선택 시 결과가 아예 안 뜨던 문제).

• 백업 목록 + 수동 복원 안내: ⚙ 설정 화면에서 그동안 쌓인 백업(날짜·용량)을 확인하고, "지금 백업 만들기" 버튼으로 즉시 추가 백업 생성. 문제 발생 시 되돌리는 방법도 화면에 단계별로 안내.
• 저신뢰 기억 필터: 목록 탭에서 자동 추출 신뢰도가 낮은(50% 미만) 기억만 골라볼 수 있는 필터 추가.
• save_memory 카테고리 지정: Claude Code가 기억을 저장할 때 분류(카테고리)를 직접 지정할 수 있도록 MCP 도구 확장(생략 시 기존처럼 자동 분류).
• 플러그인 설치 경로 문제 수정: 이전 버전은 개발 PC의 폴더 경로가 설정 파일에 고정돼 있어 다른 컴퓨터에 설치하면 MCP·명령어가 작동하지 않았음 — 어느 컴퓨터에 내려받아도 스스로 경로를 찾도록 수정.
• 에러 메시지 정리: 예상치 못한 서버 오류 시 내부 상세 정보 대신 안내 메시지만 보이도록 수정(문제 진단용 상세 기록은 서버 로그에만 남김).

• 검색 순위 개선: 검색·MCP search_memory 결과 정렬에 관련도(70%)·중요도(15%)·최신성(10%)·신뢰도(5%)를 함께 반영. 사람이 확인한 기억이 자동추출 노이즈에 밀려나지 않게 함(정확히 일치하는 결과는 여전히 최우선 — 순위가 뒤집히지 않음).
• 그래프 불러오기 실패 표시: 서버 연결 실패 시 조용히 빈 화면으로 남는 대신 오류 안내 + "다시 시도" 버튼 표시.
• 단건 삭제도 되돌리기 지원: 기억 1개만 삭제할 때도 일괄삭제와 같은 확인창 + 10초 되돌리기 적용(이전엔 되돌릴 수 없었음).
• 비활성 버튼 안내: 아직 누를 수 없는 버튼(예: 선택 없을 때 삭제 버튼)에 마우스를 올리면 이유가 표시됨.
• 검색 로딩 표시: 검색어를 입력하고 결과를 기다리는 짧은 순간에도 작은 로딩 표시가 나타남.
• 그래프 키보드 접근성: 마우스 없이 Tab·Enter만으로 그래프의 모든 기억을 순서대로 탐색·조회 가능.

• 그래프 성능: 기억 5000건 환경에서 9.8초 걸리던 그래프 생성을, 1500건 초과 시 자동 단순화하는 성능 가드로 8ms까지 단축(약 300배).
• 중복 기억 정리: 개요 탭에서 비슷한 기억 쌍을 자동 탐지 → 확인 후 "A만 남기기·B만 남기기·합치기" 선택 정리(백업+10초 되돌리기).
• 보안 강화: 로컬 API 토큰이 발급만 되고 검사되지 않던 상태를 고쳐 실제로 매 요청마다 검사하도록 활성화. 기억 저장 시 중요도·신뢰도 범위 밖 값도 자동 보정되도록 수정.
• 전체 기능 실동작 검증: HTTP API 19개, MCP 도구 7개, 클로드코드 자동저장·불러오기 훅 2개, 실제 웹 브라우저(2D/3D 그래프·검색·악성 스크립트 방어)까지 90개 이상 경우의 수를 직접 실행해 확인.

• 목록/타임라인/개요 불러오기 개수를 50/100/200/500/직접입력(1~500)으로 조절 가능하게 하고, 브라우저에 저장해 다음에 열어도 유지되도록 함.
• 헤더 ⚙ 버튼 → 5번째 탭(진짜 설정 페이지)으로 이동. 그래프 표시 노드 개수(502000)·자동 새로고침 켜짐/주기(10300초)·테마(밝게/어둡게)·안내 배너 표시 여부까지 5개 항목 완비.
• 버그 수정 1: 그래프 노드 개수에 소수(예 500.7)를 입력하면 서버가 500 에러를 내고 화면이 처리 안 된 예외를 던지던 문제 — 서버·클라이언트 양쪽에서 정수로 강제하도록 수정.
• 버그 수정 2: 일괄삭제 확인창은 "10초 안에 되돌리기 가능"이라 안내하지만 실제 되돌리기 버튼은 5.5초면 사라지던 불일치 — 10초로 통일.

• 기억 상세보기에 "저장 세션 · N시간 전" 표시 추가(여러 Claude Code 창을 동시에 쓸 때 출처 구분).
• 검색 결과가 limit으로 잘렸을 때 "관련 기억이 N건 더 있어요" 안내가 뜨도록 수정(조용한 잘림 방지).
• 신뢰도 감쇠 기능이 최초 실행 시 기존 기억을 즉시 바닥까지 떨어뜨리던 버그 수정.

• 다중 선택 → 일괄 삭제 → 확인 모달 → undo 토스트 흐름을 실제 브라우저에서 끝까지 검증.
• 검증 중 선택모드 진입 시 삭제/취소 툴바가 안 보이던 버그 발견·수정.
• MCP 도구 7개(save_memory·search_memory·get_memory·get_related·get_timeline·list_categories·add_relation) 전부 실제 프로토콜로 호출해 확인.

• 저장 중복 방지(거의 동일한 기억은 저장 스킵 + 사유 반환).
• MCP add_relation 도구, /o-brain:link 명령(관련 기억 제안 → 사람이 종류 확정).
• 대시보드 다중선택 → 일괄 삭제(확인 모달 + undo), 터치타깃 접근성 보정.
• scope(global/project) 필터, Apache-2.0 라이선스 정식 적용, 유료 Haiku API 제거(호스트 LLM 재활용으로 대체).

• save_memory MCP·/o-brain:remember·룰 기반 입력정제 등 "기억의 질" 기반 작업.
• 대시보드 모바일 가독성·터치타깃 ≥44px 보정.
• 대시보드 XSS 방어·CSP/보안 헤더 추가.

전체 이력(마일스톤별 상세)은 프로젝트의 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

• 내장 오픈소스 라이브러리(better-sqlite3, sqlite-vec, @huggingface/transformers, force-graph, 3d-force-graph, express, @modelcontextprotocol/sdk)와 로컬 AI 모델(all-MiniLM-L6-v2)은 전부 허용형 라이선스(MIT/Apache-2.0)로 확인됐습니다(카피레프트·GPL 계열 없음) — 상업적 사용에 지장이 없습니다.
• 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"은 개인 프로젝트의 작업명입니다. 정식 상표 등록 여부는 확인되지 않았으므로, 이 이름으로 상표를 출원하거나 상업적으로 크게 내세우기 전에는 별도로 공식 상표 데이터베이스를 확인하는 것을 권장합니다.
• 이 README·라이선스 안내는 법률 자문이 아닙니다. 계약·납품·재배포 등 실제 상업적 활용을 계획 중이라면, 위 내용을 참고 자료로만 쓰고 필요 시 변호사 등 전문가의 확인을 받으시기 바랍니다.
• 라이선스 전문: LICENSE 파일 · 의존성 고지 전문: NOTICE 파일

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