Heimdall의 에이전트 메모리 신뢰성 재설계

이 요약은 AI가 원문을 분석해 생성했습니다. 정확한 내용은 원문 기준으로 확인하세요.

TL;DR

Heimdall은 에이전트 메모리를 단순한 저장소가 아니라 실제 파일과 일치하는 검색 시스템으로 다루기 위해 v0.2.0에서 mutation path를 재설계했다. recursive fs.watch가 변경 가능성만 전달하고, 단일 writer reconciler가 디스크의 파일을 읽어 content hash와 generation counter를 기준으로 그래프를 수렴시킨다. 색인은 path·file·symbol·graph 깊이로 확장되며 Tree-sitter AST 파싱으로 정의와 호출 관계를 LLM tokens 없이 얻는다. Graft의 저장·랭킹 기능과 Graphify의 code-graph 추출 기능 위에 신뢰 검증과 최신화 계층을 두어, 에이전트가 오래된 경로가 아니라 재사용 가능한 코드 구조를 회수하도록 만든다.

주요 논점

01찬성소수

에이전트 메모리의 병목은 저장 용량보다 검색 결과가 실제 파일과 일치하는지 보장하는 retrieval과 trust에 있다는 입장이다. 단일 writer, 상태 기반 수렴, filesystem observation을 결합하면 경쟁 조건과 stale inference를 구조적으로 제거할 수 있다.

실용적 조언

여러 프로젝트에서 에이전트를 실행할 때는 command string을 변경 사실의 근거로 삼기보다 filesystem observation을 기준으로 두고, hook은 path hint만 전달하는 구조가 적합하다. 실제 파일 바이트를 읽어 desired graph state를 계산하면 git checkout, IDE 저장, 외부 스크립트처럼 hook 밖에서 발생한 변경도 같은 경로로 처리할 수 있다. 이 글의 구현에서는 content hash와 generation counter가 중복 갱신과 stale commit을 걸러낸다.
코드 메모리의 해상도가 필요하면 path 존재 여부에서 멈추지 않고 file, symbol, graph 단계로 색인을 확장할 수 있다. Tree-sitter가 설치되지 않은 환경에서는 file 단계로 동작하게 하고, 이후 parser가 준비되면 더 깊은 단계로 재색인하는 방식이 실패 대신 점진적 기능 저하를 만든다. AST에서 얻은 symbol과 edge는 LLM tokens를 소비하지 않으므로 context 예산과 구조화된 메모리 규모를 분리할 수 있다.

섹션별 상세

Heimdall의 기존 설계는 에이전트 세션을 감시하고 command string을 파싱해 변경 내용을 추론했지만, 여러 에이전트가 같은 파일을 수정할 때 writer serialization이 없어 duplicate node나 누락된 검색 결과가 생겼다. 프로세스마다 debounce timer가 따로 실행되어 여러 변경을 합치지 못했고, git checkout·스크립트·IDE 저장처럼 hook을 거치지 않는 변경도 놓쳤다. 파일 내용 자체를 확인하지 않아 의미가 바뀐 파일에 오래된 노드가 남는 문제도 있었다.

v0.2.0은 변경된 내용을 외부 입력으로 믿지 않고, recursive fs.watch가 경로 변경 가능성만 알린 뒤 단일 reconciler daemon이 디스크에서 실제 파일을 읽도록 바꿨다. 그래프를 쓰는 프로세스는 배타적 잠금으로 하나만 남기고, hook은 변경 설명 대신 path hint만 journal에 추가한다. content hash가 변경 기준이 되고 generation counter가 오래된 커밋을 거부하므로 reconcile 작업은 같은 입력에 반복해 실행해도 같은 상태로 수렴한다.

그래프의 색인은 path, file, symbol, graph의 네 단계 깊이를 제공한다. path에서는 파일 존재만 기록하고, file에서는 language·size·description을 더하며, symbol에서는 최상위 정의의 file:line과 signature를 추가하고, graph에서는 intra-file·cross-file import, call, inheritance edge까지 저장한다. 기본 깊이는 실행 시 확인한 시스템 능력의 최대치이며 Tree-sitter가 없으면 file 단계로 낮아졌다가 사용 가능해지면 더 깊게 재색인한다.

