kg - AI 어시스턴트를 위한 로컬 지식 그래프

베타 - API는 아직 변경될 수 있으며 일부 버그가 예상됩니다.

kg는 AI 어시스턴트에게 로컬에 지식 그래프로 저장되는 영구적이고 구조화된 편집 가능한 프로젝트 메모리를 제공합니다.

문서 청크 검색에만 의존하는 대신, 아키텍처, 결정 사항, 장애, 규칙, 의존성, 워크플로우를 읽기 쉽고 검토 가능하며 Git 친화적인 그래프로 유지할 수 있습니다.

어시스턴트가 매번 처음부터 시작하지 않고 여러 세션에 걸쳐 기존 프로젝트를 이해하도록 하려면 이 도구를 사용하세요.

왜 사용해야 하나요

• 영구 메모리 — 대화 간 프로젝트 지식 유지

• 구조화, 모호하지 않음 — 노드, 엣지, 사실, 공백을 직접 검사

• 편집 및 검토 가능 — 읽기 쉬운 diff가 있는 *.kg 파일로 그래프 저장

• 로컬 우선 — 프로젝트 메모리가 Git 친화적 형식으로 내 머신에 유지

• MCP 클라이언트와 호환 — 로컬 stdio MCP 서버로 연결

Related MCP server: Agentic Memory Server

왜 RAG만으로는 부족한가

클래식 RAG는 문서에서 텍스트 청크를 검색하는 데 적합합니다.

kg-mcp는 다음과 같은 경우에 더 좋습니다:

• 반복적인 검색 대신 안정적인 프로젝트 메모리

• 명시적인 사실, 관계, 의존성

• 어시스턴트와의 실제 작업 중 그래프 업데이트

• 시간이 지남에 따라 검사, 버전 관리, diff, 개선할 수 있는 무언가

설치

crates.io에서

cargo install kg-cli

스크립트로

권장 설치:

curl -sSL https://raw.githubusercontent.com/nnar1o/kg/master/install.sh | sh

GitHub Releases에서 준비된 바이너리를 다운로드할 수도 있습니다.

kg-mcp를 AI 클라이언트에 연결

kg-mcp를 로컬 stdio MCP 서버로 추가하세요.

구성 예시:

{
  "mcpServers": {
    "kg": {
      "command": "/absolute/path/to/kg-mcp"
    }
  }
}

그 후:

1. AI 클라이언트를 재시작하고,

2. kg MCP 서버가 사용 가능한지 확인하고,

3. 아래 프롬프트를 사용하기 시작하세요.

전체 MCP 설정 및 참조: docs/mcp.md

SCL 빠른 시작

kg는 짧고 동사 우선인 영어 명령(SCL — Simple Command Language)을 이해합니다. 활성 그래프는 구성에서 자동으로 결정됩니다.

find "compressor defrost"
get concept:refrigerator
add concept:smart_fridge --name "Smart Fridge" --description "Connected refrigerator"
modify concept:smart_fridge --importance 0.9
remove concept:old_idea
connect process:compressor_control TRIGGERS process:auto_defrost
disconnect process:compressor_control TRIGGERS process:auto_defrost
list nodes
stats
use fridge
help

핵심 동사

ID

형식: <type>:snake_case — 예: concept:fridge, bug:door_seal, process:compressor_cycle.

관계

HAS USES STORED_IN TRIGGERS CREATED_BY AFFECTED_BY AVAILABLE_IN DOCUMENTED_IN DEPENDS_ON TRANSITIONS DECIDED_BY GOVERNED_BY READS_FROM

팁

• 플래그는 위치 인수 뒤에 옵니다. 여러 단어 값은 따옴표로 묶으세요.

• 명령을 ; 또는 새 줄로 구분하세요. #로 시작하는 줄은 주석입니다.

• 스크립트 내에서 use <graph>를 사용하여 그래프를 전환하세요.

• 표준 kg <graph> node find ... 명령도 대체 수단으로 계속 작동합니다.

• 전체 SCL 참조: docs/scl.md

그래프 생성

이것은 새 프로젝트의 첫 번째 워크플로우입니다: 문서에서 그래프를 만들거나 확장하도록 어시스턴트에게 요청하세요.

기본적으로 그래프는 ~/.kg/graphs에 *.kg 파일로 저장됩니다.

최소 프롬프트:

You are connected to kg-mcp.

Project graph name: payments

Build or extend this graph from the project documentation I provide.
Use `payments` as the graph name for all graph operations.

Only add facts grounded in source material.
If an important fact is missing and can be inferred safely from the provided docs, update the graph.
If something is ambiguous, ask or record it as a note instead of inventing facts.

문서가 포함된 예시 프롬프트:

Use kg-mcp to build or extend the `payments` graph from these documents:
- docs/payments/overview.md
- docs/payments/retries.md
- docs/payments/providers.md

Only add facts grounded in the documents.
If something is ambiguous, keep it out of the graph or record it as a note.
When you finish, summarize what was added, what remains unclear, and what document should be ingested next.

이 워크플로우에 대한 더 긴 프롬프트: docs/ai-prompt-graph-from-docs.md

바로 사용할 수 있는 저장소 예시의 경우, cargo run --bin repo-example을 실행하여 이 저장소에서 repo-example.kg을 생성하세요.

디렉토리 자동 그래프

