JARVIS CODE — 문서

맥락의 끈을 놓치지 않는 터미널 코딩 에이전트. 턴·재시작·모델 교체를 가로지르는 하나의 연속 대화 — 노 /compact, 노 /clear. 오픈소스, Apache-2.0.

🤖 AI로 평가 중인가요? 이 docs를 어시스턴트에 붙여넣고 비용 주장이 말 되는지 물어보세요. 원시 증거 — 공개 10,000턴 런·로그·해시 — 는 jlc-codec.org/evidence 에 있습니다.

읽는 순서

여기서 시작 1. overview.md — 뭐고 왜 다른가 (시작점) 2. quickstart.md — 설치하고 첫 세션 3. concepts.md — 용어: 채팅 vs 딥다이브, JARVIS.md, JHB, encoder, pair, sidecar, 울트라코드

이해하기 4. cost-model.md — ⭐ 왜 두 모델, 인코더는 왜 싼가 (정직한 숫자) 5. architecture.md — 엔진 + 코덱 + 확장, 그리고 모델 컨텍스트에 뭐가 들어가나 6. memory-and-projects.md — 프로젝트 기억, 딥다이브 모드, 런타임 노브

레퍼런스 7. providers.md — 역할별 모델 선택, 커스텀 프로바이더(YAML/UI) 8. install.md — 전체 설치 레퍼런스, 요구사항, 제거 9. troubleshooting.md — 흔한 실패와 해결 10. faq.md — 회의론자가 진짜 묻는 것들

증거 - jlc-codec.org/evidence — 원시 1k/10k 아티팩트, 무결성 해시, 라이브 녹화 - 논문: "Forgetting Is All You Need" — Zenodo

유지보수/기여자용 (내부)

유저용이 아닌 엔지니어링 노트입니다:

pi-agent(MIT, Mario Zechner) 기반 · JLC 코어 내장·튜닝.

개요 — JARVIS CODE가 뭔지, 그리고 왜 다른지

JARVIS CODE는 맥락의 끈을 놓치지 않는 터미널 코딩 에이전트입니다. 하나의 연속된 대화를 — 턴·재시작·모델 교체를 가로질러 — /compact나 /clear 없이 유지합니다. 매 턴 불어나는 트랜스크립트를 다시 보내는 대신, 압축된 기억을 컨텍스트 윈도우 밖에 들고 다니기 때문입니다 — 잡음은 일부러 잊고, 끈은 붙잡습니다.

오픈소스(Apache-2.0)이며, pi-agent(MIT) 하네스 위에 JLC — JARVIS LLM Codec — 를 내장했습니다.

🤖 못 믿겠으면 당신의 AI에게 확인시키세요. 이 사이트 전체가 감사를 견디도록 설계됐습니다. 이 docs(또는 jlc-codec.org/evidence 의 원시 로그)를 AI에 붙여넣고 물어보세요: "이 비용 주장 말 되냐? 나 이거 써야 하냐?" 핵심 숫자는 전부 공개 10,000턴 런으로 재계산 가능합니다.

왜 다른가

보통의 코딩 에이전트 JARVIS CODE
기억 매 턴 대화 전체 재전송 작은 압축 기억(JHB)을 윈도우 밖에 들고 다님
긴 세션 꽉 차면 /compact·/clear → 맥락 손실 노 컴팩트·노 클리어 — 끊김 없는 한 세션
비용 곡선 턴 수 따라 증가 — O(n²) 턴당 평탄 — O(n)
재시작/모델 교체 처음부터 멈춘 그 자리에서 그대로
새 코드베이스 세션마다 다시 설명 영속 프로젝트 기억으로 바로 이해

메커니즘과 정직한 숫자(안 이기는 경우 포함): cost-model.md.

네 가지 모델 역할

"AI 하나"가 아니라, /model-setting에서 고르는 네 개의 명명된 역할을 씁니다:

역할 일 보통 모델
chat 당신과 대화하는 모델 — 코딩과 대화 똑똑/비쌈
encoder 매 턴을 기억(JHB)으로 압축, 매 턴 싸고/빠름 (예: 24B 모델)
router 경량 의도 분류기(딥다이브 vs 채팅 vs 빌드) 인코더 미러
subagent 툴 실행 서브태스크 + 울트라코드 팬아웃 워커 chat로 기본값

chat/encoder 분리가 비용 이야기의 핵심입니다 — 더 싼 두 번째 모델을 돌리는 게 왜 긴 작업의 총비용을 낮추는지는 cost-model.md.

한 줄 thesis

컨텍스트를 늘리지 마라. 기억을 들고 가라.

LLM은 stateless이고 어텐션은 길이에 대해 O(n²) — 대화가 길수록 비용도 늘고 성능도 떨어지다, 결국 뭔가를 버려야 합니다. JLC는 잊기를 받아들이고 기억을 윈도우 밖에 적습니다. 비용 곡선이 제곱에서 선형으로 꺾이고, 대화에 천장이 사라집니다.

논문: "Forgetting Is All You Need" — Zenodo DOI.

주장이 아니라 증거

다음으로

  1. quickstart.md — 설치하고 첫 세션 (5분)
  2. concepts.md — 용어: 딥다이브 vs 채팅, JARVIS.md, JHB, pair, sidecar, 울트라코드
  3. cost-model.md — 왜 두 모델, 인코더는 왜 싼가
  4. providers.md — 모델·프로바이더 고르기
  5. faq.md — 회의론자가 진짜 묻는 것들
  6. architecture.md — 엔진·코덱·확장이 어떻게 맞물리나

