Graph Memory

AI 코딩 에이전트를 위한 로컬 지식 그래프 메모리 — 모든 대화가 쿼리할 수 있는 단일 크로스 프로젝트 그래프로, 한 세션의 에이전트가 다른 모든 세션에서 캡처된 지식에 도달합니다.

로컬 지식 그래프 어시스턴스 시스템으로, 에이전트가 세션별로 메모리를 분리하는 기존 방식을 대체합니다. 지식 그래프 + PageRank 확산 검색을 통해 개념 간 연관을 구축하고, 에이전트가 하나의 세션에서 모든 프로젝트의 지식에 접근할 수 있게 합니다.

영문 요약: Graph Memory는 세션별 메모리를 단일 로컬 지식 그래프로 대체합니다. 검색은 의미적 최근접 이웃에서 시작해 자동으로 구축된 엣지를 따라 Personalized PageRank로 확산되며, 50% 의미론적 + 50% 그래프 확산 점수를 융합합니다. MCP를 통해 에이전트에 5가지 도구를 노출하고 Cytoscape.js 시각화를 제공합니다. 모든 것이 로컬에서 실행됩니다 — 임베딩은 로컬 sentence-transformers 모델, 그래프는 JSON 파일이며, LLM은 (선택적으로) 지식 추출에만 사용됩니다.

특징 / Features

• 그래프 연관 검색 — PageRank가 그래프를 따라 확산되어, 하나의 기술 포인트에서 관련된 배포 세부 사항, 교훈, 사용자 선호도를 탐색

• LLM 지식 추출 — 대화/기억에서 구조화된 지식 노드를 자동으로 추출

• 3단계 중복 제거 — MD5 → embedding 유사도 >0.85 → 새로 생성

• 메모리 수정 — 오래된 정보를 발견하면 기존 노드를 갱신

• MCP 연동 — MCP를 통해 각 에이전트에 5가지 도구를 자동 노출

• 시각화 — Cytoscape.js 다크 테마, 필터/CRUD 지원

• 로컬 실행 — 데이터가 로컬을 벗어나지 않으며, embedding 모델을 로컬에서 로드

시작하기

1. 설치

git clone https://github.com/yourname/graph-memory.git
cd graph-memory
pip install -e ".[mcp,dotenv]"

2. 설정

cp .env.example .env
# 编辑 .env 填入 LLM API key 和 base_url(检索/写入不需要 LLM,只有 extract 需要)

3. 실행

python -m graph_memory.server

http://127.0.0.1:9121/을 열어 시각화 인터페이스를 확인하세요.

첫 실행 시 embedding 모델을 다운로드합니다(기본값 BAAI/bge-base-zh-v1.5, 약 400MB). 이후에는 로컬에 캐시됩니다.

3a. 데모 데이터 (선택 사항)

처음 사용자 경험을 위해, 공용 기술 지식 샘플 세트를 주입하면 빈 프로젝트가 바로 사용 가능합니다:

python seed_demo.py

그런 다음 http://127.0.0.1:9121/에서 작은 그래프를 확인할 수 있습니다. 데모 데이터 초기화: data/graph.json과 data/embeddings.npz를 삭제한 후 서버를 다시 시작하세요.

3b. Docker 원클릭 실행

docker build -t graph-memory .
docker run -p 9121:9121 -v gm_data:/app/data -v gm_models:/root/.cache/huggingface graph-memory

4. 기존 메모리 가져오기

처음 사용할 때 Hermes / Claude Code / Codex에서 기존 메모리를 가져옵니다:

curl -X POST http://127.0.0.1:9121/api/import?source=all

Claude Code 세션 이력을 일괄 추출할 수도 있습니다:

curl -X POST http://127.0.0.1:9121/api/extract/sessions

가져오기 경로는 환경 변수(HERMES_HOME / CLAUDE_HOME / CODEX_HOME)로 재정의할 수 있으며, 기본값은 각 에이전트가 사용자 홈 디렉터리 아래의 표준 위치를 가리킵니다.

에이전트에서 사용

MCP 서버 (자동 제공)

에이전트의 MCP 설정에 graph-memory MCP 서버를 추가하고 다시 시작하면 5가지 도구가 자동으로 제공됩니다:

에이전트는 대화 중 이 도구를 직접 호출할 수 있으며, 수동 조작이 필요 없습니다.

MCP 서버는 stdio를 통해 실행되며 HTTP 클라이언트로 FastAPI 백엔드에 프록시 역할을 합니다. 자체적으로 모델을 로드하지 않으므로 백엔드와 서로 다른 그래프 데이터를 보유하지 않아 일관성을 유지합니다.

