AlmanacCode/codealmanac

AI 에이전트가 관리하는 코드베이스를 위한 살아있는 위키(wiki). Almanac은 코드가 말할 수 없는 것들, 즉 결정 사항, 흐름(flows), 불변량(invariants), 주의 사항(gotchas), 그리고 시스템이 왜 현재와 같은 구조를 갖게 되었는지에 대한 이유를 기록합니다.

npx codealmanac
cd your-repo
almanac init
...

이것이 첫 번째 경로의 전부입니다: Almanac을 설치하고, 저장소(repo)를 위한 첫 번째 위키를 구축한 다음, 검색하고 읽습니다. 그 이후부터는 정기적으로 실행되는 almanac capture sweep이 Claude/Codex의 조용한 트랜스크립트(transcripts)를 캡처하며, 예약된 Garden 작업이 위키 그래프를 깔끔하게 유지합니다.

명시적인 설치를 선호하시나요?

npm install -g codealmanac
almanac

Node 20 또는 Node 22 이상의 버전이 필요합니다. npm 패키지명은 codealmanac이며, 명령어는 almanac와 alm입니다.

원하는 작업	실행 명령어
설치 및 가이드 설치 실행	npx codealmanac
...

AI 코딩 에이전트는 코드를 읽고 그것이 무엇을 하는지 설명할 수 있습니다. 하지만 그들은 보통 특정 구현이 왜 존재하는지, 이전에 무엇이 고장 났었는지, 어떤 불변량(invariants)이 중요한지, 또는 하나의 워크플로우(workflow)가 어떻게 여러 파일과 서비스를 가로지르는지는 복구할 수 없습니다.

Almanac은 에이전트에게 지속 가능한 프로젝트 메모리를 제공합니다:

원자적 페이지 (Atomic pages): 안정적인 개념, 흐름, 결정 또는 주의 사항(gotcha) 하나당 하나의 마크다운(markdown) 페이지를 생성합니다.
코드 인식 검색 (Code-aware search): 파일을 편집하기 전에 해당 파일이나 폴더를 언급하는 페이지를 찾습니다.
토픽 그래프 (Topic graph): 페이지들을 하나의 거대한 루트 지시 파일 대신 유향 비순환 그래프(DAG)로 구성합니다.
예약된 유지보수 (Scheduled maintenance): 조용한 AI 코딩 트랜스크립트를 흡수하고 주기적으로 위키 그래프를 가꿉니다(garden).
로컬 전용 저장소 (Local-only storage): 페이지는 저장소 내부의 .almanac/에 저장되며, 글로벌 레지스트리(global registry)는 ~/.almanac/ 아래에 유지됩니다.
Git 검토 가능한 출력 (Git-reviewed output): 위키 편집 사항은 다른 변경 사항과 마찬가지로 git status에 나타납니다.

your-repo/
|-- src/
|-- .almanac/
...

마크다운 페이지가 신뢰할 수 있는 단일 원천(source of truth)입니다. index.db는 쿼리(query) 명령에 사용되는 파생된 캐시(cache)입니다.

Almanac에는 두 가지 종류의 명령어가 있습니다:

쓰기 가능한 라이프사이클 명령어 (Write-capable lifecycle commands): init, capture, ingest, garden은 설정된 AI 제공자(AI provider)를 호출할 수 있습니다.
로컬 쿼리 및 조직 명령어 (Local query and organization commands): search, show, topics, tag

,health

,list

,jobs

, 그리고 ,automation

은 로컬 파일, SQLite, 또는 실행 기록 (run records) 상에서 작동합니다.

예약된 자동화 (Scheduled automation)는 almanac capture sweep 및 almanac garden을 실행합니다. sweep은 Claude와 Codex의 트랜스크립트 저장소 (transcript stores)를 스캔하며, 자동화가 활성화되기 이전의 트랜스크립트는 무시합니다. 또한 활성 트랜스크립트가 조용해질 때까지 기다린 후, 각 트랜스크립트를 .almanac/가 포함된 가장 가까운 리포지토리 (repo)에 매핑하고, 새로운 자료에 대해 일반적인 백그라운드 캡처 작업 (background capture jobs)을 시작합니다. Garden은 주기적으로 위키 그래프 (wiki graph)를 감사하고 개선합니다.