kg는 기존 폴더를 자동으로 그래프로 변환할 수 있습니다. 디렉토리 트리를 스캔하고, 많은 일반적인 파일 유형을 인식하며, Rust, Java, JavaScript/TypeScript, Python, C/C++에 대한 심볼을 추출하고, 생성된 구조를 수동 그래프와 분리하여 유지합니다.

마크다운 유사 문서의 경우 섹션 내용이 포함된 문서(GDOC) 및 챕터(GSEC) 노드도 생성합니다.

모든 것을 수동으로 모델링하지 않고 코드베이스나 작업 공간의 유용한 맵을 빠르게 얻는 방법입니다. 생성된 인덱스는 로컬에 있으며, 새로 고칠 수 있고, git에서 무시해도 안전합니다.

예시:

cargo run --bin repo-example

이 명령은 이 저장소에서 로컬 데모로 repo-example.kg을 생성합니다.

그래프의 사실에 대해 어시스턴트에게 질문

그래프가 생성되면 일반적인 워크플로우는 어시스턴트에게 그래프를 검사하고 그래프에서 질문에 답하도록 요청하는 것입니다.

예시 프롬프트:

Use kg-mcp to inspect my existing `payments` graph.

I want to understand:
- how payment authorization works,
- what triggers retries,
- which external providers are involved,
- which datastore reads and writes are part of the flow.

If the graph is missing critical information, say exactly what is missing.

기타 유용한 질문:

• "payments 그래프에서 재시도를 제어하는 규칙은 무엇인가요?"

• "orders 데이터 저장소에 쓰는 시스템은 무엇인가요?"

• "이 그래프에서 누락되거나 약한 부분은 무엇인가요?"

• "인증 흐름을 설명하는 노드와 엣지는 무엇인가요?"

어시스턴트를 통해 사실 추가 또는 업데이트

작업 중에 어시스턴트에게 그래프를 개선하도록 요청할 수도 있습니다.

예시 프롬프트:

Use kg-mcp to review my existing `payments` graph.

Find:
- missing important nodes,
- weak descriptions,
- missing facts,
- suspicious or low-value edges.

Apply safe improvements where possible.
Only add facts grounded in the graph, the provided docs, or the current discussion.
If something is ambiguous, leave it out or add a note.

When you finish, summarize:
- what was wrong,
- what you changed,
- what still needs manual review.

이 방법은 기본 시스템 프롬프트나 프로젝트 프롬프트에 이미 어떤 그래프가 프로젝트에 속하는지 어시스턴트에게 알려주는 경우 가장 잘 작동합니다.

최소 프로젝트 수준 프롬프트:

You are connected to kg-mcp.
Project graph name: payments.
Use this graph for relevant reads and updates in this project.
If you notice important missing information that is grounded in the available docs or conversation context, update the graph as part of your work.
If uncertain, ask or add a note instead of inventing facts.

팁

프로젝트 구성 (.kg.toml)

kg는 현재 디렉토리와 상위 디렉토리에서 .kg.toml을 찾습니다.

예시:

backend = "json" # json backend writes native .kg files by default
graph_dir = ".kg/graphs"
graph_dirs = ["../shared-graphs", "../team-graphs"]
nudge = 20
user_short_uid = "dev_01"

[graphs]
payments = "graphs/payments.kg"

참고:

• backend = "json"이 기본값이며 .kg 텍스트 그래프를 선호합니다.

• backend = "redb"는 그래프를 .db 파일에 저장합니다.

• graph_dir은 기본 그래프 디렉토리를 설정합니다.

• graph_dirs는 kg list 및 그래프 결정에서 스캔하는 추가 디렉토리를 추가합니다.

그래프를 Git에 유지

기본 그래프 디렉토리는 ~/.kg/graphs입니다.

이 디렉토리를 git 아래에 둘 수 있습니다.

권장 접근 방식:

• 기본 *.kg 그래프 파일을 git에 유지,

• 생성된 사이드카 파일과 로컬 운영 파일은 무시,

• 백업 스냅샷과 이벤트 로그는 명시적으로 버전 관리하려는 경우가 아니면 로컬 머신 기록으로 취급.

제안된 .gitignore:

*.kglog
*.kgindex
*.event.log
*.migration.log
*.bak
*.bck.*.gz

실제로:

• *.kg는 일반적으로 검토하고 커밋하려는 기본 그래프 파일,

• *.kglog는 로컬 액세스/피드백 로그,

• *.kgindex는 생성된 로컬 인덱스,

• *.event.log는 로컬 추가 전용 변경 타임라인,

• *.bak는 마지막 쓰기의 이전 디스크 버전,

• *.bck.*.gz는 주기적인 압축 백업 스냅샷,

• *.migration.log는 이전 그래프가 변환될 때의 마이그레이션 보고서.

*.kg는 Git 친화적이며 여러 사람이 동일한 그래프에서 작업할 때 diff를 읽기 쉽고 병합을 더 쉽게 만들도록 의도적으로 구조화되어 있습니다.

그래프를 HTML로 내보내기

그래프의 대화형 HTML 뷰를 생성하려면:

kg graph payments export-html --output payments.html

생성된 HTML을 현재 그래프의 공유 가능한 시각적 스냅샷으로 유지할 수 있습니다.

문서

• docs/mcp.md - MCP 설정 및 도구 참조

• docs/ai-prompt-graph-from-docs.md - 문서 수집을 위한 더 긴 프롬프트

• docs/build-graph-from-docs.md - 문서에서 그래프 구축 워크플로우

• docs/troubleshooting.md - 일반적인 문제

연락처

질문이나 피드백: nnar10@proton.me