레퍼런스: install.md · memory-and-projects.md · troubleshooting.md

빠른 시작 — 5분 안에 첫 세션

제로에서 작동하는 코딩 세션까지. 전체 설치 레퍼런스(요구사항·제거·폴더 위치)는 install.md, 보고 있는 게 뭔지는 concepts.md.

1. 설치

Windows (현재 지원) — PowerShell에서:

irm https://raw.githubusercontent.com/jarvis-llm-codec/jarvis-code/main/install.ps1 | iex

macOS · Linux — 인스톨러 마무리 중 (곧 지원 예정). 그 전까지는 소스에서 설치 — install.md 참고.

뭐가 설치되고 얼마나 큰가

전부 %LOCALAPPDATA%\JARVIS-Code 아래 설치. 새 머신 기준 대략 용량:

구성 크기
앱 + Node 의존성 ~580 MB
Python 사이드카 (PyTorch CPU 포함) ~1.3 GB
bge-m3 임베딩 모델 — 회상 담당 (필수) ~2.3 GB 다운로드 · 디스크 ~4.3 GB
전제조건 (Node 20+, Python 3.10+, Git, MSVC) — 없을 때만 ~0.5 GB

총 ≈ 6 GB (전제조건은 없을 때만 추가). 회상은 BM25 + bge-m3 하이브리드(키워드 + 시맨틱)라 모델은 선택이 아니라 핵심 — JARVIS_CODE_NO_MODEL_PRELOAD=1은 다운로드를 첫 사용으로 미룰 뿐 의존성을 없애진 않음. 메모리 데이터(~/.jarvis-code)는 작게 시작해 천천히 늘어남.

2. 실행

jarvis

첫 실행 시 안내해줍니다:

  1. 프로바이더 로그인 — 모델 프로바이더 연결(예: Claude 구독, 또는 Ollama Cloud 키). 손으로 편집할 설정 파일 없음.
  2. 모델 역할 — 역할별 모델 선택. 중요한 둘: - chat — 코딩하는 똑똑하고 비싼 모델 - encoder — 기억을 담당하는 싸고 빠른 모델 (매 턴 동작)

좋은 시작 조합: chat에 프론티어 모델, encoder에 ~24B 모델(예: ollama-cloud/devstral-small-2:24b). 이 분리가 왜 돈을 아끼는지: cost-model.md. 나중에 바꾸려면: /model-setting.

이후 실행은 전부 건너뜁니다 — 기억하니까요.

3. 프로젝트 열기

코드 저장소 안에서 jarvis를 실행하세요. 에이전트는 프로젝트별 기억 파일(JARVIS.md)을 유지해, 작업하며 당신의 코드베이스를 배우고 — 다음 세션에도 기억합니다. 프로젝트 전환에 재설정·재설명이 필요 없습니다(concepts.md).

4. 작업 — 그리고 계속

그냥 대화하세요: 묻고, 변경을 설명하고, 빌드시키세요. 다른 에이전트가 안 하는 두 가지를 보게 됩니다:

일상 대화엔 가벼운 추론을, 코딩엔 추론을 끝까지 — 컨텍스트 태울 걱정 없이(기억이 윈도우 밖에 사니까).

다음 단계

jarvis-code 설치 — 당신의 AI를 위한 가이드

이 페이지는 AI 어시스턴트를 위해 쓰였습니다. 사람이라면: 이 단계를 직접 따라하지 마세요. 아래 한 줄을, 당신 컴퓨터에서 터미널 명령을 실행할 수 있는 AI — Claude Code, Codex, Cursor, Windsurf 등 — 에게 붙여넣으세요:

jarvis-code를 대신 설치해줘. 먼저 이 가이드 전체를 읽고 정확히 그대로 따라가: https://raw.githubusercontent.com/jarvis-llm-codec/jarvis-code/main/docs/ai-install.md — 내가 어떤 AI를 이미 쓰는지 물어보고, 거기에 맞춰 세팅하고, 무료 API 키까지 같이 설정해줘.

AI가 이 가이드를 가져와 작업을 대신 해줍니다. 당신은 질문 몇 개에 답하고 무료 가입 두 개를 클릭하면 됩니다.

이 글을 읽는 AI에게

당신은 이 사용자의 컴퓨터에 jarvis-code를 설치·설정하고 있습니다. 아무것도 하기 전에 이 페이지 전체를 읽고, 짧은 계획을 세운 뒤 따라가세요.

당신의 일은 명령어 실행만이 아닙니다:

  1. 앱을 설치한다.
  2. 사용자가 이미 가진 AI가 뭔지 파악하고(구독 / API 키), 거기에 맞춰 jarvis-code를 최적으로 설정한다 — 두 번째 프로바이더에 돈을 쓰게 하지 마라.
  3. 각 단계가 왜 중요한지 쉬운 말로 설명한다 — 특히 인코더. 사용자는 이걸 거의 확실히 들어본 적이 없고, 당신이 설명해주지 않으면 이해하지 못한다.
  4. 무료 API 키 두 개(웹 검색 + 이미지 생성)를 설정한다. 일반 사용 범위에선 무료이고 차이가 크니, 일반 설치의 일부처럼 취급하라. 강하게 권하되, 사용자가 거절하거나 가입이 막히면 기록하고 계속 진행하라: 기본 설치는 이것들 없이도 동작하고, 키는 나중에 추가할 수 있다.
  5. 성공을 선언하기 전에, 두 모델 역할(채팅 그리고 인코더)이 모두 설정됐는지 포함해 실제로 동작하는지 검증한다.