세션 내의 어떤 내용도 주목도 기준 (notability bar)을 충족하지 못하면 캡처 (Capture)는 아무것도 기록하지 않습니다. 아무런 결과가 없는 것 (Silence)도 유효한 결과입니다.

단독으로 almanac를 실행하면 설정 마법사 (setup wizard)가 열립니다. 이 마법사는 기본 에이전트/모델 (default agent/model)을 선택하고, 준비 상태를 확인하며, 예약된 캡처 및 Garden 자동화를 설치합니다. 또한 Almanac을 자동으로 업데이트할지 여부를 묻고, 선택 사항인 에이전트 가이드 (agent guides)를 추가합니다.

유용한 무인 설정 (unattended setup) 플래그:

almanac setup --yes
almanac setup --skip-automation
almanac setup --skip-guides
...

대화형 설정 (Interactive setup)은 예약된 자체 업데이트 (scheduled self-update)에 대해 질문하며 기본값은 'yes'입니다. 무인 설정은 프롬프트 없이 동일한 선택 사항을 적용하고 싶을 때 --auto-update를 사용합니다.

자동 커밋 (Auto-commit)은 선택 사항 (opt-in)입니다. --auto-commit이 없으면, 라이프사이클 실행 시 위키 변경 사항이 검토를 위해 워킹 트리 (working tree)에 남게 됩니다.

쓰기 권한이 필요한 명령어를 위해 Almanac이 사용할 제공자 (provider)를 선택하십시오:

# Claude
claude auth login --claudeai
# 또는:
...

Codex는 내장된 권장 기본값입니다. Claude는 번들로 제공되는 Claude Agent SDK를 사용하고, Codex는 codex app-server를 사용하며, Cursor는 현재 향후 작업 예정인 어댑터 (adapter)입니다. 쿼리 명령어 (Query commands)는 제공자 자격 증명 (provider credentials)이 필요하지 않습니다.

Almanac은 제공자 자격 증명을 절대 저장하지 않습니다. 인증 (Auth)은 각 제공자의 일반적인 로컬 자격 증명 저장소 (local credential store)에 유지됩니다. 사용자 설정은 ~/.almanac/config.toml에 저장되며, 프로젝트 기본값은 .almanac/config.toml에 저장될 수 있습니다.

명령 (Command)	목적 (Purpose)
almanac init	현재 저장소 (repo)를 위한 첫 번째 위키 (wiki)를 구축합니다.
almanac search "auth"	위키 페이지에 대한 전체 텍스트 검색 (Full-text search)을 수행합니다.
almanac search --mentions src/auth/	파일 또는 폴더를 참조하는 페이지를 찾습니다.
almanac show checkout-flow	하나의 페이지를 읽습니다.
almanac topics list	토픽 그래프 (topic graph)를 보여줍니다.
almanac tag <page> <topic...>	페이지에 토픽을 추가합니다.
almanac health	위키 그래프 (wiki graph)의 무결성을 확인합니다.
almanac capture <transcript>	세션 기록 (transcript)을 수동으로 흡수 (absorb)합니다.
almanac capture sweep --dry-run --json	예정된 캡처 (scheduled-capture) 후보를 미리 봅니다.
almanac ingest docs/adr.md	파일 또는 폴더를 위키로 흡수 (absorb)합니다.
almanac garden	위키 그래프를 감사 (audit)하고 개선합니다.
almanac jobs	로컬 백그라운드 실행 (background runs) 목록을 나열합니다.
almanac update	npm을 확인하고 최신 버전의 Almanac이 사용 가능한 경우 설치합니다.
almanac automation install --every 2h	예정된 캡처 (scheduled capture) 및 Garden을 설치하거나 조정합니다.
almanac automation install update --every 1d	예정된 Almanac 자체 업데이트 (self-update)를 설치합니다.
almanac doctor	설치, 프로바이더 (providers), 자동화 (automation) 및 위키 상태를 확인합니다.

