Ephemeral-AI-Lab/layerfs

LayerFS – AI 에이전트 워크스페이스를 위한 SQLite 백엔드, 콘텐츠 주소 지정 "타임머신"

정의

• AI 에이전트(또는 파일시스템을 다루는 모든 도구)가 임시 워크스페이스 내에서 작업할 수 있게 하는 라이브러리, CLI 및 FUSE 기반 파일시스템.
• 에이전트가 단계를 완료하면 워크스페이스를 커밋하여 전체 파일시스템 스냅샷을 불변 커밋으로 전환할 수 있습니다.
• 커밋은 LayerStack에 저장됩니다. 이는 세 가지 고전적인 기술을 사용하여 서로 위에 쌓인 레이어의 기록입니다.
  1. 콘텐츠 주소 지정 저장소 (CAS) – 객체는 바이트의 해시로 이름이 지정되므로 동일한 데이터는 한 번만 저장됩니다.
  2. 콘텐츠 정의 청킹 (CDC) – 파일은 안정적인 청크로 분할됩니다. 작은 편집은 새 청크만 생성하고 파일 전체의 새 복사본은 생성하지 않습니다.
  3. 쓰기 시 복사 (COW) – 새 레이어가 게시될 때 변경된 디렉터리와 파일만 다시 작성됩니다.
• 전체 기록은 단일 SQLite 데이터베이스(Store)에 저장됩니다. 데이터베이스는 에이전트에게 읽기 전용입니다. 커밋이 게시될 때만 LayerFS 런타임이 기록합니다.

AI에게 중요한 이유

• 최신 자율 에이전트(LLM 기반 플래너, 인간 피드백 기반 강화 학습 루프, 멀티 에이전트 시뮬레이션)는 코드, 데이터 또는 구성의 많은 가정 변형을 시도해야 합니다.
• 각 시도마다 대규모 워크스페이스의 전체 복사본을 다시 만드는 것은 낭비입니다. LayerFS를 사용하면 에이전트가 이전 레이어를 즉시(제로 카피) 포크하고 많은 병렬 롤아웃을 실행한 다음 최상의 브랜치를 승격할 수 있습니다.
• 기록이 불변하고 콘텐츠 주소 지정이므로 시스템은 수천 번의 시도에 걸쳐 대량의 데이터를 중복 제거하여 저장 공간과 I/O를 크게 줄일 수 있습니다.

주요 구성 요소 (v0.1.6 개발자 미리보기 기준)

구성 요소	역할
스토리지 엔진	CAS, CDC, COW, 객체 검증 및 SQLite Store를 관리합니다.
SDK	Client, LayerStack, Branch, Workspace와 같은 유형과 이를 생성/커밋/쿼리하는 함수를 노출하는 Rust 라이브러리.
CLI (layerfs-cli)	Store 생성, LayerStack 초기화, 워크스페이스 생성, 커밋 및 기록 검사를 위한 명령줄 인터페이스.
파일시스템 프로젝션	에이전트에게 일반 디렉터리로 표시되는 마운트 지점(호스트 구체화 또는 FUSE 컨테이너를 통해)을 제공합니다.
컨테이너 런타임	FUSE를 사용하여 경량 Linux 컨테이너를 시작하고, 가변 워크스페이스를 컨테이너 내부에 유지하면서 영구 Store는 호스트에 유지합니다.

일반적인 워크플로우

1. Store 생성 – layerfs db create store.sqlite.
2. LayerStack 초기화 – layerfs layerstack init --name demo --empty는 제네시스 레이어를 생성합니다.
3. 워크스페이스 시작 – layerfs workspace exec <branch>는 파일시스템의 개인 뷰로 프로세스(또는 컨테이너)를 시작합니다.
4. 작업 수행 – 에이전트가 도구를 실행하고 파일을 쓰는 등의 작업을 합니다.
5. 커밋 – layerfs commit <workspace>는 가변 상태를 불변 커밋으로 변환하고 현재 브랜치에 연결합니다.
6. 브랜치 / 포크 – 데이터를 복사하지 않고 대안을 탐색하기 위해 이전 커밋에서 새 브랜치를 만듭니다.

성능 하이라이트 (v0.1.6)

• 32 MiB 파일에 10바이트를 추가해도 논리적 저장소 크기는 약 0.026 MiB만 증가했습니다(CDC 덕분).
• 워크스페이스 전체에 걸친 6번의 결정적 편집으로 논리적 저장소가 약 0.225 MiB 증가했습니다.
• 모든 측정은 실제 FUSE 벤치마크 스위트에서 나온 것입니다. 기본 SQLite 페이지는 더 많이 증가할 수 있지만 논리적 콘텐츠는 작게 유지됩니다.

제한 사항 (중요)

• 개발자 미리보기 전용 – 충돌 또는 정전 내구성 보장이 없습니다. 중요한 데이터의 백업을 유지하세요.
• 클라이언트당 하나의 Store. 크로스 호스트 동기화는 아직 없습니다.
• 커밋은 자동으로 fsync되지 않습니다. 샌드박스의 가변 상태는 커밋이 게시될 때까지 메모리에만 존재합니다.
• 불변 객체를 구축하는 단일 구성 작업자만 있어 대규모 배치 가져오기가 이전 버전보다 느립니다.
• 명시적 압축이 없습니다. 오래된 저장소는 읽을 수 있지만 시스템이 공간을 자동으로 회수하지 않습니다.
• CLI JSON 출력은 임시 형식이며 안정적인 API가 아닙니다.

시작하기

# v0.1.6 태그 클론 (미리보기 코드는 `crates/` 아래에 있음)
git clone https://github.com/Ephemeral-AI-Lab/layerfs.git
cd layerfs && git checkout v0.1.6

# CLI 빌드 (Rust 1.85+, macOS/Linux 필요)
cargo build --release -p layerfs-cli
export LAYERFS_BIN=$PWD/target/release/layerfs
export LAYERFS_CONTEXT=$PWD/.layerfs/context
mkdir -p $PWD/.layerfs

# SQLite 저장소 및 데모 LayerStack 생성
$LAYERFS_BIN db create $PWD/.layerfs/store.sqlite
$LAYERFS_BIN context use --store $PWD/.layerfs/store.sqlite
$LAYERFS_BIN layerstack init --name demo --empty
$LAYERFS_BIN query layerstacks

브랜치 생성, 워크스페이스 실행 및 선택적 FUSE 컨테이너 사용에 대한 버전별 빠른 시작 가이드를 계속 참조하세요.

로드맵 스냅샷

• 0.2.0 (계획) – 휴대용 프로젝션 레이어(reflink/clonefile, 향후 OverlayFS 지원).
• 나중에 – 크로스 호스트 저장소 내보내기/가져오기, 동기화 및 더 풍부한 런타임 통합.

커뮤니티 및 지원

• Discord: https://discord.gg/DrgJ4DX9E
• WeChat 그룹(저장소에 QR 코드) – 초대는 정기적으로 만료됩니다.
• X에서 프로젝트 리더 팔로우: @yifanxu_ephai

라이선스 – MIT.

---

LayerFS는 저렴하고 버전 관리된 파일시스템 상태가 필요한 자율 AI 에이전트를 구축하는 개발자를 위한 연구용 도구입니다. 아직 프로덕션급 스토리지 시스템은 아니지만 "임시 워크스페이스 + 영구 공유 기록" 패턴을 실험하기 위한 구체적인 플랫폼을 제공합니다.