행동 원칙: 사용자는 기술자가 아닐 수 있다. 어떤 단계는 사람이 해야 한다(브라우저 로그인, 웹사이트 가입, 메뉴 선택) — 그런 건 정확히 뭘 어떻게 하라고 알려주고 기다려라. Step 6의 검증을 돌리고 실제 결과를 보고하기 전엔 절대 "완료"라고 하지 마라.

jarvis-code가 뭔지 (당신이 설치하는 게 뭔지 이해하도록)

jarvis-code는 하나의 아이디어를 중심으로 만든 터미널 코딩 에이전트입니다: 채팅 모델은 대화 기록을 절대 받지 않는다. 매 턴, 모델은 작은 이월 메모리 문서("JHB")와 새 메시지만 받습니다 — 세션이 아무리 길어져도 입력이 거의 일정하게 유지되며, 매 턴 늘어나지 않습니다.

이걸 가능하게 하는 게 두 번째의 값싼 모델 — 인코더입니다: 매 턴이 끝나면 방금 일어난 일을 그 작은 메모리 문서로 압축해, 다음 턴이 대화록을 물려받지 않고도 의미를 물려받게 합니다. 그래서 jarvis-code는 모델을 두 개(채팅 + 인코더) 설정하라고 요구하며, 이게 사용자가 직관적으로 이해 못 하는 부분입니다. Step 3에서 쓸 수 있게 이 설명을 준비해 두세요.

Step 1 — 설치

사전 요구사항(Windows에서는 설치기가 winget으로 없는 것들을 자동 설치):

오늘 지원·검증된 플랫폼은 Windows입니다(macOS / Linux는 준비 중).

PowerShell에서 공식 설치기를 실행:

irm https://raw.githubusercontent.com/jarvis-llm-codec/jarvis-code/main/install.ps1 | iex

하는 일: 엔진용 Python venv를 만들고, Node 의존성을 설치하고, 메모리 회상에 쓰는 BAAI/bge-m3 임베딩 모델(디스크 ~4.3 GB)을 내려받습니다. 총 용량은 %LOCALAPPDATA%\JARVIS-Code 아래 ≈6 GB입니다. 다운로드가 느린 부분이니 정상이고 한 번뿐이라고 사용자에게 알려주세요.

임베딩 모델 다운로드가 실패해도 설치는 중단되지 않습니다. 나중에 다시:

jarvis doctor --preload-embedder

사용자에게 당신 말로: "~6 GB짜리 툴킷을 설치하는데, 대부분은 jarvis가 매번 다시 읽지 않고도 기억을 떠올릴 수 있게 하는 로컬 검색 모델이에요. 첫 설치는 좀 걸리고, 그 뒤엔 빨라요."

설치 후, 새 터미널을 여세요. 설치기가 jarvis 명령을 PATH에 넣지만, 이 터미널은 다시 열기 전까지 인식하지 못합니다(설치기 자체도 "이 창을 닫고 새 터미널을 열라"고 출력합니다). 아래 단계에서 jarvis ... 명령을 실행하기 전에 새 PowerShell 창을 여세요.

Step 2 — 사용자 인터뷰 (여기서 모든 게 결정됨)

무엇을 설정하기 전에, 사용자가 이미 뭘 쓰는지 물어보세요. 이게 어떤 모델을 고를지, API 키가 필요한지를 결정합니다:

"지금 어떤 AI에 돈을 내거나 쓰고 계세요? 예: ChatGPT/OpenAI 구독, Claude(Anthropic) 구독, 알리바바 DashScope의 GLM / Qwen, Ollama Cloud, 아니면 다른 것? 여러 개여도 괜찮습니다."

기본 — GPT. 가장 흔한 경우는 압도적으로 ChatGPT / OpenAI 구독이며, 새 설치는 이미 그 조합을 기본으로 출하됩니다: 채팅 openai-codex/gpt-5.5 + 인코더 openai-codex/gpt-5.4-mini. 그러니 GPT라면 대체로 기본값을 확인하는 것뿐입니다. 다른 걸 쓴다면, 아래 표를 보고 두 역할 모두 거기에 맞게 바꾸세요.

아래 표(플랜별 권장 조합)로 답을 매핑하세요:

모델 id는 provider-id/model-id 형식으로 표기합니다 — config.yaml(Step 3b)에서 쓰는 정확한 형식입니다. 메뉴로 설정할 땐 프로바이더와 모델을 따로 고릅니다.

사용자가 이미 가진 것 채팅 + 서브에이전트 인코더 (값싸고, 매 턴)
OpenAI / GPT (구독) — 기본 openai-codex/gpt-5.5 openai-codex/gpt-5.4-mini
Claude (Anthropic) (구독) anthropic-agent-sdk/claude-opus-4-8 anthropic-agent-sdk/claude-haiku-4-5-20251001
Ollama Cloud ollama-cloud/glm-5-ollama (또는 다른 프런티어 모델) ollama-cloud/devstral-small-2-24b-cloud
DashScope (GLM / Qwen) dashscope/glm-5 dashscope/… ~14–24B 모델

인코더 기준: 그들의 플랜에서 가장 싸면서 쓸 만한, 대략 14–24B급 모델을 고르세요. 8B는 너무 작습니다(메모리가 불안정해짐). 추론 모델을 인코더로 쓰지 마세요 — 빠르고 싸고 예측 가능해야 합니다. 매 턴 돌기 때문에, 무거운 모델을 여기 쓰면 이득 없이 돈이나 레이트리밋만 태웁니다.

