Graphicle이 코딩 에이전트에 코드 그래프와 프로젝트 기억을 제공한다

Graphicle은 저장소의 코드 구조를 그래프로 만들고 문서·결정 사항·과거 에이전트 세션을 기억해, 코딩 에이전트에 파일과 줄 번호를 인용한 발췌문을 제공하는 Rust 프로그램이다. 사용자 컴퓨터에서 작동하며 API 키나 계정이 필요하지 않고 텔레메트리를 보내지 않는다고 소개한다. Claude Code, Cursor, Codex, VS Code, Claude Desktop과 다른 MCP 클라이언트에서 사용할 수 있다.

설치와 시작

macOS에서는 Homebrew로 설치한 뒤 저장소에서 설정을 실행한다.

brew install graphicle-ai/tap/graphicle
cd your-repo
graphicle setup

Homebrew가 없다면 다음 명령으로 설치할 수 있다. 릴리스 아카이브와 다른 설치 방법도 제공한다.

curl -fsSL https://github.com/graphicle-ai/graphicle/releases/latest/download/install.sh | sh

Windows용 네이티브 빌드는 아직 없다. WSL2에서는 리눅스 설치가 작동할 것으로 안내하지만, 아직 테스트하지 않았으며 네이티브 Windows 지원은 계획 중이다.

graphicle setup은 저장소를 색인하고 코드 그래프를 만든 뒤 발견한 코딩 에이전트를 연결한다. 세션 캡처를 켜고, Claude Code가 먼저 코드 그래프를 검색하도록 설정하며, AGENTS.md에 짧은 안내를 추가하고 Git 훅을 설치해 프로젝트를 최신 상태로 유지한다. 변경하는 파일을 모두 표시하고 각 파일의 백업을 먼저 만든다. 설정을 되돌리려면 graphicle disconnect를 실행한다.

에이전트에게 “실패한 요청을 어디서 재시도하는지 graphicle로 찾아줘”라고 물을 수 있다. 터미널에서 직접 질문하면 다음과 같이 출처가 붙은 발췌문을 받는다.

$ graphicle ask "where is tax added to prices?"
Evidence for "where is tax added to prices?"
4 excerpts · 598 of 3,000 tokens

[1] shop/pricing.py:1-7 price_with_tax()
 """Prices and tax."""
 TAX_RATE = 0.2

 def price_with_tax(price):
 """A price with the sales tax added."""
 return round(price * (1 + TAX_RATE), 2)

이는 첫 번째 발췌문 뒤를 생략한 실제 출력 예시다. 모델을 설정하지 않아도 ask는 근거를 보여준다. graphicle config set model anthropic을 실행하거나 openai, ollama를 지정하면 답변을 문장으로 생성할 수 있다.

Claude Code, Codex 또는 Cursor에 설치를 맡길 때는 다음 내용을 붙여 넣도록 안내한다.

Install Graphicle with `brew install graphicle-ai/tap/graphicle` (or, without Homebrew, `curl -fsSL https://github.com/graphicle-ai/graphicle/releases/latest/download/install.sh | sh`), then run `graphicle setup --yes` in this repository and list every file it changed.

주요 명령은 다음과 같다.

• 에이전트에 코드 그래프와 프로젝트 기억을 제공하려면 저장소에서 graphicle setup을 실행한다.
• 터미널에서 질문하려면 graphicle ask "how are failed requests retried?"를 실행한다.
• 그래프·출처·기억을 브라우저에서 보려면 graphicle open을 실행한다.
• 심볼 변경이 미치는 영향을 살펴보려면 graphicle graph extract . --code-only 다음에 graphicle graph affected "retry()"를 실행한다.
• 작동 상태를 확인하려면 graphicle doctor를, 설정을 모두 되돌리려면 graphicle disconnect를 실행한다.
• Graphify에서 옮기는 방법은 마이그레이션 안내에 있다. 팀 서버 설정은 팀 서버 문서를 참조한다.

기능과 작동 방식

Graphicle은 tree-sitter로 파일·함수·클래스·호출·임포트를 분석해 코드 그래프를 만든다. 이 과정에는 모델이 필요하지 않다. graphicle graph로 그래프를 검색하고 심볼을 설명하거나 경로를 추적할 수 있으며, 상호작용형 HTML 그래프를 내보낼 수도 있다. 코드만 추출한 뒤 graphicle graph affected "retry()"를 실행하면 해당 심볼에 의존하는 항목을 찾는다.

프로젝트 기억 기능은 Markdown·PDF·Office·HTML 문서, 검토가 끝난 결정 사항과 절차, 과거 Claude Code 및 Codex 세션을 코드와 함께 검색한다. graphicle context와 MCP 도구는 모델을 호출하지 않고 정해진 토큰 예산 안에서 출처가 표시된 발췌문을 반환한다. 에이전트가 그 발췌문을 읽고 답한다.

graphicle mcp는 코드 그래프 도구와 기억 도구를 하나의 MCP 서버로 제공한다. query_graph, get_neighbors, shortest_path 등 Graphify의 도구 이름을 사용한다. 검토된 기억은 관련 함수에 연결되며, 해당 코드가 바뀌면 오래된 기억으로 처리된다. 파일의 다른 부분만 수정하면 보통 기억은 계속 유효하다. 기억과 코드 심볼을 연결하는 규칙을 공개했다. 문서에서 코드가 언급되면 해당 정의와 연결되며 graphicle call graph.doc_links로 연결을 확인할 수 있다.

작업 공간의 여러 저장소를 아우르는 기억 검색은 graphicle context --workspace 또는 작업 공간 MCP 엔드포인트로 이용한다. 답변을 생성하기 전에는 바뀐 파일만 동기화한다. Git 훅은 커밋·병합·체크아웃 뒤에 동기화한다. 세션 캡처는 완료된 대화를 저장하고, 새 세션을 시작할 때 검토된 기억과 최근 대화를 제공한다. graphicle open은 그래프·출처·기억을 브라우저에 보여주며, 기억을 승인하는 곳이기도 하다.

작동 흐름은 세 단계다.

• 동기화할 때 .gitignore를 따르고 비밀정보를 건너뛰며, 각 출처의 버전이 지정된 사본을 보관하고 코드 그래프를 만든다.
• 에이전트가 도구를 호출하면 변경 내용을 동기화하고 코드·문서·세션·검토된 기억에서 발췌문을 순위화해 인용과 함께 반환한다. 도구 자체는 모델을 호출하지 않는다.
• 캡처한 세션은 검색 가능한 출처가 된다. 에이전트가 제안한 기억은 앱에서 승인할 때까지 반영되지 않는다.

Graphicle은 코드 그래프 도구와 기억 서버를 따로 설치하는 방식과 달리 한 번 설치하면 그래프·기억·MCP 서버·웹 앱·명령줄 도구를 제공한다. Python, Docker, 별도의 데이터베이스 서버 없이 하나의 SQLite 파일을 사용한다. 그래프 도구와 기억 서버를 따로 쓰면 도구마다 에이전트 설정이 필요하고 MCP 서버도 두 개를 별도로 구성하지만, Graphicle은 graphicle setup으로 발견한 에이전트를 연결하고 graphicle disconnect로 설정을 되돌린다. 코드 구조 분석과 문서·결정·과거 세션 검색이 한 프로그램 안에 들어 있다. 발췌문마다 파일과 줄 번호를 표시하며, 에이전트가 제안한 기억은 승인 절차를 거친다.

graphicle setup은 발견한 클라이언트에 MCP를 연결한다. 바꾸는 파일은 <file>.graphicle-bak으로 한 번 백업하며, graphicle disconnect는 추가한 설정을 제거한다.

성능·개인정보·조건

Graphicle이 공개한 속도 비교에서 Kubernetes 저장소(파일 31,000개)의 코드 전용 추출은 Graphicle 0.1.0 엔진에서 3분 18초, Graphify 0.9.88에서 26분 38초 걸렸다. 두 프로그램은 동일한 그래프를 만들었고, 같은 리눅스 호스트와 16개 CPU, 작업자 8개를 사용해 각각 한 번 탐색적으로 실행했다. Graphicle 0.1.0 엔진은 릴리스 소스를 바탕으로 한 리눅스 테스트 빌드다. Kubernetes 측정 기록을 공개했다.

더 이른 Django 비교에서는 사전 릴리스 빌드가 코드 전용 추출을 7.5초 만에 마쳤고, Graphify 0.9.77은 72.8초가 걸렸다. 같은 그래프를 만들었으며, 한 리눅스 호스트에서 작업자 8개로 번갈아 다섯 차례 실행한 중앙값이다. 10월 8일 측정 기록에 조건이 실려 있다.

기억 기능은 7개 기억 시스템과 비교했다. 점수를 매기기 전에 비교를 등록했고, 모든 시스템의 답변자와 평가자로 하나의 오픈 모델을 사용했다. Graphicle 사전 릴리스 빌드는 개발용 데이터 세트 세 개에서 다른 시스템보다 뒤처지지 않았다고 설명한다. 점수·방법·주의사항을 함께 공개했다.

Graphicle은 개인과 팀 모두를 위한 Apache-2.0 라이선스의 무료 오픈소스 프로그램이다. 팀용 상용판은 비공개 프리뷰 중이다. 기본 설정에서 프로젝트당 텍스트 파일은 최대 100,000개, 텍스트는 1GiB까지 처리하며 두 한도는 올릴 수 있다. 매우 큰 파일은 동기화를 중단하는 대신 일부만 분석하거나 검색 가능한 텍스트로 보관한다. 자세한 내용은 설정 문서의 한도 안내에 있다.

코드 그래프(--code-only), 동기화, context, MCP 서버, 세션 캡처와 앱은 API 키 없이 작동한다. graphicle ask의 문장형 답변 생성, 출처에서 기억 제안, 전체 graphicle graph extract에서 문서와 이미지를 읽는 기능에는 모델이 필요하다. Ollama의 로컬 모델이나 OpenAI 호환 서버를 쓸 수 있다. 모델 설정을 참조한다.

저장소·기억·코드 그래프는 macOS의 ~/Library/Application Support/Graphicle 또는 Linux의 ~/.local/share/graphicle에 있는 하나의 SQLite 저장소에 둔다. graphicle graph extract가 만드는 그래프 파일은 프로젝트의 .graphicle/에 저장한다. 앱과 HTTP·MCP 엔드포인트는 기본적으로 127.0.0.1에서 대기한다.

Graphicle은 계정이나 텔레메트리를 사용하지 않으며, 사용자가 요청할 때만 네트워크에 연결한다고 설명한다. 연결 대상은 사용자가 설정한 모델이나 커넥터, 전체 graphicle graph extract가 발견한 API 키에 해당하는 LLM(이때 문서와 이미지를 전송함), graphicle graph add·clone·그래프 서버의 풀 리퀘스트 도구에서 쓰는 GitHub CLI, 사용자가 지정한 피드로 graphicle update를 실행할 때다. 소스에서 빌드하면 파서 소스도 한 번 다운로드한다. 개인정보 처리 세부 내용을 공개했다.

동기화는 .gitignore를 따르고 .env 파일, 키, 자격 증명을 건너뛴다. 세션 캡처는 <private>…</private> 구간을 제외하고 자격 증명을 가린다. 기억이나 캡처 세션을 삭제하면 거기서 파생된 내용도 제거되며, 해시 체인 방식의 삭제 영수증을 제공한다.

Graphify와 라이선스

Graphicle의 코드 그래프 엔진은 Graphify를 Rust로 옮긴 것으로, Graphify 릴리스와 보조를 맞추고 파일 헤더와 NOTICE에 원저작자를 표시한다고 설명한다. 호환성 검사에서 기준으로 삼은 릴리스를 확인할 수 있다. 기억 기능과 기억 도구, 앱, 세션 캡처는 Graphify에 포함되지 않는다.

Graphify에서 전환할 때 graphicle setup은 저장소 전환을 제안하고 각 파일을 백업한다. 기존 graphify-out/은 삭제하지 않는다. 자세한 절차는 Graphify 이전 안내에 있다.

Graphicle은 Apache-2.0 라이선스로, 상업적 사용을 포함해 자유롭게 사용·수정·배포할 수 있다. 일부 제3자 구성 요소는 각자 라이선스를 유지하며, 관련 출처와 라이선스는 NOTICE, NOTICE.md와 licenses/ 폴더에 기록돼 있다. 코드 그래프 엔진은 사피 샴시(Safi Shamsi)와 Graphify 기여자들이 만든 Graphify를 바탕으로 했으며 Apache-2.0 라이선스를 따르고, 일부 부분은 MIT 라이선스로 제공된다.

문서에는 빠른 시작, 에이전트, MCP, 설치, 설정, 팀 서버, Graphify 이전, 벤치마크, FAQ, 문제 해결, 변경 기록이 있다. 상태 점검은 graphicle doctor로 할 수 있다.

소스 저장소는 프로그램(명령줄·앱·HTTP·MCP 서버)을 담은 crates/graphicle/, 코드 그래프 엔진인 crates/graphicle-graph/, 기억 라이브러리인 crates/graphicle-memory/로 구성된다. Python SDK와 TypeScript SDK, 팀 서버 배포 예시인 deploy/도 제공한다. 각 crate는 따로 빌드할 수 있으며 방법은 설치 문서에 있다.

기여는 Apache License 2.0에 따라 받으며, CLA는 필요하지 않다. 기여자는 Developer Certificate of Origin 서명을 위해 git commit -s를 사용해야 한다. 기여 안내를 참고하고, 보안 문제는 공개 이슈 대신 SECURITY.md의 절차로 신고한다. Graphicle은 KarLex AI가 만들었으며 저작권 표기는 Copyright 2026 KarLex AI, Inc.다.