Metadata-Version: 2.4
Name: organum
Version: 0.0.1
Summary: Organism Engineering CLI — accumulate identity, differentiated memory, world models and maps for the agent you already use.
Author: Jihoon Jeong
License: MIT
Keywords: agent,memory,cli,organism-engineering,context
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# organum

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

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

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

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

## 설치

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

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

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

## 사용 스케치

```bash
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 랩](https://github.com/ludex-lab/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 (예정)