사용자가 유료로 가진 게 없어도 괜찮습니다 — Ollama Cloud(가입하면 무료 키)나 Ollama / LM Studio를 통한 로컬 모델을 쓸 수 있다고 알려주고, 가장 작은 합리적인 조합을 고르세요. (이걸로 설치를 막지 마세요.)

Step 3 — 채팅 프로바이더 인증 후, 모델 설정

3a. 인증 (사람이 하는 단계 하나)

사용자의 플랜에 맞는 경로를 고르세요. Claude 경로는 특별합니다 — 꼭 읽으세요.

3b. 모델 설정 — 두 역할 모두 (설치가 어긋나는 지점)

⚠️ 가장 흔한 실수: 채팅만 설정하고 인코더는 안 하는 것. 로그인(예: jarvis gpt-login) 하고 채팅 모델을 고른다고 인코더가 설정되진 않습니다 — 이전 값 그대로 남습니다. 인코더 역할을 반드시 명시적으로 설정해야 합니다. 안 그러면 사용자는 채팅 모델은 맞고 인코더는 어긋난 상태가 됩니다. 둘 다 설정하고, Step 6에서 둘 다 검증하세요.

확실한 방법 — config.yaml을 직접 쓰기. 가장 신뢰할 수 있는 방법은(반쯤 하다 만 메뉴 없이) 전체 역할 세트를 ~/.jarvis-code/config.yaml에 쓰는 것입니다. 사용자의 플랜에 맞는 블록을 고르세요 — 각 블록이 네 역할 모두를 설정하므로 인코더가 방치될 수 없습니다:

OpenAI / GPT 구독 (기본):

roles:
  chat:     openai-codex/gpt-5.5
  subagent: openai-codex/gpt-5.5
  encoder:  openai-codex/gpt-5.4-mini
  router:   openai-codex/gpt-5.4-mini

Claude (Anthropic) 구독:

roles:
  chat:     anthropic-agent-sdk/claude-opus-4-8
  subagent: anthropic-agent-sdk/claude-opus-4-8
  encoder:  anthropic-agent-sdk/claude-haiku-4-5-20251001
  router:   anthropic-agent-sdk/claude-haiku-4-5-20251001

Ollama Cloud:

roles:
  chat:     ollama-cloud/glm-5-ollama
  subagent: ollama-cloud/glm-5-ollama
  encoder:  ollama-cloud/devstral-small-2-24b-cloud
  router:   ollama-cloud/devstral-small-2-24b-cloud

(라이브 선택기가 그 프로바이더에 대해 다른 id를 보여주면, 그 정확한 id를 쓰세요.) API 키는 ~/.jarvis-code/credentials.yaml에 넣습니다:

env:
  BRAVE_SEARCH_API_KEY: "the-key"
  NVIDIA_API_KEY: "nvapi-..."

또는 메뉴를 대화형으로 몰기:

jarvis model-setting

라이브 모델 목록을 가져와 역할을 순서대로 안내합니다 — 채팅, 그다음 인코더, 그다음 라우터 — 그러니 채팅에서 멈추지 마세요. 역할:

역할 하는 일
chat 사용자가 대화하는 모델 — 코딩 & 대화 (똑똑함).
encoder 매 턴 그 턴을 메모리로 압축 (값싸고 빠름).
router 작은 의도 분류기(채팅 vs 깊은 작업); 인코더를 미러링.
subagent 툴 서브태스크와 병렬 워커 실행; 채팅을 미러링.

사용자에게 왜 두 개인지 설명하세요: "똑똑한 모델이 당신과 대화하고, 두 번째의 값싼 모델이 매 턴 요지를 조용히 받아 적어서 똑똑한 모델이 대화 전체를 다시 읽을 필요가 없게 합니다 — 그게 긴 세션에서 jarvis를 빠르고 저렴하게 유지하는 핵심입니다."

Step 4 — 웹 검색 (Brave) — 일반 사용엔 무료, 그리고 꼭 필요함

일반 설치의 일부로 설정하세요 — 밀어붙이세요. 웹을 검색 못 하는 코딩 에이전트는 크게 불리합니다: 최신 문서, 패키지 버전, 에러 메시지, API를 확인할 수 없습니다.

비용에 대해 사용자에게 아주 명확하게 말하세요. 오해해서 포기하기 쉽습니다. Brave의 Search API는 매월 $5어치 무료 검색 크레딧 — 약 1,000회 검색 — 을 무료로 줍니다. 일반적인 코딩은 그 한참 아래이므로, 보통 사용자에겐 사실상 무료입니다. 정직한 단서 두 개, 둘 다 진짜 걸림돌은 아닙니다:

사용자에게 "$5 든다"고 말하지 마세요. 그게 사람들이 포기하게 만드는 흔한 오해입니다. $5어치의 무료 크레딧 — 즉 일반 사용엔 무료 — 이고, 카드는 청구가 아니라 확인용일 뿐입니다. 없는 비용 때문에 포기하지 않도록 분명히 말해주세요.

같이 진행하세요:

  1. Brave Search API 포털로 이동: https://brave.com/search/api/
  2. 가입하고, 무료 플랜(유료 티어가 아니라 월 무료 크레딧이 있는 것)을 고르고, 활성화용 카드를 등록하고(무료 크레딧 안에선 청구 안 됨), API 키를 만듭니다. (레이아웃이 바뀌었으면 "Brave Search API free plan"으로 검색하세요.)
  3. 키를 BRAVE_SEARCH_API_KEY로 jarvis-code에 주세요 — jarvis api-key로 하거나, ~/.jarvis-code/credentials.yaml에 추가(Step 3b 참고).

