A Rust AI agent that makes every token in the context window earn its place.

---

Why Zeph

• Adaptive skill routing -- LinUCB contextual bandit and RL-based routing learn which skills and providers work best for each query type, improving over time without manual tuning.
• Automatic memory management -- SleepGate admission control, graph memory with SYNAPSE spreading activation, and goal-conditioned writes keep long-term memory relevant without user intervention.
• Multi-model orchestration -- declare providers once, route by complexity tier (Simple/Medium/Complex/Expert). Thompson Sampling, cascade routing, and PILOT bandit selection minimize cost while maximizing quality.
• 21-crate modular architecture -- every subsystem is a standalone crate with a clean trait boundary. Feature-gate what you need: TUI, ACP, A2A, MCP, Telegram, Discord, Slack, gateway, scheduler, PDF, STT, Candle inference.
• Context engineering, not prompt engineering -- three-tier compaction pipeline, HiAgent subgoal-aware eviction, failure-driven compression guidelines (ACON), and Memex tool-output archival keep the context window efficient under any load.

---

Quick Start

cargo install zeph
zeph init          # interactive setup wizard — picks provider, model, features
zeph               # start the agent

Tip: Pre-built binaries and Docker images are on the releases page. curl -fsSL https://github.com/bug-ops/zeph/releases/latest/download/install.sh | sh also works.

Tip: Copy-paste configs for all common setups — local, cloud, hybrid, coding assistant, Telegram bot — are in the Configuration Recipes guide.

---

Feature Highlights

• Hybrid inference -- Ollama, Claude, OpenAI, Gemini, any OpenAI-compatible API, or fully local via Candle (GGUF)
• Skills-first architecture -- YAML+Markdown skill files with BM25+cosine hybrid retrieval, Bayesian re-ranking, self-learning evolution
• Semantic memory -- SQLite or PostgreSQL + Qdrant, MMR re-ranking, temporal decay, graph memory with SYNAPSE spreading activation
• MCP client -- full tool exposure, 17-pattern injection detection, elicitation support, tool-list locking
• A2A protocol -- agent-to-agent delegation over JSON-RPC 2.0 with IBCT capability tokens
• ACP server -- stdio, HTTP+SSE, WebSocket transports for IDE integration (Zed, VS Code, Helix)
• TUI dashboard -- ratatui-based with real-time metrics, security panel, plan view, command palette
• Multi-channel I/O -- CLI, Telegram, TUI, Discord, Slack — all with streaming, voice, and vision input
• Multi-model orchestration -- complexity triage routing, Thompson Sampling, cascade cost tiers, PILOT LinUCB bandit
• Security sandbox -- shell sandbox with structured output, file read sandbox, SSRF protection, PII filter, rate limiter, exfiltration guards
• Self-learning -- Agent-as-a-Judge feedback detection, skill evolution from real usage, RL admission control for memory writes
• Task orchestration -- DAG-based task graphs with LLM goal decomposition, parallel execution, plan template caching
• Sub-agents -- isolated agents with scoped tools, zero-trust secret delegation, persistent transcripts
• Code indexing -- tree-sitter AST-based indexing (Rust, Python, JS, TS, Go), semantic search, repo map generation
• Document RAG -- ingest .txt, .md, .pdf into Qdrant with automatic retrieval per turn
• Self-experimentation -- autonomous LLM config tuning via grid sweep, random sampling, neighborhood search
• Config migration -- zeph migrate-config --diff previews and applies config upgrades after version bumps
• Single binary -- ~15 MB, no runtime dependencies, ~50 ms startup, ~20 MB idle memory

---

Architecture

zeph (binary)
 |
 +-- zeph-core            agent loop, context builder, metrics, channel trait
 |    |
 |    +-- zeph-config     TOML config, env overrides, migration, init wizard
 |    +-- zeph-db         SQLite/PostgreSQL pool, migrations, store trait
 |    +-- zeph-vault      age-encrypted secret storage, vault resolution
 |    +-- zeph-common     shared types, error utilities, tracing helpers
 |    +-- zeph-sanitizer  content sanitization, injection detection, PII filter
 |    |
 |    +-- zeph-llm        LlmProvider trait, Ollama/Claude/OpenAI/Gemini/Candle backends
 |    +-- zeph-skills     SKILL.md parser, registry, embedding matcher, self-learning
 |    +-- zeph-memory     semantic memory orchestrator, graph memory, SYNAPSE
 |    +-- zeph-tools      ToolExecutor trait, shell/web/file/composite executors, audit
 |    +-- zeph-mcp        MCP client, multi-server lifecycle, tool registry
 |    +-- zeph-orchestration  DAG task graphs, planner, scheduler, aggregator
 |    +-- zeph-subagent   sub-agent spawner, transcript persistence, lifecycle hooks
 |    +-- zeph-index      AST code indexing, semantic retrieval, repo map
 |
 +-- zeph-channels        CLI, Telegram, Discord, Slack adapters
 +-- zeph-tui             ratatui TUI dashboard (feature-gated)
 +-- zeph-acp             ACP server: stdio/HTTP+SSE/WebSocket (feature-gated)
 +-- zeph-a2a             A2A client + server, agent discovery (feature-gated)
 +-- zeph-gateway         HTTP webhook gateway with bearer auth (feature-gated)
 +-- zeph-scheduler       cron-based periodic tasks (feature-gated)
 +-- zeph-experiments     autonomous LLM config experimentation engine

Optional features are grouped into use-case bundles: desktop (TUI), ide (ACP), server (gateway + A2A + otel), chat (Discord + Slack), ml (Candle + PDF). Use --features full for everything except hardware-specific GPU flags. See Feature Flags.

---

┌─ Skills (3/12) ────────────────────┐┌─ MCP Tools ─────────────────────────┐
│  web-search  [████████░░] 82% (117)││  - filesystem/read_file             │
│  git-commit  [███████░░░] 73%  (42)││  - filesystem/write_file            │
│  code-review [████░░░░░░] 41%   (8)││  - github/create_pr                 │
└────────────────────────────────────┘└─────────────────────────────────────┘

Documentation

Full documentation — installation, configuration, guides, and architecture reference — at bug-ops.github.io/zeph.

Zeph's design draws from a broad range of published research: parallel tool execution (LLMCompiler, ICML 2024), failure-driven context compression (ACON, ICLR 2026), temporal knowledge graphs (Zep/Graphiti, 2025), agentic memory linking (A-MEM, NeurIPS 2025), observation masking and schema-based summarization (Manus, 2025), and more. The full list of papers, blog posts, and specifications that shaped Zeph is at References & Inspirations.

Contributing

See CONTRIBUTING.md. Found a vulnerability? Use GitHub Security Advisories.

License

MIT