📜 Litopys

AI를 위한 살아있는 연대기.

세션과 클라이언트 전반에 걸쳐 유지되는 지속적인 그래프 기반 메모리입니다. Claude Code, Claude Desktop 및 모든 MCP 호환 에이전트를 위해 구축되었습니다.

litopys-dev.github.io/litopys — 설치, 스크린샷 및 빠른 시작

🇺🇦 우크라이나어로 읽기

왜 Litopys인가요?

오늘날의 AI 에이전트용 메모리 시스템은 절충안을 강요합니다. 서브프로세스 누출과 약 500MB의 RAM을 점유하는 무거운 벡터 데이터베이스를 사용하거나, 수십 개의 노트를 넘어가면 확장성이 떨어지는 단순 마크다운 파일을 사용해야 합니다.

Litopys는 제3의 길을 택합니다: 일반 마크다운으로 저장되고, 가벼운 MCP 계층(약 75MB RAM)을 통해 제공되며, 직접 편집이 가능하고, 키워드와 구조 모두로 쿼리할 수 있는 유형화된 지식 그래프입니다. Litopys는 우크라이나어로 "연대기"를 의미합니다. 이는 AI의 메모리가 당신에 대해 무엇을, 언제, 왜 배웠는지에 대한 살아있는 기록이어야 한다는 철학을 담고 있습니다.

Related MCP server: auxly-memory-cli

주요 기능

• 🧠 유형화된 그래프 — 6가지 노드 유형(사람, 프로젝트, 시스템, 개념, 이벤트, 교훈)과 11가지 일급 관계

• 🔌 MCP 네이티브 — Claude Code, Claude Desktop, Cursor, Cline 또는 모든 MCP 클라이언트와 호환 (참조: docs/integrations)

• 📝 마크다운 우선 — 모든 노드는 YAML 프론트매터가 포함된 일반 .md 파일입니다. 직접 편집, grep 검색, git 버전 관리가 가능합니다.

• 🤖 모델 독립적 추출기 — Anthropic, OpenAI 또는 로컬 Ollama를 선택할 수 있습니다. 리소스/비용 예산에 맞춰 선택하세요(아래 리소스 점유율 참조). 사실 정보는 검토를 거치기 전까지 격리 상태로 유지됩니다.

• 🌐 웹 대시보드 — http://localhost:3999에서 그래프를 탐색, 검색, 편집, 시각화하고 격리된 항목을 검토할 수 있습니다.

• 🔐 로컬 유지 — 그래프는 파일 형태로 ~/.litopys/graph/에 저장되며, 서버는 기본적으로 127.0.0.1에 바인딩됩니다. 텔레메트리가 없습니다.

대시보드

스크린샷은 docs/screenshots/에 포함된 합성 데모 그래프를 기준으로 촬영되었으며, 작성자의 개인적인 메모가 아닙니다.

상태

v0.1.2가 출시되었습니다 — Linux / macOS / Windows(x64 + arm64)용 사전 빌드된 바이너리가 제공되며, install.sh를 통해 SHA-256 체크섬이 검증됩니다. v0.1.1 안정 버전 이후의 보안 릴리스입니다. CHANGELOG를 참조하세요. 공개 인터페이스(MCP 도구, CLI, JSON 내보내기 schemaVersion: 1, 디스크 내 마크다운 레이아웃)는 고정되었으며, 주요 변경 사항은 0.2.x로 배포될 예정입니다.

핵심 그래프, MCP 서버(5개 도구, stdio + HTTP/SSE), 추출기 + 격리소 + 주간 요약, 타이머 데몬, 대시보드(읽기 + 쓰기 + 그래프 시각화 + 격리 검토), 신원 확인 가드레일, 단일 바이너리 빌드, 한 줄 설치 프로그램, 클라이언트별 통합 문서가 모두 제공됩니다. 계획된 후속 작업은 다음 단계를 참조하세요.

리소스 점유율

작성자의 실제 설치 환경(Ubuntu, Bun 1.x) 기준 수치입니다. MCP 서버는 가볍지만, 추출기는 선택한 어댑터에 따라 비용이 발생합니다.

