SoDam O Brain

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

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

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

---

목차

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

---

핵심 기능

| 기능 | 설명 | |------|------| | 100% 로컬 | 모든 기억이 내 PC에만 저장됩니다. 외부 서버·클라우드 전송 없음 | | 하이브리드 검색 | 키워드(FTS5) + 의미 유사도(벡터 검색)를 동시에 사용 | | 지식 그래프 | 기억들을 2D/3D 점과 선으로 시각화 | | 시간여행 | 날짜 지정으로 그 날 기준 살아있던 기억만 조회 | | 신뢰도 감쇠 | AI 추출 기억은 30일 반감기로 신뢰도 자동 감소 | | 보안 필터 | API 키·비밀번호 자동 제거 후 저장 ([REDACTED]) | | 자동 백업 | 서버 시작 시·일괄 삭제 전 스냅샷 자동 생성 | | MCP 연동 | Claude Code에서 7개 도구로 기억 저장·검색·관계 관리 | | 고아 노드 시각화 | 관계 없는 기억에 점선 테두리 표시 | | 일괄 선택·삭제 | 여러 기억을 한 번에 선택해 삭제 + 10초 안에 되돌리기 | | ⚙ 설정 페이지 | 목록 개수·그래프 노드 개수·자동 새로고침·테마·안내 배너를 화면에서 직접 조절, 브라우저에 저장돼 계속 유지 |

---

사전 준비물

| 항목 | 요구 사항 | |------|-----------| | 운영체제 | Windows 10 / 11 (64-bit) | | Node.js | 20.x LTS 이상 (nodejs.org에서 무료 설치) | | 저장 공간 | 500 MB 이상 (임베딩 모델 ~90 MB 포함) | | RAM | 4 GB 이상 (8 GB 이상 권장) | | 브라우저 | Chrome, Edge, Firefox 등 |

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

---

다운로드 방법

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

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

git clone [저장소 주소]
cd [폴더명]

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

---

설치 (2단계)

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

cd D:\AI_Dev_Work\2026y\26y_06m_21d_SoDam_O-Brain\app
npm install

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 D:\AI_Dev_Work\2026y\26y_06m_21d_SoDam_O-Brain\plugin
/plugin install o-brain@o-brain-local

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

| 명령 | 하는 일 | |------|---------| | /o-brain:status | 현재 기억 수·상태 조회 | | /o-brain:selftest | 저장·검색·보안 일괄 점검 (✅✅✅이면 정상) | | /o-brain:remember | 현재 대화에서 결정 추출·저장 | | /o-brain:link | 기억끼리 관계 연결 | | /o-brain:backup | 수동 백업 생성 | | /o-brain:open | 브라우저로 대시보드 열기(서버가 꺼져 있으면 자동으로 켬) |

---

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](./GUIDE.md)

---

실행 · 사용 방법

실행

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

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

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

| 탭 | 설명 | |----|------| | 그래프 | 기억을 점과 선으로 표시하는 지식 맵. 첫 화면. | | 개요 | 총 기억 수, 유형별·카테고리별 분포, 연결 많은 기억 | | 목록 | 기억을 카드 형태로 나열. 선택 모드로 일괄 삭제 가능 | | 타임라인 | 시간순으로 기억 표시 | | ⚙ 설정 | 목록/타임라인/개요 불러오기 개수, 그래프 표시 노드 개수, 자동 새로고침 켜짐·주기, 테마, 안내 배너 표시 여부 — 5개 항목을 이 화면에서 직접 조절. 값은 브라우저(localStorage)에 저장돼 다음에 열어도 유지됨 |

자세한 사용법(그래프 조작·관계 연결·검색·시간여행·일괄삭제 등)은 [GUIDE.md](./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장](./GUIDE.md#10-명령어-전체-목록) 참고.

---

파일·데이터 위치

| 항목 | 위치 | |------|------| | 기억 데이터베이스 | app/data/obrain.db | | 자동 백업 | app/data/backups/ (최신 10개 보관) | | API 토큰 파일 | app/data/.api-token (실행마다 갱신) | | 개인 설정 | app/.env.local (없으면 기본값 사용) | | 이 문서들 | 프로젝트 최상위(README.md/GUIDE.md/영문판/각 .html) |

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

| 변수 | 기본값 | 설명 | |------|--------|------| | OBRAIN_PORT | 7740 | 서버 포트 번호 | | OBRAIN_DATA_DIR | ./data | 데이터 저장 폴더 |

---

워크플로우

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

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

상세 흐름은 [GUIDE.md 11장](./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장](./GUIDE.md#12-보안--데이터-흐름) 참고.

---

업데이트 내용 요약

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

2026-07-06 — ⚙ 설정 페이지 신설 + 실사용 검증 중 버그 2건 수정

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

2026-07-06 — 저장 세션 표시, search_memory 잘림 투명화, 신뢰도 감쇠 버그 수정

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

2026-07-05 — 일괄삭제 실사용 검증 + 표시 버그 수정, MCP 도구 전량 검증

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

2026-06-28 ~ 2026-06-29 — 편의 기능(M3) · 노이즈 정리(M4) · scope 필터

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

2026-06-20 ~ 2026-06-23 — 최초 구현(M1·M2) · 보안 강화

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

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

---

문제해결 빠른 참조

| 증상 | 해결 | |------|------| | 'node'은 명령이 아닙니다 | nodejs.org에서 LTS 설치 → 터미널 새로 열기 | | EADDRINUSE :::7740 | .env.local에 OBRAIN_PORT=7741 추가 후 재시작 | | 그래프가 비어 있음 | npm run seed로 예제 데이터 추가 | | 브라우저 접속 안 됨 | npm start 실행 확인 → 주소가 http://127.0.0.1:7740인지 확인 | | 임베딩 다운로드 실패 | 인터넷 연결 확인 · 방화벽에서 Node.js 허용 | | 기억 실수 삭제 | 삭제 후 10초 안이면 화면의 "되돌리기" 클릭. 이미 지났다면 app/data/backups/에서 최신 .db 파일 복원 | | 설정에서 개수를 바꿨는데 그래프가 그대로 | 정상입니다 — 그래프 탭은 "표시할 노드 개수"라는 별도 설정을 씁니다(목록 개수와 다름) |

더 많은 증상별 대처는 [GUIDE.md 15장](./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장](./GUIDE.md#16-faq-자주-묻는-질문) 참고.

---

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

Apache License 2.0 © SoDam AI Studio, 2026

| 항목 | 내용 | |------|------| | 개인 사용 | 자유롭게 사용 가능 | | 수정 · 복제 | 허용 (저작권 고지 보존 필수) | | 상업적 사용 | Apache-2.0 조건 하에 허용 | | 보증 | 없음 (AS-IS) — 사용 결과 책임은 사용자에게 있음 | | 외부 서비스 | Claude / Anthropic 등 외부 서비스 약관은 별도 적용 |

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

---

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

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: sodam-ai
• Source: sodam-ai/SoDam_O-Brain
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.