쿼리 명령 (Query commands) 및 부착된 라이프사이클 실행 (lifecycle runs)은 기본적으로 조용하게(quiet) 실행됩니다. 검색 요약, 페이지 메타데이터 (metadata), 레지스트리 경로 (registry paths) 또는 라이브 에이전트 도구 활동 (live agent tool activity)과 같이 사람이 읽을 수 있는 컨텍스트가 필요한 경우 --verbose를 사용하세요. 모든 플래그(flag) 범위를 확인하려면 almanac <command> --help를 실행하세요.

기본적인 첫 번째 빌드는 컴팩트하게 유지됩니다:

almanac init
# 코드베이스 분석 중... (Analyzing codebase...) 보통 5-10분이 소요됩니다.
# init 완료: run_...
...

서브시스템 (subsystem)을 편집하기 전에

almanac search --mentions src/checkout/
almanac search "checkout timeout"
almanac show checkout-flow

로컬 명령을 통해 위키 페이지를 파이프 (Pipe) 처리하기

almanac search --topic flows --slugs | almanac show --stdin
almanac search --stale 90d | almanac tag --stdin needs-review

예정된 자동화 (scheduled automation) 조사하기

almanac automation status
almanac capture sweep --dry-run --json
almanac jobs

모든 저장소(repo)의 .almanac/README.md는

주목성 기준(notability bar), 즉 페이지를 생성할 가치가 있는 기준을 정의합니다. 기본값은 "미래의 에이전트(agent)에게 도움이 될 비자명한 지식(non-obvious knowledge)"입니다. 여기에는 연구가 필요했던 결정 사항, 실패를 통해 발견된 주의사항(gotchas), 여러 영역에 걸친 흐름(cross-cutting flows), 그리고 코드상으로는 보이지 않는 제약 사항(constraints) 등이 포함됩니다.

링크는 하나의 구문을 사용합니다:

[[checkout-flow]] # 페이지 링크
[[src/checkout/handler.ts]] # 파일 참조
[[src/checkout/]] # 폴더 참조
...

대부분의 위키(wiki) 변경 사항은 제자리 편집(edits in place)으로 이루어집니다. 페이지의 핵심 결정 사항이 뒤집히는 경우, 기존 페이지는 archived_at 및 superseded_by를 사용하여 아카이브(archive)할 수 있으며, 교체되는 페이지는 supersedes를 사용합니다.

페이지, 토픽(topics), 파일, 데이터베이스(database), 그리고 CLI 모델에 대한 내용은 Concepts 가이드를 읽어보시기 바랍니다.

각 저장소는 자체적인 .almanac/를 가집니다. ~/.almanac/registry.json에 있는 글로벌 레지스트리(global registry)는 머신 내의 모든 위키를 추적합니다.

almanac list
almanac search --wiki openalmanac "RLS"

.almanac/가 이미 커밋되어 있는 저장소를 클론(cloning)하면, 첫 번째 Almanac 명령 실행 시 자동으로 등록됩니다. 접근할 수 없는 레지스트리 항목은 글로벌 쿼리(global queries)를 실패하게 만드는 대신 건너뜁니다.

git clone https://github.com/AlmanacCode/codealmanac.git
cd codealmanac
npm install
...

코드베이스는 TypeScript로 작성되었으며, tsup으로 빌드되고, Vitest로 테스트되며, better-sqlite3를 기반으로 합니다. 릴리스(Release) 단계는 RELEASE.md에 명시되어 있습니다.

Almanac은 1.0 미만 버전입니다. 1.0 이전에는 중대한 변경 사항(Breaking changes)이 발생할 수 있으며, 이는 릴리스 노트(release notes)에 명시될 것입니다.

Apache License 2.0. LICENSE를 참조하십시오.