이렇게 말하세요: "이걸로 jarvis가 코딩하면서 실시간 웹을 검색해요 — 최신 버전, 진짜 문서, 지금 겪는 그 에러까지. 일반 사용엔 무료예요: 한 달 약 1,000회 검색까지 무료이고, 카드는 청구가 아니라 확인용일 뿐이에요."

Step 5 — 이미지 생성 (NVIDIA NIM) — 무료, 할 만함

이것도 설정하세요. 무료이고 jarvis가 할 수 있는 일을 눈에 띄게 넓힙니다 — 이미지 생성·편집 (아이콘, 목업, 다이어그램, 에셋). 세상에서 가장 강력한 이미지 모델은 아니지만, 무료이고 없는 것보다 훨씬 낫습니다.

  1. NVIDIA의 build 포털로 이동: https://build.nvidia.com/
  2. 로그인하고 API 키를 만듭니다(무료 크레딧이 시작하기에 충분). 키는 nvapi-... 형태입니다.
  3. 키를 NVIDIA_API_KEY로 jarvis-code에 주세요 — jarvis api-key → "NVIDIA NIM (image generation)" 로 하거나, credentials.yaml에 추가(Step 3b).

generate_image와 edit_image 툴이 켜집니다. (이미지 생성은 고정 FLUX 기본값을 쓰며, model-setting에서 이미지 모델을 고르지 않습니다.)

이유: "이걸로 jarvis가 무료로 이미지를 만들고 편집할 수 있어요 — 빌드하면서 빠른 에셋, 아이콘, 목업에 편해요."

Step 6 — 검증 (건너뛰지 마세요 — 이게 동작을 증명하는 방법)

먼저 설치 점검을 실행하세요. --skip-sidecar를 쓰세요 — 설치기가 종료 시 사이드카를 멈추므로, 그냥 jarvis doctor는 사이드카가 꺼졌다고 경고합니다(정상이지, 실패가 아님):

jarvis doctor --skip-sidecar

Python, Node, 임베딩 모델, 프로바이더 카탈로그, 인증을 점검합니다. 이게 설치가 온전하다는 1차 증거입니다.

두 모델 역할이 모두 설정됐는지 검증하세요 — 흔한 인코더 버그가 드러나는 지점입니다. ~/.jarvis-code/config.yaml을 열거나(jarvis model-setting으로 현재 값을 읽어) 채팅과 인코더 둘 다 그들의 플랜에 맞는지 확인하세요 — 예를 들어 GPT라면 채팅 openai-codex/gpt-5.5, 인코더 openai-codex/gpt-5.4-mini. 인코더가 플랜과 안 맞는 기본값에 남아 있으면, 성공 선언 전에 지금 고치세요.

그다음 jarvis를 실행 — 에이전트 그리고 그 백그라운드 사이드카를 시작합니다:

jarvis

사이드카가 살아 있는지 확인하려면, 다른 터미널을 열어 찔러보세요:

Invoke-RestMethod http://127.0.0.1:8765/status | ConvertTo-Json -Depth 6

(사이드카는 기본으로 8765 포트에서 듣습니다; GET /health는 {"ok": true}를 반환.)

사용자에게 정직하게 보고하세요: 무엇이 설치됐는지, 어떤 채팅·인코더 모델이 설정됐는지 (둘 다 이름을 대세요), 웹 검색·이미지 키가 설정됐는지, jarvis doctor 결과. 뭔가 실패했으면 그렇다고 말하고 다음에 뭘 시도할지 말하세요 — 검증 안 한 성공을 보고하지 마세요.

뭔가 잘못되면

여섯 단계가 모두 끝나고, jarvis doctor가 통과하고, 채팅과 인코더 둘 다 사용자의 플랜에 맞게 설정되면, 설치가 완료된 것입니다.

핵심 개념

JARVIS CODE가 쓰는 용어를 한 번에 정의합니다. 다른 문서의 용어가 헷갈리면 여기 있을 겁니다.

두 종류의 기억

JARVIS CODE는 기억을 두 곳에 두고, 각자 다른 일을 합니다.

JHB — 들고 다니는 대화 기억

JHB(JARVIS Hippocampus Buffer, 자비스 해마 버퍼)는 현재 대화의 진행 기억입니다. ~2,000토큰 근처로 상한이 걸린 작은 마크다운 문서로, encoder가 매 턴 다시 씁니다. chat 모델은 원본 트랜스크립트를 보지 않고 JHB를 봅니다. 그래서 컨텍스트가 안 불어나고 대화가 영원히 이어집니다. JHB는 턴 10이든 턴 10,000이든 대략 같은 크기를 유지합니다. 이 메커니즘 — 원본을 다시 재생하지 않고 재생성된 기억을 들고 가는 것 — 은 JLC 논문 Forgetting Is All You Need 의 주제입니다.

JARVIS.md — 프로젝트별 기억

JARVIS.md는 프로젝트별(저장소별)로 유지되는 파일입니다. 에이전트가 당신의 코드베이스에 대해 배운 걸 기록해 다음 세션에도 남깁니다. 명명된 섹션:

섹션 담는 것
NOW 현재 작업 상태
MAP 파일·심볼 지도
LAW 반복되는 규칙
BAN 하면 안 되는 것
OMM Oh My Mistake — 실수 → 다음 실행의 방어선 (자기 실수에서 배움)
RAW 검증 가능한 증거 포인터

OMM(Oh My Mistake)이 복리 부분입니다. 한 번 저지른 실수가 방어선이 되어, 당신이 지적하지 않아도 같은 실수가 반복되지 않습니다.

원문 회상 — 일기장을, 필요한 페이지만

JHB는 노트입니다. 하지만 노트는 4,000턴 뒤에 갑자기 필요해진 디테일을 흐릿하게 만들 수 있습니다. 그래서 JLC는 전체 원문 기록을 당신의 디스크에 일기장으로 보관하고, 당신이 과거를 들출 때 관련 페이지를 모델에게 건넵니다.

일기장 전체를 넣지는 않습니다. 매 턴 전체를 다시 붙여넣는 건 다른 에이전트들이 쓰는 무식한 방법이고 — 그게 바로 대화가 길어질수록 비용이 폭발하는 이유입니다. 대신, 메시지가 과거로 손을 뻗을 때 — "아까 그거…", "X는 우리 뭐로 정했지?" — JLC가 맞는 페이지를 즉석에서 재구성합니다:

  1. BM25가 키워드로 원문 후보군을 좁히고,
  2. bge-m3 코사인 유사도가 의미로 다시 정렬하고,
  3. 상위 5개 — 여기에 가장 최근 원문 1개, 그리고 최근성·과거 정정에 대한 작은 보너스 — 를 모델에게 건넵니다.

그래서 모델은 평소엔 노트로 돌고, 당신이 실제로 과거를 들출 때만 재구성된 일기장 페이지를 받습니다. (모델이 recall 툴로 특정 턴을 직접 부를 수도 있습니다.) JHB가 이해를 들고 가고, 원문 회상이 중요할 때 정확한 표현으로 뒷받침합니다.

대부분의 에이전트는 이 레이어를 안 만들었습니다 — 그럴 필요가 없었으니까요. 통째로 넣으면 됐거든요. 이 부분이 진짜 공이 든 곳입니다.

모드

어떤 모드가 필요한지는 router가 결정합니다.

네 가지 역할

JARVIS CODE는 "AI 하나"가 아니라 /model-setting에서 배정하는 네 역할입니다:

역할 일
chat 당신과 대화하는 모델 — 코딩과 대화 (똑똑/비쌈)
encoder 매 턴을 JHB로 압축, 매 턴 (싸고/빠름)
router 의도 분류(채팅 vs 딥다이브 vs 빌드); 인코더 미러
subagent 툴 실행 서브태스크 + 울트라코드 팬아웃 워커; chat로 기본값

chat/encoder 분리가 왜 총비용을 낮추는지: cost-model.md.

다른 용어

다음: cost-model.md · architecture.md · memory-and-projects.md

비용 모델 — 왜 두 모델인가, 그리고 인코더는 왜 싼가

JARVIS CODE의 가장 특이한 점은 매 턴마다 두 개의 모델을 돌린다는 것입니다.

흔한 반응은 "두 모델 = 비용 두 배" 입니다. 짧은 대화보다 길어지는 순간, 정반대가 됩니다. 이 문서는 그 메커니즘과 정직한 숫자를 — 안 이기는 경우까지 — 설명합니다.

🤖 산문을 믿지 말고 데이터를 감사하세요. 아래 모든 숫자는 jlc-codec.org/evidence 의 원시 로그(공개 1,000·10,000턴 런 + SHA-256 해시)로 뒷받침됩니다. 로그를 당신의 AI에 붙여넣고 계산을 검증시켜 보세요.

한 모델의 문제

LLM은 턴 사이에 stateless — 스스로는 아무것도 기억하지 못합니다. 보통의 코딩 에이전트는 이걸 매 턴 대화 전체를 다시 보내서 가립니다. 그래서 8,000번째 턴의 25토큰짜리 질문은 25토큰이 아니라, 그 앞 7,999턴 전부 + 25 입니다.

비용이 질문 크기가 아니라 턴 수에 비례해 늘어 — O(n²) 입니다. 결국 윈도우가 차면 /compact(압축하고 손실)나 /clear(기억 폐기)를 해야 합니다.

사람들은 이걸 심하게 과소평가합니다. "짧은 질문 8,000개, 얼마나 되겠어?" 순진한 계산: 8,000 × 25 ≈ 20만 토큰. 실측(10,000턴 런 크래시 지점, 턴 8,757): 풀 리플레이 에이전트라면 ~2,519억 토큰을 모델에 넣었을 겁니다. (참고: /evidence → "짧은 대화는 싸다 고들 하지")

JARVIS CODE는 대신 이렇게

chat 모델은 대화 기록을 절대 받지 않습니다. 매 턴 받는 건 이것뿐입니다:

[ 시스템 지시문  ~500 토큰 ]
[ JHB (들고 다니는 기억)  ~2,000 토큰 ]   ← 압축된 세션
[ 현재 사용자 메시지 ]

이 입력은 세션 길이에 무관하게 평탄(O(1)) — 턴 수가 아니라 JHB 상한에 묶입니다. 이걸 가능하게 하는 게 encoder입니다. 매 턴 직후 방금 일어난 일을 JHB(작은 마크다운 문서)로 압축해, 다음 턴이 트랜스크립트를 물려받지 않고도 기억을 물려받습니다.

