hang-in/seCall

<!-- Thanks to: @batmania52, @yeonsh, @missflash, @CoLuthien, @dev-minsoo -->

<div align="center">

seCall

AI 에이전트와 나눈 대화를 로컬 위키로 정리하고 검색하세요.

Your AI agent conversations, as a searchable local wiki.

<br/>

한국어 · English · 日本語 · 中文

</div>

---

목차

• seCall이란?
• 주요 기능
• 멀티 에이전트 수집
• 하이브리드 검색
• 지식 볼트
• Knowledge Graph
• Web UI + REST API + Obsidian 플러그인
• MCP 서버
• 멀티 기기 볼트 동기화
• 데이터 무결성
• 빠른 시작
• 사전 요구사항
• Step 1. 설치
• Step 2. 초기화
• Step 3. 세션 수집
• Step 4. 검색
• 사용법
• 세션 조회
• 임베딩 생성
• 세션 분류
• 위키 생성
• 작업 일기
• Knowledge Graph
• 설정
• 설정 키 목록
• CLI 레퍼런스
• MCP 연동
• 아키텍처
• 기술 스택
• 출처
• 라이선스

---

<div align="center"> <img src="screenshot.png" alt="seCall Obsidian 볼트" width="720" /> <br/><br/> </div>

seCall이란?

seCall은 AI 에이전트 대화를 위한 로컬 퍼스트 도구입니다. Claude Code, Codex CLI, Gemini CLI, claude.ai, ChatGPT 의 세션 로그를 수집하고, LLM 으로 Obsidian 호환 위키를 정리해 두고, BM25 + 벡터 하이브리드 검색을 CLI / MCP 서버 / REST API / 내장 웹 UI 로 제공합니다.

왜 필요한가?

• 아키텍처 결정·디버깅 흔적·설계 메모가 에이전트 JSONL 파일들에 흩어져 있어, "지난번에 그 업스트림 에러 어떻게 패치했더라?" 를 다시 찾는 게 번거롭습니다.
• seCall 은 원본 transcript 를 그대로 보존하면서 위에 LLM 이 정리한 위키를 얹고, 둘 다 검색합니다 — CLI / 웹 UI / Obsidian / MCP 호환 AI 에이전트 어디서든.

주요 기능

멀티 에이전트 수집

여러 AI 코딩 에이전트의 세션을 통합 형식으로 파싱하고 정규화합니다:

	에이전트	형식	상태
	Claude Code	JSONL	✅ 안정
	Codex CLI	JSONL	✅ 안정
	Gemini CLI	JSON	✅ 안정
	claude.ai	JSON (ZIP)	✅ v0.2 신규
	ChatGPT	JSON (ZIP)	✅ v0.2.3 신규

하이브리드 검색

• BM25 전문 검색: SQLite FTS5 + 한국어 형태소 분석 (Lindera ko-dic / Kiwi-rs 선택 가능)
• 벡터 시맨틱 검색: Ollama BGE-M3 임베딩 (1024차원) + HNSW ANN 인덱스 (usearch)로 O(log n) 탐색
• Reciprocal Rank Fusion (RRF): BM25/벡터 독립 실행 후 결합 (k=60) + 세션 다양성 강제 (세션당 최대 2개 턴)
• LLM 쿼리 확장: Claude Code를 통한 자연어 쿼리 확장

지식 볼트

Obsidian 호환 마크다운 볼트 (2계층 구조):

vault/
├── raw/.sessions/   # 불변 세션 원본 (dot-prefix → obsidian 자동 hidden, v0.5.0+)
│   └── YYYY-MM-DD/  # 날짜별 정리
├── wiki/            # AI 생성 지식 페이지
│   ├── projects/    # 프로젝트별 요약
│   ├── topics/      # 기술 주제 페이지
│   └── decisions/   # 아키텍처 의사결정 기록
└── graph/           # Knowledge Graph 출력
    └── graph.json   # 노드/엣지 데이터

• 위키 생성: pluggable LLM backend 기반 (secall wiki update --backend claude|codex|haiku — 생성은 도구 호출 가능 백엔드만; ollama/lmstudio 는 review 전용)
• Obsidian 백링크 ([[]])로 세션 ↔ 위키 페이지 연결
• Dataview 쿼리를 위한 frontmatter 메타데이터 (summary 필드로 세션 내용 즉시 파악)

Knowledge Graph

세션 간 관계를 추출하여 지식 그래프를 구축합니다:

• 노드 타입: session, project, agent, tool — frontmatter에서 자동 추출
• 규칙 기반 엣지: belongsto, byagent, usestool, sameproject, same_day (LLM 불필요)
• 시맨틱 엣지 (Gemini/Ollama/LM Studio): fixesbug, modifiesfile, introducestech, discussestopic — LLM이 세션 내용을 분석하여 추출
• 증분 빌드: 신규 세션만 노드 추가, 관계 엣지는 전체 재계산으로 정확성 보장
• MCP 도구: graph_query — AI 에이전트가 세션 간 관계를 탐색 (BFS, 최대 3홉)

Web UI + REST API + Obsidian 플러그인

secall serve는 REST API와 웹 UI를 동일 포트(8080)에서 제공하며, Obsidian 플러그인과도 동일 API를 공유합니다.

# REST API + Web UI 서버 시작
secall serve --port 8080
# 브라우저: http://127.0.0.1:8080

• 읽기 (Phase 0): /api/recall, /api/get, /api/status, /api/daily, /api/graph, /api/wiki (검색)
• 위키 본문 (Phase 1): GET /api/wiki/{project}
• 세션 메타 (Phase 0): /api/sessions, /api/projects, /api/agents, PATCH /api/sessions/{id}/{tags,favorite}
• 세션 노트 (Phase 2): PATCH /api/sessions/{id}/notes
• 태그 목록 (Phase 3): GET /api/tags?with_counts={true|false}
• true (기본): { "tags": [{ "name": "rust", "count": 12 },...] }
• false: { "tags": ["rust", "search",...] }
• 명령 (Phase 1): POST /api/commands/{sync,ingest,wiki-update}
• 그래프 재구축 (P37): POST /api/commands/graph-rebuild
• body: { since?, session?, all?, retry_failed? }
• 응답: { job_id, status: "started" }
• 단일 큐 정책: 다른 mutating job 실행 중이면 409 Conflict
• Job 관리 (Phase 1): GET /api/jobs, GET /api/jobs/{id}, GET /api/jobs/{id}/stream (SSE)
• Job 취소 (P36): POST /api/jobs/{id}/cancel
• 200: { "cancelled": true, "job_id": "..." } — 활성 job 취소 성공 (이미 완료/취소된 job 도 동일 응답으로 idempotent)
• 404: { "error": "job not found or already evicted" } — 미등록 / evict 됨

엔드포인트:

• 다크 모드 우선 모던 UI (Tailwind + shadcn/ui + Pretendard/Geist Sans)
• 2-pane 레이아웃 (좌: 검색/리스트, 우: 상세)
• 그래프 폴딩 오버레이 (노드 클릭 → 세션 로드 + 자동 폴딩)
• 태그 / 즐겨찾기 편집
• 사이드바 Commands 메뉴 — Sync / Ingest / Wiki Update 트리거 (Phase 1)
• 글로벌 진행 배너 + SSE 진행 스트리밍 + 완료/실패 toast (Phase 1)

Web UI (web/, P32 Phase 0 + P33 Phase 1):

• 검색 뷰 — 키워드/시맨틱 세션 검색
• 데일리 뷰 — 날짜별 작업 요약, 프로젝트별 세션 그룹핑, 노트 생성
• 그래프 뷰 — 노드 관계 탐색 (depth 1-3, 관계 필터)
• 세션 뷰 — 전체 마크다운 렌더링
• 상태바 — 세션 수 + 임베딩 상태 표시 (5분 갱신)

Obsidian 플러그인 (obsidian-secall/):

MCP 서버

MCP 호환 AI 에이전트에 세션 인덱스를 노출합니다:

# stdio 모드 (Claude Code, Cursor 등)
secall mcp

# HTTP 모드 (웹 클라이언트)
secall mcp --http 127.0.0.1:8080

제공 도구: recall, get, status, wikisearch, graphquery

멀티 기기 볼트 동기화

Git을 통해 여러 기기에서 지식 볼트를 동기화합니다:

# 전체 동기화: git pull → reindex → ingest → wiki → graph → git push
secall sync

# 로컬 전용 모드 (git 생략, Claude Code hook에 적합)
secall sync --local-only

• MD가 원본 — DB는 파생 캐시이며, secall reindex --from-vault로 완전 복구 가능
• 호스트 추적 — 각 세션이 어떤 기기에서 수집되었는지 기록 (frontmatter host 필드)
• 충돌 없음 — 세션은 기기별 유니크하므로 git 머지 충돌 없음

데이터 무결성

내장 린트 규칙으로 인덱스 ↔ 볼트 정합성을 검증합니다:

secall lint
# L001: 누락된 볼트 파일
# L002: 고아 볼트 파일
# L003: FTS 인덱스 갭

빠른 시작

사전 요구사항

• Rust 1.75+ (소스 빌드 시)
• Claude Code, Codex CLI, Gemini CLI 중 하나 이상
• Ollama — 벡터 검색용 (선택사항, 없으면 BM25만 사용)
• Windows: MSVC 툴체인 (Visual Studio Build Tools)

