thecodacus/understory

understory — memory that grows. Self-wiring, plain-markdown memory for AI agents (MCP + local models + a living graph).

understory – LLM 에이전트를 위한 자가 배선 마크다운 지식 베이스

정의

에이전트가 읽고, 쓰고, 쿼리할 수 있는 가벼운 파일 기반 "메모리"입니다. 메모리는 Open Knowledge Format (OKF) v0.1 을 따르는 일반 마크다운 파일 모음으로 존재하며, 각 개념은 작은 YAML 프론트매터(type 등)를 가진 마크다운 파일입니다.
리포지토리에는 이 번들을 도구 호출 인터페이스(MCP) 로 래핑하는 서버, React 웹 UI, CLI 가 포함되어 있습니다. 서버는 로컬(Docker 또는 소스에서)로 실행할 수 있으며 OpenAI 호환 또는 Anthropic 호환 LLM 엔드포인트와 통신합니다.

핵심 아이디어

결정적 번들 레이어 – LLM 프롬프트가 아닌 코드가 모든 변경 사항이 유효한 OKF 번들(프론트매터 존재, 인덱스 파일 재생성, 로그 추가, 경로 샌드박싱)을 생성하도록 보장합니다.
에이전트 주도 업데이트 – LLM에게 무엇을 변경할지 요청하고, 서버가 변경 사항을 안전하게 적용합니다.
그래프 보기 및 추적 – 개념은 힘-방향 그래프(Obsidian 스타일)로 시각화되며, 모든 에이전트 상호 작용은 그래프에서 재생할 수 있는 추적으로 기록됩니다.
프로필 – 단일 서버에서 각각 자체 API 키로 선택되는 여러 개의 격리된 메모리를 호스팅할 수 있습니다.
유지 관리 도구 – memory_maintain은 그래프에서 고아 개념이나 끊어진 링크를 린트하고 내부 에이전트에게 수리를 요청합니다.

상호 작용 방법

인터페이스	기능
MCP 서버 (`/mcp` 또는 stdio)	`memory_query`, `memory_add`, `memory_update`, `memory_status`, `memory_maintain` 도구 세트를 제공합니다. 호출은 스트리밍되므로 LLM이 도구 결과를 실시간으로 볼 수 있습니다.
웹 UI (`http://localhost:3800`)	번들 트리 탐색, 라이브 그래프 보기, 업데이트 로그 보기, 동일한 에이전트와 채팅이 가능합니다. 도구 호출이 인라인으로 표시되며 추적을 재생할 수 있습니다.
CLI (`pnpm agent:query …`, `pnpm agent:mutate …`)	테스트 또는 스크립팅을 위한 빠른 명령줄 액세스.
프로필 CLI (`profiles create	list

빠른 시작 (Docker)

services:
  understory:
    image: ghcr.io/thecodacus/understory:latest
    ports: ["3800:3800"]
    extra_hosts: ["host.docker.internal:host-gateway"]
    volumes:
      - understory-memory:/bundle   # 마크다운 번들은 여기에 저장됩니다
    environment:
      BUNDLE_ROOT: /bundle
      LLM_API_BASE_URL: ${LLM_API_BASE_URL}
      LLM_API_KEY: ${LLM_API_KEY}
      LLM_API_FORMAT: openai   # 또는 "anthropic"
      LLM_MODEL: ${LLM_MODEL:-}

docker compose up -d   # UI: http://localhost:3800, MCP: http://localhost:3800/mcp

서버를 모든 OKF 번들(로컬 폴더, 명명된 볼륨 또는 바인드 마운트)로 지정할 수 있습니다. LLM 엔드포인트는 OpenAI, DeepSeek, Anthropic, Groq 또는 로컬에서 실행되는 llama.cpp 서버일 수 있습니다.

일반적인 워크플로우

세션 시작 – 서버가 현재 지식 베이스의 간결한 개요를 LLM의 시스템 프롬프트와 memory_query 도구 설명에 주입합니다.
에이전트에게 질문 – 예: memory_query "What is our deployment schedule?".
새 사실 추가 – memory_add "We deploy on Fridays, never Mondays". 에이전트가 마크다운 개념을 만들고 백링크를 업데이트하며 UI에 새 노드가 즉시 표시됩니다.
유지 관리 – memory_maintain을 정기적으로(또는 예약하여) 실행하여 고아와 끊어진 링크를 자동으로 수정합니다.
재생 – UI에서 추적을 열어 상호 작용 중에 읽고 쓴 개념을 정확히 확인합니다.

사용 이유

인간이 읽을 수 있고 버전 관리 가능 – 메모리는 일반 마크다운으로 저장되어 Git에서 diff할 수 있으므로 변경 사항을 감사하거나 롤백할 수 있습니다.
모델 비종속 – 도구 호출을 지원하는 모든 LLM에서 작동하며 서버가 무거운 작업을 처리합니다.
자체 구성 – 내부 에이전트가 그래프를 정리하여 지식 베이스가 성장함에 따라 드리프트를 줄입니다.
멀티 테넌트 – 프로필을 사용하여 동일한 호스트에서 별도의 지식 그래프(업무, 건강, 사이드 프로젝트)를 유지할 수 있습니다.

제한 사항 / 현재 범위

검색은 단순한 선형 스캔이며 수천 개의 개념까지 확장할 수 있지만 아직 전체 텍스트 인덱스나 임베딩 기반 검색은 아닙니다.
UI는 단일 페이지 React 앱이며 베어러 토큰 외에는 인증이 없습니다(LAN 사용만 권장).
그래프 수준 스키마(유형화된 엔티티, 더 풍부한 관계)는 계획되어 있지만 구현되지 않았습니다.

참여 방법

pnpm install && pnpm build로 소스에서 리포지토리를 실행하세요. 모노레포에는 core, server, web 패키지가 포함되어 있습니다.
테스트(pnpm test)는 번들 검증, 동시성, MCP 왕복을 다룹니다.
GitHub의 이슈/PR을 통해 기여하세요. 프로젝트는 MIT 라이선스이며 확장(FTS5/임베딩 검색, 사용자 지정 페이지 유형 스키마 등)을 환영합니다.

Understory를 사용하면 LLM 에이전트에게 일반 마크다운으로 존재하는 지속적이고 편집 가능하며 시각적인 지식 그래프를 제공할 수 있습니다. 독점 데이터베이스에 얽매이지 않고 "성장하는 메모리"를 구현합니다.

thecodacus/understory

understory – LLM 에이전트를 위한 자가 배선 마크다운 지식 베이스

관련