따라서 최소 상주 비용은 MCP 서버를 위한 약 75MB입니다. 추출은 선택 사항입니다. 에이전트에서 Litopys를 읽기/쓰기 전용으로만 사용하고 데몬을 시작하지 않을 수도 있습니다. 추출을 활성화하는 경우, 로컬 Ollama 방식은 RAM을 대가로 비용을 절감하고, Anthropic/OpenAI 방식은 RAM을 절약하는 대신 세션당 비용이 발생합니다. Ollama의 keep_alive 설정 덕분에 3B/7B 수치는 일시적이며, 틱이 완료된 후 몇 분 뒤 모델은 RAM에서 해제됩니다.

빠른 시작

한 줄 설치 (Linux / macOS):

curl -fsSL https://raw.githubusercontent.com/litopys-dev/litopys/main/install.sh | sh

이 명령은 약 100MB의 단일 바이너리를 ~/.local/bin/litopys에 다운로드하고, 필요한 하위 디렉터리와 함께 ~/.litopys/graph/를 초기화하며, MCP 등록 힌트를 출력합니다.

특정 버전을 고정하려면 파이프 뒤에 할당을 배치하세요. curl 앞에 설정된 환경 변수는 curl 자체에만 적용되며 파이프된 셸에는 적용되지 않습니다:

curl -fsSL https://raw.githubusercontent.com/litopys-dev/litopys/main/install.sh | LITOPYS_VERSION=v0.1.2 sh

그런 다음 클라이언트에 MCP 서버를 등록하세요:

# Claude Code
claude mcp add litopys -- ~/.local/bin/litopys mcp stdio

// Claude Desktop — ~/Library/Application Support/Claude/claude_desktop_config.json
{
  "mcpServers": {
    "litopys": {
      "command": "/home/you/.local/bin/litopys",
      "args": ["mcp", "stdio"]
    }
  }
}

클라이언트를 재시작하세요. litopys://startup-context 리소스는 새로운 세션마다 소유자 프로필, 활성 프로젝트, 최근 이벤트 및 주요 교훈을 자동으로 로드합니다. 에이전트는 5개의 MCP 도구(litopys_search, litopys_get, litopys_related, litopys_create, litopys_link)를 통해 읽고 씁니다.

전체 클라이언트별 레시피는 docs/integrations/에 있습니다 (Claude Code, Claude Desktop, Cursor, Cline, ChatGPT Connectors, Gemini).

원격 (HTTP/SSE) 모드

원격 클라이언트(Claude Desktop 커넥터, 브라우저 기반 MCP 호스트)의 경우:

LITOPYS_MCP_TOKEN=your-secret litopys mcp http
# listens on 127.0.0.1:7777 by default
# set LITOPYS_MCP_BIND_ADDR=0.0.0.0 + TLS proxy for remote exposure
# set LITOPYS_MCP_CORS_ORIGIN=https://your-client to enable CORS

개발 설치 (소스에서 빌드)

git clone https://github.com/litopys-dev/litopys.git
cd litopys
bun install
bun run build:binary       # produces dist/litopys

선택 사항 — 장기 실행 트랜스크립트를 위한 데몬

cp packages/daemon/systemd/litopys-daemon.{service,timer} ~/.config/systemd/user/
systemctl --user enable --now litopys-daemon.timer

선택 사항 — 웹 대시보드 자동 시작

대시보드(litopys viewer)를 systemd 사용자 서비스로 실행하여 재부팅 후에도 자동으로 시작되도록 할 수 있습니다.

litopys viewer install        # generates token, writes unit, enables service
litopys viewer install --lan  # same + binds to 0.0.0.0 for LAN access
systemctl --user status litopys-viewer

# Remove:
litopys viewer uninstall

액세스 토큰. viewer install은 무작위 토큰을 자동으로 생성하여 ~/.litopys/viewer.token에 저장합니다. 설치 출력에는 토큰이 포함된 바로 사용할 수 있는 URL이 표시됩니다:

✓ litopys-viewer installed

  Open dashboard:    http://localhost:3999/?token=<token>
  Share with others: http://192.168.1.x:3999/?token=<token>   # --lan only

  Opening the link once saves the token — no re-entry needed.
  Retrieve token later: cat ~/.litopys/viewer.token

해당 URL을 한 번 열면 토큰이 localStorage에 저장되어 이후에는 프롬프트가 표시되지 않습니다. 다른 사람과 쓰기 권한을 공유하려면 ?token=…이 포함된 URL을 보내세요. 토큰을 언제든지 검색하려면 cat ~/.litopys/viewer.token을 실행하세요.