Step 1. 설치

원라인 설치 (권장) — release 바이너리를 자동으로 받아 PATH에 배치:

# macOS
curl -fsSL https://raw.githubusercontent.com/hang-in/seCall/main/install.sh | sh

# Windows (PowerShell)
irm https://raw.githubusercontent.com/hang-in/seCall/main/install.ps1 | iex

Linux는 아직 prebuilt 바이너리가 없습니다 — 아래 Cargo 빌드를 사용하세요.

• macOS: secall-aarch64-apple-darwin.tar.gz / secall-x86_64-apple-darwin.tar.gz
• Windows: secall-x86_64-pc-windows-msvc.zip (secall.exe + onnxruntime.dll)

수동 다운로드 — Releases 페이지에서 OS에 맞는 파일 다운로드:

Cargo (개발자용):

# CLI/MCP/REST API만 (웹 UI 미포함)
cargo install --path crates/secall --no-default-features

# 웹 UI 포함 — Node 22 + pnpm 9 + just 사전 설치 필요
git clone https://github.com/hang-in/seCall.git && cd seCall
just build         # web/dist 빌드 → cargo build --release
cp target/release/secall ~/.local/bin/

cargo install secall은 npm 빌드를 자동으로 수행하지 않습니다. 웹 UI를 사용하려면 Releases 바이너리 또는 위의 직접 빌드를 사용하세요.

Homebrew (예정 — tap 등록 작업 진행 중):

brew install hang-in/tap/secall

Windows 사용자: 핵심 기능(파싱, BM25 검색, vault, MCP)은 동일하게 동작합니다. 아래 기능은 MSVC 미지원으로 비활성화:

- HNSW ANN 인덱스 (usearch) — BLOB 코사인 스캔 fallback

- Kiwi-rs 형태소 분석 — Lindera ko-dic fallback

Step 2. 초기화

# 대화형 온보딩 (권장)
secall init

# 또는 인자 직접 지정
secall init --vault ~/Documents/Obsidian\ Vault/seCall
secall init --git [email protected]:you/obsidian-vault.git

• Vault 경로 설정
• Git remote (선택)
• 토크나이저 선택 (lindera/kiwi)
• 임베딩 백엔드 선택 (ollama/none)
• Ollama 설치 확인 + bge-m3 모델 자동 pull

secall init을 인자 없이 실행하면 대화형 위저드가 시작됩니다:

Step 3. 세션 수집

# Claude Code 세션 자동 감지
secall ingest --auto

# Codex CLI / Gemini CLI
secall ingest ~/.codex/sessions
secall ingest ~/.gemini/sessions

# claude.ai / ChatGPT export (ZIP)
secall ingest ~/Downloads/data-export.zip

# 또는 한 명령으로 전체 동기화
secall sync

Step 4. 검색

# BM25 전문 검색
secall recall "BM25 인덱싱 구현"

# 프로젝트, 에이전트, 날짜 필터
secall recall "에러 처리" --project seCall --agent claude-code --since 2026-04-01

# 벡터 시맨틱 검색 (Ollama 필요)
secall recall "검색 파이프라인 동작 방식" --vec

# LLM 쿼리 확장
secall recall "검색 정확도 개선" --expand

Web UI

secall serve는 REST API와 함께 웹 UI를 동일 포트에서 제공합니다 (단일 진입점).

secall serve --port 8080
# 브라우저에서 http://127.0.0.1:8080 접속

• 검색 / 세션 브라우징 (2-pane 레이아웃)
• 일일 일기 / 위키 페이지 열람 (전체 본문 — Phase 1에서 위키 본문 fetch 추가)
• 그래프 탐색 (사이드바 Graph 버튼 → 풀스크린 오버레이)
• 태그 / 즐겨찾기 편집

Phase 0 기능 (P32, 읽기 전용):

• 사이드바 Commands 메뉴 — Sync / Ingest / Wiki Update 버튼 + 옵션 다이얼로그
• SSE 진행 스트리밍 — phase별 실시간 표시
• 글로벌 진행 배너 — 어떤 페이지에서든 활성 작업 추적 (sticky top)
• 완료/실패/중단 자동 toast 알림
• 부분 성공 명시 (예: "ingest까지 OK / push 실패")
• 한 번에 하나의 mutating 작업만 실행 (단일 큐)
• 탭 닫고 재접속 시 진행 중 작업 자동 복원

Phase 1 기능 (P33, 명령 트리거):

• 시맨틱 검색 모드 토글 (Ollama 사용 시)
• 검색어 하이라이트 — 리스트 + 마크다운 본문 양쪽
• 다중 태그 AND 필터 + 날짜 quick range (오늘/이번 주/이번 달)
• 키보드 단축키 — ? 도움말, j/k 리스트 이동, / 검색 포커스, g d/w/s/c 라우트, [/] 세션 prev/next, f 즐겨찾기, e 노트
• 관련 세션 패널 — 그래프 인접 + 같은 프로젝트/태그 추천 (세션 상세 하단)
• 그래프 시각화 강화 — dagre 자동 레이아웃 + 노드 타입별 색상/아이콘 + 엣지 라벨 토글 + 범례
• 세션 메타 mini-chart — turn role 분포 (user/assistant/system) + tool 사용 빈도 top 5
• 사용자 노트 편집 — 세션별 markdown 노트 (autosave 1s, PATCH /api/sessions/{id}/notes)

Phase 2 기능 (P34, 뷰어 강화):

• /api/tags 엔드포인트 — 모든 태그 + 사용 빈도 정확 노출 (sessions 100건 휴리스틱 제거)
• SessionList 무한 스크롤 — IntersectionObserver 기반 자동 로드 (page_size=100)
• Code-split — 라우트별 + vendor (react/query/radix/viz) chunk 분리, 초기 진입 JS ≤ 250 kB (gzip)

Phase 3 기능 (P35, 성능 + 정확도):

• 실행 중 sync / ingest / wiki-update 작업을 안전하게 중단 가능
• tokioutil::sync::CancellationToken 기반 — JobRegistry / JobExecutor / BroadcastSink 통합, ProgressSink::iscancelled() 노출
• 어댑터(sync/ingest/wiki) 가 안전 지점에서 polling — phase 사이, file/session 루프 시작, LLM 호출 직전
• 부분 결과 보존 — 예: ingest 100건 중 50건 처리 후 취소 → 결과 JSON 에 ingested=50 그대로 기록
• 취소 시 최종 SSE 이벤트: Failed { error: "cancelled by user", partial_result: None }, job 상태는 Interrupted 로 강제
• REST: POST /api/jobs/{id}/cancel — 활성 200, idempotent 200, 미등록/evict 404
• Web UI: JobBanner 와 활성 JobItem 에 취소 버튼 + window.confirm 다이얼로그 (useCancelJob mutation hook)

Job Cancellation (P36, 실행 중 작업 취소):

• 이미 ingest 된 세션의 시맨틱 그래프를 별도로 재구축 가능 — embedding 만 끝낸 세션 backfill, 모델/프롬프트 교체 후 일괄 재처리 등
• DB 스키마 v8: sessions.semanticextractedat 컬럼으로 시맨틱 추출 상태 추적 (NULL = 미처리)
• CLI: secall graph rebuild [--since DATE] [--session ID] [--all] [--retry-failed]
• REST: POST /api/commands/graph-rebuild — P33 Job 시스템 + P36 cancel 통합
• Web UI: Commands 페이지 4번째 카드 "Graph Rebuild" + 옵션 다이얼로그 (since / session / all / retry-failed)
• 우선순위: --session > --all > --retry-failed > --since (동시 지정 시 위 순서로 적용) — CLI / REST / Web UI 모두 동일

Graph Sync 자동화 (P37, 시맨틱 그래프 재구축):

키보드 단축키 (Phase 2)

	키	동작
	?	단축키 도움말
	/	검색 포커스
	j / k	리스트 다음/이전 항목
	[ / ]	세션 prev/next
	g d	Daily 화면
	g w	Wiki 화면
	g s	Sessions 화면
	g c	Commands 화면
	g g	그래프 오버레이 토글
	f	현재 세션 즐겨찾기 토글
	e	현재 세션 노트 편집
	Esc	다이얼로그/오버레이 닫기

명령 사용

웹 UI에서 좌측 사이드바 Commands 메뉴 → 원하는 명령 + 옵션 → 시작.

CLI에서도 동일하게 사용 가능 (Job 시스템은 웹 UI 전용):

secall sync --local-only --dry-run
secall sync --no-graph         # graph 자동 증분 비활성 (sync 기본은 활성)
secall ingest --auto --auto-graph   # ingest 시 graph 자동 증분 활성 (기본 비활성)
secall wiki update --backend claude

# P37 — 시맨틱 그래프 재구축 (semantic_extracted_at 상태 추적)
secall graph rebuild --retry-failed              # 미처리(NULL) 세션 일괄 backfill
secall graph rebuild --since 2026-04-01          # 특정 날짜 이후 세션
secall graph rebuild --session abc12345          # 단일 세션
secall graph rebuild --all                       # 전체 재구축 (기존 결과 덮어쓰기)