AtlasMemory: AI 에이전트를 위한 증거 기반 로컬 코드베이스 메모리 시스템

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

핵심 요약

Tree-sitter와 MCP를 활용해 AI 에이전트에게 코드베이스에 대한 영구적이고 증거 기반의 이해도를 제공하는 로컬 우선 신경 메모리 시스템이다.

배경

AI 에이전트가 새로운 세션마다 전체 코드베이스를 다시 읽으며 발생하는 막대한 토큰 낭비와 환각 문제를 해결하기 위해 AtlasMemory라는 로컬 지식 그래프 시스템을 개발하여 공유했다.

의미 / 영향

이 토론에서 RAG와 유사한 접근법을 코드베이스에 적용하여 AI 에이전트의 운영 비용을 획기적으로 낮출 수 있음이 확인됐다. 커뮤니티 합의는 단순한 텍스트 검색보다 AST 기반의 구조적 이해와 증거 앵커링이 AI의 신뢰도를 높이는 핵심 요소라는 점이다.

커뮤니티 반응

작성자가 직접 개발한 도구에 대해 상세한 벤치마크와 아키텍처를 공개하여 긍정적인 반응을 얻었으며, 특히 토큰 비용 절감 효과에 대한 관심이 높다.

주요 논점

01찬성다수

AI 에이전트의 고질적인 문제인 컨텍스트 폭발과 비용 문제를 로컬 지식 그래프로 해결할 수 있다.

합의점 vs 논쟁점

합의점

AI 에이전트가 매번 전체 파일을 읽는 것은 비효율적이며 구조화된 메모리 시스템이 필요하다.
MCP(Model Context Protocol)는 에이전트와 로컬 도구를 연결하는 효과적인 표준이다.

논쟁점

에이전트가 도구를 호출하지 않고 직접 파일을 읽으려는 습성을 제어하기 위해 별도의 프롬프트나 훅 설정이 강제되어야 한다.

실용적 조언

Claude Code 사용 시 .claude/settings.json에 PreToolUse 훅을 설정하여 세션 시작 시 handshake 호출을 자동화하라.
CLAUDE.md 파일에 AtlasMemory 사용 프로토콜을 명시하여 에이전트가 직접 파일 읽기 전 메모리를 먼저 확인하도록 유도하라.

섹션별 상세

AI 에이전트가 새 세션마다 전체 코드베이스를 다시 읽으며 발생하는 토큰 낭비 문제를 해결하고자 한다. 500개 파일 규모 프로젝트에서 아키텍처 파악에만 2.5만~5만 토큰이 소모되던 과정을 AtlasMemory의 handshake 도구로 2천~3천 토큰 수준으로 단축했다. 이는 전체 탐색 비용의 약 90-95%를 절감하는 효과를 가져온다.

Tree-sitter AST 파싱을 통해 코드의 심볼, 앵커, 임포트 그래프를 추출하고 SQLite 지식 그래프를 구축한다. 로컬 환경에서 작동하며 11개 프로그래밍 언어를 지원하여 AI 에이전트가 필요한 시점에 정확한 컨텍스트 팩을 MCP를 통해 제공받는다. 코드 원문의 SHA-256 해시를 사용하여 데이터의 무결성을 보장한다.

json

{
  "mcpServers": {
    "atlasmemory": {
      "command": "npx",
      "args": ["-y", "atlasmemory"]
    }
  }
}

Claude Desktop 또는 Claude Code에서 AtlasMemory MCP 서버를 설정하는 방법

AI의 모든 주장을 실제 코드 라인 범위와 연결하는 증거 앵커링 시스템을 도입했다. prove() 함수를 호출하면 특정 파일의 라인 범위와 해시값을 대조하여 AI의 판단이 최신 코드에 기반한 것인지 검증한다. 코드가 수정되어 해시가 일치하지 않으면 해당 정보는 즉시 'stale' 상태로 표시되어 환각을 방지한다.

코드 변경 전 영향 범위를 분석하는 Impact Analysis 기능을 제공한다. 특정 심볼을 수정하기 전 analyze_impact()를 호출하면 해당 심볼에 의존하는 파일과 흐름을 그래프 형태로 파악하여 위험도를 평가한다. 이를 통해 공유 코드를 수정할 때 발생할 수 있는 예기치 못한 오류를 사전에 방지할 수 있다.

json

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": ".*",
        "hook": "echo 'REMINDER: Did you call handshake first? Use search_repo before reading files directly. AtlasMemory has indexed this codebase — use it.'"
      }
    ]
  }
}

Claude Code 세션 시작 시 AtlasMemory 사용을 강제하는 훅 설정

실무 Takeaway

AtlasMemory는 AI 에이전트의 코드 탐색 단계에서 발생하는 토큰 소모를 최대 90-95%까지 절감한다.
모든 AI의 주장은 SHA-256 해시와 라인 범위로 연결된 증거 앵커를 통해 검증되어 환각 위험을 낮춘다.
로컬 우선(Local-first) 방식으로 설계되어 코드 데이터가 외부 클라우드로 유출되지 않고 사용자 장치 내에서만 처리된다.

언급된 도구

AtlasMemory추천링크

로컬 우선 AI 에이전트용 신경 메모리 시스템

Tree-sitter추천

증거 기반 인덱싱을 위한 AST 파서

언급된 리소스

GitHubAtlasMemory GitHub Repository

문서AtlasMemory npm Package

문서VS Code Marketplace - AtlasMemory