GET 엔드포인트(탐색, 검색, 그래프 보기)는 항상 열려 있습니다. 변경 엔드포인트(노드 생성/편집/삭제, 격리소 수락/거부)는 토큰이 필요합니다.

또는 install.sh 실행 시 LITOPYS_ENABLE_VIEWER=1을 설정하여 한 줄 설치의 일부로 활성화할 수 있습니다. 로그아웃 후에도 대시보드를 유지하려면 loginctl enable-linger $USER가 필요합니다.

무결성 검사

litopys check           # human-readable report, grouped by error kind
litopys check --json    # { nodeCount, edgeCount, errorCount, errors[] } for CI

전체 그래프를 로드하고 해석한 다음, 깨진 참조, 중복 ID, 잘못된 유형의 관계, 구문/유효성 검사 실패를 표시합니다. 문제가 발견되면 0이 아닌 값을 반환하므로, git pre-push 훅이나 CI 단계에 추가하여 드리프트가 조용히 발생하는 것을 방지하세요.

그래프 백업

Litopys는 모든 것을 ~/.litopys/graph/에 일반 마크다운으로 저장하므로 파일 버전 관리가 가능한 모든 도구를 사용할 수 있습니다. 두 가지 일반적인 접근 방식은 다음과 같습니다:

Git + 비공개 원격 저장소 (증분 기록, 오프사이트, 무료):

cd ~/.litopys
git init
git add graph/ .gitignore README.md
git commit -m "baseline"
gh repo create my-litopys-graph --private --source=. --push

그 이후부터는 세션 종료 훅이나 수동 수락 시 작업 트리가 변경되므로, 주기적으로 git add -A && git commit -m "sync" && git push를 실행하여 백업을 최신 상태로 유지하세요. 그래프에는 개인적인 사실이 포함되어 있으므로 원격 저장소는 비공개로 유지하세요.

JSON 스냅샷 (이식성, diff 가능, 도구 친화적):

litopys export > graph.json              # compact
litopys export --pretty > graph.json     # indented, VCS-friendly
litopys export --no-body > meta.json     # metadata only, strip markdown bodies

덤프에는 meta(내보낸 시간, 개수, 스키마 버전)와 ID별로 정렬된 모든 노드, (from, relation, to)별로 정렬된 에지가 포함됩니다. 실행 간 결정론적이므로 diff graph-yesterday.json graph-today.json을 통해 LLM/데몬이 무엇을 추가했는지 정확히 알 수 있습니다. 분석 도구에 공급하거나, 호스트 간 마이그레이션하거나, 코드와 함께 커밋하세요.

새 호스트(또는 재설치 후)에서 스냅샷 복원:

litopys import graph.json --dry-run   # preview the plan
litopys import graph.json             # create new nodes, skip existing ones
litopys import graph.json --force     # also overwrite existing ids

기본값은 보수적이며 --force를 전달하지 않는 한 기존 노드는 건드리지 않습니다. 모든 노드는 사전에 스키마에 대해 유효성 검사를 거치므로 손상된 스냅샷은 디스크에 기록되기 전에 중단됩니다.

릴리스 기록

CHANGELOG.md를 참조하세요. 향후 작업은 실제 사용자의 피드백에 따라 결정됩니다. 불편한 점이 있으면 이슈를 열어주세요.

설계 원칙

• 에이전트 독립적. LLM 공급업체나 클라이언트에 대한 하드 의존성이 없습니다. MCP가 유일한 통합 지점입니다. Ollama가 기본 추출기이며, Anthropic/OpenAI는 선택적 어댑터입니다.

• 이식 가능한 데이터. 그래프는 디스크상에서 일반 마크다운 + YAML 프론트매터입니다. 모든 편집기에서 읽을 수 있고, git에서 버전 관리가 가능하며, 셸에서 grep 검색이 가능합니다.

• 가벼운 런타임. MCP 서버는 약 75MB RAM을 사용합니다. 추출기는 프로세스 외부에서 실행되며 모든 요청이 아닌 사용자가 설정한 일정에 따라 실행됩니다. 어댑터별 전체 비용 분석은 리소스 점유율을 참조하세요.

• 선택적 통합. 클라이언트별 도우미(훅, 설정 스니펫)는 docs/integrations/에 있으며, 이들 없이도 Litopys를 사용할 수 있습니다.

라이선스

MIT © 2026 Denis Blashchytsia 및 Litopys 기여자.