Understanding Graph 이해하기: 지속적 이해를 위한 재귀적 매체

지속적이고 검사 가능한 이해를 위한 재귀적 매체.

Understanding Graph는 AI 에이전트에게 구조화되고 지속적인 메모리를 제공하는 MCP 서버입니다. 사실을 저장하는 지식 베이스와 달리, 외부에서 유용한 이해 업데이트—긴장, 놀라움, 결정, 증거, 그리고 신념이 시간에 따라 어떻게 진화했는지—를 저장합니다. 비공개 chain-of-thought를 요구하지 않습니다. 여러 에이전트가 그래프 자체를 통해 조정할 수 있습니다: 각 에이전트는 다른 에이전트가 작성한 내용을 읽고, 그 위에 구축하며, 다음 에이전트를 위해 검사 가능한 흔적을 남깁니다—stigmergy.

왜 Understanding Graph인가?

핵심 통찰: AI 에이전트는 사실을 기억하는 것만 필요한 것이 아니라, 사용 가능한 이전 상태, 전환의 증거, 업데이트된 결론, 그리고 남은 불확실성이 필요합니다. 그래야 이후 작업이 숨겨진 숙고를 재구성하지 않고도 결론을 시험하거나 수정할 수 있습니다.

Related MCP server: Loxo

빠른 시작

권장: Codex 또는 Claude 구독 사용

그래프 기반 작업이 이루어질 디렉터리에서 초기화 프로그램을 실행하세요:

cd your-project
npx -y understanding-graph@0.1.30 init

이것은 Codex와 Claude Code 모두를 위한 프로젝트 범위 MCP 구성을 생성하고, AGENTS.md와 CLAUDE.md에 동일한 유동적 이해 계약을 설치하며, 두 클라이언트 모두를 위한 프로젝트 범위 reading-mode 스킬을 설치하고, 스타터 그래프를 설치하지 않고 무시 규칙에 로컬 projects/ 경로를 추가합니다. 두 클라이언트 중 하나를 열고, 일반 ChatGPT 또는 Claude 구독으로 로그인한 후 실제 연구, 글쓰기, 코딩 또는 의사 결정 작업을 요청하세요. 에이전트는 실제 작업이 시작될 때 설명적인 이름의 그래프를 생성합니다. "그래프를 사용하세요"라고 말할 필요가 없습니다. 모델은 구독 클라이언트에서 실행됩니다; Understanding Graph 자체는 모델 API 호출을 하지 않습니다.

새로운 연대기적 읽기를 위해 에이전트에게 파일 경로를 주고 리더 모드를 켜도록 요청하세요. 에이전트는 본문을 반환하거나 샘플링하지 않고 소스를 스테이징한 다음, source_read를 통해 다음 순서의 구절만 만나며 계속하기 전에 일반적이고 구절에 근거한 이해를 첨부할 수 있습니다. Codex는 또한 $reading-mode를 노출합니다; Claude Code는 /reading-mode를 노출합니다. 채팅에 직접 붙여넣은 텍스트는 이미 만난 것이므로, 진정으로 새로운 읽기가 중요할 때는 파일 경로를 사용하세요.

Codex는 적격 ChatGPT 플랜을 통해 이용 가능하며, Claude Code는 Claude Pro 또는 Max를 사용할 수 있습니다. 일반 플랜 제한은 여전히 적용됩니다.

설치 가능한 플러그인 (워크플로 스킬 + MCP 서버)

패키지는 .codex-plugin과 .claude-plugin 매니페스트를 모두 제공합니다. 플러그인은 MCP 기능과 understanding-work 스킬을 결합합니다. 모드가 활성화된 동안, 작업이나 향후 문의에 중요할 수 있는 실질적이고 전달 가능한 이해가 그래프에서 발전합니다. 그래프는 상태에 따라 달라지는 작은 구체적인 다음 행동 세트를 굴립니다; 모델은 사용자 작업에 대한 가중치를 판단하고 자유롭게 선택, 결합, 변경 또는 거부합니다. 위의 초기화 프로그램은 플러그인 디렉터리 목록을 기다리지 않고 동일한 계약을 제공합니다.

Claude Code의 경우, 기존 마켓플레이스 흐름은 다음과 같습니다:

# One-time: add the Emergent Wisdom marketplace
claude plugin marketplace add emergent-wisdom/marketplace

# Install the plugin
claude plugin install understanding-graph

로컬 개발의 경우:

claude --plugin-dir /path/to/understanding-graph

이것은 MCP 서버와 다음 스킬을 제공합니다:

원시 MCP 서버는 호환되는 모든 클라이언트와 작동하지만, 번들된 스킬 또는 생성된 프로젝트 지침이 권장 경험입니다. 도구 스키마만으로는 다단계 이해 워크플로를 안정적으로 활성화하지 못합니다.

초기화 프로그램이 생성하는 것

다음을 생성합니다:

• .codex/config.toml -- Codex MCP 구성

• .mcp.json -- Claude Code 프로젝트 MCP 구성

• AGENTS.md 및 CLAUDE.md -- 동일한 표준 이해 워크플로

• .agents/skills/reading-mode/SKILL.md -- 명시적 Codex 리더 워크플로

• .claude/skills/reading-mode/SKILL.md -- 명시적 Claude Code 리더 워크플로

• projects/에 대한 .gitignore 항목 -- 그래프 데이터를 로컬로 유지; 스타터 프로젝트는 생성되지 않음

디렉터리에서 열린 모든 세션은 동일한 프로젝트 루트를 공유합니다. 명명된 그래프가 선택되면, 그곳에서 작업하는 에이전트는 그것을 공유합니다. 작업에 실제 독립적인 분기가 있을 때만 추가 에이전트를 사용하세요.

원시 MCP 구성 (고급)

클라이언트가 플러그인을 설치하거나 초기화 프로그램을 실행할 수 없는 경우, MCP 서버에 직접 연결하세요:

claude mcp add ug -- npx -y understanding-graph@0.1.30 mcp

MCP 초기화는 여전히 간결한 그래프 사용 계약을 제공하지만, 서버 지침에 대한 클라이언트 지원은 다양합니다. 일관된 동작을 위해 번들된 understanding-work 스킬 또는 생성된 프로젝트 지침도 제공하세요.

클라이언트별 설정 가이드: Claude Code · Claude Desktop · Cursor · mcporter

Claude Desktop

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "understanding-graph": {
      "command": "npx",
      "args": ["-y", "understanding-graph@0.1.30", "mcp"],
      "env": {
        "PROJECT_DIR": "/path/to/your/projects",
        "UG_SOURCE_ROOT": "/path/to/your/source-project"
      }
    }
  }
}

UG_SOURCE_ROOT는 파일 기반 소스 로딩을 해당 디렉터리로 제한합니다. 프로젝트 초기화 프로그램은 이를 프로젝트 루트로 자동 설정합니다.

Cursor / Windsurf

MCP 구성에 추가하세요:

{
  "mcpServers": {
    "understanding-graph": {
      "command": "npx",
      "args": ["-y", "understanding-graph@0.1.30", "mcp"],
      "env": {
        "PROJECT_DIR": "/path/to/your/projects"
      }
    }
  }
}

웹 UI / 3D 시각화

루트 npm 패키지는 빌드된 프론트엔드를 포함하고 웹 서버에 의존하므로, 게시된 패키지는 UI를 직접 실행할 수 있습니다:

PROJECT_DIR=/path/to/your/projects npx -y understanding-graph@0.1.30 start
# open http://localhost:3000

각 프로세스에 자체 포트와 프로젝트 저장소 루트를 지정하여 독립적인 사이드카를 실행하세요. 루트는 동일한 볼륨의 형제 디렉터리일 수 있습니다:

PORT=3101 PROJECT_DIR=/srv/undergraph/worker-1 npx -y understanding-graph@0.1.30 start
PORT=3102 PROJECT_DIR=/srv/undergraph/worker-2 npx -y understanding-graph@0.1.30 start

배포에서는 절대 경로를 사용하세요. 설치된 패키지와 읽기 전용 프론트엔드를 공유하는 것은 안전합니다; 독립적인 사이드카를 동일한 PROJECT_DIR에 지정하지 마세요.

서버는 기본적으로 루프백에 바인딩됩니다. 다른 호스트에서 워커를 실행하려면 HOST와 비공개 워커 토큰을 명시적으로 설정하세요; 둘 다 없으면 비루프백 시작은 안전하게 실패합니다:

HOST=0.0.0.0 PORT=3101 \
UG_WORKER_TOKEN=replace-with-a-long-random-secret \
PROJECT_DIR=/srv/undergraph/worker-1 \
npx -y understanding-graph@0.1.30 start

신뢰할 수 있는 호출자는 모든 /api 또는 /admin 요청에 Authorization: Bearer <UG_WORKER_TOKEN>을 보내야 합니다. 원격 트래픽은 TLS 또는 비공개 인증 네트워크 뒤에 두세요.

대신 체크아웃에서 UI를 개발하려면:

git clone https://github.com/emergent-wisdom/understanding-graph.git
cd understanding-graph
npm install
npm run build
npm run start:web
# open http://localhost:3000

선택 사항: 임베딩 기반 검색 활성화

graph_semantic_search, graph_similar, graph_semantic_gaps, graph_backfill_embeddings는 @huggingface/transformers(로컬 임베딩 모델, 컴파일 후 약 160 MB)를 사용할 수 있습니다. 기본 설치를 작게 유지하기 위해 선택적 peer dependency입니다. npx 기반 프로젝트의 경우, Node가 동일한 의존성 트리에서 peer를 해결할 수 있도록 두 패키지를 모두 로컬에 설치하세요:

npm install --save-dev understanding-graph@0.1.30 @huggingface/transformers@4.2.0
npx understanding-graph@0.1.30 init

별도의 전역 @huggingface/transformers 설치는 격리된 npx 캐시 설치를 안정적으로 충족하지 못합니다.

이것이 없어도 그래프의 나머지 부분은 정상적으로 작동합니다. graph_understand와 graph_semantic_search는 임베딩을 사용할 수 없을 때 결정적 어휘 검색을 사용합니다; 의미 전용 분석 도구는 선택적 모델이 필요할 때 설명합니다.

작동 방식

직접적인 개념 및 엣지 변형은 graph_batch를 통해 이루어집니다. 관련 워크플로 모드는 또한 최상위 수준에서 문서 헬퍼를 노출합니다; 관련 문서, 개념 및 엣지 변경이 함께 적용되어야 할 때 배치를 사용하세요. 모든 배치는 commit_message를 요구하며 SQLite 트랜잭션에서 실행됩니다: 어떤 작업이 실패하면 전체 배치는 실행되지 않은 것처럼 롤백됩니다. source_read와 같은 워크플로 도구는 자체 원자적 업데이트를 관리합니다. 일반 작업은 기록을 보존하면서 노드를 수정, 아카이브 또는 대체합니다; 되돌릴 수 없는 제거는 별도의 명시적으로 선택된 관리 작업입니다. 커밋 스트림은 검사 가능한 업데이트 로그가 됩니다—각 노드의 커밋 메시지는 Origin Story가 됩니다.

1. project_switch({ project: "my-project" })
2a. DIRECT: use graph_understand, graph_batch, or another graph tool immediately
2b. GUIDED: graph_suggest_next({ task, workflow: "coding" })
3. [if guided, judge, modify, reject, skip, or choose a sampled route]
4. graph_batch({ commit_message, agent_name, ... }) # preserve artifact + understanding

선택적 chooser는 이해를 심화하거나 다양화하고, 소홀히 된 자료를 회수하고, 현재 관점을 시험하거나, 유용한 연결을 노출할 수 있는 그래프 특정 포인터를 표면화하는 보조 도구입니다. 제안은 그래프 및 워크플로 가중 압력에서 서버 측에서 샘플링되며, 가능할 때 구체적인 노드 또는 영역을 포함하고, 최근에 제안된 작업 종류를 일시적으로 가중치를 낮춥니다. 모델은 작업 적합성에 대한 책임을 유지하며 항상 직접 작업하거나, 다른 일을 하거나, 작업을 만들어내기보다 중단할 수 있습니다. UG_GUIDANCE_MODE를 direct로 설정하여 주변 제안 프롬프트를 제거하세요; graph_suggest_next는 요청 시 계속 사용할 수 있습니다.

원자적 커밋

graph_batch는 개념 및 엣지 변경과 원자적 다단계 문서 변경을 위한 진입점입니다. 하나의 배치 안에서 graph_add_concept, graph_connect, graph_question, graph_supersede, doc_create 등을 연결할 수 있습니다. 사전 검증 검사는 graph_connect에 대해 ID와 제목 참조를 모두 허용하며, 전이적 도달 가능성을 계산합니다(따라서 A → B → existing 체인은 A가 existing에 직접 닿지 않더라도 유효합니다). 배치 중간에 실패하면 전체 트랜잭션이 롤백되며, 절반 상태는 남지 않습니다.

프로젝트 간 참조

한 프로젝트의 그래프 노드는 graph_add_reference({ refProject, refNodeId })를 통해 다른 프로젝트의 노드를 참조할 수 있습니다. 다른 프로젝트는 graph_lookup_external로 전환 없이 읽거나, graph_global_lookup으로 ID만으로 찾을 수 있습니다. 이것은 entangled-alignment 연대기 주석 파이프라인에서 사용되는 계층적 이해 그래프의 기반이며, 시대와 문서가 상호 참조를 그립니다.

핵심 개념

노드(이해 단위)

각 인지 노드는 트리거로 왜 생성되었는지를 표시하는 작성된 이해 업데이트를 포착합니다.

트리거는 인지 행위이지 범주가 아닙니다. 에이전트가 바로 이 순간에 노드를 생성한 이유를 포착하며, 그것이 어떤 종류의 것인지를 나타내지 않습니다. 가장 자주 사용하게 될 일곱 가지:

덜 일반적이지만 사용 가능: hypothesis, model, evaluation, analysis, experiment, serendipity, repetition, randomness, reference, library. 이러한 일반 인지 노드는 미래 에이전트가 작업에 다시 들어갈 때 도움이 될 경우, 확정된 결론뿐만 아니라 풍부하고 잠정적이며 해결되지 않은 증언을 보존할 수 있습니다. thinking 트리거는 다릅니다. 이는 별도의 합성 Reader/CMP 합성기를 위해 예약되어 있으며, 기본 그래프에서 연대기적 훈련 블록을 재구성합니다. 예약된 블록은 일반 읽기, 쓰기, 코딩 및 일반 워크플로우에 숨겨지고 불변입니다. 오직 TOOL_MODE=synthetic_reader만 접근할 수 있습니다. 의도적으로 선택된 18가지 트리거 유형 전체는 understanding-graph 논문(섹션 3.1)에 문서화되어 있습니다. 이는 주장된 형식적 최소값이 아니라 진화하는 설계입니다.

엣지(연결)

문서

구조화된 산문, 원본 자료, 그래프 네이티브 코드는 동일한 주소 지정 가능한 문서 트리를 공유합니다. 리프는 구절, 함수, 클래스, 타입 또는 테스트일 수 있으며, 각각 고유한 목적, 원본 커밋, 개정, 그리고 그것을 형성한 질문, 결정, 증거 또는 긴장에 대한 타입 링크를 기록합니다. 이를 통해 나중에 Reader는 doc_read({ nodeId, showProvenance: true, showRevisions: true })를 호출하여 파일이 존재하는 이유뿐만 아니라 정확히 하나의 단위가 존재하는 이유를 물을 수 있습니다.

implements는 추상적 약속에서 구체적 단위로 향합니다. expresses와 inspired_by는 아티팩트 단위에서 그것이 렌더링하는 것 또는 작성자가 영향력 있다고 보고한 것으로 향합니다. learned_from은 인지 업데이트에서 그것을 유발한 소스 또는 아티팩트 조우로 향합니다. 이들은 검증된 원인이 아니라 검사 가능한 작성된 주장입니다. 코드 루트는 실행 가능한 파일을 생성합니다. 단위는 재생성 전에 분할, 병합, 이동 및 재정렬될 수 있습니다.

프로젝트

다른 컨텍스트를 위한 격리된 그래프. 각 프로젝트는 자체 SQLite 데이터베이스를 가집니다.

도구 개요

배치 연산

개념 및 노드 관리(선택된 모드에 나열되지 않는 한 배치 연산)

연결 관리(선택된 모드에 나열되지 않는 한 배치 연산)

읽기 및 분석

합성 및 탐구

문서 연산(가용성은 워크플로우 모드에 따라 다름)

소스 읽기

프로젝트 관리

프로젝트 간

멀티 에이전트 조정 (Solver)

Claude Code 에이전트 팀과의 멀티 에이전트

Understanding Graph는 Claude Code 에이전트 팀을 위한 공유 영구 매체로 설계되었습니다. npx -y understanding-graph@0.1.30 init 실행 후, 리드는 이름이 지정된 그래프를 생성하거나 선택합니다. 해당 프로젝트 루트에서 작업하는 모든 팀원은 이를 공유할 수 있습니다 — 번들 데이터 없이 스티그머지(stigmergy) 방식입니다.

작동 방식

You: "Create an agent team to research and implement auth for this app"

Claude (Team Lead):
  ├── Researcher teammate   ─── reads/writes shared graph ───┐
  ├── Backend teammate       ─── reads/writes shared graph ───┤  Same Understanding Graph
  ├── Security teammate      ─── reads/writes shared graph ───┤  (via MCP)
  └── synthesizes findings from graph_history()               ┘

1. init은 모든 팀원에게 동일한 유동 프로토콜을 설치합니다 — 각 에이전트는 그래프를 표준 매체로 취급하며, 직접 작업하거나 자연스러운 선택 지점에서 graph_suggest_next에 구체적인 가능성을 요청할 수 있습니다.

2. 커밋 메시지가 조정 계층입니다 — 각 graph_batch에는 commit_message가 필요합니다. 보안 팀원이 "보안 에이전트: localStorage에서 JWT 발견 — 편의성과 XSS 위험 사이의 긴장"이라고 작성하면, 백엔드 팀원은 graph_history()를 통해 이를 확인하고 조치를 취합니다.

3. 트리거가 기여를 분류합니다 — 팀원들은 노드에 태그(tension, question, decision, surprise)를 지정하여 중요한 것을 쉽게 찾을 수 있게 합니다: "해결되지 않은 모든 긴장 표시" 또는 "아직 열려 있는 질문은?"

4. 필수 직접 메시징 없이 지속적인 인계 — 팀원들은 그래프 자체를 통해 조정할 수 있습니다. 연구자는 question 노드를 남기고, 백엔드 에이전트는 graph_find_by_trigger로 이를 찾아 answers 엣지를 생성합니다.

스웜으로 시작하기

cd your-project
npx -y understanding-graph@0.1.30 init     # one-time setup

그런 다음 Claude Code에서:

Create an agent team with 3 teammates to [your task].
Each teammate should work through the shared Understanding Graph,
preserve material understanding as it emerges, and use graph_batch
with descriptive commit messages so the team can coordinate.

장기 실행 조정 (solver 시스템)

단일 팀을 넘어 여러 세션에 걸친 작업이나 비동기 인계가 필요한 경우:

solver 시스템은 SQLite 데이터베이스에 유지되므로 작업이 세션 간에 유지됩니다. 한 팀이 위임한 작업을 향후 팀이 이어받을 수 있습니다.

아키텍처

packages/
  core/          # Graph logic, SQLite storage, embeddings
  mcp-server/    # MCP server (41 default / 69 full tools + batch operations)
  web-server/    # REST API + serves frontend
  frontend/      # 3D visualization (React + Three.js)

스택:

• SQLite + better-sqlite3 -- 영구 저장소

• Graphology -- 인메모리 그래프 연산

• MCP 프로토콜 -- 에이전트 통합

• Transformers.js -- 의미 검색을 위한 로컬 임베딩

개발

git clone https://github.com/emergent-wisdom/understanding-graph.git
cd understanding-graph
npm install
npm run build
npm run start:web    # Web UI at http://localhost:3000

개발 모드

# Terminal 1: Web server with hot reload
npm run dev:web