Skill (에이전트 지침)

SKILL.md은 에이전트에게 사용 안내를 제공합니다. 에이전트가 로드한 후 다음 규칙을 따릅니다:

• 답변 전에 먼저 그래프 메모리 검색

• 답변 후 가치 있는 새 지식을 추출하여 기록

• 오래된 정보를 발견하면 적극적으로 갱신

사용 방법

방법 1: 에이전트와 직접 대화

"그서버의 추론 프로젝트 알려줘"

에이전트가 자동으로 retrieve을 호출해 관련 지식을 검색하고, 프로젝트 경로/포트/브랜치 정보를 얻은 뒤 답변합니다.

방법 2: 에이전트가 새 지식을 기억

"기억해, vLLM 0.25에서 speculative decoding을 지원해졌어"

에이전트가 write을 호출해 지식 그래프에 기록하고, 기존 노드와 자동으로 연결합니다.

방법 3: 오래된 정보 수정

"이서버의 포트가 8000이 아니라 바뀌었어"

에이전트가 update으로 기존 노드를 갱신합니다.

방법 4: 시각적 탐색

http://127.0.0.1:9121/을 열어 검색, 필터링, 조회/추가/수정/삭제를 수행합니다.

아키텍처

┌──────────────────────────────────────────┐
│  Agent (Hermes / Claude Code / ...)       │
│  ┌─────────────┐  ┌──────────────────┐   │
│  │ MCP Client  │  │ Skill (指导)     │   │
│  └──────┬──────┘  └──────────────────┘   │
│         │ stdio                           │
│  ┌──────▼──────┐                          │
│  │ MCP Server  │  (轻量, 不加载模型)       │
│  │ mcp_server  │                          │
│  └──────┬──────┘                          │
└─────────┼─────────────────────────────────┘
          │ HTTP
┌─────────▼─────────────────────────────────┐
│  FastAPI Server (port 9121)              │
│  ┌───────────┐  ┌──────────┐  ┌────────┐ │
│  │ GraphEngine│  │ LLM提取  │  │ 导入器 │ │
│  │ NetworkX  │  │ OpenAI   │  │        │ │
│  │ PageRank  │  │ 兼容API  │  └────────┘ │
│  │ bge embed │  └──────────┘              │
│  └───────────┘                            │
│       │                                   │
│  ┌────▼────┐  ┌────────────┐              │
│  │ graph   │  │ embeddings │              │
│  │ .json   │  │ .npz       │              │
│  └─────────┘  └────────────┘              │
└─────────────────────────────────────────────┘

MCP 서버는 경량 HTTP 클라이언트로 embedding 모델을 로드하지 않습니다. 모든 계산은 FastAPI 서버에서 수행되어, 두 프로세스가 각각 엔진을 보유하는 일이 없으므로 데이터 불일치를 방지합니다.

API

벤치마크

python benchmark.py

30문제 × 3라운드 × LLM 점수로 "MEMORY.md 만 사용" vs "그래프 메모리 추가"의 답변 품질을 비교합니다.

문제 세트는 사용자의 지식 기반에 맞게 직접 사용자 지정해야 합니다(bencharmark.py 상단 주석 참고). 검색 동작 자체의 회귀 테스트는 regression.py(불립 함수 기반 스냅샷 비교, LLM 의존 안 함) 사용합니다:

python regression.py snapshot baseline      # 改代码前
python regression.py snapshot after-change  # 改代码后
python regression.py compare baseline after-change

테스트

pip install -e ".[test]"
pytest tests/ -q

엔진 계층 테스트는 결정론적 fake embedder를 사용하여 실제 모델을 다운로드하지 않으므로 오프라인에서 실행할 수 있습니다.

지식 관리 (비대 방지)

일상적인 사용이 오래면 그래프가 비대해집니다. 주기적으로 관리 도구를 실행하세요:

python manage.py status        # 查看图健康状态
python manage.py dedup         # 扫描重复节点报告
python manage.py merge          # 合并相似节点(embedding >0.85)
python manage.py prune --dry-run   # 预览孤立+过时节点
python manage.py prune              # 执行清理

정리 규칙:

• 차수 < 2이고 90일 동안 업데이트되지 않은 노드가 삭제됩니다 (관련 관계 유지)

• 유사한 노드를 병합할 때는 더 길거나 자세한 내용을 보존

• 모든 작업은 --dry-run 미리보기 지원

설정

라이선스

MIT