이 구조는 검색 결과의 정확도와 에이전트 context 사용량을 분리한다. Tree-sitter AST 파싱으로 symbol과 edge를 얻으면서 LLM tokens를 사용하지 않고, 검색 결과는 symbol match를 file-level hit으로 묶어 50배 많은 node도 agent context를 늘리지 않는다. 따라서 단순히 ATS 관련 파일이 있었다는 기억에서 벗어나, 해당 pipeline의 정확한 function과 호출 관계를 함께 회수하는 형태로 바뀐다.

저장 계층과 에이전트용 신뢰 계층을 분리한 점도 핵심이다. Graft는 Apache 2.0 기반으로 SQLite, local embeddings, graph edges를 사용한 storage·ranking engine을 맡고, Graphify는 MIT 라이선스의 per-repo code-graph extractor로 tree-sitter를 통해 29개 file extension을 처리한다. Heimdall은 이 위에서 session watching, graph freshness, filesystem re-verification, single-writer reconciliation을 담당해 저장된 기억이 실제 경로와 내용에서 벗어나지 않게 한다.

용어 해설

상태 기반 수렴(Level-Triggered Convergence): — 파일 변경 이벤트 자체를 해석해 다음 상태를 추측하는 대신, reconciler가 디스크의 현재 바이트를 읽고 그래프가 그 상태와 일치할 때까지 갱신하는 방식이다. 이벤트를 놓치거나 중복으로 받아도 최종 상태를 다시 계산하므로 경쟁 조건과 오래된 추론을 줄인다.
단일 작성자 조정기(Single-Writer Reconciler): — 여러 프로세스가 그래프를 동시에 수정하지 못하게 하나의 daemon만 쓰기 작업을 맡는 구조다. 배타적 잠금으로 단일 작성자를 강제하고, 다른 프로세스는 경로 힌트만 journal에 남긴다. 이후 daemon이 실제 파일을 읽어 그래프를 갱신한다.
콘텐츠 해시(Content Hash): — 파일 내용의 바이트에서 계산한 해시를 변경 여부를 판단하는 기준으로 사용하는 방식이다. 경로가 같아도 내용이 달라지면 해시가 달라져 재색인 대상이 되며, 같은 내용의 반복 이벤트는 불필요한 갱신을 피한다. 이 글에서는 generation counter와 함께 오래된 커밋을 거부하는 데 쓰인다.
Tree-sitter AST 파싱(Tree-sitter AST Parsing): — Tree-sitter가 소스 코드를 추상 구문 트리로 읽어 최상위 정의, 파일 내 위치, 함수 시그니처, import·call·inheritance 관계를 얻는 방식이다. Python bridge를 통해 처리하며 LLM 토큰을 사용하지 않는다. Tree-sitter가 없으면 file 깊이로 낮아지고, 다시 사용할 수 있게 되면 더 깊은 색인으로 전환된다.
하이브리드 검색(Hybrid Retrieval): — 키워드나 의미 임베딩만 단독으로 사용하지 않고 SQLite, local embeddings, graph edges를 결합해 관련 항목을 찾고 순위를 매기는 검색 방식이다. Graft는 이 저장·랭킹 역할을 맡고, Heimdall은 세션 감시와 신뢰 검증으로 검색 결과가 실제 파일과 맞는지 확인한다.

언급된 도구

Heimdall추천링크

여러 프로젝트의 AI coding agent를 위해 세션 감시, 그래프 최신화, filesystem 기반 신뢰 검증, single-writer reconciliation을 제공하는 계층이다.

Graft중립링크

SQLite, local embeddings, graph edges를 이용해 저장과 ranking, hybrid retrieval을 담당하는 engine이다.

Graphify중립링크

Tree-sitter를 사용해 저장소별 code graph를 추출하는 vendored library이며 29개 file extension을 처리한다.

언급된 리소스

GitHubGraft

GitHubGraphify

GitHubHeimdall