# Terminal 2: Frontend dev server
cd packages/frontend && npm run dev

환경 변수

작동 원칙

1. 그래프를 매체로 사용 — Understanding 모드가 활성화된 동안, 작업에 중요한 전달 가능한 이해와 주소 지정 가능한 아티팩트 단위를 보존하십시오. 단순한 최종 답변만이 아니라.

2. 모델에 주도권 유지 — graph_suggest_next는 선택적 지원이 유용할 때 가중치가 적용된 구체적인 자극을 제공합니다. 모델은 사용자의 작업에 따라 직접 작업하거나 이를 선택, 결합, 수정, 거부, 대체 또는 건너뛸 수 있습니다.

3. 작업을 변경할 수 있을 때 다시 진입 — 고정된 타이머나 의례가 아니라, 진정한 선택 지점, 예상치 못한 상황, 저항 또는 불확실성에서 축적된 그래프를 다시 방문하십시오.

4. 전사가 아닌 종합 — 입력을 복사하는 대신, 만남이 무엇을 변경했는지 보존하십시오. 해결되지 않은 함의와 긴장을 포함하여. PURE는 개방적 탐색 후 선택적 안정화 확인으로 사용할 수 있습니다. 이는 할당량이나 출현에 대한 게이트가 아닙니다.

5. 출처 보존 — 설명적 커밋, 전용 수정 및 대체 작업, 실제 아티팩트의 증거, 그리고 협업이 실제로 요구할 때 명시적 소유권 또는 인계를 사용하십시오.

sema와 함께 사용

Understanding Graph는 에이전트에게 공유 일화적 메모리를 제공합니다 — 결정 뒤에 기록된 해석적 추적입니다. Sema는 공유 의미적 메모리를 제공합니다 — 인지 패턴의 콘텐츠 주소 지정 어휘입니다. 이 둘은 결합됩니다:

# Add both to Claude Code
claude mcp add ug   -- npx -y understanding-graph@0.1.30 mcp
claude mcp add sema -- uvx --from semahash sema mcp

둘 다 설치된 상태에서 에이전트는 다음을 수행할 수 있습니다:

1. 노드의 understanding 또는 why 텍스트 내에서 sema 패턴 URI(예: sema://StateLock#7859)를 참조하여 조정 프리미티브의 의미를 고정합니다.

2. graph_semantic_search를 사용하여 현재 프로젝트에서 패턴을 참조하는 노드를 찾습니다. 검색이 여러 그래프에 걸쳐 있을 때는 프로젝트를 명시적으로 전환하거나 프로젝트 간 참조 도구를 사용하십시오.

3. sema_handshake를 호출하여 두 에이전트가 그래프에서 서로의 사고 위에 구축하기 전에 동일한 패턴 정의를 공유하는지 확인합니다 — 실패 시 폐쇄되는 핸드셰이크는 조용한 의미적 드리프트를 방지합니다.

전체 워크스루: sema와 함께 Understanding Graph 사용

그래프 내부에서 코딩

코드는 그래프 문서 루트와 그 순서가 지정된 자식 노드에 있습니다. doc_generate 또는 doc_generate_all로 실행 가능한 파일을 생성하고, 실제 빌드와 테스트를 실행한 다음, 소스 노드를 수정하거나 재배열하고 재생성하십시오 — 생성된 프로젝션을 직접 패치하지 마십시오.

전체 워크플로는 coding-inside-the-graph를 참조하십시오.

인용

@misc{westerberg2026understanding,
  title        = {Understanding Graph: A Recursive Medium for Persistent Understanding},
  author       = {Westerberg, Henrik},
  year         = {2026},
  month        = aug,
  publisher    = {Zenodo},
  doi          = {10.5281/zenodo.19462658},
  url          = {https://doi.org/10.5281/zenodo.19462658}
}

기계 판독 가능 버전은 CITATION.cff를 참조하십시오 (GitHub는 이를 통해 "이 저장소 인용" 버튼을 렌더링합니다).

라이선스

MIT -- LICENSE

GitHub: emergent-wisdom/understanding-graph npm: understanding-graph MCP 프로토콜: modelcontextprotocol.io