Skip to content

README.md

Latest commit

 

History

History
245 lines (180 loc) · 9.47 KB

README.md

File metadata and controls

245 lines (180 loc) · 9.47 KB

Zeph

Zeph

A memory-first AI agent for long-running work on local, cloud, and decentralized inference.

Crates.io docs CI codecov MSRV License: MIT

Zeph is a Rust-native AI agent built for work that cannot fit into one chat window: coding sessions, operations, research loops, document RAG, scheduled jobs, and multi-agent workflows. It keeps short-term context sharp, persists long-term memory, builds a relationship graph from decisions and entities, and routes each task to the cheapest provider that can handle it.

Unlike single-session assistants, Zeph is designed to remember why a decision happened, not just the last messages around it.

Why Try Zeph

If you want... Zeph gives you...
An agent that survives long projects SQLite conversation history, semantic recall, graph memory, session digests, trajectory memory, and goal-aware compaction.
Lower infrastructure cost A default SQLite vector backend, local Ollama defaults, feature-gated bundles, and provider routing for simple vs. hard tasks.
More than keyword memory Typed graph facts, BFS recall, SYNAPSE spreading activation, MMR reranking, temporal decay, and write-quality gates.
Provider freedom Ollama, Claude, OpenAI, Gemini, Candle, any OpenAI-compatible endpoint, and a Gonka.ai path through GonkaGate.
Agent-grade safety Age-encrypted vault secrets, sandboxed tool execution, MCP injection detection, SSRF guards, PII filtering, and exfiltration checks.
Daily operator ergonomics CLI, TUI dashboard, MCP tools, plugins, skills, sub-agents, ACP for IDEs, A2A, scheduler, and JSON output modes.

Quick Start

Install the latest release:

curl -fsSL https://github.com/bug-ops/zeph/releases/latest/download/install.sh | sh

Or install from crates.io:

cargo install zeph

Initialize and run:

zeph init
zeph doctor
zeph --tui

Important

Zeph requires Rust 1.95 or later when building from source. Pre-built binaries do not require a Rust toolchain.

For a local-first setup, run Ollama and pull the default lightweight models:

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

Gonka.ai

Zeph is being wired for Gonka.ai in two phases:

  • GonkaGate today: use the existing OpenAI-compatible provider path and store the gp-... key in the age vault as ZEPH_COMPATIBLE_GONKAGATE_API_KEY.
  • Native Gonka next: the gonka provider config shape and vault key resolution have landed; the signed native transport is the active follow-up.

Example GonkaGate provider:

[[llm.providers]]
name = "gonkagate"
type = "compatible"
base_url = "https://api.gonkagate.com/v1"
model = "Qwen/Qwen3-235B-A22B-Instruct-2507-FP8"
default = true

Zeph resolves compatible provider secrets by name. For name = "gonkagate", store the gateway key under:

ZEPH_COMPATIBLE_GONKAGATE_API_KEY

Note

Native type = "gonka" currently validates configuration but still returns "gonka provider is not yet implemented" at provider construction. Use GonkaGate until the signed node transport lands.

What Makes It Different

Memory is the product

Zeph combines several memory layers instead of treating recall as a side feature:

Layer Purpose
Working context Keeps the current task coherent under context pressure.
Semantic memory Stores conversations, tool outputs, documents, and summaries for retrieval.
Graph memory Records entities, decisions, relationships, causality, temporal links, and hierarchy.
Episodic memory Preserves session-level scenes, digests, goals, and trajectories.
Quality gates Reject noisy writes, validate compaction, and log retrieval failures for later improvement.

Ask "Why did we choose PostgreSQL?" and Zeph can traverse decision edges instead of searching raw chat text.

Built for low-resource setups

Zeph does not require a heavyweight stack to be useful:

  • The default vector backend is embedded SQLite.
  • Qdrant is optional for larger semantic and graph workloads.
  • The default local chat model is qwen3.6:8b through Ollama.
  • Feature bundles let you build only what you need: desktop, ide, server, chat, ml, or full.
  • Release builds are optimized for small native binaries.

Multi-model by design

Declare providers once in [[llm.providers]], then route work by complexity, cost, latency, and reliability:

[[llm.providers]]
name = "fast"
type = "ollama"
model = "qwen3:8b"
embedding_model = "qwen3-embedding"
embed = true

[[llm.providers]]
name = "quality"
type = "claude"
model = "claude-sonnet-4-6"
default = true

[llm]
routing = "bandit"

Use local models for extraction, embeddings, routing, and summarization. Keep expensive models for planning, code generation, and expert reasoning.

Tools without loose secrets

Secrets live in the Zeph age vault, not in .env files or shell profiles. Tool execution goes through trust gates, command filters, sandboxing, audit logs, and redaction paths. MCP tools are discovered and exposed without dropping the injection and authorization checks.

Demo

Zeph TUI Dashboard

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 plugin list --overlay   # inspect plugin config overlays
zeph router stats            # inspect adaptive provider routing
zeph memory export dump.json # export memory snapshot
zeph project purge --dry-run # preview local state cleanup

Installation Options

Pre-built Binary

curl -fsSL https://github.com/bug-ops/zeph/releases/latest/download/install.sh | sh

Cargo

cargo install zeph
cargo install zeph --features desktop

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
./target/release/zeph init

Feature Highlights

Area Highlights
Memory SQLite/PostgreSQL history, embedded SQLite vectors or Qdrant, graph memory, SYNAPSE, SleepGate, ReasoningBank, document RAG.
Context Goal-aware compaction, typed pages, tool-output archive, session recap, active-goal injection.
Skills SKILL.md registry, hot reload, BM25 + embedding matching, trust levels, self-learning skill improvement.
Providers Ollama, Claude, OpenAI, Gemini, OpenAI-compatible APIs, Candle local inference, adaptive routing.
Tools Shell, file, web, MCP, tool quotas, approval gates, audit trail, sandboxing, output compression.
Interfaces CLI, TUI, Telegram, Discord, Slack, ACP, A2A, HTTP gateway, scheduler daemon.
Code intelligence Tree-sitter indexing, semantic repo map, LSP diagnostics and hover context through MCP.
Observability Debug dumps, JSONL mode, Prometheus metrics, OpenTelemetry traces, profiling builds.

Architecture

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 through 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

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

Contributing

See CONTRIBUTING.md, CODE_OF_CONDUCT.md, and SECURITY.md.

License

MIT