organum 0.0.1

Organism Engineering CLI — accumulate identity, differentiated memory, world models and maps for the agent you already use.

organum

⚠️ pre-1.0 — format unstable. .organum/ 상태 포맷은 v0이며 예고 없이 바뀔 수 있다. 포맷 동결 전까지 프로덕션 상태를 여기 맡기지 말 것. (스펙: docs/format-v0.md)

Organism Engineering CLI — 당신의 에이전트는 오늘도 유능했고, 내일이면 그걸 전부 잊는다. organum init 한 번이면 기억하고, 지도를 그리고, 자기를 돌보기 시작한다.

organum은 실무자가 이미 쓰고 있는 에이전트(Claude Code 등)에 기관(organ)을 입히는 도구다. 프로젝트-로컬 .organum/ 디렉터리에 정체성·분화된 기억·세계모델·지도를 축적하고, 에이전트의 컨텍스트에 주입하고, 돌봄 의례(회고/점검/백업)를 제공한다.

organum은 상태와 규율의 도구지, 에이전트가 아니다: 크리처도, 오케스트레이션도, 자체 LLM 호출도 없다. LLM이 필요한 작업(distill/reflect)은 사용자의 기존 CLI를 서브프로세스로 위임한다.

설치

pip install organum   # 아직 미출시 — 지금은 소스에서: pip install -e .

(구명 organon은 PyPI 점유로 2026-07-04 organum으로 개명 — 경위는 docs/journal.md.)

요구사항: Python 3.10+ · 외부 의존성 없음 (stdlib only)

사용 스케치

organum init                 # .organum/ 상태 디렉터리 생성
organum context              # [Self]+[Map]+[WM] 주입 블록을 stdout으로
                             #   → 시스템 프롬프트/CLAUDE.md에 붙이거나 훅으로 자동화
organum remember "..."       # 형성 맥락 태그와 함께 기억 저장 (guard가 저장 경계에서 필터)
organum recall --when 24h    # 시간창 질의: "지난 24시간 무슨 일이 있었나"
organum map                  # 리포 지도 (git ls-files로 시드 + frontier: 안 읽은 영역 = "?")
organum map frontier         # 지금 안 가본 곳 목록
organum distill              # 세션 로그 → 세계모델 (형태-우선 템플릿 강제, 신뢰도 태그)
organum reflect              # 세션 회고 → self.md carry-forward 갱신
organum checkup              # 상태 건강 점검
organum backup               # 오프-머신 스냅샷 (day 1 기능)

구현 상태 (P1): init · context · backup · restore 동작 (snapshot은 day 1 기능). 나머지는 P2.

왜 이 포맷인가

설계는 취향이 아니라 Ludex 랩의 pre-registered 실험에서 왔다 — 단, 현재 증거는 in-ecosystem causal evidence, one domain이며 "리포 지도가 코딩 에이전트를 돕는다"로의 전이는 P3 dogfood 스터디(사전등록)가 검증한다:

• 세계모델은 형태(form)로: prose 요약(정답 포함!)은 효과 0 (p=.79), 구조 지도+frontier는 탐험 해방 (exact-p=.0096, d=1.61). → distill은 map-shaped + frontier-explicit 출력을 강제한다. 판별 기준: "계획 없이 다음 행동으로 컴파일되는가?"
• 지도는 정적 시드가 공짜인 도메인에선 시드하라: self-built 지도도 유효하지만(Holm p=.029) oracle 대비 earning tax가 있다. 리포는 git ls-files로 턴1 완전 열거가 되므로 map은 GIVEN-MAP형(정적 시드) + frontier 마킹이다.
• 에러 폴백이 기억을 오염시킨다: 실사고 — "[Error: timed out]"이 영속 기억이 되어 이후 행동을 오염. → guard가 저장 지점에서 실패 산출물을 차단한다.

관련 작업

memory 도구는 많다 (Letta/mem0/Zep/MemGPT 계열). organum의 차별점은 분화(시간/공간/절차를 다른 경로로) · 형태-우선 세계모델 · frontier · 운영 규율의 동봉. 정면 비교 1페이지는 작성 중 (Ray 소유, P1 내 초안).

라이선스

MIT (예정)