Zeph

Most AI assistants forget everything the moment you close the window. Zeph is built the other way around: it remembers.

Point it at your code, your documents, or your team chat, and it keeps working across days and sessions — recalling not just what was said, but why a decision was made. It runs on your laptop with free local models, reaches for the cloud (or a decentralized network) only when a task is genuinely hard, and keeps your API keys encrypted and your tools sandboxed the entire time.

It’s a single ~12 MB Rust binary. No Python, no Node, no database server to babysit.

---

Try it in 60 seconds

curl -fsSL https://github.com/bug-ops/zeph/releases/latest/download/install.sh | sh
zeph init      # interactive wizard sets up your provider and keys
zeph           # start talking

Prefer to stay fully offline? Run Ollama, pull two small models, and nothing ever leaves your machine:

ollama pull qwen3:8b
ollama pull qwen3-embedding
zeph init && zeph

That’s it — install, configure, chat. Want the dashboard instead? zeph --tui.

---

What you can do with it

Why people choose Zeph

---

Under the hood

The sections below go from the headline idea to the implementation detail. Skim the summaries; expand the ▸ details blocks when you want to see exactly how it works.

Memory is the product

Most agents bolt recall on as an afterthought. In Zeph, memory is the core. It runs several layers at once instead of dumping everything into one vector index:

So you can ask “Why did we choose Kafka?” and Zeph follows causal edges from Kafka through the decision graph to surface the original rationale — instead of returning ten documents that happen to contain the word.

Token efficiency by design

Adding more skills and tools shouldn’t inflate every prompt. Zeph keeps prompt size O(K), not O(N): with 50 skills installed, only the ~5 relevant to your query are loaded — roughly 2,500 tokens of skill context instead of ~50,000.

Run it your way: local, cloud, or decentralized

Declare every provider once in [[llm.providers]], then let Zeph route each task to the cheapest option that can handle it — with automatic fallback if one fails.

[[llm.providers]]
name = "fast"            # cheap local model for extraction, embeddings, routing
type = "ollama"
model = "qwen3:8b"
embedding_model = "qwen3-embedding"
embed = true

[[llm.providers]]
name = "quality"         # reserved for planning, code, hard reasoning
type = "claude"
model = "claude-sonnet-5"
default = true

[llm]
routing = "bandit"

Eight provider types work out of the box: Ollama, Claude, OpenAI, Gemini, any OpenAI-compatible endpoint (Groq, Together, Fireworks…), Candle for fully-local GGUF inference, and two decentralized networks:

Skills that improve themselves

Skills are plain SKILL.md markdown files — easy to write, version, and share. Edit one and it hot-reloads; no restart. Matching is by meaning, so “check disk space” finds the system-info skill without a keyword match.

When a skill repeatedly fails, Zeph notices (its feedback detector works across 7 languages), reflects on the cause, and generates an improved version — with Wilson-score ranking promoting what actually works and auto-rollback if a new version regresses.

Security you can actually audit

Secrets live in an age-encrypted vault, never in .env files. Every tool call passes through trust gates, command filters, sandboxing, and an audit log. Content from untrusted sources (web pages, tool output, MCP servers) is sanitized before it ever reaches the model.

Messenger as agent infrastructure

Zeph’s Telegram integration treats the messenger as a coordination layer, not a thin input box:

• Guest Mode — answer anonymous, unauthenticated users via Bot API 10.0’s answerGuestQuery through a transparent local proxy (no second getUpdates, no 409 conflicts).
• Bot-to-bot — register as a managed bot and accept tasks from other bots in a depth-capped, allowlisted chain — multi-agent pipelines without becoming an open relay.
• Voice in a TEE — voice notes are transcribed by a Cocoon STT provider inside a hardware enclave; the audio never leaves it unencrypted.

---

Feature highlights

Installation

# Pre-built binary (no Rust toolchain needed)
curl -fsSL https://github.com/bug-ops/zeph/releases/latest/download/install.sh | sh

# Cargo
cargo install zeph
cargo install zeph --features desktop   # with the TUI dashboard

# Docker
docker pull ghcr.io/bug-ops/zeph:latest

# From source
git clone https://github.com/bug-ops/zeph.git
cd zeph && cargo build --release --features full

Builds run only what you need via feature bundles: desktop (TUI), ide (ACP), server (gateway + A2A + telemetry), chat (Discord + Slack), ml (Candle + PDF), or full. Cross-platform: Linux, macOS, Windows on x86_64 and ARM64.

[!IMPORTANT] Building from source requires Rust 1.98 or later. Pre-built binaries do not need a toolchain.

Common commands

zeph init                    # generate config through the wizard
zeph doctor                  # run preflight checks
zeph --tui                   # launch the dashboard
zeph ingest ./docs           # ingest documents into semantic memory
zeph skill list              # inspect installed skills
zeph router stats            # inspect adaptive provider routing
zeph memory export dump.json # export a memory snapshot

Architecture

A Cargo workspace (Edition 2024) of focused crates. See the architecture overview and crate map.

zeph
  src/                       CLI, bootstrap, init wizard, command handlers
  crates/zeph-core           agent loop and runtime orchestration
  crates/zeph-config         TOML schema, migration, provider registry
  crates/zeph-llm            provider abstraction and model backends
  crates/zeph-memory         semantic, graph, episodic, and document memory
  crates/zeph-skills         skill registry, matching, trust, learning
  crates/zeph-tools          tool executors, sandboxing, policy, audit
  crates/zeph-mcp            MCP client and tool lifecycle
  crates/zeph-tui            ratatui dashboard
  crates/zeph-acp            IDE integration via Agent Client Protocol
  crates/zeph-a2a            agent-to-agent protocol support
  crates/zeph-subagent       sub-agent definitions, spawning, transcripts
  crates/zeph-orchestration  DAG planning, scheduling, verification

Documentation

• Full documentation · Installation · First conversation
• Memory concepts · Graph memory · Adaptive routing
• Configuration recipes · Feature flags · CLI reference · Security model

Zeph draws on published work in parallel tool execution, temporal knowledge graphs, agentic memory linking, failure-driven compression, retrieval quality, and multi-model routing. See References & Inspirations.

Contributing

See CONTRIBUTING.md, CODE_OF_CONDUCT.md, and SECURITY.md. Coverage-guided fuzzing harnesses for parser-like components live in fuzz/.

License

Licensed under either of MIT or Apache License, Version 2.0 at your option.