Zeph
<div align="center">
<img src="https://raw.githubusercontent.com/bug-ops/zeph/HEAD/book/src/assets/zeph_v8_github.png" alt="Zeph" width="800">
장기 실행 작업을 위한 메모리 중심 AI 에이전트 — 로컬, 클라우드 또는 분산형.
Crates.io
docs
CI
codecov
MSRV
Tests
License: MIT OR Apache-2.0
</div>
대부분의 AI 어시스턴트는 창을 닫는 순간 모든 것을 잊어버립니다. Zeph는 그 반대로 작동합니다: 기억합니다.
코드, 문서 또는 팀 채팅에 연결하면 며칠과 세션에 걸쳐 계속 작동하며, 단순히 무엇이 말해졌는지뿐만 아니라 결정이 내려진 이유까지 기억합니다. 무료 로컬 모델을 사용하여 노트북에서 실행되며, 작업이 정말 어려울 때만 클라우드(또는 분산형 네트워크)를 사용하고, 전체 과정 동안 API 키를 암호화하고 도구를 샌드박스 처리하여 안전하게 유지합니다.
단일 크기 약 12 MB의 Rust 바이너리입니다. Python도 없고, Node도 없고, 관리해야 할 데이터베이스 서버도 없습니다.
60초 만에 사용해 보기
curl -fsSL https://github.com/bug-ops/zeph/releases/latest/download/install.sh | sh
zeph init
zeph
완전히 오프라인 상태를 유지하는 것을 선호하십니까? Ollama를 실행하고 작은 모델 두 개를 가져오면, 아무것도 장치 외부로 나가지 않습니다:
ollama pull qwen3:8b
ollama pull qwen3-embedding
zeph init && zeph
그게 전부입니다 — 설치하고, 구성하고, 채팅합니다. 대신 대시보드를 원하십니까? zeph --tui를 사용하세요.
Zeph로 할 수 있는 일
| |
|---|
| 코드 작성하기 | Zeph를 저장소(repo)에 겨냥하세요. 파일 읽기, 명령어 실행, 코드 검색을 수행하고 전체 프로젝트 컨텍스트를 바탕으로 답변합니다. 프로젝트별 지침이 필요하면 저장소에 zeph.md 파일을 넣거나 ACP를 통해 에디터에 연결하세요. |
| ... | |
사람들이 Zeph를 선택하는 이유
<div align="center">
<img src="https://raw.githubusercontent.com/bug-ops/zeph/HEAD/book/src/assets/zeph.gif" alt="Zeph TUI 대시보드" width="800">
</div>
내부 작동 원리 (Under the hood)
아래 섹션들은 헤드라인 아이디어에서 구현 세부 사항까지 다룹니다. 요약만 훑어보고, 정확히 어떻게 작동하는지 알고 싶을 때 ▸ 상세 내용 블록을 확장하세요.
메모리가 핵심 제품이다 (Memory is the product)
대부분의 에이전트는 검색 기능을 나중에 추가하는(bolt on) 방식으로 구현합니다. 하지만 Zeph에서는 메모리 자체가 핵심입니다. 모든 것을 하나의 벡터 인덱스에 쏟아붓는 대신, 여러 계층을 동시에 실행합니다:
- A-MAC (Adaptive Memory Admission Control): 다중 요소 점수(미래 유용성, 사실적 신뢰도, 참신성, 최신성, 목표 관련성)를 통해 기억할 가치가 있는 정보를 쓰기 전에 결정하므로 노이즈가 그래프에 도달하는 것을 막습니다.
- Typed graph edges (MAGMA): 관계 유형(인과적, 시간적, 의미적, 계층적, 동시 발생)별로 분류되어 탐색 시 단순히 유사도 순위가 아닌 유형 필터링이 가능합니다.
- SYNAPSE spreading activation: 검색어(recall)가 엔티티를 씨앗으로 삼아 홉(hop)마다 감쇠 및 측면 억제(lateral inhibition)를 통해 그래프를 타고 전파되며, 다중 홉 링크 중 평면 검색으로는 놓치기 쉬운 것들을 표면화합니다.
- BeliefMem: 증거를 Noisy-OR 규칙과 결합한 확률적 엣지 레이어이며, 신뢰도가 임계값을 넘을 때만 사실을 커밋된 그래프로 승격시킵니다. 불확실한 지식은 여전히 불확실하게 유지됩니다.
- APEX-MEM: 이중 시간성 엣지(
valid_from/until은 사실에, created_at/expired_at는 수집에 적용). 모순되는 정보가 덮어쓰기(overwrite)하는 대신 우선권을 가지며, 사용자가 시간을 거슬러 올라갈 수 있는 완전한 감사 추적 기록을 남깁니다.
- MemCoT: 에이전트의 이해도가 어떻게 진화했는지에 대한 Zoom-In (추론 사슬) 및 Zoom-Out (사실 → 결정 → 마일스톤) 뷰를 제공합니다.
- SleepGate + optical forgetting: 배경 패스를 통해 중요도가 낮은 기억을 소프트 삭제하고, 오래된 기억은 두 개의 독립적인 축을 따라 연령별로 압축합니다.
- Compaction probe validation: 요약이 끝날 때마다 Q&A 프로브가 핵심 사실들이 살아남았는지 확인하며, 그렇지 않으면 에이전트는 원래의 대화 내용을 유지합니다.
memory concepts와 graph memory를 참조하세요.
</details>
설계상의 토큰 효율성 (Token efficiency by design)
더 많은 스킬과 도구를 추가한다고 해서 모든 프롬프트가 부풀려지지는 않습니다. Zeph는 프롬프트 크기를 **O(N)이 아닌 O(K)**로 유지합니다: 50개의 스킬을 설치해도, 질의와 관련된 약 5개만 로드되어 ~50,000 토큰 대신 대략 2,500 토큰의 스킬 컨텍스트만을 사용합니다.
<details>
<summary><b>▸ 프롬프트가 작게 유지되는 방식</b></summary>
- Skill 선택(Skill selection) — 하이브리드 BM25 + 임베딩 유사도(Reciprocal Rank Fusion, k=60)를 통해 상위 K개의 스킬을 선택합니다. 메타데이터는 먼저 로드되며(~각 100 토큰), 본문은 활성화 시에만 로드됩니다.
- 도구 스키마 필터링(Tool-schema filtering) — 도구 정의는 턴(turn)마다 관련성에 따라 필터링되며, 관련 없는 스키마는 컨텍스트 창에서 완전히 제거됩니다.
- 도구 결과 및 의미론적 응답 캐싱(Tool-result & semantic-response caching) — 결정론적인 결과와 의미적으로 동등한 질의는 이전 답변을 재사용하여 또 다른 API 호출 없이 사용합니다.
- 투기적 디스패치(Speculative dispatch) — 읽기 전용 도구는 모델이 여전히 작성하는 동안 미리 실행됩니다. 만약 나중에 동일한 도구를 호출하더라도, 결과가 이미 준비되어 있습니다.
- 목표 인식 압축(Goal-aware compaction) (HiAgent) — 다단계 작업 중에는 현재의 하위 목표에 더 이상 관련 없는 정보만 압축하여 활성 작업 메모리를 보존합니다.
Why Zeph?와 토큰 효율성(token efficiency)를 확인하세요.
</details>
원하는 방식으로 실행하기: 로컬, 클라우드 또는 분산형 방식
모든 제공업체(provider)는 [[llm.providers]]에 한 번 선언하고, Zeph가 해당 작업을 처리할 수 있는 가장 저렴한 옵션으로 라우팅하도록 합니다. 하나가 실패하면 자동으로 폴백(fallback)됩니다.
[[llm.providers]]
name = "fast"
type = "ollama"
...
여덟 가지 제공업체 유형이 즉시 작동합니다: Ollama, Claude, OpenAI, Gemini, 모든 OpenAI 호환 엔드포인트(Groq, Together, Fireworks 등), 완벽하게 로컬인 GGUF 추론을 위한 Candle, 그리고 두 개의 분산형 네트워크입니다:
| Network | Type | 특별한 점 (What's special) |
|---|
| Gonka | gonka / compatible | 분산 GPU 노드 — 공유 속도 제한 없음, 단일 공급업체 종속성 없음, OpenAI와 호환되는 게이트웨이. |
| Cocoon | cocoon | 하드웨어 TEE 격리 — 노드 운영자가 사용자의 프롬프트나 가중치(weights)를 읽을 수 없음, 증명된 음성 인식 기능 포함. |
<details>
<summary><b>▸ 라우팅 전략 (Routing strategies)</b></summary>
다섯 가지 전략이 구현되었으며, 그 위에 평판 및 안정성 레이어가 추가됩니다:
- EMA (기본값) — 지연 시간(latency)의 지수 이동 평균(exponential moving average)에 따라 제공업체를 재정렬합니다.
- Thompson Sampling — 베이지안 Beta($ ext{α}, eta$) 밴딧을 사용하여 탐색과 활용 사이의 균형을 맞춥니다.
- Cascade — 비용 우선 방식이며, 출력이 퇴행적(degenerate)으로 보일 때만 점진적으로 증가합니다.
- Complexity Triage — 분류기(classifier)가 작업별로 등급(simple → expert)을 선택합니다.
- Contextual bandit (LinUCB) — 요청을 임베딩하고 제공업체별 품질을 온라인으로 학습합니다.
평판 인식 선택 방식은 유효하지 않은 도구 호출(tool calls)을 방출하는 제공업체에 페널티를 부과하며, 에이전트 안정성 지수(Agent Stability Index)는 응답 일관성을 추적하고, 품질 게이트가 선택된 출력을 검증합니다. 자세한 내용은 adaptive inference를 참조하세요.
</details>
자체 개선하는 스킬 (Skills that improve themselves)
스킬은 작성, 버전 관리 및 공유가 쉬운 일반 SKILL.md 마크다운 파일입니다. 하나를 수정하면 재시작 없이 즉시 로드(hot-reloads)됩니다. 매칭은 의미 기반이므로, *
- 신뢰 수준(Trust levels) — 가져온 스킬은 명시적으로 신뢰되기 전까지는 제한된 도구 하위 집합으로 격리(quarantined) 상태로 시작하며, 변조는 호출별 BLAKE3 해싱을 통해 감지됩니다.
- 실패 기반 진화(Failure-driven evolution) — 설정 가능한 횟수만큼 실패한 후, LLM이 해당 스킬을 재생성합니다 (최대 10 버전으로 제한되며, 성능 하한선 이하로 내려가면 롤백됩니다).
- 베이지안 재순위 지정(Bayesian re-ranking) — Wilson 하한 점수(95% CI)를 가진 스킬은 자동으로 0.85 이상일 경우 승격되고 0.40 미만일 경우 강등됩니다.
- 암묵적 피드백(Implicit feedback) — 정규 표현식 기반 탐지기(LLM 비용 없음)가 수정 사항을 포착하고 재사용하며, LLM 심판은 경계 케이스만 처리합니다.
self-learning 및 skill trust를 참조하세요.
실제로 감사할 수 있는 보안(Security you can actually audit)
비밀 정보는 .env 파일에 절대 저장되지 않고, age-encrypted 금고에 보관됩니다. 모든 도구 호출은 신뢰 게이트, 명령어 필터, 샌드박싱(sandboxing), 감사 로그를 거칩니다. 신뢰할 수 없는 출처(웹 페이지, 도구 출력, MCP 서버)의 콘텐츠는 모델에 도달하기 전에 항상 정제됩니다.
<details>
<summary><b>▸ 깊이 방어(Defense in depth)</b></summary>