소담 오브레인 (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. 화면 우측 상단 ⚙ 설정에서 목록 개수·그래프 노드 개수 등을 취향대로 조절

상세 스텝바이스텝: GUIDE.md

실행 · 사용 방법

실행

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

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

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

자세한 사용법(그래프 조작·관계 연결·검색·시간여행·일괄삭제 등)은 GUIDE.md 7장 참고.

주요 명령어

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

전체 HTTP API 엔드포인트·MCP 도구 입출력 표는 GUIDE.md 10장 참고.

파일·데이터 위치

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

워크플로우

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

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

상세 흐름은 GUIDE.md 11장 참고.

아키텍처 요약

[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로 안전하게 거부(실측 확인됨)

데이터 흐름 다이어그램·보안 헤더 전체 목록은 GUIDE.md 12장 참고.

업데이트 내용 요약

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

• 백업 목록 + 수동 복원 안내: ⚙ 설정 화면에서 그동안 쌓인 백업(날짜·용량)을 확인하고, "지금 백업 만들기" 버튼으로 즉시 추가 백업 생성. 문제 발생 시 되돌리는 방법도 화면에 단계별로 안내.
• 저신뢰 기억 필터: 목록 탭에서 자동 추출 신뢰도가 낮은(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에 있습니다(개발 참고용 문서).

문제해결 빠른 참조

더 많은 증상별 대처는 GUIDE.md 15장 참고.

FAQ (자주 묻는 질문)

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

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

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

더 많은 FAQ는 GUIDE.md 16장 참고.

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

Apache License 2.0 © SoDam AI Studio, 2026

• 내장 오픈소스 라이브러리(better-sqlite3, sqlite-vec, @huggingface/transformers, force-graph 등)는 각자의 라이선스(MIT/Apache-2.0)를 따릅니다
• "Claude", "Anthropic"은 해당 회사의 상표입니다. O-Brain은 이들과 공식 제휴 관계가 없습니다
• 라이선스 전문: LICENSE 파일 · 의존성 고지 전문: NOTICE 파일
• 법률·저작권·상업 조건의 상세 항목(허용/의무/책임제한/상표/개인정보 등 12개 세부 조항)은 GUIDE.md 17장 참고

이 문서와 README.html의 내용은 동일합니다. 상세 가이드: GUIDE.md (한국어) · GUIDE.en.md (영문)