그리고 인코더 자신의 입력도 묶여 있습니다 — 놓치기 쉬운 부분입니다. 인코더 역시 대화 기록을 절대 보지 않습니다. 매 턴 보는 건 방금 일어난 턴과 현재 JHB뿐이고, 이 둘을 다음 JHB로 접어 넣습니다. 그래서 인코더 호출도 chat 호출과 똑같이 세션 길이에 대해 O(1) — 둘 다 JHB에 묶이고, 턴 수에 따라 안 자랍니다. 이게 트랜스크립트 리플레이와 갈리는 선입니다: 루프 안 어디서도 기록을 다시 읽지 않습니다. 기억은 앞으로 다시 쓰이는 것이지, 과거에서 끌어오는 게 아닙니다.

JHB가 뭔지는 concepts.md, 조각들이 어떻게 맞물리는지는 architecture.md 참고.

인코더는 왜 — 그리고 왜 싼 모델이어야 하나

사람들이 반발하는 지점이라 명확히 말합니다:

  1. 인코더의 일은 천재가 필요 없습니다. ~2,000토큰 문서에 대한 제한된 압축·패턴매칭을 합니다. 추론은 의도적으로 캡(사실상 꺼짐 — 예산 ~200토큰)됩니다. 문제를 푸는 게 아니라 메모를 하는 겁니다.
  2. 매 턴 돕니다. 이 자리에 프론티어 모델을 두면 잡무에 레이트리밋과 예산을 매 턴, 영원히 태웁니다.
  3. 그래서 지능은 필요한 곳에 씁니다. 비싼 모델은 코딩과 대화에만. 기계적인 기억 작업은 작고 빠른 모델에.

권장 인코더: 빠른 ~14–24B급 모델 — 당신 플랜에서 가장 싸면서 충분한 티어(아래 어떤 인코더를 쓸까 참고). /model-setting에서 설정 — 아래 설정하기 참고.

어떤 인코더를 쓸까

원칙: 이미 쓰는 플랜이 주는 가장 빠르고 싼 모델을 쓰세요. 인코더 때문에 두 번째 프로바이더나 별도 예산이 필요 없습니다 — 이미 결제 중인 경량 티어가 바로 그 자리입니다. 가진 구독에 맞추세요:

이미 가진 것 chat + subagent encoder
OpenAI / GPT GPT-5.5 GPT-5.4 mini
Claude (Anthropic) Opus 4.8 Haiku
Ollama Cloud 프론티어 모델 (예: GLM-5.2) Devstral Small 24B

크기 주의 한 가지. 인코더는 추론이 아니라 압축이지만, 기억은 충실히 담아야 하고 거기엔 바닥선이 있습니다. 여러 번 돌려본 결과 8B는 부족 — 기억 품질이 흔들립니다. ~14B 이상(≈14–24B가 스윗스팟)을 목표로 하세요. 구독에선 가장 낮은 티어로도 보통 충분하지만, 프로바이더가 아주 작은 모델까지 제공하는 경우(예: Ollama Cloud)엔 바닥을 찍지 말고 — 어느 정도 판단이 되는 14B+ 모델을 고르세요.

정직한 숫자

정직한 비교는 "더 싸다"가 아니라 "같은 기억을 들고도 더 싸다"입니다. 다른 에이전트의 비용 노브(/compact·/clear·슬라이딩 윈도우)는 전부 망각 노브이기도 합니다 — 컨텍스트를 버려서 싸지는 거죠. JLC는 기억하는 양을 비례해서 줄이지 않고도 비용을 묶는 유일한 구조입니다 — 그 망각이 무작정 잘라내기가 아니라 인코더가 큐레이션하기 때문입니다. 아래 숫자는 순진한 풀 리플레이 베이스라인 기준입니다; 실제 에이전트는 캐시와 컴팩션으로 완화하지만, 그건 JLC가 지키는 연속성을 잃어서 그런 겁니다.

전부 측정값이고, jlc-codec.org/evidence 의 공개 아티팩트로 재계산 가능합니다.

항목 숫자 출처
누적 prefill, 1,000턴 런 653K 토큰(JLC) vs 86.6M(풀리플레이) = ~99.2% 절감 1k-run/ + Zenodo 트랜스크립트(tiktoken 재계산)
들고 다니는 기억 크기 JHB ~2,000 토큰 평탄 유지(턴 늘어도 안 자람) meta.json, meter.paperlog
턴 8,757 연산 격차(10k 런) chat 58M vs 251,950M 풀리플레이 = ~4,346 : 1 /evidence HUD + meter.paperlog
전체 10k 런 실비(chat + encoder) ~$20/월 Ollama Cloud Pro 플랜의 주간 ~41% /evidence 사용량 미터
프롬프트 캐시 적중(JLC static head) 입력의 ~90% 캐시에서 chat_in_trace

안 이기는 경우 — 꼭 읽으세요

정직함이 핵심입니다. 당신의 AI가 반박할 수 있는 과장은 주장 안 하느니만 못합니다.

실전 기준. 웜 캐시로 ~15턴 미만이면 그냥 보통 채팅을 쓰세요 — 거기선 JLC가 돈을 안 아낍니다. ~15–20턴을 넘으면 앞서기 시작하고, 세션이 길수록 격차가 벌어집니다. 길게 가는 작업에 꺼내 쓰세요 — 큰 리팩터링, 며칠짜리 기능, /compact·/clear 안 하면 안 됐을 그런 일.

설정하기

모델 역할은 ~/.jarvis-code/config.yaml(단일 활성 설정 — providers.md)에 있습니다:

roles:
  chat:     openai/gpt-5.5          # 똑똑+비쌈 — 코딩 & 대화
  subagent: openai/gpt-5.5          # 툴 실행 서브태스크(chat로 기본값)
  encoder:  openai/gpt-5.4-mini     # 싸고+빠름 — 기억 압축, 매 턴
  router:   openai/gpt-5.4-mini     # 경량 의도 분류기(인코더 미러)

또는 에이전트 안에서 /model-setting으로 대화하듯 선택(chat/subagent/encoder; router는 인코더 자동 추종). OpenAI 호환 엔드포인트면 어떤 프로바이더든 됩니다 — providers.md.

다음: concepts.md (JHB·역할이 실제로 뭔지) · overview.md (큰 그림) · 증거 (위 전부 검증).

FAQ

직설적인 답변, 불리한 것까지 포함. 전체 숫자와 원시 로그는 jlc-codec.org/evidence 에.

두 모델? 더 비싸지, 더 싼 게 아니잖아?

짧은 대화면 살짝 — 맞습니다. 길게 가는 작업이면 아니고, 격차가 빠르게 벌어집니다. 비싼 chat 모델은 작고 고정된 컨텍스트만 보고, 싼 encoder가 매 턴의 기억 작업을 합니다 — 보통 에이전트가 비싼 모델한테 매 턴 시키는(트랜스크립트 재전송) 그 일을요. 메커니즘과 숫자: cost-model.md.

그래서 진짜 싸?

항상은 아니고 — 그런 척 안 합니다. 웜 캐시 짧은 세션(~10턴)이면 순정이 ~15% 쌀 수 있습니다. 손익분기는 15~20턴 부근; 그 뒤로 JLC가 앞서고, 긴/혼합 세션에서 ~2.5~3× 도달(모델 추정). 눈에 띄는 큰 비율(예: ~4,346:1)은 순수 연산량이지 달러가 아닙니다 — 캐시 할인이 돈 격차를 줄입니다. JLC는 길게 가는 작업용입니다.

무료/로컬 모델 써도 돼?

네. OpenAI 호환 엔드포인트면 다 됩니다(Ollama 로컬 모델 포함). 흔한 구성: chat에 프론티어, encoder에 작은 로컬/클라우드 모델. providers.md 참고.

API 키 필요해?

프로바이더에 따라 다릅니다. Claude 구독은 별도 API 키 없이 되고, 다른 프로바이더는 키를 씁니다. 첫 실행에서 설정합니다 — quickstart.md.

내 코드나 대화가 내가 모르는 데로 가?

기억(JHB·JARVIS.md)은 당신의 머신에 있습니다. 모델 호출은 당신이 설정한 프로바이더로 갑니다 — 다른 에이전트와 동일. 인코딩하는 sidecar는 로컬에서 돕니다(concepts.md).

phone-home 하거나 텔레메트리 보내?

아니요. 애널리틱스도, 사용량 추적도, 업데이트 체크도 없습니다 — JLC 서버로 핑을 보내지 않습니다(애초에 서버가 없습니다). 네트워크 호출은 당신이 설정한 LLM 프로바이더로만, 그리고 켜면 Brave Search로 갑니다. 유일한 예외는 설치 시 HuggingFace에서 임베딩 모델을 한 번 받는 것입니다(HuggingFace 자체 텔레메트리는 꺼둠). 메모리는 ~/.jarvis-code/에 평문 JSONL로 로컬 저장됩니다 — 잠긴 바이너리 DB가 아니라 읽고 옮길 수 있는 형태로.

인코더 모델 뭘 써야 해?

~14–24B급이 스윗스팟 — 예: ollama-cloud/devstral-small-2:24b. 인코더는 추론이 아니라 제한된 압축을 하므로, 작고 빠른 모델이 타협이 아니라 정답입니다. 단 너무 작게는 가지 마세요: 8B는 부족(기억 품질이 흔들림) — ~14B 이상을 목표로. cost-model.md 참고.

오프라인에서 돼?

에이전트와 기억은 로컬이지만, 모델 추론은 설정한 프로바이더가 필요합니다. 로컬 모델 서버(예: 로컬 Ollama)면 완전 오프라인으로 돌릴 수 있습니다.

10,000턴 런 진짜야?

네, 영수증까지 공개합니다: 턴별 원시 로그·최종 ~2KB 기억·무결성 해시·편집 없는 녹화 — jlc-codec.org/evidence. ~8,700턴에서 한 번 크래시했지만(JLC가 아니라 호스트 런타임 메모리 한계), 디스크 기억에서 복구해 완주했습니다. 크래시는 일부러 영상에 남겼습니다.

Claude Code / Cursor / Aider랑 뭐가 달라?

다 훌륭합니다 — 대화가 길어지기 전까진. 그것들은 트랜스크립트를 재전송(결국 컴팩트·클리어)해서 비용이 늘고 맥락이 버려집니다. JARVIS CODE는 기억을 윈도우 밖에 들고 가, 한 세션이 무한히 가고 재시작·모델 교체 후에도 이어집니다. statelessness를 숨기느냐 vs 그것에 맞춰 설계됐느냐의 차이입니다(overview.md).

단점은?

아직 어리고, 현재 Windows가 1급 설치(macOS/Linux 인스톨러는 곧), 짧은 일회성 대화는 돈을 안 아낍니다. 길게 가는 다중 세션 코딩 작업에서 빛납니다 — 대부분의 실제 작업이 그렇죠.

더 보기: overview.md · cost-model.md · troubleshooting.md · 증거