unified-brain
DevLoops에서 제공하는 System One 코딩 에이전트를 위한 영구 메모리.
2026년 10월 24일, 저는 제가 unified-brain이라고 부르는 프레임워크를 OSS로 공개했습니다. 이 프레임워크는 빠르고 저렴하며, 최첨단 코딩 에이전트만큼 정확한 증거 수집 기능을 제공합니다. 동일한 9개 질문, 74점 xz 벤치마크(evals/questions/xz.md)에서 이 프레임워크는 Claude Fable 5.1 에이전트와 동일한 93.2%를 기록했으며, Claude Opus 5.5 에이전트의 94.6%에 비해서도 비용은 1/8 수준(프롬프트 캐싱 활성화 시)이고 속도는 2.4~3.5배 빠릅니다. 이 프레임워크는 10월 29일에는 86.5%에서 시작했으며, 격차를 해소한 네 가지 검색 개선 사항은 각각 evals/results/에 작성되어 있습니다. 여기서 수집 과정은 최첨단 의사 결정 심사 모델인 Jev가 수행하며, 최첨단 모델 자체가 수행하는 것이 아닙니다.
핵심 기술(magic sauce)은 System One 모델, 즉 Jev를 통해 검색(retrieval), 필터링(filtering), 판단(judging)을 용이하게 하는 중간 OS (SQLITE) 메모리 계층입니다.
unified-brain에서 생성된 에이전트는 Cursor의 MCP, OpenCode 또는 Claude Code 등에서 실행될 수 있어 사용자가 선호하는 환경에 연결하여 사용할 수 있습니다.
따라서 명확히 하자면: unified-brain은 자체적인 환경(harness)이 아니라 모든 환경이 플러그인할 수 있는 인식 계층(perception layer)입니다!
이 저장소의 evals/에 있는 두 개의 대규모 OS 라이브러리(xz 및 open62541)에 대한 평가 결과는 최첨단 에이전트와 충분히 근접하며, 그 비용은 훨씬 적습니다. 저는 이것이 AI를 더 신뢰할 수 있게 만드는 데 필요한 연결고리라고 믿습니다.
이는 다음과 같은 한계점들 때문입니다:
- 추론과 환각의 격차 (The Reasoning and Hallucination Gap):
LLM 턴 기반 추론은 불확실성과 확률적 결과를 도입합니다.
하지만.. unified-brain의 System One 발견 엔진은 작업을 수백 개의 예/아니오 호출로 분해하기 때문에, 검색 과정 자체가 산문으로 추론할 수 없으며 경로를 환각(hallucinate) 할 수도 없습니다. 5개의 등급별 xz 실행을 거치면서 답변에는 최대 한 번의 잘못된 주장만 포함되었고, 항상 가장 긴 답변에서 동일한 주장이었습니다. 이는 작성자가 증거 자료에 올바른 값과 함께 오기한 것에 불과하며, 검색 오류(retrieval error)가 아닙니다. 실행 간 재현성은 아직 결정적으로 측정되지 않았습니다.
장시간 코딩 작업은 막대한 양의 토큰을 소모하여 에이전트가 초기의 지침을 잊거나 대규모 아키텍처를 추적하지 못하게 만듭니다.
하지만 Unified-brain은 자신이 작동하는 컨텍스트의 SQLITE 영구 레이어 덕분에 캐시된 메모리가 필요 없습니다. 필요한 것을 즉석에서 검색할 뿐입니다. 작가는 평균적으로 질문당 80k 토큰(2k~166k)을 읽으며, 이는 프론티어 에이전트의 질문당 1.1–2.2M 청구 토큰에 대비되는 수치이며, 질문 간에 아무것도 누적되지 않습니다. 모든 질문은 서로 독립적입니다. 왜냐하면 git diff와 커밋은 프로젝트의 메모리 레이어에서 자동으로 흡수되기 때문입니다(이 마지막 부분은 아직 작업 중입니다).
하지만 이 제안된 전환(설립된 턴 기반 탐색에서 System One 증거 수집으로)을 통해 얻을 수 있는 가장 흥미로운 발전은 불필요한 자기회귀적 조사(autoregressive investigation)를 피함으로써 반복적인 가중치 및 주의 상태 메모리 트래픽을 줄일 수 있다는 점입니다. 영구 검색과 비자기회귀적 판단(non-autoregressive judgments)을 발견에 사용함으로써, unified-brain은 기존 에이전트가 프롬프트 캐싱을 사용하더라도 정확하게 답변하는 질문당 에너지 소비를 줄일 수 있는 신뢰할 만한 메커니즘을 갖추고 있습니다.
이러한 낙관론을 뒷받침하는 몇 가지 아키텍처적 요인:
-
중간 디코딩 단계 감소—캐싱을 사용하더라도. 기존의 전체 주의(full-attention) 에이전트에서는 생성되는 각 추론 또는 도구 선택 토큰이 KV 캐시를 통해 누적된 컨텍스트에 주의를 기울입니다. 캐싱은 이전 토큰 상태의 재계산을 방지하지만, 후속 생성을 위해 필요한 주의 작업과 메모리 접근을 없애지는 못합니다. 많은 중간 생성 토큰들을 경계가 있는 비자기회귀적 판단으로 대체함으로써, unified-brain은 발견 과정에서 이러한 반복적인 접근을 피할 수 있습니다.
-
KV 캐시 압력 감소. 조사 상태(investigation state)를 생성 모델 외부로 유지하면 저장, 접근 또는 재계산해야 하는 중간 토큰의 주의 상태(attention states)를 줄일 수 있습니다.
-
탐색 기록에 대한 주의 감소(Less attention over exploration history). 작성자는 실패한 검색, 중복된 도구 결과, 이전 조사 논의 등에 반복적으로 주의를 기울일 필요 없이 선택된 증거를 받을 수 있습니다.
-
캐싱 누락 시 반복적인 프리필 작업 감소(Less repeated prefill work when caching misses). 발견(discovery)과 합성(synthesis)을 분리함으로써, 프롬프트가 성장하거나 변경되어 중복 계산이 트리거될 기회를 줄입니다.
-
재사용 가능한 저장소 준비(Reusable repository preparation). 영구적인 심볼 및 기록 인덱스(Persistent symbol and history indexes)는 여러 질문에 걸쳐 증거를 구문 분석하고 정리하는 비용을 분산시킵니다.
-
독립적 판단의 효율적인 실행(Efficient execution of independent judgments). 비(非)자동회귀적(Non-autoregressive) 결정은 배치 처리되거나 동시에 실행될 수 있어, 중간 산문(intermediate prose)을 생성하지 않으면서 더 나은 하드웨어 활용 기회를 만듭니다.
-
프론티어 모델 실행 수요 감소(Reduced demand for frontier-model execution). 생성형 모델(generative model)을 주로 합성 작업에 할당함으로써 전체 추론(inference) 워크로드를 줄일 수 있으며, 이는 고정된 양의 작업을 위해 필요한 서비스 용량(serving capacity)을 낮출 잠재력이 있습니다.
-
잠재적으로 더 큰 서비스 용량(Potentially greater serving capacity). 생성형 조사(generative investigation)를 줄이는 것은 모델 실행 시간과 KV-캐시 용량을 확보하여 기존 인프라가 분당 더 많은 정확하게 답변된 질문을 처리할 수 있게 할 수 있습니다. 이 이득은 서비스 병목 현상 및 Jev, 검색(retrieval), 최종 합성 작업에 필요한 리소스에 따라 달라집니다.
-
잠재적으로 적은 수정 시도(Potentially fewer corrective attempts). 구조화된 발견(structured discovery)이 증거의 완전성과 정확성을 개선한다면, 비용이 많이 드는 후속 조사 및 답변 재생성(answer regeneration)을 줄일 수 있습니다.
에너지 절감량 중 어느 것도 측정되지 않았습니다. 측정된 양은 evals/에 있는 토큰(tokens), 달러($), 초(seconds)입니다.
여러분이 이 프로젝트를 포크(fork)하여 직접 확인해 보시기를 권합니다! 저는 메모리 중간 구조(memory intermediate structures)가 System One 모델과 결합하여 곧 AI 역량을 다음 단계로 끌어올릴 것이라고 확신합니다.
이 프로젝트의 철학은 근본적으로 무차별적인 확장(brute force scaling)에 의존하기보다는, 아키텍처적 우아함(architectural elegance)을 통해 소프트웨어 엔지니어링(SWE)의 현대 추론 문제를 해결하는 것입니다.
flowchart TD
classDef step fill:#2d3748,stroke:#4a5568,stroke-width:2px,color:#fff;
classDef process fill:#2b6cb0,stroke:#3182ce,stroke-width:2px,color:#fff;
...
Jev가 독점적이며 의존성을 만든다는 것을 이해하지만, 시간이 지남에 따라 오픈 소스(OS) 모델들이 격차를 좁혀나가서 OS 최종 사용자들에게 추가적인 선택권을 줄 것이라고 기대합니다. 하지만 현재로서는, 제한적인 실험을 거친 후 제가 내린 결론은 동등성(parity)이 없다는 것입니다.
지금은, 최첨단 에이전트들이 오늘날 도달하지 못하는 가격으로 최종 사용자들에게 새로운 기능을 제공하기 위해 이러한 혁신의 물결을 타고야 한다고 생각합니다.
작동 방식 (How it works)
unique-brain은 저장소의 전체 git 히스토리(git history)를 읽고, tree-sitter를 사용하여 모든 심볼(함수, 타입, 매크로, 설정 항목 등)의 모든 버전을 해당 심볼을 도입한 커밋과 함께 문제의 저장소 내 단일 SQLite db( <repo>/.unified-brain.db)에 저장합니다. 게다가 이 시스템은 임의의 커밋 시점에 두 가지 질문에 답할 수 있습니다:
- 질문하기(Ask) — "X는 왜 Y를 수행하는가?"에 대한 답변을 사용자가 선택한 커밋 시점에 활성화되어 있던 본문에서 찾습니다. 이 과정은 임베딩(embeddings) → Jev (코드를 통해 이름에 점수를 매기고 추적하는 작은 심사 모델) → 사용자가 선택한 LLM의 작성을 거칩니다.
- 타임라인/보고서(Timeline / reports) — 커밋 범위(range of commits)를 선택하고 모든 변경된 심볼에 대해 평가를 받습니다: 이 변경이 커밋 메시지가 말하는 바대로 작동하는가, 아니면 결함이나 악의적인 의도가 숨겨져 있는가? 각 판결에는 심사 모델에게 제시된 증거(diffs, 동일 커밋 변경 사항, 호출자(callers), Jev가 추적한 체인)가 함께 제공됩니다.
데이터 수집(ingestion) 과정 중에는 LLM이 사용되지 않습니다. 마지막에 단일 임베딩 패스(embedding pass)가 실행됩니다.
요구 사항 (Requirements)
- Python 3.11 이상 버전 (SQLite가 포함되어 있어 별도로 설치하거나 실행할 것이 없음)
- API 키: OpenRouter (Jev), 임베딩 제공업체 1개 —
Voyage AI 또는 DeepInfra (Qwen3-Embedding-8B, 더 저렴함) — 그리고 라이터(writer) 제공업체 1개 (Fireworks를 사용한 DeepSeek 또는 Anthropic).
빠른 시작
아래의 모든 내용은 가상 환경이 활성화된 상태에서 unified-brain 폴더 내 터미널에서 실행됩니다. 예제에서는 ~/code/xz에 있는 xz 클론을 사용합니다. 사용자 자신의 경로를 사용하세요.
1. 설치
git clone https://github.com/DevLoops-ai/unified-brain.git
cd unified-brain
python3 -m venv .venv && source .venv/bin/activate
...
.env 파일을 열고 파트 1을 채우세요. 최소한의 설정(주석은 반드시 별도의 줄에 있어야 함 — python-dotenv는 KEY=값 # 텍스트를 값 # 텍스트로 읽음):
# the database the service answers about (written by step 2)
DB_PATH=/Users/you/code/xz/.unified-brain.db
# writer: llmbase = DeepSeek V4.1 Flash on Fireworks, or anthropic
...
2. 인덱싱될 내용 확인
데이터를 수집(ingest)하기 전에, 몇 초 동안 인게스터가 어떤 파일을 기호별로 커버하는지, 무엇을 통째로 저장하는지, 그리고 무엇을 건너뛰는지 보여줍니다 (바이너리 파일은 저장되지 않습니다).
python ingester.py ~/code/xz scan-coverage
3. 리포지토리 수집
인게스터는 git 히스토리를 읽고 <repo>/.unified-brain.db라는 하나의 파일을 작성합니다. LLM은 사용되지 않으며, 이는 CPU 작업과 git으로 이루어집니다. 커밋이 들어오면, 임베딩 패스가 저장된 본문(bodies)에 대해 한 번 실행됩니다.
첫 번째 시도입니다 — 히스토리의 일부를 가져와 몇 분 안에 결과를 확인할 수 있습니다:
python next_claude.py ~/code/xz \
--since f7fa309e1f7178d04c7bedc03b73077639371e97 \
...
--since <ref>는 커밋 또는 태그 이후부터 시작하며, --max N은 N개의 커밋 이후에 중지합니다.
진행 상황은 커밋당 한 줄씩 출력하고 마지막에 요약(예: ✅ 1349 commit(s) ingested … skills created=… updated=… obsoleted=…)을 표시한 후 임베딩 패스(🧬 embedding pass [voyage] … 1943/1943)를 진행합니다.
리포지토리 전체 히스토리는 다음과 같습니다:
python next_claude.py ~/code/xz
노트북에서는 시간이 오래 걸립니다 (open62541: M3에서 13,474 커밋을 96분 만에 처리하고, 임베딩에 56분이 추가 소요됨). macOS에서는 caffeinate를 사용하여 전원을 유지하고, 동일한 터미널에서 실행합니다:
caffeinate -i python next_claude.py ~/code/open62541
중간에 중단되었나요 (Ctrl+C, 절전 모드, 충돌)? 마지막으로 처리된 커밋부터 계속하려면 다음 명령을 사용하세요:
python next_claude.py ~/code/xz --resume
처음부터 다시 시작하려면 .unified-brain.db 파일을 삭제하세요.
4. 임베딩 (재실행이 필요한 경우에만)
데이터 수집 과정(ingest)에서 이미 CODE_EMBED_PASS2를 통해 임베딩 패스가 실행됩니다. 별도의 명령이 필요한 경우는 두 가지입니다:
python next_claude.py ~/code/xz --embed-only
...
두 제공업체 모두 동일한 데이터베이스에 존재할 수 있으며, QA_VECTOR_STORE가 질문을 사용하는 쪽을 선택합니다. 예상 비용은 다음과 같습니다: DeepInfra에서 Qwen을 사용할 경우 open62541의 277,080개 본문 버전이 약 $1.30입니다. 임베딩 없이 카운트하려면 --dry-run을 추가하세요.
5. 서비스 시작
.env 파일의 DB_PATH는 질문하고 싶은 데이터베이스(하나의 서비스, 하나의 리포지토리)를 가리켜야 합니다. 그런 다음:
python codebase_qa_service.py
http://127.0.0.1:8000을 열어 질문하고, 커밋 타임라인 및 보고서는 http://127.0.0.1:8000/timeline에서 확인하세요. 서버는 로컬호스트(localhost)에서만 수신합니다. 각 답변은 일련의 숫자로 끝납니다: 단계별 시간, Jev 비용, 작성자 속도.
Ctrl+C를 누르면 중지됩니다.
리포지토리를 전환하려면 서비스를 중지하고, DB_PATH를 변경한 후, 다시 시작하세요.
6. 코딩 에이전트에게 전달하기 (Cursor, Claude Code, 모든 MCP 클라이언트)
unified_brain_mcp.py는 하나의 도구인 retrieve를 가진 MCP 서버입니다. 에이전트는 질문을 전달하고, 파일, 심볼, 라인을 포함하는 답변에 필요한 증거(evidence)를 돌려받은 후, 그로부터 답안을 작성합니다. 이 서버는 실행 중인 서비스와 통신하므로, 5단계가 반드시 실행 중이어야 합니다. 만약 서비스가 중지되면 에이전트는 이를 인지하고 해당 상태로 작동합니다.
Cursor — 작업 중인 프로젝트의 .cursor/mcp.json 파일에서 확인 가능합니다 (Cursor 설정 → 사용자 정의 → MCP에서 표시). Agent 모드를 사용하세요:
{"mcpServers": {"unified-brain": {
"command": "/path/to/unified-brain/.venv/bin/python",
"args": ["/path/to/unified-brain/unified_brain_mcp.py"]
...
Claude Code — .mcp.json 파일에서 동일한 객체를 사용합니다. 이 도구는 20~60초가 소요됩니다 (Jev가 읽고 있음). 에이전트에게 해당 질문에 unified-brain을 사용하도록 요청하세요.
또한, 스크립트를 위한 일반 HTTP 응답도 제공합니다: POST /api/retrieve, GET /api/grep, /api/symbol/{name}, /api/body, /api/history, /api/commit/{hash}.
질문의 비용 (What a question costs)
env.example 파일의 파트 1에 명시된 구성으로 측정됩니다: