주요 콘텐츠로 건너뛰기
AI 튜토리얼

Graphicle로 코딩 에이전트를 위한 로컬 코드 그래프와 메모리 구축

Graphicle 설치, 코딩 에이전트 연결, 저장소 코드 그래프 구축, 인용된 컨텍스트 검색, 종속성 검사, 모델 구성, 프로젝트 지식을 로컬에서 최신 상태로 유지하는 방법을 알아봅니다.

약 11분 소요
Graphicle로 코딩 에이전트를 위한 로컬 코드 그래프와 메모리 구축

Graphicle이란?

Graphicle은 저장소 코드 그래프와 코딩 에이전트를 위한 프로젝트 메모리를 결합한 로컬 Rust 프로그램입니다. 파일, 함수, 클래스, 호출, 가져오기를 색인하는 동시에 문서, 결정 사항, 절차, 과거 에이전트 세션도 기억합니다.

에이전트나 개발자가 질문하면 Graphicle은 소스 파일과 줄 범위를 식별하는 인용된 발췌문을 반환합니다. 코드 그래프와 핵심 컨텍스트 도구는 API 키나 계정 없이 작동하며, 명시적으로 모델 또는 이를 필요로 하는 커넥터를 구성하지 않는 한 Graphicle은 어떤 데이터도 외부로 전송하지 않습니다.

Graphicle은 Claude Code, Cursor, Codex, VS Code, Claude Desktop 및 기타 MCP 클라이언트와 함께 사용할 수 있습니다. 명령줄 인터페이스, MCP 서버, 브라우저 앱, 단일 SQLite 기반 데이터 저장소를 제공합니다.

주요 기능

  • 코드 그래프: tree-sitter 기반 파서를 사용해 파일, 심볼, 호출, 가져오기, 경로 및 영향을 받는 코드를 탐색합니다.
  • 프로젝트 메모리: Markdown, PDF, Office 및 HTML 문서, 검토된 결정 사항, 절차, 캡처된 에이전트 세션을 검색합니다.
  • 인용된 컨텍스트: 모델을 호출하지 않고 토큰 예산 내에서 코드와 프로젝트 지식의 관련 발췌문을 가져옵니다.
  • 에이전트 통합: 한 번의 설정 명령으로 지원되는 코딩 에이전트를 MCP를 통해 연결합니다.
  • 코드와 연결된 메모리: 검토된 메모리를 해당 메모리가 설명하는 함수에 연결할 수 있으며, 코드가 변경되면 오래된 메모리로 표시됩니다.
  • 로컬 우선 운영: 데이터는 로컬에 저장되고 엔드포인트는 기본적으로 루프백에서 수신하며, Graphicle은 텔레메트리나 계정을 사용하지 않습니다.
  • 자동 동기화: 답변 전에 변경된 파일을 동기화하며, Git 훅을 사용하면 커밋, 병합, 체크아웃 후에도 동기화할 수 있습니다.

Graphicle 설치

Graphicle은 현재 macOS와 Linux를 지원합니다. macOS 또는 Homebrew가 설치된 Linux 시스템에서 가장 간단한 설치 방법은 다음과 같습니다.

brew install graphicle-ai/tap/graphicle

Homebrew를 사용할 수 없다면 릴리스 설치 프로그램을 사용하세요.

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

GitHub 릴리스 페이지에서 플랫폼별 아카이브를 다운로드할 수도 있습니다. 현재 Windows 네이티브 지원은 제공되지 않지만, README에 따르면 Linux 설치가 WSL2에서 작동할 수 있으며 아직 테스트되지는 않았습니다.

저장소 설정

에이전트가 이해할 수 있도록 하려는 저장소로 이동한 다음 설정을 실행하세요.

cd your-repo
graphicle setup

설정 과정에서는 저장소를 색인하고 코드 그래프를 구축하며, 시스템에서 찾은 코딩 에이전트를 연결합니다. 컴퓨터에 설치된 클라이언트에 따라 Claude Code, Codex, Cursor, VS Code, Claude Desktop 및 기타 MCP 클라이언트의 MCP 구성을 업데이트할 수 있습니다.

설정은 세션 캡처도 활성화하고, Claude Code 검색이 코드 그래프를 사용하도록 지정하며, AGENTS.md에 짧은 섹션을 추가하고, 프로젝트를 최신 상태로 유지하는 데 도움이 되는 Git 훅을 설치합니다. Graphicle은 변경하거나 생성하는 모든 파일을 나열하고, 수정하기 전에 백업을 만듭니다. 대화형 프롬프트 없이 설정을 실행하려면 다음을 사용하세요.

graphicle setup --yes

통합 변경 사항을 되돌리려면 다음을 실행하세요.

graphicle disconnect

disconnect 명령은 설정 과정에서 추가한 항목을 제거합니다. 저장소에 이미 존재하는 Graphify 출력 디렉터리는 삭제하지 않습니다.

터미널에서 질문하기

설정 후 graphicle ask를 사용해 저장소를 검색하세요.

graphicle ask "where is tax added to prices?"

Graphicle은 파일 이름, 줄 범위, 심볼 및 발췌문이 포함된 근거를 반환합니다. 결과는 다음과 같을 수 있습니다.

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이 작성된 답변을 추가하도록 하려면 Anthropic, OpenAI 또는 Ollama와 같은 지원되는 모델 제공업체를 구성하세요.

graphicle config set model anthropic

Ollama를 통한 로컬 모델과 OpenAI 호환 서버도 지원됩니다. 모델 설정은 구성 문서를 참조하세요.

에이전트와 Graphicle 사용

graphicle setup으로 MCP 클라이언트를 연결한 후 코딩 에이전트에게 저장소 관련 질문에 Graphicle을 사용하도록 요청하세요. 예를 들면 다음과 같습니다.

Graphicle을 사용해 실패한 요청이 재시도되는 위치를 찾아줘.

에이전트는 Graphicle의 코드 그래프 및 메모리 도구를 사용하고, 인용된 발췌문을 받은 다음, 그 결과를 자체 추론과 결합할 수 있습니다. Graphicle은 코드 그래프 도구와 메모리 도구가 포함된 하나의 MCP 서버를 제공합니다. 그래프 도구에는 query_graph, get_neighbors, shortest_path와 같은 이름이 포함됩니다.

그래프와 프로젝트 메모리 탐색

Graphicle의 브라우저 앱을 열려면 다음을 실행하세요.

graphicle open

이 앱에서는 코드 그래프, 소스 자료 및 프로젝트 메모리를 탐색할 수 있습니다. 제안된 메모리를 검토하고 승인하는 곳이기도 합니다.

설치 및 통합 상태를 확인하는 종합적인 상태 점검을 실행하려면 다음을 사용하세요.

graphicle doctor

에이전트가 연결되지 않거나 동기화가 완료되지 않은 것처럼 보일 때, 또는 구성된 환경을 확인하려 할 때 doctor를 사용하세요.

종속성과 영향을 받는 코드 탐색

Graphicle은 코드만으로 구성된 그래프를 구축하고 조회할 수 있습니다. 먼저 그래프를 추출하세요.

graphicle graph extract . --code-only

그런 다음 어떤 코드가 특정 심볼에 의존하는지 확인합니다:

graphicle graph affected "retry()"

graph 명령은 저장소를 검색하고, 심볼을 설명하고, 경로를 추적하며, 대화형 HTML 그래프를 내보낼 수 있습니다. --code-only 모드에는 모델이 필요하지 않습니다.

Graphicle은 프로젝트 문서에 언급된 코드와 해당 문서가 참조하는 정의를 연결할 수도 있습니다. 문서 연결 그래프 명령을 사용하여 이러한 관계를 나열합니다:

graphicle call graph.doc_links

답변 모델 없이 컨텍스트 가져오기

context 명령은 코드, 문서, 세션 및 검토된 메모리에서 관련 발췌문을 가져옵니다. 모델을 호출하지 않습니다:

graphicle context

여러 저장소가 포함된 작업 공간의 경우 작업 공간 전체에서 컨텍스트를 요청합니다:

graphicle context --workspace

이를 통해 한 저장소의 구현이 다른 저장소의 문서나 소스 코드에 의존하는 경우에도 Graphicle을 유용하게 사용할 수 있습니다. 작업 공간 MCP 구성은 MCP 문서에 설명되어 있습니다.

동기화 및 개인정보 보호 이해하기

동기화 중에 Graphicle은 .gitignore를 준수하며 환경 파일, 키, 자격 증명을 건너뜁니다. 세션 캡처는 <private>...</private> 범위 안의 콘텐츠를 제거하고 자격 증명을 마스킹합니다.

macOS에서 기본 로컬 데이터 폴더는 ~/Library/Application Support/Graphicle입니다. Linux에서는 ~/.local/share/graphicle입니다. graphicle graph extract로 생성한 그래프는 프로젝트 내부의 .graphicle/에 저장됩니다.

앱, HTTP 엔드포인트 및 MCP 엔드포인트는 기본적으로 127.0.0.1에서 수신 대기합니다. 네트워크 액세스는 구성된 모델이나 커넥터, 문서 또는 이미지를 LLM으로 전송하는 전체 그래프 추출, 일부 GitHub CLI 작업 또는 업데이트 피드처럼 네트워크가 필요한 기능을 요청할 때만 발생합니다.

고급 팁

답변을 근거에 기반하도록 유지하기

Graphicle의 인용된 발췌문을 사용하여 에이전트의 주장을 정확한 파일과 줄을 기준으로 확인하세요. 이는 디버깅, 익숙하지 않은 저장소 이해, 변경 사항 검토에 특히 유용합니다.

제안된 메모리 검토하기

에이전트가 제안한 메모리는 자동으로 신뢰할 수 있는 프로젝트 지식이 되지 않습니다. 승인하기 전에 앱에서 검토하세요. 코드 심볼에 연결된 메모리는 관련 코드가 변경되면 오래된 내용이 될 수 있지만, 같은 파일의 다른 부분을 편집해도 대개 최신 상태로 유지됩니다.

최신 컨텍스트에 Git 훅 사용하기

설정 중 설치된 훅을 유지하여 저장소를 동기화된 상태로 유지하세요. 훅은 커밋, 병합 및 체크아웃 후에 동기화하며, Graphicle은 답변 전에 변경된 파일도 동기화합니다.

저장소 한도 조정하기

기본적으로 프로젝트에는 최대 100,000개의 텍스트 파일과 1 GiB의 텍스트가 포함될 수 있습니다. 더 큰 저장소에서 작업하는 경우 구성에서 한도를 높일 수 있습니다. 매우 큰 파일은 동기화를 중단하는 대신 일부만 분석되거나 검색 가능한 텍스트로 보존될 수 있습니다.

다른 MCP 클라이언트 연결하기

Graphicle이 자동으로 감지하지 못하는 클라이언트의 경우 MCP 가이드에 설명된 간단한 JSON MCP 구성을 추가하세요. 동일한 MCP 서버가 그래프 및 메모리 기능을 모두 제공합니다.

결론

Graphicle은 코딩 에이전트에 저장소 구조와 프로젝트 지식을 로컬에서 검색할 수 있는 형태로 제공합니다. 설치한 후 graphicle setup을 실행하고 ask, context, open 및 graph를 사용하여 인용과 함께 코드를 조사하세요. 생성된 답변이 필요할 때만 모델을 구성하면 됩니다. 그래프, 동기화, MCP 서버, 세션 캡처 및 앱은 모델 없이도 작동할 수 있습니다.

자세한 내용은 프로젝트의 빠른 시작 가이드, 에이전트 가이드, 구성 참조 및 FAQ를 계속해서 확인하세요.