understory 🌱

자라나는 메모리.

에이전트 아래에 놓이는 계층: 스스로 연결되는 순수 마크다운 메모리. 에이전트가 학습하는 모든 사실은 마크다운 개념으로 정리되어 살아있는 지식 그래프로 상호 연결되며, 에이전트 스스로가 건강하게 유지합니다 — 검색 가능하고, diff 가능하며, 전적으로 당신의 것입니다. 로컬 모델에서도 훌륭하게 동작합니다.

번들은 Open Knowledge Format (OKF) v0.1 스펙을 따릅니다 — YAML frontmatter가 있는 순수 마크다운 파일로, 사람이 읽을 수 있고, git에서 diff가 가능하며, 도구 간에 이식 가능합니다.

세 가지 진입점, 하나의 에이전트:

• MCP 서버 — stdio 또는 streamable HTTP를 통한 memory_query / memory_add / memory_update / memory_status / memory_maintain 도구. 각 호출은 시스템 프롬프트에 OKF 스펙을 담은 내부 LLM 에이전트를 구동합니다.

• 웹 UI — 번들을 탐색하고(트리, 개념 뷰어, 업데이트 로그, 적합성 배지), 메모리를 Obsidian 스타일의 force-directed 그래프로 확인하며(드래그/팬/줌, 유형별 색상, 연결 수에 따른 크기, 고아 노드는 빨간 테두리, 클릭하여 열기), 같은 에이전트와 채팅하여 테스트할 수 있습니다. 도구 호출이 인라인으로 렌더링되어 작동하는 모습을 지켜볼 수 있습니다.

• 쿼리 경로 재생 — 모든 에이전트 실행(쿼리/변경/채팅)은 탐색 경로(검색 → 읽기 → 쓰기)를 간결한 표기법으로 기록하여 <bundle>/.traces/ 아래에 저장합니다. 그래프 뷰는 최근 실행을 나열하며, 하나를 선택하면 경로를 그래프 위의 번호가 매겨진 방향성 홉으로 재생합니다 — 방문한 개념은 테두리로, 검색 결과는 점선으로, 나머지는 흐리게 표시됩니다.

• CLI — pnpm agent:query "..." / pnpm agent:mutate "..." 스모크 엔트리.

설계 원칙: 적합성은 프롬프트가 아니라 코드로 강제됩니다. 결정론적 번들 계층은 frontmatter(type 필수)를 검증하고, index.md 파일을 재생성하며, log.md 항목을 추가하고(최신순, 스펙 §7), 모든 경로를 번들 루트로 샌드박싱합니다. LLM은 무엇을 변경할지 결정하고, 코드는 결과가 적합한 번들이 되도록 보장합니다.

빠른 시작 (Docker)

클론이 필요 없습니다 — 이미지는 공개되어 있습니다. 다음을 docker-compose.yml로 저장하세요:

services:
  understory:
    image: ghcr.io/thecodacus/understory:latest
    ports:
      - "3800:3800"
    # Lets the container reach a llama.cpp server running on the host via
    # http://host.docker.internal:8080/v1 (see "Local llama.cpp" below).
    extra_hosts:
      - "host.docker.internal:host-gateway"
    volumes:
      # Your memory lives here as plain markdown — a named volume, or point
      # a bind mount (e.g. ./my-memory:/bundle) at any OKF bundle.
      - 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
      LLM_MODEL: ${LLM_MODEL:-}
      # Optional fallback
      LLM_FALLBACK_API_BASE_URL: ${LLM_FALLBACK_API_BASE_URL:-}
      LLM_FALLBACK_API_KEY: ${LLM_FALLBACK_API_KEY:-}
      LLM_FALLBACK_API_FORMAT: ${LLM_FALLBACK_API_FORMAT:-openai}
      LLM_FALLBACK_MODEL: ${LLM_FALLBACK_MODEL:-}
    restart: unless-stopped

volumes:
  understory-memory:

docker compose up -d

제공자 선택

범용 제공자 시스템은 OpenAI 호환 또는 Anthropic 호환 API를 모두 지원합니다. LLM_API_BASE_URL + LLM_API_KEY + LLM_MODEL을 설정하고 LLM_PROVIDER는 설정하지 않은 채로 두세요.

DeepSeek:

LLM_API_BASE_URL=https://api.deepseek.com/v1 LLM_API_KEY=sk-... LLM_MODEL=deepseek-chat

OpenAI:

LLM_API_BASE_URL=https://api.openai.com/v1 LLM_API_KEY=sk-... LLM_MODEL=gpt-4o

Anthropic (Claude):

LLM_API_BASE_URL=https://api.anthropic.com/v1 LLM_API_KEY=sk-ant-... LLM_API_FORMAT=anthropic LLM_MODEL=claude-sonnet-5

Groq:

LLM_API_BASE_URL=https://api.groq.com/openai/v1 LLM_API_KEY=gsk_... LLM_MODEL=llama-3.3-70b-versatile

로컬 llama.cpp:

LLM_API_BASE_URL=http://host.docker.internal:8080/v1 LLM_MODEL=

understory가 Docker에서 실행될 때 localhost는 호스트가 아니라 컨테이너 자체입니다 — 따라서 호스트의 llama-server는 host.docker.internal로 접근합니다(위의 compose 파일은 이미 extra_hosts로 이를 매핑합니다). llama-server와 같은 머신에서 소스로 실행하는 경우 http://localhost:8080/v1을 사용하세요.

DeepSeek 폴백이 있는 로컬 llama.cpp:

LLM_API_BASE_URL=http://host.docker.internal:8080/v1 LLM_MODEL= \
LLM_FALLBACK_API_BASE_URL=https://api.deepseek.com/v1 LLM_FALLBACK_API_KEY=sk-... LLM_FALLBACK_MODEL=deepseek-chat

이전 LLM_PROVIDER + 제공자별 키 환경 변수도 여전히 동작하지만(하위 호환) 더 이상 사용되지 않습니다(deprecated).

그런 다음:

• 웹 UI → http://localhost:3800 — 메모리를 탐색하고, 그래프를 보고, 에이전트와 채팅하세요

• MCP 엔드포인트 → http://localhost:3800/mcp (streamable HTTP) — 모든 MCP 클라이언트에 등록하세요:

  claude mcp add --transport http ustory http://localhost:3800/mcp

• 이제 에이전트는 memory_query / memory_add / memory_update / memory_status / memory_maintain을 가지며, 모든 세션 시작 시 메모리의 시드 개요를 받습니다.

무언가를 가르쳐 보세요(memory_add: "우리는 금요일에 배포하고, 월요일에는 절대 하지 않습니다"), 그런 다음 그래프를 열고 개념이 스스로 연결되는 모습을 지켜보세요. Portainer로 배포하시나요? docker-compose.portainer.yml을 repository stack으로 사용하세요.

Related MCP server: Kremis

스택

pnpm 모노레포:

제공자는 LLM_API_BASE_URL, LLM_API_KEY, LLM_API_FORMAT(openai 또는 anthropic), LLM_MODEL을 통해 구성됩니다. 모든 OpenAI 호환 엔드포인트(DeepSeek, OpenAI, Groq, OpenRouter, llama.cpp 등)는 LLM_API_FORMAT=openai로 동작하며, Anthropic 호환 엔드포인트는 LLM_API_FORMAT=anthropic을 사용합니다. 선택적 폴백은 해당하는 LLM_FALLBACK_* 변수를 사용합니다.

llama.cpp

# on the inference box — --jinja enables OpenAI-style tool calling
llama-server -m model.gguf --jinja --host 0.0.0.0 --port 8080

# here — no model id needed, it's discovered for llama-server-like local endpoints
LLM_API_BASE_URL=http://inference-box:8080/v1 LLM_API_FORMAT=openai LLM_MODEL= \
BUNDLE_ROOT=./sample-bundle node packages/server/dist/index.js

llama-swap 뒤에서도 동작합니다: 디스커버리는 현재 로드된 모델을 우선하므로 쿼리가 수 분이 걸리는 모델 교체를 유발하지 않습니다. LLM_MODEL=로 특정 모델을 고정하세요.

소스에서 실행

pnpm install
pnpm build
cp .env.example .env   # add your API key

BUNDLE_ROOT=./sample-bundle \
LLM_API_BASE_URL=https://api.deepseek.com/v1 \
LLM_API_KEY=sk-... \
LLM_API_FORMAT=openai \
LLM_MODEL=deepseek-chat \
node packages/server/dist/index.js
# → http://localhost:3800  (web UI + /api + /mcp)

또는 컨테이너를 직접 빌드하세요: docker compose up --build(저장소의 docker-compose.yml은 소스에서 빌드하고 ./sample-bundle을 마운트합니다).

개발 모드(서버는 :3800, Vite HMR은 프록시와 함께 :5180):

BUNDLE_ROOT=./sample-bundle pnpm --filter @understory/server dev
pnpm --filter @understory/web dev

MCP 등록 (Claude Code / Desktop)

claude mcp add ustory \
  -e BUNDLE_ROOT=/path/to/your/bundle \
  -e LLM_API_BASE_URL=https://api.deepseek.com/v1 \
  -e LLM_API_KEY=sk-... \
  -e LLM_API_FORMAT=openai \
  -e LLM_MODEL=deepseek-chat \
  -- node /path/to/understory/packages/server/dist/mcp/stdio.js

또는 HTTP MCP 클라이언트를 http://host:3800/mcp로 지정하세요.

인증

기본적으로 서버는 열려 있습니다 — localhost나 신뢰할 수 있는 LAN에서는 문제없습니다. 다른 곳에 노출하기 전에 AUTH_TOKEN을 설정하세요:

AUTH_TOKEN=$(openssl rand -hex 24)

설정하면 /mcp와 /api는 Authorization: Bearer <token>을 요구합니다(웹 UI는 계속 접근 가능하며 토큰을 입력하라는 메시지를 표시합니다). 인증된 MCP 클라이언트는 헤더로 등록하세요:

claude mcp add --transport http ustory http://host:3800/mcp \
  --header "Authorization: Bearer <token>"

stdio 전송은 토큰이 필요 없습니다 — 클라이언트가 생성하는 로컬 프로세스이기 때문입니다.

시드 메모리

네 개의 도구 이름만 보는 클라이언트 LLM은 메모리를 확인해야 한다는 본능을 결코 얻지 못합니다. 따라서 세션 시작 시 서버는 모델에 도달하는 두 채널을 통해 지식 베이스의 내용(디렉토리, 유형 + 설명이 있는 개념, 최근 활동)에 대한 간결한 개요를 주입합니다:

1. MCP initialize instructions 필드(Claude 같은 클라이언트는 이를 시스템 프롬프트에 넣습니다), 그리고

2. memory_query 도구 설명 — 모든 도구 호출 클라이언트가 로드하는 범용 폴백.

시드는 새로운 세션마다 새로 생성됩니다. 장기 실행(stdio) 세션에서 memory_add / memory_update 후에는 도구 설명이 tools/list_changed를 통해 새로고침되어 세션이 자신의 쓰기를 볼 수 있습니다. 대역 외 편집(수동 편집, 다른 클라이언트)은 다음 세션에서 반영됩니다.

그래프 건강 & 유지보수

메모리는 메모 더미가 아니라 그래프이며, 그래프는 썩습니다: 개념이 고아가 되거나(아무것도 연결되지 않음) 링크가 끊어집니다. 두 가지 메커니즘이 이를 건강하게 유지합니다:

• 쓰기 시점 연결 — 새로운 지식은 속한 개념을 풍부하게 하거나(기존 엔티티의 속성은 별도로 정리되지 않고 패치됩니다), 별개의 엔티티인 경우 생성되고 그리고 관련 개념에서 역링크됩니다. 모순은 제자리에서 대체되며, 이전 값과 나란히 남겨지지 않습니다.

• memory_maintain — 결정론적 린트(graph 아래의 memory_status에 표시되는 고아 + 끊어진 링크)가 내부 에이전트를 구동하여 고아를 관련 개념에 연결하고 매달린 링크를 수정합니다. 드리프트에 대응하기 위해 주기적으로 실행하세요; 그래프가 이미 건강하면 아무 작업도 하지 않습니다.

이 설계는 Karpathy의 LLM Wiki의 패턴(index.md + log.md, 생성 대 강화, 고아 린트)을 반영합니다. 규모가 필요할 때까지 해당 패턴에서 연기된 것: 명시적 페이지 유형 스키마와 하이브리드 FTS5+임베딩 검색(search.ts의 단순 스캔은 수천 개 이하의 개념에서는 충분합니다).

테스트

pnpm test                                  # core: 18 tests (spec §5/§6/§7/§9, sandbox, search, concurrency)
pnpm --filter @understory/server exec tsx scripts/mcp-smoke.mts   # MCP stdio round-trip (needs SMOKE_BUNDLE + an API key)

환경

.env.example을 참조하세요. BUNDLE_ROOT는 필수이며, GIT_AUTOCOMMIT=true는 모든 변경을 커밋합니다.