Zeph

You have an LLM. You want it to actually do things — run commands, search files, remember context, learn new skills. But wiring all that together means dealing with token bloat, provider lock-in, and context that evaporates between sessions.

Zeph is a lightweight AI agent written in Rust that connects to any LLM provider (local Ollama, Claude, OpenAI, or HuggingFace models), equips it with tools and skills, and manages conversation memory — all while keeping prompt size minimal. Only the skills relevant to your current query are loaded, so adding more capabilities never inflates your token bill.

What You Can Do with Zeph

Development assistant. Point Zeph at your project directory, and it reads files, runs shell commands, searches code, and answers questions with full context. Drop a ZEPH.md file in your repo to give it project-specific instructions.

Chat bot. Deploy Zeph as a Telegram, Discord, or Slack bot with streaming responses, user whitelisting, and voice message transcription. Your team gets an AI assistant in the channels they already use.

Self-hosted agent. Run fully local with Ollama — no data leaves your machine. Encrypt API keys with age vault. Sandbox tool access with path restrictions and command confirmation. You control everything.

Get Started

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

Three commands: install the binary, generate a config, start talking.

Cross-platform: Linux, macOS, Windows (x86_64 + ARM64).

Next Steps

• Why Zeph? — what sets Zeph apart from other LLM wrappers
• First Conversation — from zero to “aha moment” in 5 minutes
• Installation — all installation methods (source, binaries, Docker)

Why Zeph?

Token Efficiency

Most agent frameworks inject all available tools and instructions into every prompt. Zeph takes a different approach at every layer:

• Skill selection — only the top-K most relevant skills per query (default: 5) are loaded via embedding similarity. With 50 skills installed, a typical prompt contains ~2,500 tokens of skill context instead of ~50,000. Progressive loading fetches metadata first (~100 tokens each), full body on activation, and resource files on demand.
• Tool schema filtering — tool definitions are filtered per-turn based on semantic relevance to the current task, removing irrelevant schemas from the context window entirely.
• TAFC (Think-Augmented Function Calling) — for complex tools, the model reasons about parameter values before committing, reducing error-driven retries that waste tokens.
• Tool result caching — deterministic tool results are cached within the session, eliminating redundant executions and their token overhead.
• Semantic response caching — LLM responses are cached by embedding similarity, so semantically equivalent queries reuse previous answers without an API call.

Prompt size is O(K), not O(N) — and every layer actively works to keep it there.

Intelligent Context Management

Long conversations are the norm, not an edge case. Zeph manages context pressure automatically:

• Structured anchored summarization — summaries follow a typed schema with mandatory sections (goal, files modified, decisions, open questions, next steps), preventing the compressor from silently dropping critical facts.
• Compaction probe validation — after every summarization, a Q&A probe verifies that key facts survived compression. If the probe fails, the agent falls back to keeping original turns.
• Subgoal-aware compaction (HiAgent) — during multi-step tasks, the agent tracks the current subgoal and only compresses information that is no longer relevant to it, preserving active working memory.
• Write-time importance scoring — memory entries receive an importance score at write time based on content markers, information density, and role, so frequently-referenced and explicitly important memories surface higher during retrieval.

Graph Memory

Beyond flat vector search, Zeph builds a structured knowledge graph from conversations:

• MAGMA typed edges — relationships between entities are classified into five types (Causal, Temporal, Semantic, CoOccurrence, Hierarchical), enabling type-filtered traversal.
• SYNAPSE spreading activation — retrieval activates a seed entity and propagates through the graph with hop-by-hop decay and lateral inhibition, surfacing multi-hop connections that flat similarity search misses.
• Community detection — label propagation identifies entity clusters, providing topic-level context for retrieval.

Ask “why did we choose Kafka?” and Zeph follows causal edges from Kafka through the decision graph to surface the original rationale — not just documents that mention the word.

Hybrid Inference

Mix local and cloud models in a single setup. Run embeddings through free local Ollama while routing chat to Claude or OpenAI. The orchestrator classifies tasks and routes them to the best provider with automatic fallback chains — if the primary provider fails, the next one takes over. Thompson Sampling exploration balances cost and quality across providers. Switch providers with a single config change. Any OpenAI-compatible endpoint works out of the box (Together AI, Groq, Fireworks, and others).

Skills-First Architecture

Skills are plain markdown files — easy to write, version control, and share. Zeph matches skills by embedding similarity, not keywords, so “check disk space” finds the system-info skill even without exact keyword overlap. Edit a SKILL.md file and changes apply immediately via hot-reload, no restart required.

Skills evolve autonomously: when the agent detects repeated failures via the multi-language FeedbackDetector (supporting 7 languages), it reflects on the cause and generates improved skill versions. Wilson score re-ranking ensures that well-performing skills surface first.

Task Orchestration

For complex goals, Zeph decomposes work into a task DAG and executes it with parallel scheduling:

• Plan template caching — successful plans are cached by goal embedding, so similar future requests reuse an adapted template instead of replanning from scratch (50% cost reduction, 27% latency improvement).
• Tool dependency graph — tools declare ordering constraints (requires for hard gates, prefers for soft boosts), enabling the agent to present tools in the right sequence without hardcoded execution order.

Privacy and Security

Run fully local with Ollama — no API calls, no data leaves your machine. Store API keys in an age-encrypted vault instead of plaintext environment variables. Tools are sandboxed: configure allowed directories, block network access from shell commands, require confirmation for destructive operations like rm or git push --force. Imported skills start in quarantine with restricted tool access until explicitly trusted. Content from untrusted sources (web scraping, tool output, MCP servers) is sanitized through a multi-layer isolation pipeline before reaching the agent.

Multi-Channel

Deploy Zeph across CLI, TUI dashboard, Telegram, Discord, and Slack with consistent feature parity across all channels. The TUI provides real-time metrics, a command palette, and live status indicators for background operations. All 7 channels support the same 16-method Channel trait — no feature is silently missing in any mode.

Lightweight and Fast

Zeph compiles to a single Rust binary (~12 MB). No Python runtime, no Node.js, no JVM dependency. Native async throughout with no garbage collector overhead. Builds and runs on Linux, macOS, and Windows across x86_64 and ARM64 architectures.

Installation

Install Zeph from source, the install script, pre-built binaries, or Docker.

Install Script (recommended)

Run the one-liner to download and install the latest release:

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

The script detects your OS and architecture, downloads the binary to ~/.zeph/bin/zeph, and adds it to your PATH. Override the install directory with ZEPH_INSTALL_DIR:

ZEPH_INSTALL_DIR=/usr/local/bin curl -fsSL https://github.com/bug-ops/zeph/releases/latest/download/install.sh | sh

Install a specific version:

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

After installation, run the configuration wizard:

zeph init

From crates.io

cargo install zeph

With optional features:

cargo install zeph --features tui,a2a

From Source

git clone https://github.com/bug-ops/zeph
cd zeph
cargo build --release

The binary is produced at target/release/zeph. Run zeph init to generate a config file.

Pre-built Binaries

Download from GitHub Releases:

Docker

Pull the latest image from GitHub Container Registry:

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

Or use a specific version:

docker pull ghcr.io/bug-ops/zeph:v0.9.8

Images are scanned with Trivy in CI/CD and use Oracle Linux 9 Slim base with 0 HIGH/CRITICAL CVEs. Multi-platform: linux/amd64, linux/arm64.

See Docker Deployment for full deployment options including GPU support and age vault.

First Conversation

This guide takes you from a fresh install to your first productive interaction with Zeph.

Prerequisites

• Zeph installed and zeph init completed
• Either Ollama running locally (ollama serve), or a Claude/OpenAI API key configured

Start the Agent

zeph

You see a You: prompt. Type a message and press Enter.

Ask About Files

You: What files are in the current directory?

Behind the scenes:

1. Zeph embeds your query and matches the file-ops skill (ranked by cosine similarity)
2. The skill’s instructions are injected into the prompt
3. The agent calls the list_directory or find_path tool to list files
4. You get a structured answer with the directory listing

You did not tell Zeph which skill to use — it figured it out from context.

Run a Command

You: Check disk usage on this machine

Zeph matches the system-info skill and runs df -h via the bash tool. If a command is potentially destructive (like rm or git push --force), Zeph asks for confirmation first:

Execute: rm -rf /tmp/old-cache? [y/N]

See Memory in Action

You: What files did we just look at?

Zeph remembers the full conversation. It answers from context without re-running any commands. With semantic memory enabled (Qdrant), Zeph can also recall relevant context from past sessions.

Useful Slash Commands

Type exit, quit, or press Ctrl-D to stop the agent.

Next Steps

• Configuration Wizard — customize providers, memory, and channels
• Configuration Recipes — copy-paste configs for common setups (local, cloud, hybrid, coding assistant, Telegram bot)
• Skills — understand how skill matching works
• Tools — what the agent can do with shell, files, and web

Configuration Wizard

Run zeph init to generate a config.toml through a guided wizard. This is the fastest way to get a working configuration.

zeph init
zeph init --output ~/.zeph/config.toml   # custom output path

Step 1: Secrets Backend

Choose how API keys and tokens are stored:

• env (default) — read secrets from environment variables
• age — encrypt secrets in an age-encrypted vault file (recommended for production)

When age is selected, API key prompts in subsequent steps are skipped since secrets are stored via zeph vault set instead.

Step 2: LLM Provider

Select your inference backend:

• Ollama — local, free, default. Provide model name (default: mistral:7b)
• Claude — Anthropic API. Provide API key
• OpenAI — OpenAI or compatible API. Provide base URL, model, API key
• Orchestrator — multi-model routing. Select a primary and fallback provider
• Compatible — any OpenAI-compatible endpoint

Choose an embedding model for skill matching and semantic memory (default: qwen3-embedding).

Step 3: Memory

Set the SQLite database path and optionally enable semantic memory with Qdrant. Qdrant requires a running instance (e.g., via Docker).

Step 4: Channel

Pick the I/O channel:

• CLI (default) — terminal interaction, no setup needed
• Telegram — provide bot token, set allowed usernames
• Discord — provide bot token and application ID (requires discord feature)
• Slack — provide bot token and signing secret (requires slack feature)

Step 5: Update Check

Enable or disable automatic version checks against GitHub Releases (default: enabled).

Step 6: Scheduler

Configure the cron-based task scheduler (requires scheduler feature):

• Enable scheduler — toggle scheduled task execution on/off
• Tick interval — how often the scheduler polls for due tasks in seconds (default: 60)
• Max tasks — maximum number of scheduled tasks (default: 100)

Skip this step if you do not use scheduled tasks.

Step 7: Orchestration

Configure multi-agent task orchestration (requires orchestration feature):

• Enable orchestration — toggle task graph execution on/off
• Max tasks per graph — upper bound on tasks per /plan invocation (default: 20)
• Max parallel tasks — concurrency limit for task execution (default: 4)
• Require confirmation — show plan summary and ask /plan confirm before executing (default: true)
• Failure strategy — how to handle task failures: abort, retry, skip, or ask
• Planner model — LLM override for plan generation (empty = agent’s primary model)

Step 8: Daemon

Configure headless daemon mode with A2A endpoint (requires daemon + a2a features):

• Enable daemon — toggle daemon supervisor on/off
• A2A host/port — bind address for the A2A JSON-RPC server (default: 0.0.0.0:3000)
• Auth token — bearer token for A2A authentication (recommended for production)
• PID file path — location for instance detection (default: ~/.zeph/zeph.pid)

Skip this step if you do not plan to run Zeph in headless mode.

Step 9: ACP

Configure the Agent Client Protocol server (requires acp feature):

• Agent name — name advertised in the ACP manifest (default: zeph)
• Agent version — version string for the manifest (defaults to the binary version)

Step 10: LSP Code Intelligence

Configure LSP code intelligence via mcpls:

• Enable LSP via mcpls — expose 16 LSP tools (hover, definition, references, diagnostics, call hierarchy, rename, and more) to the agent through the MCP client
• Workspace root(s) — one or more project directories for mcpls to index; defaults to the current directory

When enabled, the wizard generates an [[mcp.servers]] block with command = "mcpls" and a 60-second timeout (LSP servers need warmup time). If mcpls is not found in PATH, the wizard prints the install command: cargo install mcpls.

After answering this step, the wizard prompts for LSP context injection (requires the lsp-context feature):

• Enable automatic LSP context injection — automatically inject diagnostics after write_file calls so the agent sees compiler errors without making explicit tool calls. Defaults to enabled when mcpls is configured. Skipped automatically when mcpls is not enabled.

When enabled, the wizard generates an [agent.lsp] config section with enabled = true and default sub-section values.

See LSP Code Intelligence for full setup details, including hover-on-read and references-on-rename configuration.

Step 11: Sub-Agents

Configure the sub-agent system:

• Enable sub-agents — toggle parallel sub-agent execution
• Max concurrent — maximum sub-agents running at the same time (default: 1)

Step 12: Router

Configure the Thompson Sampling model router (requires router feature):

• Enable router — toggle router on/off
• State file path — where to persist alpha/beta statistics (default: ~/.zeph/router_thompson_state.json)

Step 13: Experiments

Configure autonomous self-experimentation:

• Enable autonomous experiments — toggle the experiment engine on/off (default: disabled)
• Judge model — model used for LLM-as-judge evaluation (default: claude-sonnet-4-20250514)
• Schedule automatic runs — enable cron-based experiment sessions (default: disabled)
• Cron schedule — 5-field cron expression for scheduled runs (default: 0 3 * * *, daily at 03:00)

When enabled, the agent can autonomously tune its own inference parameters by running A/B trials against a benchmark dataset. See Experiments for details.

Step 14: Self-Learning

Configure the self-learning feedback detector:

• Correction detection strategy — regex (default) or judge
  • regex — pattern matching only, zero extra LLM calls
  • judge — LLM-backed classifier for borderline cases; you can specify a dedicated model
• Correction confidence threshold — Jaccard overlap threshold (default: 0.7)

Step 15: Compaction Probe

Configure post-compression context integrity validation:

• Enable compaction probe — validate summary quality after each hard compaction event (default: disabled)
• Probe model — model for probe LLM calls; leave empty to use the summary provider (default: empty)
• Pass threshold — minimum score for the Pass verdict (default: 0.6)
• Hard fail threshold — score below this blocks compaction entirely (default: 0.35)
• Max questions — number of factual questions generated per probe (default: 3)

When enabled, each hard compaction is followed by a quality check. If the summary fails to preserve critical facts (HardFail), compaction is blocked and original messages are preserved. See Context Engineering — Compaction Probe for tuning guidance.

Step 16: Debug Dump

Enable debug dump at startup:

• Enable debug dump — write LLM requests/responses and raw tool output to numbered files in .zeph/debug (default: disabled)

Debug dump is intended for context debugging — use it when you need to inspect exactly what is sent to the LLM and what comes back. See Debug Dump for details.

Step 17: Security

Configure security features:

• PII filter — scrub emails, phone numbers, SSNs, and credit card numbers from tool outputs before they reach the LLM context and debug dumps (default: disabled)
• Tool rate limiter — sliding-window per-category limits (shell 30/min, web 20/min, memory 60/min) to prevent runaway tool calls (default: disabled)
• Skill scan on load — scan skill content for injection patterns when skills are loaded; logs warnings but does not block execution (default: enabled)
• Pre-execution verification — block destructive commands (e.g. rm -rf /) and injection patterns before every tool call (default: enabled)
  • Allowed paths — comma-separated path prefixes where destructive commands are permitted (empty = deny all). Example: /tmp,/home/user/scratch
  • Shell tools checked by default: bash, shell, terminal (configurable in config.toml via security.pre_execution_verify.destructive_commands.shell_tools)
• Guardrail (requires guardrail feature) — LLM-based prompt injection pre-screening via a dedicated safety model (e.g. llama-guard-3:1b)

Step 18: Review and Save

Inspect the generated TOML, confirm the output path, and save. If the file already exists, the wizard asks before overwriting.

After the Wizard

The wizard prints the secrets you need to configure:

• env backend: export ZEPH_CLAUDE_API_KEY=... commands to add to your shell profile
• age backend: zeph vault init and zeph vault set commands to run

Further Reading

• Configuration Reference — full config file and environment variables
• Vault — Age Vault — vault setup, custom secrets, and Docker integration

Skills

Skills give Zeph specialized knowledge for specific tasks. Each skill is a markdown file (SKILL.md) containing instructions and examples that are injected into the LLM prompt when relevant.

Instead of loading all skills into every prompt, Zeph selects only the top-K most relevant (default: 5) using a combination of BM25 keyword matching and embedding cosine similarity fused via Reciprocal Rank Fusion. This keeps prompt size constant regardless of how many skills are installed.

How Matching Works

1. You send a message — for example, “check disk usage on this server”
2. Zeph embeds your query using the configured embedding model
3. The top 5 most relevant skills are selected by cosine similarity
4. Selected skills are injected into the system prompt
5. Zeph responds using the matched skills

This happens automatically on every message. You never activate skills manually.

Bundled Skills

Use /skills in chat to see active skills and their usage statistics.

Key Properties

• Progressive loading: only metadata (~100 tokens per skill) is loaded at startup. Full body is loaded on first activation and cached
• Hot-reload: edit a SKILL.md file, changes apply without restart
• Two matching backends: in-memory (default) or Qdrant (faster startup with many skills, delta sync via BLAKE3 hash). Both support BM25+cosine hybrid search via Reciprocal Rank Fusion (enabled by default, disable with hybrid_search = false)
• Secret gating: skills that declare x-requires-secrets in their frontmatter are excluded from the prompt if the required secrets are not present in the vault. This prevents the agent from attempting to use a skill that would fail due to missing credentials
• Compact prompt mode: when context budget is tight, skills.prompt_mode = "auto" (default) switches to a condensed XML format that includes only name, description, and triggers — ~80% smaller than full bodies. Force with "compact" or disable with "full". See Context Engineering — Skill Prompt Modes

External Skill Management

Zeph includes a SkillManager that installs, removes, and verifies external skills. Skills can be installed from git URLs or local paths into the managed directory (~/.config/zeph/skills/), which is automatically appended to skills.paths.

Installed skills start at the quarantined trust level. Use zeph skill verify to check BLAKE3 integrity, then promote with zeph skill trust <name> verified or zeph skill trust <name> trusted.

See CLI Reference — zeph skill for the full subcommand list, or use the in-session /skill install and /skill remove commands for hot-reloaded management without restart.

Deep Dives

• Add Custom Skills — create your own skills
• Self-Learning Skills — how skills evolve through failure detection
• Skill Trust Levels — security model for imported skills

Memory and Context

Zeph uses a dual-store memory system: SQLite for structured conversation history and a configurable vector backend (Qdrant or embedded SQLite) for semantic search across past sessions.

Conversation History

All messages are stored in SQLite. The CLI channel provides persistent input history with arrow-key navigation, prefix search, and Emacs keybindings. History persists across restarts.

When conversations grow long, Zeph compacts history automatically using a two-tier strategy. The soft tier fires at soft_compaction_threshold (default 0.70): it prunes tool outputs and applies pre-computed deferred summaries without an LLM call. The hard tier fires at hard_compaction_threshold (default 0.90): it runs full LLM-based chunked compaction. Compaction uses dual-visibility flags on each message: original messages are marked agent_visible=false (hidden from the LLM) while remaining user_visible=true (preserved in UI). A summary is inserted as agent_visible=true, user_visible=false — visible to the LLM but hidden from the user. This is performed atomically via replace_conversation() in SQLite. The result: the user retains full scroll-back history while the LLM operates on a compact context.

Semantic Memory

With semantic memory enabled, messages are embedded as vectors for similarity search. Ask “what did we discuss about the API yesterday?” and Zeph retrieves relevant context from past sessions automatically. Both vector similarity and keyword (FTS5) search respect visibility boundaries — only agent_visible=true messages are indexed and returned, so compacted originals never appear in recall results.

Two vector backends are available:

Semantic memory uses hybrid search — vector similarity combined with SQLite FTS5 keyword search — to improve recall quality. When the vector backend is unavailable, Zeph falls back to keyword-only search.

Result Quality: MMR and Temporal Decay

Two post-processing stages improve recall quality beyond raw similarity:

• Temporal decay attenuates scores based on message age. A configurable half-life (default: 30 days) ensures recent context is preferred over stale information. Scores decay exponentially: a message at 1 half-life gets 50% weight, at 2 half-lives 25%, etc.
• MMR re-ranking (Maximal Marginal Relevance) reduces redundancy in results by penalizing candidates too similar to already-selected items. The mmr_lambda parameter (default: 0.7) controls the relevance-diversity trade-off: higher values favor relevance, lower values favor diversity.

Both are disabled by default. Enable them in [memory.semantic]:

[memory.semantic]
enabled = true
recall_limit = 5
temporal_decay_enabled = true
temporal_decay_half_life_days = 30
mmr_enabled = true
mmr_lambda = 0.7

Quick Setup

Embedded SQLite vectors (no external dependencies):

[memory]
vector_backend = "sqlite"

[memory.semantic]
enabled = true
recall_limit = 5

Qdrant (production):

[memory]
vector_backend = "qdrant"  # default

[memory.semantic]
enabled = true
recall_limit = 5

See Set Up Semantic Memory for the full setup guide.

Cross-Session History Restore

When a session is resumed, Zeph restores previous message history from SQLite. The restore pipeline applies sanitize_tool_pairs() to ensure every ToolUse message has a matching ToolResult. Orphaned ToolUse or ToolResult parts at session boundaries — caused by session interruptions or compaction boundary splits — are detected and stripped before the history reaches the LLM. This prevents Claude API 400 errors that occur when the API receives unmatched tool call pairs.

Context Engineering

Token counts throughout the context pipeline are computed by TokenCounter — a shared BPE tokenizer (cl100k_base) with a DashMap cache. This replaced the previous chars / 4 heuristic and provides accurate budget allocation, especially for non-ASCII content and tool schemas. See Token Efficiency — Token Counting for implementation details.

When context_budget_tokens is set (default: 0 = unlimited), Zeph allocates the context window proportionally:

A two-tier pruning system manages overflow:

1. Tool output pruning (cheap) — replaces old tool outputs with short placeholders
2. Chunked LLM compaction (fallback) — splits middle messages into ~4096-token chunks, summarizes them in parallel (up to 4 concurrent LLM calls), then merges partial summaries. Falls back to single-pass if any chunk fails.

Both tiers run automatically. See Context Engineering for tuning options.

Project Context

Drop a ZEPH.md file in your project root and Zeph discovers it automatically. Project-specific instructions are included in every prompt as a <project_context> block. Zeph walks up the directory tree looking for ZEPH.md, ZEPH.local.md, or .zeph/config.md.

Embeddable Trait and EmbeddingRegistry

The Embeddable trait provides a generic interface for any type that can be embedded in Qdrant. It requires id(), content_for_embedding(), content_hash(), and to_payload() methods. EmbeddingRegistry<T: Embeddable> is a generic sync/search engine that delta-syncs items by BLAKE3 content hash and performs cosine similarity search. This pattern is used internally by skill matching, MCP tool registry, and code indexing.

Credential Scrubbing

When memory.redact_credentials is enabled (default: true), Zeph scrubs credential patterns from message content before sending it to the LLM context pipeline. This prevents accidental leakage of API keys, tokens, and passwords stored in conversation history. The scrubbing runs via scrub_content() in the context builder and covers the same patterns as the output redaction system (see Security — Secret Redaction).

Autosave Assistant Responses

By default, only user messages generate vector embeddings. Enable autosave_assistant to persist assistant responses to SQLite and optionally embed them for semantic recall:

[memory]
autosave_assistant = true    # Save assistant messages (default: false)
autosave_min_length = 20     # Minimum content length for embedding (default: 20)

When enabled, assistant responses shorter than autosave_min_length are saved to SQLite without generating an embedding (via save_only()). Responses meeting the threshold go through the full embedding pipeline. User messages always generate embeddings regardless of this setting.

Memory Snapshots

Export and import conversation history as portable JSON files for backup, migration, or sharing between instances.

# Export all conversations, messages, and summaries
zeph memory export backup.json

# Import into another instance (duplicates are skipped)
zeph memory import backup.json

The snapshot format (version 1) includes conversations, messages with multipart content, and summaries. Import uses INSERT OR IGNORE semantics — existing messages with matching IDs are skipped, so importing the same file twice is safe.

LLM Response Cache

Cache identical LLM requests to avoid redundant API calls. The cache is SQLite-backed, keyed by a blake3 hash of the message history and model name.

[llm]
response_cache_enabled = true   # Enable response caching (default: false)
response_cache_ttl_secs = 3600  # Cache entry lifetime in seconds (default: 3600)

[memory]
response_cache_cleanup_interval_secs = 3600  # Interval for purging expired cache entries (default: 3600)

A periodic background task purges expired entries. The cleanup interval is configurable via [memory] response_cache_cleanup_interval_secs (default: 3600 seconds). Streaming responses bypass the cache entirely — only non-streaming completions are cached.

Semantic Response Caching

In addition to exact-match caching, Zeph supports embedding-based similarity matching for cache lookups. When semantic_cache_enabled = true, the system embeds incoming message context and searches for cached responses with cosine similarity above semantic_cache_threshold (default: 0.95). This allows cache hits even when messages are paraphrased or slightly different.

[llm]
response_cache_enabled = true
semantic_cache_enabled = true          # Enable semantic similarity matching (default: false)
semantic_cache_threshold = 0.95        # Cosine similarity threshold for cache hit (default: 0.95)
semantic_cache_max_candidates = 10     # Max entries to examine per lookup (default: 10)

The threshold controls the tradeoff between hit rate and relevance: lower values (0.92) produce more hits but risk returning less relevant cached responses; higher values (0.98) are more conservative. semantic_cache_max_candidates controls how many entries are examined per query — increase to 50+ for better recall at the cost of latency.

Write-Time Importance Scoring

When importance_enabled = true, each message receives an importance score (0.0-1.0) at write time. The score is computed by an LLM classifier that evaluates how decision-relevant the message content is. During semantic recall, the importance score is blended with the similarity score using importance_weight (default: 0.15), boosting recall of architecturally significant decisions and key facts.

[memory.semantic]
importance_enabled = true         # Enable write-time importance scoring (default: false)
importance_weight = 0.15          # Blend weight for importance in recall ranking (default: 0.15)

The weight controls how much importance influences the final recall ranking: 0.0 disables importance entirely (pure similarity), 1.0 makes importance the dominant signal. The default 0.15 provides a subtle boost to high-importance messages without disrupting similarity-based ranking.

Native Memory Tools

When a memory backend is configured, Zeph registers two native tools that the model can invoke explicitly during a conversation, in addition to automatic recall that runs at context-build time.

memory_search

Searches long-term memory across three sources and returns a combined markdown result:

• Semantic recall — vector similarity search against past messages (same as automatic recall)
• Key facts — structured facts extracted and stored via memory_save
• Session summaries — summaries from other conversations, excluding the current session

The model invokes this tool when it needs to actively retrieve information rather than rely on what was injected automatically. Example: the user asks “what was the API key format we agreed on last week?” and the model has no relevant context in the current window.

Parameters:

memory_save

Persists content to long-term memory as a key fact, making it retrievable in future sessions.

The model uses this when it identifies information worth preserving explicitly — decisions, preferences, or facts the user stated that should survive context compaction. Content is validated (non-empty, max 4096 characters) before being stored via remember().

Parameters:

Registration

MemoryToolExecutor is registered in the tool chain only when a memory backend is configured. If [memory] is absent or [memory.semantic] is disabled, neither tool appears in the model’s tool list.

Query-Aware Memory Routing

By default, semantic recall queries both SQLite FTS5 (keyword) and Qdrant (vector) backends and merges results via reciprocal rank fusion. Query-aware routing selects the optimal backend(s) per query, avoiding unnecessary work.

[memory.routing]
strategy = "heuristic"   # Currently the only strategy (default)

The heuristic router classifies queries into three routes:

Question words override code pattern heuristics: "how does error_handling work" routes Semantic, not Keyword. Relationship patterns take priority over all other heuristics: "how is Rust related to this project" routes Graph, not Semantic.

The agent calls recall_routed() on SemanticMemory, which delegates to the configured router before querying. When Qdrant is unavailable, Semantic-route queries return empty results; Hybrid-route queries fall back to FTS5 only.

Adaptive Memory Admission Control (A-MAC)

By default, every message that crosses the minimum length threshold is embedded and stored in the vector backend. A-MAC adds a learned gate that evaluates each candidate message against the current memory state before committing the write. Only messages that are sufficiently novel — dissimilar to recently stored content — are admitted, preventing the vector index from filling with near-duplicate information.

A-MAC is disabled by default. Enable it in [memory.admission]:

[memory.admission]
enabled = true
threshold = 0.40            # Composite score threshold; messages below this are rejected (default: 0.40)
fast_path_margin = 0.15     # Skip full check and admit immediately when score >= threshold + margin (default: 0.15)
admission_provider = "fast" # Provider name for LLM-assisted admission decisions (optional)

[memory.admission.weights]
future_utility = 0.30       # LLM-estimated future reuse probability (heuristic mode only)
factual_confidence = 0.15   # Inverse of hedging markers (e.g. "I think", "maybe")
semantic_novelty = 0.30     # 1 - max similarity to existing memories
temporal_recency = 0.10     # Always 1.0 at write time
content_type_prior = 0.15   # Role-based prior (user messages score higher)

The fast_path_margin short-circuits the admission check for clearly novel messages, reducing embedding lookups on low-similarity content. When admission_provider is set, borderline cases (similarity near threshold) are escalated to an LLM for a binary admit/reject decision; without it, the threshold comparison is the sole gate.

RL-Based Admission Strategy

The default heuristic strategy uses static weights and an optional LLM call for the future_utility factor. The rl strategy replaces the future_utility LLM call with a trained logistic regression model that learns from actual recall outcomes.

The RL model collects (query, content, was_recalled) triples from every admitted and rejected message over time. When the training corpus reaches rl_min_samples, the model is trained and deployed. Below that threshold the system automatically falls back to heuristic.

[memory.admission]
enabled = true
admission_strategy = "rl"          # "heuristic" (default) or "rl"
rl_min_samples = 500               # Training samples required before RL activates (default: 500)
rl_retrain_interval_secs = 3600    # Background retraining interval in seconds (default: 3600)

Warning

admission_strategy = "rl" is currently a preview feature. The model infrastructure is wired and sample collection is active, but the trained model is not yet connected to the admission path — the system will emit a startup warning and fall back to heuristic. Full RL-gated admission is tracked in #2416.

Note

Migration 055 adds the tables required for RL sample storage. Run zeph --migrate-config when upgrading an existing installation.

MemScene Consolidation

MemScene groups semantically related messages into scenes — short-lived narrative units covering a coherent sub-topic within a session. Scenes are detected automatically in the background and consolidated into a single embedding before the individual messages are demoted in the recall index. This compresses the vector space without discarding information: a scene embedding captures the collective meaning of its member messages, and scene summaries are searchable in future sessions.

MemScene is configured under [memory.tiers]:

[memory.tiers]
scene_enabled = true
scene_similarity_threshold = 0.80  # Minimum cosine similarity for messages to be grouped into the same scene (default: 0.80)
scene_batch_size = 10              # Number of messages to evaluate per consolidation cycle (default: 10)
scene_provider = "fast"            # Provider name for scene summary generation

scene_provider must reference a [[llm.providers]] entry. If unset, the default provider is used. Scenes are stored in SQLite alongside their member message IDs and can be inspected with zeph memory stats.

Active Context Compression

Zeph supports two compression strategies for managing context growth:

[memory.compression]
strategy = "reactive"    # Default — compress only when reactive compaction fires

Reactive (default) relies on the existing two-tier compaction pipeline (Tier 1 tool output pruning, Tier 2 chunked LLM compaction). No additional configuration needed.

Proactive fires compression before reactive compaction when the current token count exceeds threshold_tokens:

[memory.compression]
strategy = "proactive"
threshold_tokens = 80000       # Fire when context exceeds this token count (>= 1000)
max_summary_tokens = 4000      # Cap for the compressed summary (>= 128)
# model = ""                   # Reserved for future per-compression model selection (currently unused)

Proactive and reactive compression are mutually exclusive per turn: if proactive compression fires, reactive compaction is skipped for that turn (and vice versa). The compacted_this_turn flag resets at the start of each turn.

Proactive compression emits two metrics: compression_events (count) and compression_tokens_saved (cumulative tokens freed).

Note

Validation rejects threshold_tokens < 1000 and max_summary_tokens < 128 at startup.

Tool Output Archive (Memex)

When archive_tool_outputs = true, Zeph saves the full body of every tool output in the compaction range to SQLite before summarization begins. The archived entries are stored in the tool_overflow table with archive_type = 'archive' and are excluded from the normal overflow cleanup pass.

During compaction the LLM sees placeholder messages instead of the full outputs, keeping the summarization prompt small. After the LLM produces its summary, Zeph appends UUID reference lines (one per archived output) to the summary text. This gives you a complete audit trail of tool outputs that survived context compaction.

This feature is disabled by default because it increases SQLite storage usage. Enable it when you need durable tool output history across long sessions:

[memory.compression]
archive_tool_outputs = true

Tip

Tool output archives are written by database migration 054. Run zeph --migrate-config if you are upgrading an existing installation.

Failure-Driven Compression Guidelines

When [memory.compression_guidelines] is enabled, the agent learns from its own compaction mistakes. After each hard compaction, it watches the next several LLM responses for a two-signal context-loss indicator: an uncertainty phrase (e.g. “I don’t recall”, “I’m not sure if”) combined with a prior-context reference (e.g. “earlier you mentioned”, “we discussed before”). When both signals appear together in the same response, the pair is recorded as a compression failure in SQLite.

A background updater wakes on a configurable interval, and when the number of unprocessed failure pairs exceeds update_threshold, it calls the LLM to synthesize updated compression guidelines. The resulting guidelines are sanitized to strip prompt-injection attempts and stored in SQLite. Every subsequent compaction prompt includes the active guidelines inside a <compression-guidelines> block, steering the summarizer to preserve categories of information that were lost before.

The feature is disabled by default:

[memory.compression_guidelines]
enabled = true
update_threshold = 5             # Minimum failure pairs before triggering an update (default: 5)
max_guidelines_tokens = 500      # Token budget for the guidelines document (default: 500)
max_pairs_per_update = 10        # Failure pairs consumed per update cycle (default: 10)
detection_window_turns = 10      # Turns after hard compaction to watch for context loss (default: 10)
update_interval_secs = 300       # Seconds between background updater checks (default: 300)
max_stored_pairs = 100           # Maximum unused failure pairs retained (default: 100)

Note

Guidelines are injected only when enabled = true and at least one guidelines version exists in SQLite. The guidelines document grows incrementally as the agent accumulates failure experience.

Per-Category Compression Guidelines

By default a single global guidelines document is maintained for the entire conversation. When categorized_guidelines = true, the updater maintains four independent documents — one per content category — and injects only the relevant document during compaction:

Each category runs its own update cycle: a category is updated only when its unprocessed failure pair count reaches update_threshold, avoiding unnecessary LLM calls for categories that have few failures.

Enable per-category guidelines alongside the base feature:

[memory.compression_guidelines]
enabled = true
categorized_guidelines = true    # Maintain separate guidelines per content category (default: false)
update_threshold = 5

Tip

Per-category guidelines reduce the chance that tool-output compression rules interfere with how assistant reasoning is compressed, and vice versa. Enable this when you have long sessions mixing heavy tool use with extended reasoning chains.

Graph Memory

With the graph-memory feature enabled, Zeph extracts entities and relationships from conversations and stores them as a knowledge graph in SQLite. This enables multi-hop reasoning (“how is X related to Y?”), temporal fact tracking (“user switched from vim to neovim”), and cross-session entity linking.

Graph memory is opt-in and complementary to vector + keyword search. After each user message, a background task extracts entities and edges via LLM. On subsequent turns, matched graph facts are injected into the context as a system message alongside recalled messages. The context budget allocates 4% of available tokens to graph facts (taken proportionally from summaries, semantic recall, cross-session, and code context allocations). Messages flagged with injection patterns skip extraction for security.

[memory.graph]
enabled = true
max_hops = 2
recall_limit = 10

See Graph Memory for the full concept guide.

Session Summary on Shutdown

When a session ends (graceful shutdown), Zeph checks whether a session summary already exists for the conversation. If none does — which is typical for short or interrupted sessions that never triggered hard compaction — it generates a lightweight LLM summary of the recent messages and stores it in the zeph_session_summaries vector collection. This makes the session retrievable by search_session_summaries in future conversations, enabling cross-session recall even for brief interactions.

The guard is SQLite-authoritative: if a summary record exists in SQLite (written by either the shutdown path or a previous hard compaction), the shutdown path is skipped. This handles the edge case where a Qdrant write failed but the SQLite record succeeded.

[memory]
shutdown_summary = true              # default: true
shutdown_summary_min_messages = 4   # skip sessions with fewer user turns
shutdown_summary_max_messages = 20  # cap LLM input to the last N messages

The LLM call is bounded by a 5-second timeout (10 seconds worst-case if the structured output call times out and falls back to plain text). Errors are logged as warnings and never propagate to the caller — shutdown completes regardless.

Structured Anchored Summarization

When hard compaction fires, the summarizer can produce structured summaries anchored to specific information categories. The AnchoredSummary format replaces free-form prose with five mandatory sections:

1. Session Intent — what the user is trying to accomplish
2. Files Modified — file paths, function names, structs referenced
3. Decisions Made — architectural or implementation decisions with rationale
4. Open Questions — unresolved items or ambiguities
5. Next Steps — concrete actions to take immediately

Anchored summaries are validated for completeness (session_intent and next_steps must be non-empty) and rendered as Markdown with [anchored summary] headers for context injection. This structured format reduces information loss during compaction compared to unstructured prose summaries.

Deep Dives

• Set Up Semantic Memory — Qdrant setup guide
• Graph Memory — entity-relationship tracking and multi-hop reasoning
• Context Engineering — budget allocation, compaction, recall tuning

Graph Memory

Graph memory augments Zeph’s existing vector + keyword search with entity-relationship tracking. It stores entities, relationships, and communities extracted from conversations in SQLite, enabling multi-hop reasoning, temporal fact tracking, and cross-session entity linking.

Status: Experimental.

Why Graph Memory?

Flat vector search finds semantically similar messages but cannot answer relationship questions:

Graph memory tracks who/what (entities), how they relate (edges), and when facts change (bi-temporal timestamps).

Data Model

Entities

Named nodes with a type. Each entity has a canonical name (normalized, lowercased) used as the unique key, and a display name (the most recently seen surface form). Stored in graph_entities with a UNIQUE(canonical_name, entity_type) constraint.

Entity Aliases

Multiple surface forms can refer to the same canonical entity. The graph_entity_aliases table maps variant names to entity IDs. For example, “Rust”, “rust-lang”, and “Rust language” can all resolve to the same entity with canonical name “rust”.

The entity resolver checks aliases before creating a new entity:

1. Normalize the input name (trim, lowercase, strip control characters, truncate to 512 bytes)
2. Search existing aliases for a match with the same entity type
3. If found, reuse the existing entity and update its display name
4. If not found, create a new entity and register the normalized name as its first alias

This prevents duplicate entities caused by trivial name variations.

Edges (MAGMA Typed Edges)

Directed relationships between entities. Each edge carries:

• relation — verb describing the relationship (prefers, uses, works_on)
• edge type — one of five typed categories (see below)
• fact — human-readable sentence (“User prefers neovim for Rust development”)
• confidence — 0.0 to 1.0 score
• bi-temporal timestamps — valid_from/valid_until for fact validity, created_at/expired_at for ingestion time

Edge Types

MAGMA (Multi-graph Attribute-typed Graph Memory Architecture) classifies edges into five semantic types, enabling type-aware traversal and filtering:

Edge types are extracted by the LLM during background extraction and stored alongside the relation string. Type-aware queries can filter or weight edges by type during retrieval.

When a fact changes (e.g., user switches from vim to neovim), the old edge is invalidated (valid_until and expired_at set) and a new edge is created. Both are preserved for temporal queries.

Partial indexes on (source_entity_id, valid_from) WHERE valid_to IS NOT NULL and (target_entity_id, valid_from) WHERE valid_to IS NOT NULL accelerate temporal range queries (migration 030).

Active edges are deduplicated on (source_entity_id, target_entity_id, relation). When the same relation is re-extracted, the existing row is updated with the higher confidence value instead of creating a duplicate row. This prevents repeated extractions from inflating edge counts over long conversations.

Communities

Groups of related entities with an LLM-generated summary. Community detection runs periodically via label propagation (Phase 5).

Background Extraction

After each user message is persisted, Zeph spawns a background extraction task (when [memory.graph] enabled = true). The extraction pipeline:

1. Collects the last 4 user messages as conversational context
2. Sends the current message plus context to the configured LLM (extract_model, or the agent’s primary model when empty)
3. Parses the LLM response into entities and edges, respecting max_entities_per_message and max_edges_per_message limits
4. Upserts extracted data into SQLite with bi-temporal timestamps

Extraction runs non-blocking via spawn_graph_extraction — the agent loop continues without waiting for it to finish. A configurable timeout (extraction_timeout_secs, default: 15) prevents slow LLM calls from accumulating.

Security

Messages flagged with injection patterns are excluded from extraction. When the content sanitizer detects injection markers (has_injection_flags = true), maybe_spawn_graph_extraction returns early without queuing any work. This prevents untrusted content from poisoning the knowledge graph.

TUI Status

During extraction, the TUI displays an “Extracting entities…” spinner so the user knows background work is in progress.

Entity Resolution

By default, entities are deduplicated using exact name matching. When use_embedding_resolution = true, Zeph uses cosine similarity search in Qdrant to find semantically equivalent entities before creating new ones.

The resolution logic uses a two-threshold approach:

This handles cases where the same concept appears under different names (e.g., “VS Code” and “Visual Studio Code”, “k8s” and “Kubernetes”). On any failure (Qdrant unavailable, embedding error), resolution falls back to exact match silently.

Configure in [memory.graph]:

[memory.graph]
use_embedding_resolution = true     # default: false
entity_similarity_threshold = 0.85  # auto-merge threshold
entity_ambiguous_threshold = 0.70   # LLM disambiguation threshold

Retrieval: BFS Traversal

Graph recall uses breadth-first search to find relevant facts:

1. Match query to entities (by name or embedding similarity)
2. Traverse edges up to max_hops (default: 2) from matched entities
3. Collect active edges (valid_until IS NULL) along the path
4. Score facts using composite_score = entity_match * (1 / (1 + hop_distance)) * evolved_weight(retrieval_count, confidence)

The BFS implementation is cycle-safe and uses at most max_hops + 2 SQLite queries regardless of graph size.

A-MEM Link Weight Evolution

Edges accumulate a retrieval_count — the number of times they were traversed during graph recall. Each traversal increments the counter and the edge’s effective weight in scoring is computed as:

evolved_weight(count, confidence) = confidence * (1.0 + 0.2 * ln(1.0 + count)).min(1.0)

At count = 0 the weight equals the base confidence. At count = 1 it is boosted by ~14%; at count = 10 by ~48%. The boost is capped at 1.0 regardless of count.

This means frequently retrieved edges — facts the agent has found useful many times — gradually rise in composite score and appear earlier in recall results. Edges that are never traversed remain at base confidence.

Link Weight Decay

A background decay task can periodically reduce retrieval_count to prevent indefinite accumulation:

[memory.graph.note_linking]
link_weight_decay_lambda = 0.95      # Multiplicative decay per interval, (0.0, 1.0] (default: 0.95)
link_weight_decay_interval_secs = 86400  # Decay interval in seconds (default: 24h)

With decay_lambda = 0.95, each decay pass multiplies retrieval_count by 0.95, slowly reducing the influence of stale traversals. Set decay_lambda = 1.0 to disable decay entirely.

SYNAPSE Spreading Activation

SYNAPSE (SYNaptic Activation and Propagation for Semantic Exploration) is an alternative retrieval strategy that replaces BFS with biologically inspired spreading activation over the entity graph. When enabled, it provides richer multi-hop recall with natural decay and lateral inhibition.

Hybrid Seed Selection

Before spreading activation, SYNAPSE selects seed entities using hybrid ranking that combines FTS5 full-text score with structural importance:

hybrid_score = fts_score * (1 - seed_structural_weight) + structural_score * seed_structural_weight

structural_score is derived from an entity’s degree (number of active edges) and edge-type diversity. This prioritizes structurally central entities as seeds even when their name match is weak.

seed_community_cap prevents a single dense community from monopolizing all seed slots, encouraging coverage across unrelated parts of the graph.

How Spreading Works

1. Seed activation — matched entities receive activation level 1.0
2. Propagation — activation spreads along edges, decaying by decay_lambda per hop: activation(hop) = parent_activation * decay_lambda
3. Lateral inhibition — when an entity’s activation exceeds inhibition_threshold (default: 0.8), it suppresses activation of neighboring entities. This prevents highly connected hub nodes from dominating results
4. Threshold gating — entities with activation below activation_threshold (default: 0.1) are excluded from results
5. Timeout — the entire activation process is bounded by a 500ms timeout to prevent runaway computation on large graphs

Edge-Type Filtering

SYNAPSE leverages MAGMA typed edges during propagation. Activation flows preferentially along Causal and Semantic edges, with reduced flow along CoOccurrence edges. This produces more semantically coherent activation patterns compared to untyped BFS.

Configuration

[memory.graph.spreading_activation]
enabled = true                      # Replace BFS with spreading activation (default: false)
decay_lambda = 0.85                 # Per-hop decay factor, (0.0, 1.0] (default: 0.85)
max_hops = 3                        # Maximum propagation depth (default: 3)
activation_threshold = 0.1          # Minimum activation to include in results (default: 0.1)
inhibition_threshold = 0.8          # Activation level triggering lateral inhibition (default: 0.8)
max_activated_nodes = 50            # Cap on activated nodes to return (default: 50)
seed_structural_weight = 0.4        # Structural score weight in hybrid seed ranking (default: 0.4)
seed_community_cap = 3              # Max seeds per community; 0 = unlimited (default: 3)

When spreading_activation.enabled = false (the default), graph recall uses BFS as described above.

Temporal Queries

Two temporal query methods allow point-in-time fact retrieval:

Timestamps must be SQLite datetime strings: "YYYY-MM-DD HH:MM:SS".

Temporal Decay Scoring

When temporal_decay_rate > 0, a recency boost is applied to graph fact scores:

boost = 1 / (1 + age_days * temporal_decay_rate)
final_score = base_score + boost (capped at 2× base)

With temporal_decay_rate = 0.0 (default), scoring is unchanged. The temporal_decay_rate field is validated at deserialization: finite values in [0.0, 10.0] only; NaN and Inf are rejected.

Community Detection

Community detection groups related entities into clusters using label propagation. Instead of treating the knowledge graph as a flat collection of facts, communities reveal thematic clusters — for example, a group of entities related to “Rust tooling” or “deployment infrastructure.”

How It Works

Every community_refresh_interval messages (default: 100), a background task runs full community detection:

1. Load all entities from SQLite; load active edges in chunks (keyset pagination via WHERE id > ? LIMIT ?, chunk size controlled by lpa_edge_chunk_size, default: 10,000). Chunked loading reduces peak memory on large graphs compared to loading all edges at once. Set lpa_edge_chunk_size = 0 to restore the legacy stream-all path.
2. Construct an undirected petgraph graph in memory
3. Run label propagation for up to 50 iterations until convergence: each node adopts the most frequent label among its neighbors, with ties broken by smallest label value
4. Discard groups with fewer than 2 entities
5. Compute a BLAKE3 fingerprint (sorted entity IDs + intra-community edge IDs) for each community. Communities whose membership has not changed since the last detection run skip LLM summarization entirely — a second consecutive run on an unchanged graph triggers zero LLM calls.
6. Generate LLM summaries (2-3 sentences) in parallel for communities whose fingerprint changed, bounded by community_summary_concurrency (default: 4) concurrent calls
7. Persist communities to the graph_communities SQLite table

Incremental Assignment

Between full detection runs, newly extracted entities are assigned to existing communities incrementally. When a new entity has edges to entities already in a community, it joins via neighbor majority vote — no full re-detection is triggered. If no neighbors belong to any community, the entity remains unassigned until the next full run.

Viewing Communities

Use the /graph communities TUI command to list detected communities and their summaries (Phase 6).

Graph Eviction

Graph data grows unboundedly without eviction. Zeph runs three eviction rules during every community refresh cycle to keep the graph manageable.

Expired Edge Cleanup

Edges invalidated (valid_to set) more than expired_edge_retention_days days ago are deleted. These are facts superseded by newer information — the active replacement edge is retained.

Orphan Entity Cleanup

Entities with no active edges and last_seen_at older than expired_edge_retention_days days are deleted. An entity with no connections that has not been seen recently is stale.

Entity Count Cap

When max_entities > 0 and the entity count exceeds the cap, the oldest entities (by last_seen_at) with the fewest active edges are deleted first. Set max_entities = 0 (default) to disable the cap.

Configuration

Configure eviction in [memory.graph]:

• expired_edge_retention_days — days to retain expired edges before deletion (default: 90)
• max_entities — maximum entities to retain; 0 means unlimited (default: 0)

Entity Search: FTS5 Full-Text Index

Entity lookup (used by find_entities_fuzzy) is backed by an FTS5 virtual table (graph_entities_fts) that indexes entity names and summaries. This replaces the earlier LIKE-based search with ranked full-text matching.

Key details:

• Tokenizer: unicode61 with prefix matching — handles Unicode names and supports prefix queries (e.g., rust*).
• Ranking: Uses FTS5 bm25() with a 10x weight on the name column relative to summary, so exact name hits rank above summary-only mentions.
• Sync: Insert/update/delete triggers keep the FTS index in sync with graph_entities automatically.
• Migration: The FTS5 table and triggers are created by migration 023.

No additional configuration is needed — FTS5 search is used automatically when graph memory is enabled.

Context Injection

When graph memory contains entities relevant to the current query, Zeph injects a [knowledge graph] system message into the context at position 1 (immediately after the base system prompt). Each fact is formatted as:

- Rust uses cargo (confidence: 0.95)
- User prefers neovim (confidence: 0.88)

Entity names, relations, and targets are escaped — newlines and angle brackets are stripped — to prevent graph-stored strings from breaking the system prompt structure.

Graph facts receive 3% of the available context budget (carved from the semantic recall allocation, which drops from 8% to 5%). When the budget is zero (unlimited mode) or graph memory is disabled, no budget is allocated and no facts are injected.

Configuration

Enable graph memory in your config.toml:

[memory.graph]
enabled = true               # Enable graph memory (default: false)
extract_model = ""           # LLM model for extraction; empty = agent's model
max_entities_per_message = 10
max_edges_per_message = 15
max_hops = 2                 # BFS traversal depth (default: 2)
recall_limit = 10            # Max graph facts injected into context
extraction_timeout_secs = 15
entity_similarity_threshold = 0.85
entity_ambiguous_threshold = 0.70
use_embedding_resolution = false  # Enable embedding-based entity dedup
community_refresh_interval = 100  # Messages between community recalculation
community_summary_concurrency = 4 # Parallel LLM calls for community summaries (1 = sequential)
lpa_edge_chunk_size = 10000       # Edges per chunk during community detection (0 = legacy stream-all)
expired_edge_retention_days = 90  # Days to retain expired (superseded) edges
max_entities = 0                  # Entity cap (0 = unlimited)
temporal_decay_rate = 0.0         # Recency boost for graph recall; 0.0 = disabled (default)
                                  # Range: [0.0, 10.0]. Formula: 1/(1 + age_days * rate)
edge_history_limit = 100          # Max versions returned by edge_history() per source+predicate pair

[memory.graph.note_linking]
# enabled = false                 # Enable A-MEM note linking after extraction (default: false)
# similarity_threshold = 0.85     # Min cosine similarity to create a similar_to edge (default: 0.85)
# top_k = 10                      # Max similar entities to link per extracted entity (default: 10)
# timeout_secs = 5                # Linking pass timeout in seconds (default: 5)
# link_weight_decay_lambda = 0.95 # Multiplicative decay factor for retrieval_count, (0.0, 1.0] (default: 0.95)
# link_weight_decay_interval_secs = 86400  # Seconds between decay passes (default: 86400 = 24h)

[memory.graph.spreading_activation]
enabled = false                   # Replace BFS with spreading activation (default: false)
decay_lambda = 0.85               # Per-hop decay factor (default: 0.85)
max_hops = 3                      # Maximum propagation depth (default: 3)
activation_threshold = 0.1        # Minimum activation for inclusion (default: 0.1)
inhibition_threshold = 0.8        # Lateral inhibition threshold (default: 0.8)
max_activated_nodes = 50          # Cap on returned nodes (default: 50)
seed_structural_weight = 0.4      # Structural score weight in hybrid seed ranking (default: 0.4)
seed_community_cap = 3            # Max seeds per community; 0 = unlimited (default: 3)

Schema

Graph memory uses five SQLite tables (created by migrations 021, 023, 024, 027–030, independent of feature flag):

• graph_entities — entity nodes with canonical_name (unique key) and name (display form)
• graph_entity_aliases — maps variant names to entity IDs for canonicalization
• graph_edges — directed relationships with bi-temporal timestamps (valid_from, valid_until, expired_at)
• graph_communities — entity groups with summaries
• graph_metadata — persistent key-value counters

Migration 030 adds partial indexes for temporal range queries (see Temporal Queries above).

A graph_processed flag on the existing messages table tracks which messages have been processed for entity extraction.

TUI Commands

All /graph commands are available in the interactive session (CLI and TUI):

Commands that query the database (/graph entities, /graph communities, /graph backfill) emit a status message before results so you always know what is happening.

CLI Flag

--graph-memory enables graph memory for the session, overriding memory.graph.enabled in config:

zeph --graph-memory

Note: The [memory.graph] config section must be present in config.toml for graph extraction, entity resolution, and BFS recall to activate at startup. Setting enabled = true without providing the section leaves graph config at its default state (disabled). Use zeph --init to generate the full config structure.

Configuration Wizard

When running zeph init, you will be prompted:

1. “Enable knowledge graph memory? (experimental)” — sets memory.graph.enabled = true
2. “LLM model for entity extraction (empty = same as agent)” — sets memory.graph.extract_model (leave empty to use the same model as the main agent)

Backfill

To populate the graph from existing conversations, use /graph backfill. This processes all messages that have not yet been graph-extracted and stores the resulting entities and edges.

/graph backfill             # process all unprocessed messages
/graph backfill --limit 100 # process at most 100 messages

Backfill runs synchronously in the agent loop and reports progress after each batch of 50 messages. For large conversation histories, use --limit to spread the work across multiple sessions. LLM costs apply per message processed.

Implementation Phases

Graph memory is being implemented incrementally:

1. Schema & Core Types — migration, types, CRUD store, config
2. Entity & Relation Extraction — LLM-powered extraction pipeline
3. Graph-Aware Retrieval — BFS traversal with fuzzy entity matching, composite scoring, and cycle-safe traversal
4. Background Extraction — non-blocking extraction in agent loop, context injection, budget allocation
5. Community Detection — label propagation with petgraph, graph eviction
6. TUI & Observability — /graph commands, metrics, init wizard

See Also

• Memory & Context — overview of Zeph’s memory system
• Configuration Reference — full config reference
• Feature Flags — all available feature flags

LLM Providers

Zeph supports multiple LLM backends. Choose based on your needs:

Claude does not support embeddings natively. Use a multi-provider setup with embed = true on an Ollama or OpenAI provider entry to combine Claude chat with local embeddings. Gemini supports embeddings via the text-embedding-004 model — set embedding_model in the Gemini [[llm.providers]] entry to enable.

Quick Setup

Ollama (default — no API key needed):

ollama pull mistral:7b
ollama pull qwen3-embedding
zeph

Claude:

ZEPH_CLAUDE_API_KEY=sk-ant-... zeph

OpenAI:

ZEPH_LLM_PROVIDER=openai ZEPH_OPENAI_API_KEY=sk-... zeph

Gemini:

ZEPH_LLM_PROVIDER=gemini ZEPH_GEMINI_API_KEY=AIza... zeph

Gemini

Zeph supports Google Gemini as a first-class LLM backend. Gemini is a strong choice when you want access to Google’s latest models (Gemini 2.5 Pro, Gemini 2.0 Flash), very long context windows, extended thinking, or native multimodal reasoning.

Why Gemini

Google’s Gemini 2.5 family brings extended thinking (visible as streaming Thinking chunks in Zeph’s TUI), native tool use, vision, and embeddings. For tasks that require deep reasoning over large codebases or long documents, Gemini’s context capacity complements Zeph’s existing RAG pipeline.

Integration Overview

The GeminiProvider translates Zeph’s internal message format to Gemini’s generateContent API:

• The system prompt becomes a top-level systemInstruction field (Gemini’s required format).
• The assistant role is mapped to "model" (Gemini’s terminology for the model turn).
• Consecutive messages with the same role are automatically merged — Gemini requires strict user/model alternation.
• If the conversation starts with a model turn, a synthetic empty user message is prepended to satisfy the API contract.
• Tool definitions are converted to Gemini functionDeclarations with JSON schema normalization ($ref inlining, anyOf/oneOf → nullable, type name uppercasing).
• Vision inputs are sent as inlineData parts with base64-encoded image data.

Streaming uses streamGenerateContent?alt=sse. Thinking parts (returned with thought: true by Gemini 2.5 models) are surfaced as StreamChunk::Thinking and shown in the TUI sidebar.

Configuration

[llm]
[[llm.providers]]
type = "gemini"
model = "gemini-2.0-flash"           # default; use "gemini-2.5-pro" for extended thinking
max_tokens = 8192
# embedding_model = "text-embedding-004"  # enable Gemini embeddings (optional)
# thinking_level = "medium"              # minimal, low, medium, high (Gemini 2.5+)
# thinking_budget = 8192                 # token budget for thinking; -1 = dynamic, 0 = off
# include_thoughts = true                # surface thinking chunks in TUI
# base_url = "https://generativelanguage.googleapis.com/v1beta"  # default

Store the API key in the vault (recommended):

zeph vault set ZEPH_GEMINI_API_KEY AIza...

Or export it as an environment variable:

export ZEPH_GEMINI_API_KEY=AIza...

Run zeph init and choose Gemini as the provider to have the wizard generate a complete config with all Gemini parameters, including the thinking level prompt.

Capabilities

Embeddings

Set embedding_model in the Gemini [[llm.providers]] entry to enable Gemini embeddings. When set, supports_embeddings() returns true and Zeph uses POST /v1beta/models/{model}:embedContent for semantic memory and skill matching — no Ollama dependency required.

[[llm.providers]]
type = "gemini"
model = "gemini-2.0-flash"
embedding_model = "text-embedding-004"

Streaming and Thinking

When streaming is active, Zeph emits chunks as they arrive from the SSE stream (streamGenerateContent?alt=sse). For Gemini 2.5 models that return thinking parts, the TUI shows a “Thinking…” indicator while the model reasons and then switches to the response stream. Both paths use the same retry infrastructure (send_with_retry) — HTTP 429 (rate limit) and 503 (service unavailable) responses trigger automatic backoff and retry.

Configure thinking via thinking_level (categorical) or thinking_budget (token count). Both fields are optional and apply only to Gemini 2.5+ models.

Streaming Tool Use

Gemini delivers functionCall parts as complete objects within a single SSE event (not incrementally chunked). The SSE parser collects all functionCall parts from the event’s parts array and emits a single StreamChunk::ToolUse with all tool calls. When an event contains both text and function call parts, tool calls take priority and any text in that event is dropped (matching the non-streaming behavior).

Streaming tool use is available on all Gemini models that support function calling, including Gemini 2.0 Flash.

Switching Providers

Change the type field in the [[llm.providers]] entry. All skills, memory, and tools work the same regardless of which provider is active.

[llm]
[[llm.providers]]
type = "claude"   # ollama, claude, openai, gemini, candle, compatible
model = "claude-sonnet-4-6"

Response Caching

Enable SQLite-backed response caching to avoid redundant LLM calls for identical requests. The cache key is a blake3 hash of the full message history and model name. Streaming responses bypass the cache.

[llm]
response_cache_enabled = true
response_cache_ttl_secs = 3600  # 1 hour (default)

See Memory and Context — LLM Response Cache for details.

Deep Dives

• Use a Cloud Provider — Claude, OpenAI, and compatible API setup
• Model Orchestrator — multi-provider routing with fallback chains
• Adaptive Inference — Thompson Sampling and EMA-based provider routing
• Local Inference (Candle) — HuggingFace GGUF models

Tools

Tools give Zeph the ability to interact with the outside world. Three built-in tool types cover most use cases, with MCP providing extensibility.

Shell

Execute any shell command via the bash tool. Commands are sandboxed:

• Path restrictions: configure allowed directories (default: current working directory only)
• Network control: block curl, wget, nc with allow_network = false
• Confirmation: destructive commands (rm, git push -f, drop table) require a y/N prompt
• Output filtering: test results, git diffs, and clippy output are automatically stripped of noise to reduce token usage
• Detection limits: indirect execution via process substitution, here-strings, eval, or variable expansion bypasses blocked-command detection; these patterns trigger a confirmation prompt instead

File Operations

File tools provide structured access to the filesystem. All paths are validated against an allowlist. Directory traversal is prevented via canonical path resolution.

Read/write: read, write, edit, grep

Navigation: find_path (find files matching a glob pattern), list_directory (list entries with [dir]/[file]/[symlink] type labels)

Mutation: create_directory, delete_path, move_path, copy_path — all sandbox-validated, symlink-safe

Web Scraping

Two tools fetch data from the web:

• web_scrape — extracts elements matching a CSS selector from an HTTPS page
• fetch — returns plain text from a URL without requiring a selector

Both tools share the same configurable timeout (default: 15s), body size limit (default: 1 MiB), and SSRF protection: private hostnames and IP ranges are blocked before any connection is made, DNS results are validated to prevent rebinding attacks, and HTTP redirects are followed manually (up to 3 hops) with each target re-validated. See SSRF Protection for Web Scraping.

Code Search

The search_code tool provides unified code intelligence: it combines semantic vector search (Qdrant), structural AST extraction (tree-sitter), and LSP symbol/reference resolution into a single agent-callable operation. Results are ranked and deduplicated across all three layers.

search_code is always available — zeph-index and tree-sitter are compiled into every build. Semantic vector search additionally requires Qdrant (vector_backend = "qdrant") and an active code index ([index] enabled = true). Without Qdrant, the tool falls back to structural and LSP layers.

> find the authentication middleware
→ [structural] src/middleware/auth.rs:12 pub fn auth_layer
→ [semantic] src/middleware/auth.rs:45-87 (score: 0.91)
→ [lsp] 3 references found

See Code Indexing for setup and configuration.

Diagnostics

The diagnostics tool runs cargo check or cargo clippy --message-format=json and returns a structured list of compiler diagnostics (file, line, column, severity, message). Output is capped at a configurable limit (default: 50 entries) and degrades gracefully if cargo is absent.

MCP Tools

Connect external tool servers via Model Context Protocol. MCP tools are embedded and matched alongside skills using the same cosine similarity pipeline — adding more servers does not inflate prompt size. See Connect MCP Servers.

Permissions

Three permission levels control tool access:

Configure per-tool pattern rules in [tools.permissions]:

[[tools.permissions.bash]]
pattern = "cargo *"
action = "allow"

[[tools.permissions.bash]]
pattern = "*sudo*"
action = "deny"

First matching rule wins. Default: ask.

Tool Error Taxonomy

When a tool call fails, Zeph classifies the error into one of 11 categories defined by ToolErrorCategory. The classification drives retry decisions, LLM parameter-reformat paths, and reputation scoring.

Quality failures (ToolNotFound, InvalidParameters, TypeMismatch) trigger self-reflection — the LLM is shown a structured error and asked to correct its parameters. Infrastructure failures (RateLimited, ServerError, NetworkError, Timeout) are retried automatically and never trigger self-reflection.

When a tool call fails, the LLM receives a ToolErrorFeedback block instead of an opaque error string:

[tool_error]
category: invalid_parameters
error: missing required field: url
suggestion: Review the tool schema and provide correct parameters.
retryable: false

This structured format lets the LLM understand what went wrong and whether retrying with corrected parameters is appropriate. See Tool System for the full reference.

ErasedToolExecutor

The ToolExecutor trait is made object-safe via ErasedToolExecutor, enabling Box<dyn ErasedToolExecutor> for dynamic dispatch. This allows Agent<C> to hold any tool executor combination without a generic type parameter, simplifying the agent signature and making it easier to compose executors at runtime.

Scheduler Tools

When the scheduler feature is enabled, three tools are injected into the LLM tool catalog:

These tools are backed by SchedulerExecutor, which forwards requests over an mpsc channel to the background scheduler loop. See Scheduler for the full reference.

Think-Augmented Function Calling (TAFC)

TAFC enriches tool schemas for complex tools by injecting a thinking field that encourages the LLM to reason about parameter selection before committing to values. Tools with a complexity score above complexity_threshold (default: 0.6) are augmented automatically.

[tools.tafc]
enabled = true                # Enable TAFC schema augmentation (default: false)
complexity_threshold = 0.6    # Tools with complexity >= this are augmented (default: 0.6)

Complexity is computed from the number of required parameters, nesting depth, and enum cardinality. TAFC does not modify the tool’s behavior — it only changes the JSON Schema presented to the LLM, adding a thinking string field where the model can reason step-by-step before selecting parameter values.

Tool Schema Filtering

ToolSchemaFilter dynamically selects which tool definitions are included in the LLM context based on embedding similarity to the current query. Instead of sending all tool schemas on every turn (consuming tokens), only the most relevant tools are presented.

The filter integrates with the dependency graph: tools whose hard prerequisites have not yet been satisfied are excluded regardless of relevance score.

Tool Result Cache

Idempotent tool calls within a session are cached to avoid redundant execution. The cache is keyed by tool name and a hash of the arguments. Non-cacheable tools (those with side effects like bash, write, memory_save, and all MCP tools) are excluded automatically.

[tools.result_cache]
enabled = true     # Enable tool result caching (default: true)
ttl_secs = 300     # Cache entry lifetime in seconds, 0 = no expiry (default: 300)

Tool Dependency Graph

Configure sequential tool availability based on prerequisites. A tool with hard dependencies (requires) is hidden from the LLM until all prerequisites have completed successfully in the current session. Soft dependencies (prefers) add a similarity boost when satisfied.

[tools.dependencies]
enabled = true            # Enable dependency gating (default: false)
boost_per_dep = 0.15      # Similarity boost per satisfied soft dependency (default: 0.15)
max_total_boost = 0.2     # Maximum total boost from soft dependencies (default: 0.2)

[tools.dependencies.rules.deploy]
requires = ["build", "test"]   # Hard gate: deploy hidden until build and test complete
prefers = ["lint"]             # Soft boost: deploy scores higher if lint ran

This is useful for multi-step workflows where tool order matters (e.g., read before edit, build before deploy).

Deep Dives

• Tool System — full reference with filter pipeline, native tool use, iteration control
• Security — sandboxing and path validation details

Instruction Files

Zeph automatically loads project-specific instruction files from the working directory and injects their content into the system prompt before every inference call. This lets you give the agent standing context — coding conventions, domain knowledge, project rules — without repeating them in every message.

How it works

At startup, Zeph scans the working directory for instruction files and loads them into memory. The content is injected into the volatile section of the system prompt (Block 2), after environment context and before skills and tool catalog. This placement keeps the stable cache block (Block 1) intact for prompt caching.

Each loaded file appears as:

<!-- instructions: CLAUDE.md -->
<file content>

Only the filename (not the full path) is embedded in the prompt.

File discovery

Files are loaded in the following order:

zeph.md and .zeph/zeph.md are always loaded regardless of provider or auto_detect setting — they are the universal entry point for project instructions.

Deduplication

Candidates are deduplicated by canonical path before loading. Symlinks that resolve to the same file are counted once. Files that are already loaded via another candidate path are skipped.

Security

• Path traversal protection: the canonical path of each file must remain within the project root. Symlinks pointing outside the project directory are rejected with a warning.
• Null byte guard: files containing null bytes are skipped (indicates binary or corrupted content).
• Size cap: files exceeding max_size_bytes (default 256 KiB) are skipped. Configurable.
• No TOCTOU: the canonical path is resolved before File::open() — canonicalization and open use the same path, eliminating the time-of-check/time-of-use race.

Configuration

[agent.instructions]
auto_detect   = true    # Auto-detect provider-specific files (default: true)
extra_files   = []      # Additional files to load (absolute or relative to cwd)
max_size_bytes = 262144  # Per-file size cap, bytes (default: 256 KiB)

# Supply extra instruction files at startup (repeatable)
zeph --instruction-file /path/to/rules.md --instruction-file conventions.md

Tip

Use zeph.md in your project root for rules that apply regardless of which LLM provider you use. Use CLAUDE.md or AGENTS.md alongside it for provider-specific overrides.

Hot reload

Zeph watches all resolved instruction paths for filesystem changes and reloads them automatically — no restart required.

When any watched .md file is created, modified, or deleted, Zeph re-runs the full file discovery and loads the updated content into the next inference call. Changes take effect within 500 ms (the debounce window).

# Edit your instruction file while the agent is running:
echo "- Always use snake_case for variable names" >> zeph.md
# Zeph picks up the change automatically on the next turn.

What is watched:

• All directories containing auto-detected provider files (zeph.md, CLAUDE.md, AGENTS.md, etc.)
• Parent directories of any explicit files supplied via extra_files or --instruction-file
• Sub-provider config directories when using the orchestrator or router

Boundary check: explicit files with absolute paths outside the project root are boundary-checked. Their parent directory is only watched if it passes the project-root constraint; content security is always enforced by the loader regardless.

Note

The watcher only starts when at least one instruction path is resolved. If no instruction files exist at startup, hot reload is disabled and a log message is emitted.

Example: zeph.md

# Project Instructions

- Language: TypeScript, strict mode
- Test framework: vitest
- Commit messages follow Conventional Commits
- Never modify files under `generated/`
- Prefer explicit type annotations over inference

Place this file in your project root. Zeph will include it in every system prompt automatically.

load_skill Tool

The load_skill tool lets the LLM fetch the full body of any registered skill on demand, without that body being pre-loaded into the system prompt.

Problem it solves

Zeph selects the top-K most relevant skills for each message (default: 5) and injects their full bodies into the system prompt. All other registered skills appear in the prompt only as compact metadata — name and description — inside an <other_skills> catalog. This keeps the prompt lean regardless of how many skills are installed.

The drawback is that the LLM sees a skill is available but cannot read its instructions. When the agent determines a non-TOP skill is actually relevant, it had no way to retrieve its content. load_skill closes that gap.

How it works

When native tool use is enabled, load_skill is registered alongside other tools (shell, file, web scrape, etc.) and exposed to the LLM via the tool catalog.

Signature:

{
  "tool": "load_skill",
  "parameters": {
    "skill_name": "<name from other_skills catalog>"
  }
}

The tool reads the skill body from the shared in-memory registry (which holds all registered skills, not just the top-K). The body is returned as the tool result and the LLM continues inference with the full instructions now in context.

When to use it

The LLM should call load_skill when:

1. A skill appears in <other_skills> by name and description.
2. The description suggests that skill contains instructions relevant to the current task.
3. The full instructions are needed to proceed correctly.

Example: the user asks to generate an MCP bridge. The mcp-generate skill did not rank in the top-K for this session, but its name and description appear in <other_skills>. The LLM calls load_skill("mcp-generate") to retrieve the full instructions before generating the bridge.

Note

load_skill is only useful with native tool use (providers that support structured tool_use responses). In legacy bash-block mode the tool is not exposed.

Security model

• Read-only: the tool only reads from the registry. It cannot create, modify, or delete skills.
• Registry-scoped: only skills present in the runtime registry can be loaded. Arbitrary file paths are not accepted — the parameter is a skill name, not a path.
• Size cap: bodies are passed through truncate_tool_output, which caps output at 30,000 characters. If a body exceeds this limit, the tool returns the head and tail of the body with a truncation notice in the middle.
• No path traversal: body loading goes through SkillRegistry::get_body, which reads from the pre-validated path stored at registry load time. No user-supplied path is ever resolved at call time.

Error cases

All error messages are descriptive and include the skill name where applicable, so the LLM can report the issue to the user or try an alternative skill.

Relationship to skill matching

load_skill complements — it does not replace — the automatic top-K matching. The matching pipeline runs first and selects the most semantically relevant skills for the current query. load_skill is a fallback for cases where the matcher did not rank a skill highly enough but the LLM’s own reasoning identifies it as relevant.

If you find yourself repeatedly needing load_skill for the same skill, that skill’s description or trigger keywords may need tuning so the matcher picks it up automatically.

See also

• Skills — how skills are matched and injected
• Add Custom Skills — creating your own skills
• Context Engineering — Skill Prompt Modes — compact vs full body injection

Scheduler

The scheduler runs background tasks on a cron schedule or at a specific future time, persisting job state in SQLite so tasks survive restarts. It is an optional, feature-gated component (--features scheduler) that integrates with the agent loop through three LLM-callable tools. The scheduler is enabled by default when the feature is compiled in.

Prerequisites

Enable the scheduler feature flag before building:

cargo build --release --features scheduler

See Feature Flags for the full flag list.

Task Modes

Every task has one of two execution modes:

The scheduler ticks every 60 seconds by default. run_with_interval(secs) accepts a custom interval (minimum 1 second).

Task Kinds

The kind field identifies what handler executes when the task fires:

Unknown kinds are accepted at runtime and stored as Custom. If no handler is registered for a kind when the task fires, the task is skipped with a debug-level log entry.

Cron Expression Format

The scheduler accepts both standard 5-field cron expressions (min hour day month weekday) and 6-field expressions with an explicit seconds field (sec min hour day month weekday). When a 5-field expression is provided, seconds default to 0.

0 3 * * *         # daily at 03:00 UTC (5-field, standard)
0 2 * * SUN       # Sundays at 02:00 UTC (5-field, standard)
*/15 * * * *      # every 15 minutes (5-field, standard)
0 0 3 * * *       # daily at 03:00 UTC (6-field, with seconds)
0 0 2 * * SUN     # Sundays at 02:00 UTC (6-field, with seconds)
0 */15 * * * *    # every 15 minutes (6-field, with seconds)
* * * * * *       # every second (6-field, testing only)

Expressions are parsed by the cron crate. An invalid expression is rejected immediately with SchedulerError::InvalidCron.

LLM-Callable Tools

When the scheduler feature is enabled, SchedulerExecutor registers three tools with the agent so the LLM can manage tasks in natural language.

schedule_periodic

Schedule a recurring task using a cron expression.

{
  "name": "daily-cleanup",
  "cron": "0 0 3 * * *",
  "kind": "memory_cleanup",
  "config": {}
}

Returns a summary string indicating whether the task was created or updated, and its next scheduled run time.

schedule_deferred

Schedule a one-shot task to fire at a specific future time.

{
  "name": "follow-up",
  "run_at": "2026-03-10T18:00:00Z",
  "kind": "custom",
  "task": "Check if PR #1130 was merged and notify the team"
}

run_at formats

run_at accepts any of the following (must resolve to a future time):

task field patterns

The task string determines how the agent behaves when the task fires. Two patterns:

Reminder for the user — the agent notifies the user without acting:

{ "task": "Remind the user to call home" }
{ "task": "Remind the user: standup in 5 minutes" }

Action for the agent — the agent executes the instruction autonomously:

{ "task": "Check if PR #42 was merged and notify the user" }
{ "task": "Generate an end-of-day summary and send it" }

The task field is sanitized before injection: control characters below U+0020 (except \n and \t) are stripped, and the string is truncated to 512 Unicode code points.

list_tasks

List all currently scheduled tasks with their kind, mode, and next run time.

{}

Returns a formatted table with columns: NAME, KIND, MODE, and NEXT RUN. No parameters required. Also available as the /scheduler list slash command in the CLI and TUI, or as /scheduler with no subcommand.

cancel_task

Cancel a scheduled task by name. Works for both periodic and one-shot tasks.

{
  "name": "daily-cleanup"
}

Returns "Cancelled task '<name>'" if the task existed, or "Task '<name>' not found" otherwise.

Static Task Registration

For tasks that must always be present at startup, register them programmatically before calling scheduler.init():

#![allow(unused)]
fn main() {
use zeph_scheduler::{JobStore, Scheduler, ScheduledTask, TaskKind};
use tokio::sync::watch;
async fn example(store: JobStore) -> anyhow::Result<()> {
let (_shutdown_tx, shutdown_rx) = watch::channel(false);
let (mut scheduler, _msg_tx) = Scheduler::new(store, shutdown_rx);

let task = ScheduledTask::new(
    "daily-cleanup",
    "0 0 3 * * *",
    TaskKind::MemoryCleanup,
    serde_json::Value::Null,
)?;
scheduler.add_task(task);

scheduler.init().await?;
tokio::spawn(async move { scheduler.run().await });
Ok(())
}
}

init() persists each task to the scheduled_jobs SQLite table and computes the initial next_run timestamp. Subsequent restarts reuse the persisted next_run — tasks do not fire spuriously on boot.

Custom Task Handlers

Implement the TaskHandler trait to execute arbitrary async logic when a task fires:

#![allow(unused)]
fn main() {
use std::pin::Pin;
use std::future::Future;
use zeph_scheduler::{SchedulerError, TaskHandler};
struct MyHandler;

impl TaskHandler for MyHandler {
    fn execute(
        &self,
        config: &serde_json::Value,
    ) -> Pin<Box<dyn Future<Output = Result<(), SchedulerError>> + Send + '_>> {
        Box::pin(async move {
            // perform work using config
            Ok(())
        })
    }
}
}

Register the handler before starting the loop:

#![allow(unused)]
fn main() {
use zeph_scheduler::{Scheduler, TaskKind};
fn example(scheduler: &mut Scheduler) {
scheduler.register_handler(&TaskKind::HealthCheck, Box::new(MyHandler));
}
}

Custom One-Shot Tasks and Agent Injection

For custom kind one-shot tasks scheduled via the LLM, the scheduler injects the sanitized task string directly into the agent loop at fire time. This requires attaching a custom_task_tx sender:

#![allow(unused)]
fn main() {
use tokio::sync::mpsc;
use zeph_scheduler::Scheduler;
fn example(scheduler: Scheduler, agent_tx: mpsc::Sender<String>) -> Scheduler {
let scheduler = scheduler.with_custom_task_sender(agent_tx);
scheduler
}
}

When the task fires and no handler is registered for Custom(_), the scheduler calls try_send on this channel, delivering the prompt as a new agent conversation turn.

Sanitization

The sanitize_task_prompt function protects the agent loop from malformed input in the task field:

• Strips all Unicode control characters below U+0020, except \n (U+000A) and \t (U+0009)
• Truncates to 512 Unicode code points (not bytes), preserving multibyte safety

Configuration

Add a [scheduler] section to config.toml to declare static tasks:

[scheduler]
enabled = true
tick_secs = 60      # scheduler poll interval in seconds (minimum: 1)
max_tasks = 100     # maximum number of concurrent tasks

[[scheduler.tasks]]
name = "daily-cleanup"
cron = "0 0 3 * * *"
kind = "memory_cleanup"

[[scheduler.tasks]]
name = "weekly-skill-refresh"
cron = "0 0 2 * * SUN"
kind = "skill_refresh"

Persistence and Recovery

Job metadata is stored in the scheduled_jobs SQLite table (same database as memory). Each row tracks:

• name — unique task identifier
• cron_expr — cron string for periodic tasks (empty for one-shot)
• task_mode — "periodic" or "oneshot"
• kind — task kind string
• next_run — RFC 3339 UTC timestamp of the next scheduled firing
• last_run — RFC 3339 UTC timestamp of the last successful execution
• run_at — target timestamp for one-shot tasks
• done — boolean; set to true after a one-shot completes

After a process restart, next_run is read from the database. If next_run is NULL for a periodic task (e.g., first boot after an upgrade), the scheduler computes and persists the next occurrence on the following tick rather than firing immediately.

Shutdown

The scheduler listens on a watch::Receiver<bool> shutdown signal and exits the loop cleanly when true is sent:

#![allow(unused)]
fn main() {
use tokio::sync::watch;
let (shutdown_tx, shutdown_rx) = watch::channel(false);
// ... build and start scheduler ...
let _ = shutdown_tx.send(true); // signal shutdown
}

Listing Tasks

Use any of the following to view all scheduled tasks:

• CLI / slash command: /scheduler list (or /scheduler with no subcommand) — prints a table with NAME, KIND, MODE, and NEXT RUN columns.
• LLM tool: ask the agent “list my scheduled tasks” — the list_tasks tool is called automatically.
• TUI command palette: open the palette with :, type scheduler, and select scheduler:list.

TUI Integration

When both tui and scheduler features are enabled, the command palette includes a scheduler:list entry. Open the palette with : in normal mode, type scheduler, and select the entry to display all active tasks as a table with columns NAME, KIND, MODE, and NEXT RUN.

The task list is refreshed from SQLite every 30 seconds in the background. Background task execution is indicated by the system status spinner in the TUI status bar.

Related

• Experiments — autonomous self-tuning engine with scheduled runs via [experiments.schedule]
• Daemon Mode — running the scheduler alongside the gateway and A2A server
• Feature Flags — enabling the scheduler feature
• Tools — how SchedulerExecutor integrates with the tool system

LSP Context Injection

Feature flag: lsp-context (included in --features full)

LSP Context Injection automatically adds compiler-derived information to the agent’s context after certain tool calls — without the LLM needing to issue explicit tool requests.

What It Does

Three hooks fire automatically during a conversation:

The injected data appears as a [lsp ...] prefixed message in the conversation history — the same pattern used by semantic recall and graph facts. A per-turn token_budget cap prevents runaway context growth.

Why It Matters

Without this feature, the agent has to explicitly call get_diagnostics, get_hover, or get_references after every file operation. With LSP Context Injection enabled, the feedback loop is automatic:

1. Agent writes a file.
2. Zeph fetches diagnostics from the language server.
3. Errors appear as the next turn’s context — the agent fixes them immediately.

No extra round-trips. No “check for errors” prompt needed.

Prerequisites

• mcpls configured as an MCP server (see LSP Code Intelligence)
• lsp-context feature enabled (already included in the full feature set)

Enabling

# For a single session
zeph --lsp-context

# Or set permanently in config.toml

[agent.lsp]
enabled = true

The interactive wizard (zeph --init) prompts for this setting after the mcpls step.

Graceful Degradation

When mcpls is unavailable, all hooks silently skip. The agent continues working normally — no errors are shown, no functionality is lost. Individual failures are logged at debug level only.

Configuration and Details

Full configuration reference, token budget tuning, and TUI status command: LSP Context Injection → guides/lsp.md

For IDE-proxied LSP via ACP (Zed, Helix, VS Code): ACP LSP Extension → guides/lsp.md

Code Intelligence

Zeph provides out-of-the-box code intelligence for any project you work in — without plugins, language servers, or manual configuration. It combines three complementary layers into a unified search_code tool that the agent calls automatically when it needs to understand your codebase.

The Problem with Context Windows

When an agent needs to understand a large codebase, it faces a fundamental constraint: it cannot read every file. A grep-based approach works for small projects or large context windows, but becomes expensive at scale — each grep cycle consumes tokens, and an 8K-context local model might exhaust its budget after 3–4 searches.

Zeph’s code intelligence pre-indexes your project and retrieves the most relevant code for each query, so the agent spends its context budget on reasoning rather than searching.

Three Layers, One Tool

The search_code tool unifies three search strategies:

Structural Search (tree-sitter)

Tree-sitter parses your source files into an AST and extracts named symbols — functions, structs, classes, impl blocks — with accurate visibility annotations and line numbers. Structural search is fast, offline, and works for all supported languages without any external services.

Use structural search when you need exact definitions: “where is AuthMiddleware defined?”

Semantic Search (Qdrant)

When your question is conceptual rather than syntactic — “how does the authentication flow work?” — semantic search finds relevant code by meaning, not keyword. Each source chunk is embedded into a vector and stored in Qdrant. At query time, the question is embedded and the closest chunks are retrieved.

Semantic search requires a running Qdrant instance and an active code index. Enable it once and Zeph keeps the index up to date as you edit files.

LSP Integration

For precise cross-reference questions — “what calls this function?”, “go to definition” — Zeph delegates to the language server via the mcpls MCP tool. LSP answers are authoritative because they come from the same compiler-backed analysis used by IDEs.

LSP integration requires mcpls to be configured under [[mcp.servers]].

How the Agent Uses It

The agent calls search_code with a natural-language query. Zeph runs all available layers in parallel, deduplicates results, and returns a ranked list with file paths, line numbers, and relevance scores:

> find where API keys are validated

[structural] src/vault/mod.rs:34  pub fn validate_key
[semantic]   src/vault/mod.rs:34–67  (score: 0.94)
[semantic]   src/auth/middleware.rs:12–45  (score: 0.81)
[lsp]        3 references to `validate_key`

The agent uses these results to read specific files rather than scanning the entire codebase.

Repo Map

Alongside per-query retrieval, Zeph maintains a compact structural map of the project — a list of every public symbol with its file and line number. The repo map is injected into the system prompt and cached (default: 5 minutes). It gives the model a bird’s-eye view of the codebase without consuming significant context.

The repo map is generated via tree-sitter queries and works for all providers, including Claude and OpenAI. It does not require Qdrant.

Example:

<repo_map>
  src/agent.rs :: pub struct Agent (line 12), pub fn new (line 45), pub fn run (line 78)
  src/config.rs :: pub struct Config (line 5), pub fn load (line 30)
  src/vault/mod.rs :: pub fn validate_key (line 34), pub fn get_secret (line 68)
  ... and 14 more files
</repo_map>

Setup

Structural search and repo map (always available)

No setup required. Tree-sitter grammars are compiled into every Zeph build. The repo map is enabled by default with a 1024-token budget.

[index]
repo_map_budget = 1024    # tokens; set to 0 to disable
repo_map_ttl_secs = 300   # cache TTL

Semantic search (requires Qdrant)

1. Start Qdrant:

   docker compose up -d qdrant
   

2. Enable indexing:

   [index]
   enabled = true
   auto_index = true    # re-index on startup and on file changes
   

3. On first run, Zeph indexes the project automatically. Subsequent runs only re-embed changed files.

LSP integration (requires mcpls)

Configure mcpls as an MCP server in your config or via zeph init:

[[mcp.servers]]
name = "mcpls"
command = "mcpls"
args = ["--config", ".zeph/mcpls.toml"]

Run zeph init to have the wizard generate the correct mcpls config for your project.

Supported Languages

Related

• Code Indexing — full configuration reference, chunking algorithm, retrieval tuning
• LSP Context Injection — automatic diagnostic and hover injection on file read/write
• Tools — how search_code fits into the tool catalog
• Feature Flags — tree-sitter grammar sub-features

Task Orchestration

Use task orchestration to break a complex goal into a directed acyclic graph (DAG) of dependent tasks, execute them in parallel where possible, and recover from failures without restarting the entire plan. This page explains the core types, DAG algorithms, scheduling model, result aggregation, and the /plan CLI commands.

Task orchestration persists graph state in SQLite so execution survives restarts.

Core Types

TaskGraph

A TaskGraph represents a plan: a goal string, a list of TaskNode entries, and graph-level defaults for failure handling. Each graph has a UUID-based GraphId and tracks its lifecycle through GraphStatus.

TaskNode

Each node in the DAG carries a TaskId (zero-based index), a title, a description, dependency edges, and an optional agent hint for sub-agent routing. Nodes progress through TaskStatus:

TaskResult

When a task completes, it produces a TaskResult containing:

• output — text output from the task
• artifacts — file paths produced by the task
• duration_ms — wall-clock execution time
• agent_id / agent_def — which sub-agent executed the task (optional)

DAG Algorithms

The orchestration module provides four core algorithms:

validate

Checks structural integrity before execution begins:

• Task count does not exceed max_tasks.
• At least one task exists.
• tasks[i].id == TaskId(i) invariant holds.
• No self-references or dangling dependency edges.
• No cycles (verified via topological sort).
• At least one root node (no dependencies).

toposort

Kahn’s algorithm producing dependency order (roots first). Used internally by validate and available for scheduling.

ready_tasks

Returns all tasks eligible for scheduling: tasks already in Ready status, plus Pending tasks whose dependencies have all reached Completed. The function is idempotent across scheduler ticks.

propagate_failure

Applies the effective failure strategy when a task fails:

Each task can override the graph-level default strategy via its failure_strategy and max_retries fields.

Persistence

Graph state is persisted to the task_graphs SQLite table (migration 022_task_graphs.sql). The GraphPersistence wrapper serializes TaskGraph to JSON for storage and provides CRUD operations:

The RawGraphStore trait abstracts the storage backend; SqliteGraphStore in zeph-memory is the default implementation.

LLM Planner

The LLM planner performs goal decomposition: it takes a high-level user goal and breaks it into a validated TaskGraph via a single LLM call with structured JSON output.

Planning Flow

1. The user provides a natural-language goal (e.g., “build and deploy the staging environment”).
2. The planner builds a prompt containing the goal, the available agent catalog, and formatting rules.
3. The LLM returns a JSON object with a tasks array. Each task specifies a task_id, title, description, optional depends_on edges, an optional agent_hint, and an optional failure_strategy.
4. The response is parsed and validated: task IDs must be unique kebab-case strings (^[a-z0-9]([a-z0-9-]*[a-z0-9])?$), dependency references must resolve, and the total task count must not exceed max_tasks.
5. String task_id values from the LLM output are mapped to internal TaskId(u32) indices based on array position.
6. The resulting TaskGraph is checked for DAG acyclicity via dag::validate.

If the LLM returns malformed JSON, chat_typed retries the call once before propagating the error as OrchestrationError::PlanningFailed.

Agent Catalog

The planner receives the list of available SubAgentDef entries and includes each agent’s name, description, and tool policy in the system prompt. This allows the LLM to assign an agent_hint to each task, routing it to the most appropriate agent. Unknown agent hints are logged as warnings and silently dropped rather than failing the plan.

Configuration Fields

Two config fields control planner behavior:

• planner_provider — provider name from [[llm.providers]] for planning LLM calls. When empty, the agent’s primary provider is used. Set this to a provider name (e.g. "quality") to dedicate a specific model for planning.
• planner_max_tokens — maximum tokens for the planner LLM response (default: 4096). Currently reserved for future use: the underlying chat_typed API does not yet support per-call token limits.

See Configuration for the full [orchestration] section reference.

Topology Classification

When topology_selection = true in [orchestration], the scheduler classifies the DAG structure before execution and adjusts dispatch strategy and parallelism accordingly.

TopologyClassifier performs a single O(|V|+|E|) Kahn’s toposort pass and assigns one of six topology variants:

Dispatch Strategies

• FullParallel — dispatch all ready tasks up to max_parallel immediately.
• Sequential — dispatch one task at a time in dependency order.
• LevelBarrier — dispatch tasks level-by-level (all depth-0 tasks, then all depth-1 tasks once depth-0 completes, etc.). Used for tree-structured plans where each level depends on the entire previous level completing.
• Adaptive — conservative parallel dispatch at half capacity. Used for mixed DAGs with diamond patterns that cannot be cleanly classified.

ExecutionMode per Task

The LLM planner can annotate individual tasks with an execution_mode hint:

{
  "task_id": "build",
  "title": "Build artifacts",
  "depends_on": [],
  "execution_mode": "parallel"
}

execution_mode is stored on TaskNode and persisted to SQLite. Missing fields in existing stored JSON default to parallel for backward compatibility.

Configuration

[orchestration]
topology_selection = true   # Enable topology classification (default: false, requires experiments feature)

When topology_selection = false, the scheduler uses FullParallel with the configured max_parallel — no classification overhead.

Plan Verification

PlanVerifier evaluates whether a completed task’s output satisfies its description. It uses a cheap LLM provider (verify_provider) to produce a structured VerificationResult. When gaps are found, replan() generates new TaskNodes and injects them into the live graph.

Gap Severity

Three severity levels classify identified gaps:

Fail-Open Behavior

All LLM failures in the verification path are fail-open:

• verify() returns complete = true when the LLM call fails — the task stays Completed and downstream tasks are dispatched normally.
• replan() returns an empty Vec on LLM failure — no new tasks are injected.
• After 3 consecutive LLM failures, an ERROR log is emitted to surface misconfiguration.

Verification never blocks graph execution. Downstream tasks are unblocked immediately upon task completion, regardless of verification outcome.

Configuration

[orchestration]
# verify_provider = "fast"   # Provider name from [[llm.providers]] for verification calls (default: empty = primary)

When verify_provider is empty, verification uses the agent’s primary provider.

Execution

Once a TaskGraph is validated and persisted, the DAG scheduler drives execution by producing actions for the caller to perform.

DagScheduler

DagScheduler implements a tick-based execution loop. On each tick it inspects the graph, checks for ready tasks, monitors timeouts, and emits SchedulerAction values:

The scheduler never holds a mutable reference to SubAgentManager — it produces actions for the caller to execute (command pattern). This keeps the scheduler testable in isolation and avoids borrow conflicts.

Concurrency Backoff

When all ready tasks are deferred because max_parallel concurrency slots are full, wait_event() applies exponential backoff instead of spinning: 250ms → 500ms → 1s → 2s → 4s, capped at 5s. The backoff resets to 250ms as soon as the first task successfully spawns. This eliminates CPU spin-loops and log floods under sustained high concurrency.

When the sub-agent manager rejects a spawn with a ConcurrencyLimit error, the affected task is reverted to Ready instead of being marked Failed, preventing spurious failure cascades.

Event Channel

Sub-agents report completion via an mpsc::Sender<TaskEvent> channel. Each TaskEvent carries the task ID, agent handle ID, and an outcome (Completed with output/artifacts, or Failed with an error message). The scheduler buffers events in a VecDeque between wait_event() and tick() calls.

A stale event guard rejects completion events from agents that were timed out and retried — preventing a late response from a previous attempt from overwriting the retry result.

Task Timeout

The scheduler monitors wall-clock time for each running task against task_timeout_secs. When a task exceeds the timeout, the scheduler marks it as failed with a timeout error and applies the configured failure strategy (retry, abort, skip, or ask).

Cross-Task Context Injection

When a task becomes ready, the scheduler collects output from its completed dependencies and injects it into the task prompt as a <completed-dependencies> XML block. This gives downstream tasks access to upstream results without manual plumbing.

The injection respects dependency_context_budget (total character budget across all dependencies). Output is truncated at character-safe boundaries (no mid-codepoint splits). The ContentSanitizer is applied to dependency output before injection to prevent prompt injection from upstream task results.

Agent Router

The AgentRouter trait selects which sub-agent definition to use for a given task. The built-in RuleBasedRouter implements a 3-step fallback chain:

1. Exact match — task.agent_hint matched against available agent names.
2. Tool keyword matching — keywords in the task description (e.g., “implement”, “edit”, “build”) matched against agent tool policies. This is an MVP heuristic (English-only, last resort).
3. First available — unconditional fallback to the first agent in the list.

For reliable routing, set agent_hint on each task node during planning. The keyword matching step is a best-effort fallback, not authoritative routing.

Inline Execution (Single-Agent Setup)

When no sub-agents are configured, the scheduler emits RunInline instead of marking tasks as Failed. The main agent provider executes the task prompt directly. This means /plan works in single-agent setups without requiring any [agents] configuration.

SubAgentManager Integration

SubAgentManager::spawn_for_task() wraps the standard spawn() method and hooks into the scheduler’s event channel. When the sub-agent’s JoinHandle resolves, it automatically sends a TaskEvent to the scheduler. This is minimally invasive — no changes to SubAgentHandle or run_agent_loop internals.

Result Aggregation

When all tasks in a graph reach a terminal state (completed, skipped, or failed), the orchestrator synthesizes a single coherent response via the Aggregator trait.

LlmAggregator

LlmAggregator is the default implementation. It:

1. Collects all Completed task outputs.
2. Truncates each output to a per-task character budget derived from aggregator_max_tokens (budget = aggregator_max_tokens × 4 characters, divided equally across completed tasks).
3. Applies the ContentSanitizer to each output to guard against prompt injection from task results.
4. Builds a synthesis prompt listing task outputs under ### Task: <title> headers. Skipped tasks are listed separately with a note that their output is absent.
5. Calls the LLM to produce a single summary that directly addresses the original goal.

Fallback behavior: if the LLM call fails for any reason, LlmAggregator falls back to raw concatenation — goal header followed by each task’s output verbatim. The call never fails with an error as long as at least one completed or skipped task exists.

Note

If the graph has no completed or skipped tasks at all (e.g., every task failed before producing output), aggregation returns OrchestrationError::AggregationFailed.

TUI Integration

When running with the TUI dashboard (--features tui), the right side panel provides live plan progress without leaving the interface.

Press p in Normal mode to toggle between the Sub-agents view and the Plan View. The panel shows each task with its current status, assigned agent, elapsed time, and any error message:

+--------------------+
| Plan: deploy stag… |
| ↻ Preparing env    |  Running   agent-1   12s
| ✓ Build image      |  Completed agent-2   45s
| ✗ Push artifact    |  Failed    agent-2   8s   image push timeout
| · Run smoke tests  |  Pending   —         —
+--------------------+

Use plan:confirm, plan:cancel, plan:status, and plan:list from the command palette (Ctrl+P) instead of typing /plan … in the input line.

See TUI Dashboard — Plan View for the full keybinding and color reference.

CLI Commands

Note

Parsing ambiguity: goals that begin with a reserved subcommand name (status, list, cancel, confirm, resume, retry) are interpreted as that subcommand. Rephrase the goal to avoid collisions — e.g., /plan write a status report instead of /plan status report.

Confirmation Flow

When confirm_before_execute is enabled (the default), /plan <goal> does not execute immediately. Instead it:

1. Calls the LLM planner to decompose the goal into a TaskGraph.
2. Displays a summary of planned tasks with agent assignments.
3. Stores the graph in a pending state.

The user then runs /plan confirm to start execution, or /plan cancel to discard the pending plan. If a new /plan <goal> is submitted while a plan is already pending, the agent rejects it with a warning — cancel or confirm the existing plan first.

Canceling a Running Plan

/plan cancel is delivered even during active plan execution. The agent loop polls the input channel concurrently with the scheduler’s event wait (tokio::select!). When /plan cancel arrives mid-execution, it calls cancel_all() on the scheduler, aborts all running sub-agent tasks, and exits the scheduler loop with a Canceled graph status. Messages received during execution that are not cancel commands are queued and processed after the plan finishes.

Resume a Paused Graph

A graph enters the paused state when a task fails and the effective failure strategy is ask. This gives the user a chance to decide how to proceed.

Use /plan resume (or /plan resume <id> for a specific graph) to continue execution. The scheduler re-evaluates ready tasks from the current state — no previously completed task is re-run.

When to use: the ask strategy is useful when a task failure may or may not be critical. Configure it per-task in the planner output or as the graph-level default_failure_strategy.

Retry Failed Tasks

Use /plan retry (or /plan retry <id> for a specific graph) to re-attempt all tasks that did not complete successfully:

• Tasks in Failed status are reset to Ready; their assigned_agent field is cleared to prevent scheduler deadlock on a stale assignment.
• Tasks in Skipped status are reset to Pending so they can be re-evaluated once their dependencies succeed.
• Tasks that already Completed are not re-run.

This is equivalent to a targeted re-run of the failed subtree without discarding the entire plan.

Metrics

OrchestrationMetrics tracks plan and task counters. The struct is always present in MetricsSnapshot and defaults to zero when orchestration is inactive.

Metrics are updated in the agent loop as tasks progress. They are available through the same watch channel that feeds the TUI dashboard.

Configuration

Add an [orchestration] section to config.toml:

[orchestration]
enabled = true
max_tasks = 20                      # Maximum tasks per graph (default: 20)
max_parallel = 4                    # Maximum concurrent task executions (default: 4)
default_failure_strategy = "abort"  # abort, retry, skip, or ask (default: "abort")
default_max_retries = 3             # Retries for the "retry" strategy (default: 3)
task_timeout_secs = 300             # Per-task timeout in seconds, 0 = fallback to 600s (default: 300)
# planner_provider = "quality"      # Provider name from [[llm.providers]] for planning; empty = primary provider
planner_max_tokens = 4096           # Max tokens for planner response (default: 4096; reserved)
dependency_context_budget = 16384   # Character budget for cross-task context (default: 16384)
confirm_before_execute = true       # Show confirmation before executing a plan (default: true)
aggregator_max_tokens = 4096        # Token budget for the aggregation LLM call (default: 4096)
# topology_selection = false        # Enable DAG topology classification and adaptive dispatch (requires experiments feature)
# verify_provider = ""              # Provider for post-task completeness verification; empty = primary provider

[orchestration.plan_cache]
enabled = false                     # Enable plan template caching (default: false)
similarity_threshold = 0.90         # Min cosine similarity for cache hit (default: 0.90)
ttl_days = 30                       # Days since last access before eviction (default: 30)
max_templates = 100                  # Maximum cached templates (default: 100)

Plan Template Caching

When [orchestration.plan_cache] is enabled, successful plan decompositions are cached as templates. On subsequent /plan invocations, the planner first searches for a cached template with cosine similarity above similarity_threshold (default: 0.90). If a match is found, the cached task graph structure is reused — skipping the LLM planning call entirely.

[orchestration.plan_cache]
enabled = true                # Enable plan template caching (default: false)
similarity_threshold = 0.90   # Min cosine similarity for a cache hit (default: 0.90)
ttl_days = 30                 # Days since last access before eviction (default: 30)
max_templates = 100            # Maximum cached templates (default: 100)

Templates are stored in SQLite (migration 040_plan_cache.sql) and embedded for similarity search. The cache is keyed by the goal embedding, so semantically equivalent goals (e.g., “deploy staging” and “deploy the staging environment”) can share the same template.

Subgoal-Aware Compaction

When task orchestration is active, the context compaction system tracks subgoal boundaries within the conversation. The SubgoalRegistry records which message ranges belong to each subgoal and their completion state (Active, Completed, Abandoned).

During hard compaction, the summarizer preserves messages associated with active subgoals while aggressively compacting completed subgoal ranges. This prevents compaction from destroying the context that an in-progress orchestration task depends on.

Limitations

• English-only keyword routing: The RuleBasedRouter step 2 (tool keyword matching) only recognizes English keywords such as “implement”, “build”, “edit”. Task descriptions in other languages always fall through to the first-available-agent fallback. Use explicit agent_hint values in planner output for reliable routing.
• Task count cap: The max_tasks limit (default 20) is enforced at planning time. Graphs exceeding this limit are rejected by dag::validate and must be decomposed into smaller sub-goals.
• Dynamic re-planning via verification: When verify_provider is set and a task completes with gaps, PlanVerifier can inject new tasks into the live graph. This is the only supported form of dynamic graph modification — the original task structure is otherwise fixed once confirmed.
• No hot-reload of orchestration config: Changes to the [orchestration] section of config.toml require a restart to take effect.
• planner_max_tokens is reserved: This config field is parsed and stored but not yet applied at runtime. The underlying chat_typed API does not yet support per-call token limits.
• Residual prompt injection risk: Task descriptions and cross-task context are wrapped in ContentSanitizer spotlight tags to mitigate prompt injection, but the risk is not fully eliminated — treat orchestrated task outputs with appropriate caution.
• Single-agent inline execution: When no sub-agents are defined, tasks run inline on the main provider in sequence (no parallelism). Configure [agents] entries and max_parallel > 1 for concurrent execution.

Related

• Sub-Agent Orchestration — sub-agents that execute individual tasks
• Feature Flags
• Configuration — full config reference

Reactive Hooks

Zeph can run shell commands automatically in response to environment changes. Two hook events are supported: working directory changes and file system changes.

Hook Types

cwd_changed

Fires when the agent’s working directory changes — either via the set_working_directory tool or an explicit directory change detected after tool execution.

[[hooks.cwd_changed]]
command = "echo"
args = ["Changed to $ZEPH_NEW_CWD"]

[[hooks.cwd_changed]]
command = "git"
args = ["status", "--short"]

Environment variables available to the hook process:

file_changed

Fires when a file under watch_paths is modified. Changes are detected via notify-debouncer-mini with a 500 ms debounce window — rapid successive modifications produce a single event.

[hooks.file_changed]
watch_paths = ["src/", "config.toml"]

[[hooks.file_changed.handlers]]
command = "cargo"
args = ["check", "--quiet"]

[[hooks.file_changed.handlers]]
command = "echo"
args = ["File changed: $ZEPH_CHANGED_PATH"]

Environment variable available to the hook process:

The set_working_directory Tool

The set_working_directory tool gives the LLM an explicit, persistent way to change the agent’s working directory. Unlike cd in a bash tool call (which is ephemeral and scoped to one subprocess), set_working_directory updates the agent’s global cwd and triggers any cwd_changed hooks.

Use set_working_directory to switch into /path/to/project

After the tool executes, subsequent bash and file tool calls run relative to the new directory.

TUI Indicator

When a hook fires, the TUI status bar shows a short spinner message:

• cwd_changed → Working directory changed…
• file_changed → File changed: <path>…

The indicator disappears once all hook commands for that event have completed.

Configuration Reference

# cwd_changed hooks — run in order when the working directory changes
[[hooks.cwd_changed]]
command = "echo"
args = ["cwd is now $ZEPH_NEW_CWD"]

# file_changed hooks — watch_paths + handler list
[hooks.file_changed]
watch_paths = ["src/", "tests/"]   # relative or absolute paths to watch
debounce_ms = 500                  # debounce window in milliseconds (default: 500)

[[hooks.file_changed.handlers]]
command = "cargo"
args = ["check", "--quiet"]

Logging

Zeph supports persistent file-based logging alongside the standard stderr output. File logging uses tracing-appender for non-blocking writes with automatic log rotation, keeping your agent sessions observable without impacting performance.

How it works

Zeph initialises two independent tracing layers at startup:

The two layers are completely independent. RUST_LOG governs what appears on stderr (or your terminal), while the [logging] config section governs what is written to the log file. You can set RUST_LOG=warn for quiet terminal output while keeping level = "debug" in the config to capture detailed file logs.

Configuration

[logging]
file = ".zeph/logs/zeph.log"  # Path to the log file (default; empty string disables)
level = "info"                 # File log level: trace, debug, info, warn, error
rotation = "daily"             # Rotation strategy: daily, hourly, or never
max_files = 7                  # Rotated log files to retain (default: 7)

Fields

The log directory is created automatically if it does not exist.

CLI override

Use --log-file to override the file path for a single session:

# Log to a custom path
zeph --log-file /tmp/debug-session.log

# Disable file logging for this run
zeph --log-file ""

Priority: --log-file > ZEPH_LOG_FILE env var > [logging] file config value.

Environment variables

Interactive command

During a session, type /log to display the current logging configuration and the last 20 lines of the log file:

> /log
Log file:  .zeph/logs/zeph.log
Level:     info
Rotation:  daily
Max files: 7

Recent entries:
2026-03-09T10:15:32.000Z  INFO zeph_core::agent: turn completed tokens=1523
...

Init wizard

The zeph init wizard includes a logging step where you can configure:

1. Log file path (or leave empty to disable)
2. File log level
3. Log rotation strategy

RUST_LOG vs file level

Tip

For deep debugging sessions, combine RUST_LOG=debug with level = "debug" in the config to get full output in both sinks. Redirect stderr if needed: RUST_LOG=debug zeph 2>/dev/null.

Experiments

The experiments engine lets Zeph autonomously tune its own configuration by running controlled A/B trials against a benchmark. Inspired by karpathy/autoresearch, it varies a single parameter at a time, evaluates both baseline and candidate responses using an LLM-as-judge, and keeps the variation only if the candidate scores higher. This is an optional, feature-gated component (--features experiments) that persists results in SQLite.

Prerequisites

Enable the experiments feature flag before building:

cargo build --release --features experiments

The experiments feature is also included in the full feature set:

cargo build --release --features full

See Feature Flags for the full flag list.

How It Works

Each experiment session follows a four-step loop:

1. Select a parameter — pick one tunable parameter (e.g., temperature, top_p, retrieval_top_k) and generate a candidate value.
2. Run baseline — send a benchmark prompt with the current configuration and record the response.
3. Run candidate — send the same prompt with the varied parameter and record the response.
4. Judge — an LLM evaluator scores both responses on a numeric scale. If the candidate exceeds the baseline by at least min_improvement, the variation is accepted; otherwise it is reverted.

The engine repeats this loop up to max_experiments times per session, staying within max_wall_time_secs and eval_budget_tokens limits.

Tunable Parameters

The engine can vary the following parameters:

Search Space

The search space defines the bounds and resolution for each tunable parameter. It is represented by a SearchSpace containing a list of ParameterRange entries.

Each ParameterRange specifies:

The default search space covers five LLM generation parameters:

You can customize the search space by adding or removing parameters. The remaining tunable parameters (retrieval_top_k, similarity_threshold, temporal_decay) are not included in the default space but can be added manually.

Config Snapshot

A ConfigSnapshot captures the values of all tunable parameters for a single experiment arm. It serves as the bridge between the runtime configuration and the variation engine.

• The baseline snapshot is created from the current Config via ConfigSnapshot::from_config.
• Each variation produces a new snapshot with exactly one parameter changed (snapshot.apply(&variation)).
• The diff method compares two snapshots and returns the single Variation that differs, or None if zero or more than one parameter changed.

Snapshots also provide to_generation_overrides() to extract LLM-relevant parameters for use during evaluation.

Variation Strategies

The variation engine uses a VariationGenerator trait to produce candidate parameter values. Each call to next() returns a Variation that changes exactly one parameter from the baseline. This one-at-a-time constraint isolates the effect of each change, making it possible to attribute score differences to a specific parameter.

All strategies track visited variations via a HashSet<Variation> to avoid re-testing the same configuration. Floating-point values use OrderedFloat for reliable hashing and equality.

Grid

GridStep performs a systematic sweep of every parameter through its discrete steps from min to max. Parameters are swept one at a time: all grid points for the first parameter are enumerated before moving to the next. Already-visited variations are skipped. Returns None when the full grid has been covered.

Grid is the default starting strategy. It provides complete coverage of the discrete search space and is deterministic (no randomness involved). Values are quantized to the nearest step to avoid floating-point accumulation errors.

Random

Random samples uniformly within each parameter’s bounds. At each call, it picks a random parameter, samples a random value from its [min, max] range, and quantizes to the nearest step. The sample is rejected if already visited. After 1000 consecutive rejections, the space is considered exhausted.

Random sampling is seeded (SmallRng::seed_from_u64) for reproducibility. It is useful when the grid is too large to sweep exhaustively or when you want to explore the space without systematic bias.

Neighborhood

Neighborhood perturbs the current best configuration by a small amount. At each call, it picks a random parameter and computes a new value as baseline ± U(-radius, radius) * step, then clamps and quantizes the result. This focuses exploration around a known-good region.

Neighborhood is most useful as a refinement step after a grid or random sweep has identified a promising baseline. The radius parameter (must be positive) controls the perturbation range in units of step. For example, radius = 1.0 with step = 0.1 means perturbations of at most ±0.1 from the baseline value.

Strategy Selection

Choose a strategy based on your goals:

A typical workflow combines strategies across sessions: start with Grid or Random to identify promising regions, then switch to Neighborhood for fine-tuning.

Benchmark Dataset

A benchmark dataset is a TOML file containing a list of test cases. Each case defines a prompt to send to the subject model, with optional context, reference answer, and tags.

[[cases]]
prompt = "Explain the difference between TCP and UDP"
tags = ["knowledge", "networking"]

[[cases]]
prompt = "Write a Python function to find the longest palindromic substring"
reference = "Dynamic programming approach with O(n^2) time"
tags = ["coding", "algorithms"]

[[cases]]
prompt = "Summarize the key ideas of the transformer architecture"
context = "The transformer was introduced in 'Attention Is All You Need' (2017)..."
tags = ["knowledge", "ml"]

Case Fields

Load a dataset from disk with BenchmarkSet::from_file:

#![allow(unused)]
fn main() {
use std::path::Path;
use zeph_core::experiments::BenchmarkSet;
let dataset = BenchmarkSet::from_file(Path::new("benchmarks/default.toml"))?;
dataset.validate()?; // rejects empty case lists
}

LLM-as-Judge Evaluator

The Evaluator scores a subject model’s responses by sending each one to a separate judge model. The judge rates responses on a 1–10 scale across four weighted criteria:

The judge returns structured JSON output (JudgeOutput) containing a numeric score and a one-sentence justification.

Evaluation Flow

1. Subject calls – the evaluator sends each benchmark case to the subject model sequentially, collecting responses.
2. Judge calls – responses are scored in parallel (up to parallel_evals concurrent tasks, default 3) using a separate judge model.
3. Budget check – before each judge call, the evaluator checks cumulative token usage against the configured budget. If the budget is exhausted, remaining cases are skipped.
4. Report – per-case scores are aggregated into an EvalReport.

Security

Subject responses are wrapped in <subject_response> XML boundary tags before being sent to the judge. XML metacharacters (&, <, >) in the response and reference fields are escaped to prevent prompt injection from the evaluated model.

Creating an Evaluator

#![allow(unused)]
fn main() {
use std::sync::Arc;
use zeph_core::experiments::{BenchmarkSet, Evaluator};
use zeph_llm::any::AnyProvider;
fn example(judge: Arc<AnyProvider>, subject: &AnyProvider, benchmark: BenchmarkSet) {
let evaluator = Evaluator::new(
    judge,              // judge model provider
    benchmark,          // loaded benchmark dataset
    100_000,            // token budget for all judge calls
)?
.with_parallel_evals(5); // override default concurrency (3)
}
}

Run the evaluation:

#![allow(unused)]
fn main() {
use zeph_core::experiments::Evaluator;
use zeph_llm::any::AnyProvider;
async fn example(evaluator: &Evaluator, subject: &AnyProvider) {
let report = evaluator.evaluate(subject).await?;
println!("Mean score: {:.1}/10 ({} of {} cases)",
    report.mean_score, report.cases_scored, report.cases_total);
}
}

Evaluation Report

EvalReport contains aggregate metrics and per-case detail:

Each CaseScore entry contains:

Budget Enforcement

The evaluator tracks cumulative token usage across all judge calls with an atomic counter. Before each judge call, the current total is checked against the configured budget_tokens. If the budget is exhausted:

• The current batch of in-flight judge calls is drained
• Remaining cases are excluded from scoring
• The report is marked as partial (is_partial = true)

Budget exhaustion is not a fatal error – the evaluator returns a valid EvalReport with partial results.

Parallel Evaluation

Judge calls run concurrently using FuturesUnordered with a Semaphore controlling the maximum number of in-flight requests. The default concurrency limit is 3 and can be overridden with with_parallel_evals. Subject calls remain sequential to avoid overwhelming the subject model.

Each parallel judge task receives a cloned provider instance so per-task token usage tracking is isolated. The shared atomic token counter aggregates usage across all tasks for budget enforcement.

Safety Model

The experiments engine uses a conservative, double opt-in design:

1. Feature gate — the experiments feature must be compiled in. It is off by default.
2. Config gate — enabled = true must be set in [experiments]. Default is false.
3. No auto-apply — auto_apply defaults to false. When disabled, accepted variations are recorded but not written back to the live configuration. Set to true only when you want the agent to self-tune in production.
4. Budget limits — max_experiments, max_wall_time_secs, and eval_budget_tokens cap resource usage per session.
5. Sandboxed scope — experiments only vary inference and retrieval parameters. They cannot modify tool permissions, security settings, or system prompts.

Configuration

Add an [experiments] section to config.toml:

[experiments]
enabled = true
# eval_model = "claude-sonnet-4-20250514"  # Model for LLM-as-judge evaluation (default: agent's model)
# benchmark_file = "benchmarks/eval.toml"  # Prompt set for A/B comparison
max_experiments = 20                       # Max variations per session (default: 20, range: 1-1000)
max_wall_time_secs = 3600                  # Wall-clock budget per session in seconds (default: 3600, range: 60-86400)
min_improvement = 0.5                      # Minimum score delta to accept a variation (default: 0.5, range: 0.0-100.0)
eval_budget_tokens = 100000                # Token budget for all judge calls in a session (default: 100000, range: 1000-10000000)
auto_apply = false                         # Write accepted variations to live config (default: false)

[experiments.schedule]
enabled = false                            # Enable cron-based automatic runs (default: false)
cron = "0 3 * * *"                         # Cron expression for scheduled runs (default: daily at 03:00)
max_experiments_per_run = 20               # Max variations per scheduled run (default: 20, range: 1-100)
max_wall_time_secs = 1800                  # Wall-time cap per scheduled run in seconds (default: 1800, range: 60-86400)

Field Reference

Persistence

Experiment results are stored in the experiment_results SQLite table (same database as memory). Each row tracks:

• session_id — groups results from a single experiment run
• parameter — which parameter was varied (e.g., temperature)
• value_json — the candidate value as JSON
• baseline_score / candidate_score — numeric scores from the judge
• delta — score difference (candidate minus baseline)
• latency_ms — wall-clock time for the trial
• tokens_used — tokens consumed by the judge call
• accepted — whether the variation met the min_improvement threshold
• source — manual or scheduled

Error Handling

Scheduler Integration

When both experiments and scheduler features are enabled, the experiment engine can run automatically on a cron schedule. This is configured via the [experiments.schedule] section.

How It Works

1. At startup, if experiments.enabled and experiments.schedule.enabled are both true, the scheduler registers an auto-experiment periodic task with the configured cron expression.
2. When the cron fires, an ExperimentTaskHandler spawns a non-blocking tokio::spawn task that runs a full experiment session.
3. An AtomicBool running guard prevents overlapping sessions. If a previous session is still in progress when the next cron trigger fires, the new run is skipped with a warning log.
4. Scheduled runs use ExperimentSource::Scheduled tagging so results can be distinguished from manual runs in the persistence layer (the source column in experiment_results).
5. The schedule.max_wall_time_secs field (default: 1800s) overrides the top-level max_wall_time_secs for scheduled runs, ensuring background sessions finish before the next cron trigger on typical schedules.

Requirements

• Both experiments and scheduler feature flags must be compiled in.
• A valid benchmark_file must be configured (the handler loads the benchmark set on each run).
• The agent’s LLM provider must be available for both subject and judge calls.

Task Kind

The scheduler uses a dedicated TaskKind::Experiment variant (kind string: "experiment"). This can also be used in [[scheduler.tasks]] config entries, though the [experiments.schedule] section is the recommended way to configure automatic runs.

CLI Flags

Two flags provide headless experiment access (requires experiments feature):

Both flags cause the process to exit after completion — they do not start the interactive agent loop.

# Run a one-shot experiment session
zeph --experiment-run --config config.toml

# View past results
zeph --experiment-report

See CLI Reference for the full flag list.

TUI Commands

The following /experiment commands are available in the TUI dashboard:

Only one experiment session can run at a time. Starting a new session while one is already running returns an error message. The TUI displays a spinner with status updates during experiment execution.

Init Wizard

The zeph init wizard includes an experiments step (after the scheduler section). It prompts:

1. Enable autonomous experiments — master switch (enabled field, default: no).
2. Judge model — model used for LLM-as-judge evaluation (eval_model, default: claude-sonnet-4-20250514).
3. Schedule automatic runs — enable cron-based experiment sessions (schedule.enabled, default: no).
4. Cron schedule — 5-field cron expression (schedule.cron, default: 0 3 * * *).

The wizard generates the corresponding [experiments] and [experiments.schedule] sections in the output config file. The ExperimentConfig struct is always compiled (not feature-gated), so the wizard step is available regardless of the experiments feature flag.

See Configuration Wizard for the full wizard walkthrough.

Related

• Scheduler — cron-based task scheduler that drives automatic experiment runs
• Daemon & Scheduler — running the scheduler alongside the gateway and A2A server
• Self-Learning Skills — passive feedback detection and Wilson score ranking
• Model Orchestrator — multi-model routing and fallback chains
• Feature Flags — enabling the experiments feature
• Configuration — full config reference
• Adaptive Inference — runtime model routing that experiments can tune

Use a Cloud Provider

Connect Zeph to Claude, OpenAI, Gemini, or any OpenAI-compatible API instead of local Ollama.

Breaking change (v0.17.0): The old [llm.cloud], [llm.orchestrator], and [llm.router] config sections have been removed. Run zeph --migrate-config to automatically convert your config file.

Claude

ZEPH_CLAUDE_API_KEY=sk-ant-... zeph

Or in config:

[llm]
[[llm.providers]]
type = "claude"
model = "claude-sonnet-4-6"
max_tokens = 4096
# server_compaction = true          # Server-side context compaction (Claude API beta)
# enable_extended_context = true    # 1M token context window (Sonnet/Opus 4.6 only)

Claude does not support embeddings. Use a multi-provider setup to combine Claude chat with Ollama embeddings, or use OpenAI embeddings.

Server-Side Compaction

Enable server_compaction = true to let the Claude API manage context length on the server side. When the context approaches the model’s limit, Claude produces a compact summary in-place. Zeph surfaces the compaction event in the TUI and via the server_compaction_events metric.

Note: Server compaction is not supported on Haiku models. When enabled on Haiku, Zeph emits a WARN and falls back to client-side compaction automatically.

1M Extended Context

For Sonnet 4.6 and Opus 4.6, enable enable_extended_context = true to unlock the 1M token context window. The auto_budget feature scales accordingly. Enable with --extended-context CLI flag or in the provider entry in config.

Gemini

ZEPH_GEMINI_API_KEY=AIza... zeph

Or in config:

[llm]
[[llm.providers]]
type = "gemini"
model = "gemini-2.0-flash"    # or "gemini-2.5-pro" for extended thinking
max_tokens = 8192
# embedding_model = "text-embedding-004"  # enable Gemini-native embeddings
# thinking_level = "medium"              # Gemini 2.5+ only: minimal, low, medium, high

Gemini supports embeddings natively when embedding_model is set — no separate Ollama instance required. See LLM Providers — Gemini for the full feature matrix.

OpenAI

ZEPH_OPENAI_API_KEY=sk-... zeph

[llm]
[[llm.providers]]
type = "openai"
base_url = "https://api.openai.com/v1"
model = "gpt-5.2"
max_tokens = 4096
embedding_model = "text-embedding-3-small"
reasoning_effort = "medium"   # optional: low, medium, high (for o3, etc.)

When embedding_model is set, Qdrant subsystems use it automatically for skill matching and semantic memory.

Compatible APIs

Use type = "compatible" with the appropriate base_url:

[llm]
[[llm.providers]]
name = "groq"
type = "compatible"
base_url = "https://api.groq.com/openai/v1"
model = "llama-3.3-70b-versatile"
max_tokens = 4096

Common base_url values:

Hybrid Setup

Embeddings via free local Ollama, chat via paid Claude API:

[llm]
routing = "cascade"   # try cheapest provider first

[[llm.providers]]
name = "local"
type = "ollama"
model = "qwen3:8b"
embedding_model = "qwen3-embedding"
embed = true          # use this provider for embeddings

[[llm.providers]]
name = "cloud"
type = "claude"
model = "claude-sonnet-4-6"
max_tokens = 4096
default = true        # use this provider for chat by default

See Adaptive Inference for routing strategy options.

Interactive Setup

Run zeph init and select your provider in Step 2. The wizard handles model names, base URLs, and API keys. See Configuration Wizard.

Configuration Recipes

Copy-paste configs for the most common Zeph setups. Each recipe shows only the sections that differ from the defaults — paste them into a new config.toml and run:

zeph --config config.toml

Tip: Run zeph init for an interactive wizard that generates the config file for you. These recipes are for when you want to start from a known baseline or understand what each setting does.

Which recipe do I need?

1. Minimal local (Ollama)

[llm]
[[llm.providers]]
type = "ollama"
base_url = "http://localhost:11434"
model = "qwen3:8b"
embedding_model = "qwen3-embedding"  # for semantic skill matching

[vault]
backend = "env"  # no secrets needed for local Ollama

[memory]
history_limit = 20  # keep context lean for smaller models

2. Full cloud — Claude

[llm]
# Claude does not provide embeddings; skill matching uses keyword fallback.
# For semantic memory, combine with an Ollama embedding model (see recipe #5).
[[llm.providers]]
type = "claude"
model = "claude-sonnet-4-6"
max_tokens = 8192
# server_compaction = true  # let Claude API manage context instead of client-side compaction

[vault]
backend = "env"  # reads ZEPH_CLAUDE_API_KEY from environment

[memory]
history_limit = 50

3. Full cloud — OpenAI

[llm]
[[llm.providers]]
type = "openai"
base_url = "https://api.openai.com/v1"
model = "gpt-4o-mini"
max_tokens = 4096
embedding_model = "text-embedding-3-small"  # used for skill matching and semantic memory

[vault]
backend = "env"  # reads ZEPH_OPENAI_API_KEY from environment

[memory]
history_limit = 50

4. Compatible provider

[llm]
[[llm.providers]]
name = "groq"
type = "compatible"
base_url = "https://api.groq.com/openai/v1"
model = "llama-3.3-70b-versatile"
max_tokens = 4096
# API key: set ZEPH_COMPATIBLE_GROQ_API_KEY in your environment

[vault]
backend = "env"

5. Hybrid: Ollama + Claude fallback

[llm]
routing = "cascade"   # try cheapest first; fall back on failure

[[llm.providers]]
name = "ollama"
type = "ollama"
base_url = "http://localhost:11434"
model = "qwen3:8b"
embedding_model = "qwen3-embedding"     # local embeddings — always available offline
embed = true

[[llm.providers]]
name = "claude"
type = "claude"
model = "claude-haiku-4-5-20251001"    # fast + cheap fallback
max_tokens = 4096
default = true

[vault]
backend = "env"

6. Orchestrator for complex tasks

[llm]
routing = "task"   # route by task type

[[llm.providers]]
name = "planner"
type = "ollama"
base_url = "http://localhost:11434"
model = "qwen3:14b"            # larger model for planning and goal decomposition
embedding_model = "qwen3-embedding"
embed = true

[[llm.providers]]
name = "executor"
type = "ollama"
base_url = "http://localhost:11434"
model = "qwen3:8b"             # smaller model for tool execution steps
default = true

[orchestration]
enabled = true            # enable /plan commands and task graph execution
max_tasks = 20
max_parallel = 2          # conservative for local inference
confirm_before_execute = true

[vault]
backend = "env"

7. Coding assistant

[llm]
[[llm.providers]]
type = "ollama"
base_url = "http://localhost:11434"
model = "qwen3:8b"
embedding_model = "qwen3-embedding"

[vault]
backend = "env"

# AST-based code indexing: builds a semantic map of the repository.
# Uses SQLite vector backend by default; add recipe #10 for Qdrant.
[index]
enabled = true
watch = true          # reindex incrementally on file changes
max_chunks = 12
repo_map_tokens = 500 # include a structural map in the system prompt

[tools.shell]
allow_network = false  # restrict shell tools to local-only for coding sessions
confirm_patterns = ["rm ", "git push"]

# LSP code intelligence via mcpls MCP server.
# mcpls auto-detects language servers from project files.
[[mcp.servers]]
id = "mcpls"
command = "mcpls"
args = ["--workspace-root", "."]
timeout = 60  # LSP servers need warmup time

8. Telegram bot

[llm]
[[llm.providers]]
type = "claude"
model = "claude-sonnet-4-6"
max_tokens = 4096

[vault]
backend = "env"  # reads ZEPH_CLAUDE_API_KEY and ZEPH_TELEGRAM_BOT_TOKEN

[telegram]
# token = "your-bot-token"  # or set ZEPH_TELEGRAM_BOT_TOKEN env var
allowed_users = ["yourusername"]  # restrict access — do not leave empty on a public server

[memory]
history_limit = 50  # longer history for async messaging patterns

[security]
autonomy_level = "supervised"  # always ask before destructive operations

[daemon]
enabled = true         # keep the process alive and restart on crash
pid_file = "~/.zeph/zeph.pid"

9. Privacy-first (fully local)

[llm]
[[llm.providers]]
type = "ollama"
base_url = "http://localhost:11434"
model = "qwen3:8b"
embedding_model = "qwen3-embedding"

[vault]
backend = "env"  # no secrets needed

[memory]
history_limit = 30
vector_backend = "sqlite"  # embedded vector index — no Qdrant required

[memory.semantic]
enabled = true

[tools.shell]
allow_network = false
blocked_commands = ["curl", "wget", "nc", "ssh", "scp", "rsync"]
confirm_patterns = ["rm ", "git push", "sudo "]

[security]
autonomy_level = "supervised"
redact_secrets = true

[security.content_isolation]
enabled = true

[a2a]
enabled = false  # no agent-to-agent network server

[gateway]
enabled = false  # no HTTP gateway

[observability]
exporter = ""  # no telemetry

10. Semantic memory add-on (Qdrant)

[memory]
qdrant_url = "http://localhost:6334"
vector_backend = "qdrant"   # switch from embedded SQLite to external Qdrant

[memory.semantic]
enabled = true
recall_limit = 5             # messages recalled per query
vector_weight = 0.7          # blend of vector similarity vs keyword (FTS5)
keyword_weight = 0.3
temporal_decay_enabled = true
temporal_decay_half_life_days = 30  # older memories fade gradually
mmr_enabled = true           # diversify results (avoid near-duplicate recalls)
mmr_lambda = 0.7

Combining recipes

Recipes 1–9 are standalone base configs. Recipe 10 (semantic memory) can be layered on top of any of them by merging the [memory] sections.

Common combinations:

• Local with memory: recipe 1 + recipe 10 (use vector_backend = "sqlite" for zero dependencies)
• Cloud + memory: recipe 2 or 3 + recipe 10 (OpenAI handles embeddings natively)
• Privacy + memory: recipe 9 already includes vector_backend = "sqlite" — semantic memory is on
• Coding + orchestrator: recipe 7 + recipe 6 sections for multi-model routing

For the full configuration reference with all available options, see Configuration.

Run via Telegram

Deploy Zeph as a Telegram bot with streaming responses, MarkdownV2 formatting, and user whitelisting.

Setup

1. Create a bot via @BotFather — send /newbot and copy the token.

2. Configure the token:

   ZEPH_TELEGRAM_TOKEN="123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11" zeph
   

   Or store in the age vault:

   zeph vault set ZEPH_TELEGRAM_TOKEN "123456:ABC..."
   zeph --vault age
   

3. Required — restrict access to specific usernames:

   [telegram]
   allowed_users = ["your_username"]
   

   The bot refuses to start without at least one allowed user. Messages from unauthorized users are silently rejected.

Bot Commands

Streaming

Telegram has API rate limits, so streaming works differently from CLI:

• First chunk sends a new message immediately
• Subsequent chunks edit the existing message in-place (throttled to one edit per 10 seconds)
• Long messages (>4096 chars) are automatically split
• MarkdownV2 formatting is applied automatically

Voice and Image Support

• Voice notes: automatically transcribed via STT when stt feature is enabled
• Photos: forwarded to the LLM for visual reasoning (requires vision-capable model)
• See Audio & Vision for backend configuration

Other Channels

Zeph also supports Discord, Slack, CLI, and TUI. See Channels for the full reference.

Add Custom Skills

Create your own skills to teach Zeph new capabilities. A skill is a single SKILL.md file inside a named directory.

Skill Structure

.zeph/skills/
└── my-skill/
    └── SKILL.md

SKILL.md Format

Two parts: a YAML header and a markdown body.

---
name: my-skill
description: Short description of what this skill does.
---
# My Skill

Instructions and examples go here. This content is injected verbatim
into the LLM context when the skill is matched.

Header Fields

Secret-Gated Skills

If a skill requires API credentials or tokens, declare them with x-requires-secrets:

---
name: github-api
description: GitHub API integration — search repos, create issues, review PRs.
x-requires-secrets: github-token, github-org
---

Secret names use lowercase with hyphens. They map to vault keys with the ZEPH_SECRET_ prefix:

Activation gate: if any declared secret is missing from the vault, the skill is excluded from the prompt. It will not be matched or suggested until the secret is provided.

Scoped injection: when the skill is active, its secrets are injected as environment variables into shell commands the skill executes. Only the secrets declared by the active skill are exposed — not all vault secrets.

Store secrets with the vault CLI:

zeph vault set ZEPH_SECRET_GITHUB_TOKEN ghp_yourtokenhere
zeph vault set ZEPH_SECRET_GITHUB_ORG my-org

See Vault — Custom Secrets for full details.

Name Rules

Lowercase letters, numbers, and hyphens only. No leading, trailing, or consecutive hyphens. Must match the directory name.

Skill Resources

Add reference files alongside SKILL.md:

.zeph/skills/
└── system-info/
    ├── SKILL.md
    └── references/
        ├── linux.md
        ├── macos.md
        └── windows.md

Resources in scripts/, references/, and assets/ are loaded lazily on first skill activation (not at startup). OS-specific files (linux.md, macos.md, windows.md) are filtered by platform automatically.

Local file references in the skill body (e.g., [see config](references/config.md)) are validated at load time. Broken links and path traversal attempts (../../../etc/passwd) are rejected.

Configuration

[skills]
paths = [".zeph/skills", "/home/user/my-skills"]
max_active_skills = 5

Skills from multiple paths are scanned. If a skill with the same name appears in multiple paths, the first one found takes priority.

Testing Your Skill

1. Place the skill directory under .zeph/skills/
2. Start Zeph — the skill is loaded automatically
3. Send a message that should match your skill’s description
4. Run /skills to verify it was selected

Changes to SKILL.md are hot-reloaded without restart (500ms debounce).

Installing External Skills

Use zeph skill install to add skills from git repositories or local paths:

# From a git URL — clones the repo into ~/.config/zeph/skills/
zeph skill install https://github.com/user/zeph-skill-example.git

# From a local path — copies the skill directory
zeph skill install /path/to/my-skill

Installed skills are placed in ~/.config/zeph/skills/ and automatically discovered at startup. They start at the quarantined trust level (restricted tool access). To grant full access:

zeph skill verify my-skill        # check BLAKE3 integrity
zeph skill trust my-skill trusted  # promote trust level

In an active session, use /skill install <url|path> and /skill remove <name> — changes are hot-reloaded without restart.

See Skill Trust Levels for the full security model.

Deep Dives

• Skills — how embedding-based matching works
• Self-Learning Skills — automatic skill evolution
• Skill Trust Levels — security model for imported skills

MCP Integration

Connect external tool servers via Model Context Protocol (MCP). Tools are discovered, embedded, and matched alongside skills using the same cosine similarity pipeline — only relevant MCP tools are injected into the prompt, so adding more servers does not inflate token usage.

Configuration

Stdio Transport (spawn child process)

[[mcp.servers]]
id = "filesystem"
command = "npx"
args = ["-y", "@anthropic/mcp-filesystem"]

HTTP Transport (remote server)

[[mcp.servers]]
id = "remote-tools"
url = "http://localhost:8080/mcp"

Per-Server Trust and Tool Allowlist

Each [[mcp.servers]] entry accepts a trust_level and an optional tool_allowlist to control which tools from that server are exposed to the agent.

# Operator-controlled server: all tools allowed, SSRF checks skipped
[[mcp.servers]]
id = "internal-tools"
command = "npx"
args = ["-y", "@acme/internal-mcp"]
trust_level = "trusted"

# Community server: only the listed tools are exposed
[[mcp.servers]]
id = "filesystem"
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/workspace"]
trust_level = "untrusted"
tool_allowlist = ["read_file", "list_directory", "search_files"]

# Sandboxed server: fail-closed — no tools exposed unless explicitly listed
[[mcp.servers]]
id = "experimental"
url = "http://localhost:9000/mcp"
trust_level = "sandboxed"
tool_allowlist = ["safe_tool_a", "safe_tool_b"]

The default trust level is untrusted. When tool_allowlist is not set on an untrusted server, a startup warning is logged to encourage explicit allowlisting of the tools you intend to use.

Security

[mcp]
allowed_commands = ["npx", "uvx", "node", "python", "python3"]
max_dynamic_servers = 10

allowed_commands restricts which binaries can be spawned as MCP stdio servers. Commands containing path separators (/ or \) are rejected to prevent path traversal — only bare command names resolved via $PATH are accepted. max_dynamic_servers limits the number of servers added at runtime.

Environment variables containing secrets (API keys, tokens, credentials — 21 variables plus BASH_FUNC_* patterns) are automatically stripped from MCP child process environments. See MCP Security for the full blocklist.

Dynamic Management

Add and remove MCP servers at runtime via chat commands:

/mcp add filesystem npx -y @anthropic/mcp-filesystem
/mcp add remote-api http://localhost:8080/mcp
/mcp list
/mcp remove filesystem

After adding or removing a server, Qdrant registry syncs automatically for semantic tool matching.

Native Tool Integration (Claude / OpenAI)

When the active provider supports structured tool calling (Claude, OpenAI), MCP tools are exposed as native ToolDefinitions — no text injection into the system prompt.

McpToolExecutor implements tool_definitions(), which returns all connected MCP tools as typed definitions with qualified names in server_id:tool_name format. The agent calls execute_tool_call() when the LLM returns a structured tool_use block for an MCP tool. The executor parses the qualified name, looks up the tool in the shared list, and dispatches the call to manager.call_tool().

The shared tool list (Arc<RwLock<Vec<McpTool>>>) is updated automatically when servers are added or removed via /mcp add / /mcp remove. This means the provider sees the current tool set on every turn without requiring a restart.

For providers without native tool support (Ollama with tool_use = false, Candle), append_mcp_prompt() falls back to injecting tool descriptions as text into the system prompt, filtered by relevance score via Qdrant.

Semantic Tool Discovery

By default, MCP tools are matched against the current request using the same cosine similarity pipeline as skills. The SemanticToolIndex adds a configurable discovery layer on top of this baseline:

[mcp.tool_discovery]
strategy = "Embedding"          # "Embedding" (default), "Llm", or "None"
top_k = 10                      # Maximum tools to inject per turn (default: 10)
min_similarity = 0.30           # Minimum cosine similarity for a tool to be included (default: 0.30)
always_include = ["read_file"]  # Tool names that bypass the similarity gate entirely
min_tools_to_filter = 5         # Only apply filtering when the server exposes at least this many tools (default: 5)

strategy controls how candidate tools are ranked:

always_include accepts bare tool names or qualified server_id:tool_name strings. Entries in this list are injected regardless of their similarity score. Use it for tools the agent should always have available (e.g., read_file, list_directory).

min_tools_to_filter prevents aggressive filtering on small servers. When a server exposes fewer tools than this value, all tools from that server are included unconditionally.

MCP Elicitation

MCP servers can request structured user input mid-task via the elicitation/create protocol method. This allows a server to prompt for missing parameters, confirmations, or credentials without requiring a separate out-of-band channel.

Enabling Elicitation

Elicitation is disabled by default. Enable it globally or per server:

[mcp]
elicitation_enabled = true       # global default (default: false)
elicitation_timeout = 120        # seconds to wait for user input (default: 120)
elicitation_queue_capacity = 16  # max queued requests (default: 16)
elicitation_warn_sensitive_fields = true  # warn before sensitive field prompts

[[mcp.servers]]
id = "my-server"
command = "npx"
args = ["-y", "@acme/mcp-server"]
elicitation_enabled = true       # per-server override (overrides global default)

Sandboxed trust-level servers are never permitted to elicit regardless of config.

How It Works

When a server sends elicitation/create:

• CLI: the user sees a phishing-prevention header showing the server name, followed by field prompts. Fields are typed (string, integer, number, boolean, enum).
• Non-interactive channels (Telegram, ACP without a connected client): the request is automatically declined.
• If the request queue is full (exceeds elicitation_queue_capacity), the request is auto-declined with a warning log instead of blocking or accumulating indefinitely.

Security Notes

• Always review which servers have elicitation_enabled = true. A compromised server with elicitation access can prompt for arbitrary user input.
• elicitation_warn_sensitive_fields = true (default) logs a warning when field names match secret patterns before prompting.
• See Elicitation Security for the full security model.

How Matching Works

MCP tools are embedded in Qdrant (zeph_mcp_tools collection) with BLAKE3 content-hash delta sync. Unified matching injects both skills and MCP tools into the system prompt by relevance score — keeping prompt size O(K) instead of O(N) where N is total tools across all servers.

LSP Code Intelligence

Zeph can use Language Server Protocol (LSP) servers — rust-analyzer, pyright, gopls, and others — for compiler-level code understanding. The integration is provided by mcpls, an MCP-to-LSP bridge that exposes 16 LSP capabilities as standard MCP tools.

No changes to Zeph itself are required. Enabling LSP intelligence is purely a configuration step.

What You Get

• Type information: ask “what type is this variable?” and get the compiler’s answer, not a guess.
• Definition navigation: jump to the source of any function, type, or trait.
• Reference analysis: find every usage of a symbol before renaming or deleting it.
• Diagnostics: get compiler errors and warnings for any file on demand.
• Call hierarchy: trace data flow up and down the call graph.
• Symbol search: find any symbol across the entire workspace by name.
• Code actions: apply quick fixes and refactorings suggested by the language server.
• Safe rename: rename a symbol across all files in one step.

Prerequisites

• Zeph with MCP support (always-on since v0.13)

• mcpls binary:

  cargo install mcpls
  

• At least one language server for your project:

  Language	Language Server	Install
  Rust	rust-analyzer	rustup component add rust-analyzer
  Python	pyright	pip install pyright or npm install -g pyright
  TypeScript	typescript-language-server	npm install -g typescript-language-server
  Go	gopls	go install golang.org/x/tools/gopls@latest

Quick Start

Run zeph --init and answer Yes when asked:

== MCP: LSP Code Intelligence ==

mcpls detected.
Enable LSP code intelligence via mcpls? (Y/n)

Alternatively, add the configuration manually (see Configuration below).

Verify the Setup

Start Zeph and ask a question that triggers LSP:

You: What type does the `build_config` function return in src/init.rs?

The agent will call get_hover and return the compiler’s type signature. If you see a meaningful type instead of an error, mcpls is working.

Configuration

The wizard generates the following block in config.toml:

[[mcp.servers]]
id = "mcpls"
command = "mcpls"
args = ["--workspace-root", "."]
# LSP servers need warmup time. The default MCP timeout is 30s; 60s is recommended for mcpls.
timeout = 60

For a workspace with multiple roots (e.g. a monorepo):

[[mcp.servers]]
id = "mcpls"
command = "mcpls"
args = [
    "--workspace-root", "./backend",
    "--workspace-root", "./frontend",
]
timeout = 60

Advanced: mcpls.toml

For multi-language projects or to pin specific language servers, create mcpls.toml in your workspace root. mcpls auto-detects language servers from project files (Cargo.toml, pyproject.toml, tsconfig.json, go.mod) when no mcpls.toml is present.

Rust project:

[servers.rust-analyzer]
command = "rust-analyzer"
languages = ["rust"]

Python project:

[servers.pyright]
command = "pyright-langserver"
args = ["--stdio"]
languages = ["python"]

TypeScript project:

[servers.typescript]
command = "typescript-language-server"
args = ["--stdio"]
languages = ["typescript", "javascript"]

Go project:

[servers.gopls]
command = "gopls"
languages = ["go"]

Multi-language project:

[servers.rust-analyzer]
command = "rust-analyzer"
languages = ["rust"]

[servers.pyright]
command = "pyright-langserver"
args = ["--stdio"]
languages = ["python"]

Available Tools

mcpls exposes the following MCP tools. Zeph selects the appropriate tool based on context.

Core (P0 — use these daily)

Navigation (P1)

Editing (P2)

Diagnostics & Debug

Usage Patterns

Diagnostic-Driven Workflow

After editing a file, verify correctness:

1. Edit the file with the shell tool.
2. Call get_diagnostics on the changed file.
3. For each error, call get_code_actions to see available fixes.
4. Apply fixes or edit manually.
5. Repeat until get_diagnostics returns no errors.

Impact Analysis Before Refactoring

1. Call get_references on the symbol to change.
2. Review all usage sites.
3. Make changes.
4. Call get_diagnostics on all affected files.

Type Exploration

1. Call get_hover on an unknown symbol to see its type and docs.
2. Call get_definition to read the implementation.
3. Call get_references to understand usage patterns.

Call Graph Analysis

1. Call prepare_call_hierarchy on a function.
2. Call incoming_calls to see what calls it (data consumers).
3. Call outgoing_calls to see what it calls (dependencies).

Troubleshooting

“Server not starting” or no results:

Check the language server logs:

Ask: Show me the mcpls server logs.

The agent will call server_logs and display the raw output. Common causes:

• Language server not installed or not in PATH.
• Wrong working directory — confirm --workspace-root matches your project root.

“Stale diagnostics after editing a file”:

mcpls does not forward textDocument/didChange notifications to the LSP server. Diagnostics reflect the state of the file on disk. After editing, save the file before calling get_diagnostics.

“Timeout errors”:

The default timeout = 60 should be enough for most language servers. If rust-analyzer or another slow server times out on first use (it performs initial indexing), increase the timeout:

[[mcp.servers]]
id = "mcpls"
command = "mcpls"
args = ["--workspace-root", "."]
timeout = 120

“No results for hover or definition”:

mcpls opens files lazily. The first access to a file may be slower. If results are consistently empty, verify that the language server is installed and that mcpls.toml (if present) has the correct languages mapping for your file type.

LSP Context Injection

Note

Requires the lsp-context feature flag (included in --features full).

Zeph can automatically inject LSP-derived data into the agent’s context without the LLM needing to make explicit tool calls. Three hooks are provided:

• Diagnostics on save — after every write_file tool call, Zeph fetches diagnostics from the LSP server and injects errors directly into the next LLM turn. The agent sees compiler errors immediately and can fix them without manual intervention.
• Hover on read (opt-in) — after read_file, Zeph pre-fetches hover information for key symbol definitions in the file and injects it as annotations. Disabled by default.
• References on rename — before rename_symbol, Zeph fetches all reference locations and presents them to the LLM for review.

Enabling

# CLI flag — enable for this session
zeph --lsp-context

# Config file — enable permanently

[agent.lsp]
enabled = true

The wizard (zeph --init) prompts for this setting after the mcpls step. It is skipped automatically when mcpls is not configured.

Configuration

[agent.lsp]
enabled = true
mcp_server_id = "mcpls"   # MCP server that provides LSP tools (default: "mcpls")
token_budget = 2000        # Max tokens to spend on injected LSP context per turn

[agent.lsp.diagnostics]
enabled = true             # Inject diagnostics after write_file (default: true when [agent.lsp] is enabled)
max_per_file = 20          # Max diagnostics per file
max_files = 5              # Max files per injection batch
min_severity = "error"     # Minimum severity: "error", "warning", "info", or "hint"

[agent.lsp.hover]
enabled = false            # Pre-fetch hover info on read_file (default: false — opt-in)
max_symbols = 10           # Max symbols to fetch hover for per file

[agent.lsp.references]
enabled = true             # Inject reference list before rename_symbol (default: true)
max_refs = 50              # Max references to show per symbol

How Injection Works

LSP notes are injected into the message history (not the system prompt) as a [lsp ...] prefixed user message, following the same pattern used by semantic recall, graph facts, and code context:

[lsp diagnostics]
src/main.rs:42:5 error[E0308]: mismatched types — expected `u32`, found `String`
src/main.rs:55:1 error[E0599]: no method named `foo` found for struct `Bar`

Notes exceeding token_budget are dropped with a truncation marker. The budget resets each turn.

Graceful Degradation

LSP context injection is fully optional. When the configured MCP server is unavailable:

• Hooks silently skip — the agent continues working normally
• No error is logged or shown to the user
• Individual tool call failures are logged at debug level only

This means the agent works correctly whether or not mcpls is installed or running.

TUI: /lsp Command

In TUI mode, type /lsp to show LSP context injection status:

• Whether hooks are active and the configured MCP server is connected
• Count of diagnostics, hover entries, and references injected this session
• Token budget usage for the current turn

Requirements

The lsp-context feature requires the mcp feature (always-on since v0.13) and a configured mcpls MCP server. See the Configuration section above for mcpls setup.

ACP LSP Extension

Requires the acp feature flag (included in --features full).

When Zeph runs as an ACP server (connected to an IDE like Zed, Helix, or VS Code), the IDE can expose its own LSP capabilities directly to the agent. This is the third and most integrated path to LSP intelligence: instead of running a separate mcpls process, the agent sends LSP requests back to the IDE through the ACP connection.

How It Works

During the ACP initialize handshake, the IDE can advertise LSP support by including "lsp": true in its meta capabilities. When Zeph sees this flag, it creates an AcpLspProvider that sends ext_method requests back to the IDE for LSP operations.

The agent can also fall back to an McpLspProvider (mcpls) when the IDE does not advertise LSP support but mcpls is configured as an MCP server. Priority order:

1. ACP provider (IDE-proxied) — used when the IDE advertises meta["lsp"]
2. MCP provider (mcpls) — used when mcpls is configured under [[mcp.servers]]

Supported Methods

The ACP LSP extension exposes seven methods via ext_method:

Push Notifications

The IDE can also push data to the agent via ext_notification:

Pushed diagnostics are stored in a bounded DiagnosticsCache with LRU eviction. The cache size is controlled by max_diagnostic_files (default: 5).

Configuration

[acp.lsp]
enabled = true                     # Enable LSP extension when IDE supports it (default: true)
auto_diagnostics_on_save = true    # Fetch diagnostics on lsp/didSave notification (default: true)
max_diagnostics_per_file = 20      # Max diagnostics accepted per file (default: 20)
max_diagnostic_files = 5           # Max files in DiagnosticsCache, LRU eviction (default: 5)
max_references = 100               # Max reference locations returned (default: 100)
max_workspace_symbols = 50         # Max workspace symbol search results (default: 50)
request_timeout_secs = 10          # Timeout for LSP ext_method calls in seconds (default: 10)

See Configuration Reference for the full [acp.lsp] section.

Capability Negotiation

The LSP extension is negotiated per-session. The flow is:

1. IDE sends initialize with meta: { "lsp": true } in client capabilities.
2. Zeph responds with the list of supported LSP methods in its server capabilities.
3. The IDE can now receive ext_method calls for the advertised LSP methods.
4. The IDE can send ext_notification for lsp/publishDiagnostics and lsp/didSave.

If the IDE does not include "lsp": true, the ACP LSP provider is marked as unavailable and Zeph falls back to the MCP provider (mcpls) if configured.

Coordinates

All positions use 1-based line and character coordinates (ACP/MCP convention). The IDE is responsible for converting between 1-based (ACP) and 0-based (LSP) coordinates.

Limitations

• No live file sync: mcpls does not support textDocument/didChange. Edits are invisible to the LSP server until the file is saved and mcpls reopens it. Always save before querying.
• No file watcher: workspace/didChangeWatchedFiles is not implemented. Adding new files requires restarting mcpls.
• Pull-based diagnostics: diagnostics are fetched on demand, not pushed proactively. Use get_cached_diagnostics for fast repeated checks. When lsp-context injection is enabled, diagnostics are fetched automatically after write_file with a short delay for LSP re-analysis. When using the ACP LSP extension with auto_diagnostics_on_save, diagnostics are fetched automatically on lsp/didSave notifications from the IDE.
• Stale diagnostics on first fetch: After a file write, there is a 200ms delay before fetching to allow the language server to begin re-analysis. Diagnostics may still reflect the previous file state if the server is slow.
• Untrusted code: LSP server output (diagnostics, hover text, server_logs) may contain content from the source files being analyzed. If analyzing untrusted code (e.g., cloned repositories), adversarial content in comments or string literals could appear in the LLM context. Zeph’s content sanitizer automatically wraps this output for isolation.
• ACP LSP is !Send: The AcpLspProvider holds Rc<RefCell<...>> state and must run inside a tokio::task::LocalSet. HTTP transport sessions requiring Send are not yet supported.

IDE Integration

Zeph can act as a first-class coding assistant inside Zed and VS Code through the Agent Client Protocol. The editor spawns Zeph as a stdio subprocess and communicates over JSON-RPC; no daemon or network port is required.

For a full reference on ACP capabilities, transports, and configuration options, see ACP (Agent Client Protocol).

Prerequisites

• Zeph installed and configured (zeph init completed, at least one LLM provider active).
• ACP feature enabled in the binary (included in the default release build).
• Zed 1.0+ with the official ACP extension, or VS Code with the ACP extension.

Verify that ACP is available in your binary:

zeph --acp-manifest

Expected output:

{
  "name": "zeph",
  "version": "0.15.3",
  "transport": "stdio",
  "command": ["zeph", "--acp"],
  "capabilities": ["prompt", "cancel", "load_session", "set_session_mode", "config_options", "ext_methods"],
  "description": "Zeph AI Agent",
  "readiness": {
    "notification": { "method": "zeph/ready" },
    "http": { "health_endpoint": "/health", "statuses": [200, 503] }
  }
}

If the command is not found, ensure the Zeph binary directory is on your PATH (see Troubleshooting).

Enabling ACP in config.toml

Add the following section to your config.toml if it is not already present:

[acp]
enabled = true
# Optional: restrict which skills are exposed over ACP
# allowed_skills = ["code-review", "refactor"]

The enabled flag makes plain zeph auto-start ACP using the configured transport value. The explicit CLI flags (--acp, --acp-http, --acp-manifest) still work independently of this setting. No network configuration is needed for the default stdio transport used by IDE extensions.

Launching Zeph as an ACP stdio server

The editor extension manages the process lifecycle. When the user opens the assistant panel, the extension runs:

zeph --acp

Zeph reads JSON-RPC messages from stdin and writes responses to stdout. You can test the connection manually:

echo '{"jsonrpc":"2.0","id":1,"method":"acp/manifest"}' | zeph --acp

Readiness checks for extensions

IDE integrations can stop guessing when Zeph has finished warming up:

• stdio transport: wait for the first zeph/ready notification before sending the first interactive request. Example payload:

{"jsonrpc":"2.0","method":"zeph/ready","params":{"version":"0.15.0","pid":12345,"log_file":"/path/to/zeph.log"}}

• HTTP transport: poll GET /health until it returns 200 OK.

curl -fsS http://127.0.0.1:8080/health

If startup is still in progress, Zeph returns 503 Service Unavailable with {"status":"starting", ...}. Once ready, the response becomes {"status":"ok","version":"...","uptime_secs":...}.

IDE setup

Zed

1. Open Settings (Cmd+, on macOS, Ctrl+, on Linux).
2. Add the agent configuration under "agent":

{
  "agent": {
    "profiles": {
      "zeph": {
        "provider": "acp",
        "binary": "zeph",
        "args": ["--acp"]
      }
    },
    "default_profile": "zeph"
  }
}

3. Reload the window. The Zeph entry appears in the assistant model selector.

VS Code

Install the ACP extension from the marketplace, then add to settings.json:

{
  "acp.agents": [
    {
      "name": "Zeph",
      "command": "zeph",
      "args": ["--acp"]
    }
  ]
}

Subagent visibility features

When Zeph orchestrates subagents internally, the IDE extension surfaces the execution hierarchy directly in the chat view.

Subagent nesting

Every session_update message carries a _meta.claudeCode.parentToolUseId field that identifies which parent tool call spawned the update. ACP-aware extensions (Zed, VS Code) use this field to nest subagent output under the originating tool call card in the chat panel, giving a clear visual tree of agent activity.

Live terminal streaming

AcpShellExecutor streams bash output in real time. Each chunk is delivered as a session_update with a _meta.terminal_output payload. The extension appends these chunks to the tool call card as they arrive, so you see command output line by line without waiting for the process to finish.

Agent following

When Zeph reads or writes a file, the ToolCall.location field carries the filePath of the target. The IDE extension receives this location and moves the editor cursor to the active file, keeping the viewport synchronized with what the agent is working on.

Troubleshooting

zeph: command not found

The binary is not on your PATH. Add the installation directory:

# Cargo install default
export PATH="$HOME/.cargo/bin:$PATH"

Add the export to your shell profile (~/.zshrc, ~/.bashrc) to make it permanent.

--acp flag not recognized

Your binary was built without the ACP feature. Rebuild with:

cargo install zeph --features acp

Or use the official release binary, which includes ACP by default.

Extension connects but returns no responses

Run zeph --acp-manifest in the terminal to confirm the process starts and outputs valid JSON. If it hangs or errors, check your config.toml for syntax errors and verify that [acp] enabled = true is present.

Verifying the manifest

zeph --acp-manifest

The capabilities array must include "prompt" for basic chat to work. If any capability is missing, ensure you are running the latest release.

Semantic Memory

Enable semantic search to retrieve contextually relevant messages from conversation history using vector similarity.

Requires an embedding model. Ollama with qwen3-embedding is the default. Claude API does not support embeddings natively — use the orchestrator to route embeddings through Ollama while using Claude for chat.

Vector Backend

Zeph supports two vector backends for storing embeddings:

The sqlite backend stores vectors in the same SQLite database as conversation history and performs cosine similarity search in-process. It requires no external services, making it ideal for local development and single-user deployments.

Setup with SQLite Backend (Quickstart)

No external services needed:

[memory]
vector_backend = "sqlite"

[memory.semantic]
enabled = true
recall_limit = 5

The vector tables are created automatically via migration 011_vector_store.sql.

Setup with Qdrant Backend

1. Start Qdrant:

   docker compose up -d qdrant
   

2. Enable semantic memory in config:

   [memory]
   vector_backend = "qdrant"  # default, can be omitted
   
   [memory.semantic]
   enabled = true
   recall_limit = 5
   

3. Automatic setup: Qdrant collection (zeph_conversations) is created automatically on first use with correct vector dimensions (1024 for qwen3-embedding) and Cosine distance metric. No manual initialization required.

How It Works

• Hybrid search: Recall uses both Qdrant vector similarity and SQLite FTS5 keyword search, merging results with configurable weights. This improves recall quality especially for exact term matches.
• Automatic embedding: Messages are embedded asynchronously using the configured embedding_model and stored in Qdrant alongside SQLite.
• FTS5 index: All messages are automatically indexed in an SQLite FTS5 virtual table via triggers, enabling BM25-ranked keyword search with zero configuration.
• Graceful degradation: If Qdrant is unavailable, Zeph falls back to FTS5-only keyword search instead of returning empty results.
• Startup backfill: On startup, if Qdrant is available, Zeph calls embed_missing() to backfill embeddings for any messages stored while Qdrant was offline.

Hybrid Search Weights

Configure the balance between vector (semantic) and keyword (BM25) search:

[memory.semantic]
enabled = true
recall_limit = 5
vector_weight = 0.7   # Weight for Qdrant vector similarity
keyword_weight = 0.3  # Weight for FTS5 keyword relevance

When Qdrant is unavailable, only keyword search runs (effectively keyword_weight = 1.0).

Temporal Decay

Enable time-based score attenuation to prefer recent context over stale information:

[memory.semantic]
temporal_decay_enabled = true
temporal_decay_half_life_days = 30  # Score halves every 30 days

Scores decay exponentially: at 1 half-life a message retains 50% of its original score, at 2 half-lives 25%, and so on. Adjust temporal_decay_half_life_days based on how quickly your project context changes.

MMR Re-ranking

Enable Maximal Marginal Relevance to diversify recall results and reduce redundancy:

[memory.semantic]
mmr_enabled = true
mmr_lambda = 0.7  # 0.0 = max diversity, 1.0 = pure relevance

MMR iteratively selects results that are both relevant to the query and dissimilar to already-selected items. The default mmr_lambda = 0.7 works well for most use cases. Lower it if you see too many semantically similar results in recall.

Autosave Assistant Responses

By default, only user messages are embedded. Enable autosave_assistant to also embed assistant responses for richer semantic recall:

[memory]
autosave_assistant = true
autosave_min_length = 20  # Skip embedding for very short replies

Short responses (below autosave_min_length bytes) are still saved to SQLite but skip the embedding step. User messages always generate embeddings regardless of this setting.

Memory Export and Import

Back up or migrate conversation data with portable JSON snapshots:

zeph memory export conversations.json
zeph memory import conversations.json

See CLI Reference — zeph memory for details.

Semantic Response Caching

Complement exact-match response caching with embedding-based similarity matching:

[llm]
response_cache_enabled = true
semantic_cache_enabled = true          # Enable semantic cache (default: false)
semantic_cache_threshold = 0.95        # Cosine similarity for cache hit (default: 0.95)
semantic_cache_max_candidates = 10     # Max entries examined per lookup (default: 10)

Lower the threshold (e.g., 0.92) for more cache hits with slightly less precise matching. Increase semantic_cache_max_candidates for better recall at the cost of lookup latency.

Write-Time Importance Scoring

Score messages by decision-relevance at write time to improve recall quality:

[memory.semantic]
importance_enabled = true         # Enable importance scoring (default: false)
importance_weight = 0.15          # Blend weight in recall ranking (default: 0.15)

Messages with high importance scores (architectural decisions, key constraints, user preferences) receive a recall boost proportional to importance_weight. The score is computed by an LLM classifier at message persist time and stored in the importance_score column (migration 039).

Storage Architecture

Both stores work together: SQLite holds the data, the vector backend enables similarity search over it. With the Qdrant backend, the embeddings_metadata table in SQLite maps message IDs to Qdrant point IDs. With the SQLite backend, vectors are stored directly in vector_points and vector_point_payloads tables.

The messages table includes agent_visible, user_visible, and compacted_at columns (migration 013_message_metadata.sql) plus an index on conversation_id. Semantic recall and FTS5 keyword search filter by agent_visible=1, ensuring compacted messages are excluded from retrieval results.

Enable Self-Learning Skills

This guide walks you through enabling and tuning Zeph’s self-learning system so that skills automatically improve based on execution outcomes and user corrections.

For a full technical reference of the underlying mechanisms, see Self-Learning Skills.

Prerequisites

• Zeph installed and configured with at least one LLM provider
• Qdrant running locally (required for correction recall)
• At least one skill installed

Step 1 — Enable Core Learning

Add the following to your config/default.toml:

[skills.learning]
enabled = true
auto_activate = false   # review LLM-generated improvements before they go live
min_failures = 3
improve_threshold = 0.7

With auto_activate = false, new skill versions are generated but held for your approval. Run /skill versions to review them and /skill approve <id> to promote one.

Step 2 — Enable Implicit Feedback Detection

FeedbackDetector watches each user turn for implicit corrections — phrases like “that’s wrong”, “try again”, or significant topic shifts. Detected corrections are stored and recalled automatically.

[agent.learning]
correction_detection = true
correction_confidence_threshold = 0.7  # tune sensitivity (lower = more corrections captured)
correction_recall_limit = 3
correction_min_similarity = 0.75

Corrections are stored in both SQLite and the zeph_corrections Qdrant collection. The top-3 most similar corrections are injected into the system prompt on relevant queries.

Multi-Language Support

FeedbackDetector matches correction patterns across 7 languages: English, Russian, Spanish, German, French, Chinese (Simplified), and Japanese. Each language uses dual anchoring: anchored patterns (message starts with the phrase) and unanchored patterns (phrase embedded mid-sentence). No per-language configuration is needed — all patterns are compiled into a single flat list at startup.

Mixed-language inputs are supported: “That’s неправильно” (Russian correction embedded in English) matches correctly. For unsupported languages (Korean, Arabic, etc.), the regex detector returns no signal; enable the judge detector (detector_mode = "judge") to handle these cases via LLM classification.

Step 2b — Enable LLM-Backed Judge (Optional)

By default, correction detection uses regex patterns only. If you want higher recall for ambiguous or non-English corrections, enable the judge detector:

[skills.learning]
detector_mode = "judge"
judge_model = "claude-sonnet-4-6"   # leave empty to use the primary provider
judge_adaptive_low = 0.5            # regex confidence floor (default: 0.5)
judge_adaptive_high = 0.8           # regex confidence ceiling (default: 0.8)

The judge only fires when regex confidence is borderline or when regex finds nothing — it does not replace regex. A rate limiter caps judge calls at 5 per 60 seconds. Judge calls run in the background and do not block the response.

Start with detector_mode = "regex" (the default) and switch to "judge" only if you notice corrections being missed. The judge adds LLM cost per borderline detection.

Step 3 — Switch to Hybrid Skill Matching

BM25+cosine hybrid matching improves recall for skills with distinctive trigger keywords while keeping semantic matching for paraphrased queries.

[skills]
hybrid_search = true
cosine_weight = 0.7   # reduce to 0.5 to give BM25 more weight

When hybrid search is enabled, the system prompt includes skill health attributes (trust, wilson, outcomes) so the LLM can factor in reliability.

Step 4 — Enable EMA Routing (Multi-Provider Setups)

If you run multiple providers via routing = "ema" in [llm], EMA routing continuously reorders providers by latency:

[llm]
routing = "ema"
router_ema_enabled = true
router_ema_alpha = 0.1       # lower = more weight on historical latency
router_reorder_interval = 10 # re-evaluate every 10 requests

Monitoring

Use these in-session commands to monitor the system:

/skill stats       — Wilson scores, trust levels, outcome counts per skill
/skill versions    — list pending and approved LLM-generated versions

The TUI dashboard (zeph --tui) shows real-time confidence bars:

• Green bar — Wilson score ≥ 0.75
• Yellow — 0.40–0.74
• Red — below 0.40 (at risk of automatic demotion)

Manually Triggering Improvement

If a skill is clearly wrong, reject it immediately instead of waiting for failures to accumulate:

/skill reject <name> <reason>

For example:

/skill reject docker "generates docker run commands without the -it flag for interactive shells"

This triggers the LLM improvement pipeline on the next agent cycle.

Recommended Starting Configuration

[skills]
hybrid_search = true
cosine_weight = 0.7

[skills.learning]
enabled = true
auto_activate = false
min_failures = 3
improve_threshold = 0.7
rollback_threshold = 0.5
min_evaluations = 5
max_versions = 10
cooldown_minutes = 60
detector_mode = "regex"   # switch to "judge" for LLM-backed detection

[agent.learning]
correction_detection = true
correction_confidence_threshold = 0.7
correction_recall_limit = 3
correction_min_similarity = 0.75

Keep auto_activate = false until you have enough history to trust the LLM-generated improvements.

Migrate Config

As Zeph gains new features, the configuration file grows. When you upgrade from an older version, your existing config.toml may be missing entire sections. The migrate-config command closes that gap: it reads your config, adds every missing parameter as a commented-out block with documentation, and reformats the result.

Existing values are never changed. The command is safe to run multiple times — the output is identical on each run (idempotent).

Quick Start

Preview what would change without touching your file:

zeph migrate-config --config ~/.zeph/config.toml --diff

Apply the migration in place:

zeph migrate-config --config ~/.zeph/config.toml --in-place

What It Does

Given a minimal config like:

[agent]
model = "claude-sonnet-4-6"

After migration, missing sections appear as commented-out blocks:

[agent]
model = "claude-sonnet-4-6"

# [llm]
# # Maximum tokens allowed in a single LLM request.
# max_tokens = 8192
# # Number of retry attempts on transient errors.
# retries = 3
# ...

# [memory]
# # SQLite database path.
# db_path = ".zeph/data/zeph.db"
# ...

To activate a section, uncomment the [section] header and the parameters you want to change. Delete or leave commented any that you want to keep at their defaults.

Flags

Typical Workflow

1. Run with --diff to review what would be added:

   zeph migrate-config --config config.toml --diff
   

2. If the diff looks correct, apply in place:

   zeph migrate-config --config config.toml --in-place
   

3. Open the file and uncomment any new parameters you want to configure.

4. Restart Zeph with the updated config.

What Gets Added

The canonical reference covers all config sections:

• [agent] — model, system prompt, token budgets, instruction files
• [llm] — provider-level timeouts, retries, streaming
• [memory] — SQLite path, session limits, compaction, decay, MMR
• [tools] — shell sandbox, web scrape, filters, audit, anomaly detection
• [channels] — Telegram, Discord, Slack settings
• [tui] — TUI dashboard display options
• [mcp] — MCP server definitions
• [a2a] — A2A protocol settings
• [acp] — Agent Client Protocol (stdio/HTTP/WebSocket)
• [agents] — sub-agent concurrency and memory scope defaults
• [orchestration] — task graph and planner settings
• [graph-memory] — entity extraction and knowledge graph options
• [security] — content isolation, exfiltration guard, quarantine
• [vault] — secrets backend (env or age)
• [scheduler] — cron task scheduler
• [gateway] — HTTP webhook ingestion
• [index] — AST-based code indexing
• [experiments] — A/B testing for prompt parameters
• [logging] — log level, file output, rotation

Parameters that already exist in your file are never overwritten or reordered within their section.

TUI Usage

In an interactive session, run:

> /migrate-config

or open the command palette and select config:migrate. The TUI shows the diff as a system message. To apply changes, use the CLI --in-place flag.

Notes

• The reference config is embedded in the binary — no network access or external files required.
• Unknown keys you have added to your config are preserved at the end of each section.
• Array-of-tables blocks ([[compatible]], [[mcp.servers]]) are passed through unchanged.
• The --in-place write is atomic: the file is written to a temporary location in the same directory and renamed, so a crash mid-write cannot corrupt the original.

Docker Deployment

Docker Compose automatically pulls the latest image from GitHub Container Registry. To use a specific version, set ZEPH_IMAGE=ghcr.io/bug-ops/zeph:v0.9.8.

Quick Start (Ollama + Qdrant in containers)

# Pull Ollama models first
docker compose --profile cpu run --rm ollama ollama pull mistral:7b
docker compose --profile cpu run --rm ollama ollama pull qwen3-embedding

# Start all services
docker compose --profile cpu up

Apple Silicon (Ollama on host with Metal GPU)

# Use Ollama on macOS host for Metal GPU acceleration
ollama pull mistral:7b
ollama pull qwen3-embedding
ollama serve &

# Start Zeph + Qdrant, connect to host Ollama
ZEPH_LLM_BASE_URL=http://host.docker.internal:11434 docker compose up

Linux with NVIDIA GPU

# Pull models first
docker compose --profile gpu run --rm ollama ollama pull mistral:7b
docker compose --profile gpu run --rm ollama ollama pull qwen3-embedding

# Start all services with GPU
docker compose --profile gpu -f docker/docker-compose.yml -f docker/docker-compose.gpu.yml up

PostgreSQL Backend

Zeph supports PostgreSQL as an alternative to the default SQLite backend via the zeph-db crate. The docker-compose.yml includes a postgres service that exposes the ZEPH_DATABASE_URL environment variable automatically.

To use PostgreSQL with Docker Compose:

# Start Zeph with PostgreSQL
ZEPH_DATABASE_URL=postgres://zeph:zeph@localhost:5432/zeph docker compose --profile postgres up

Or set database_url in your config:

[memory]
database_url = "postgres://zeph:zeph@localhost:5432/zeph"

Schema Migration

When using PostgreSQL for the first time, or after an upgrade, run the migration CLI to apply schema changes:

zeph db migrate

The --init setup wizard includes a backend selection step. Choose PostgreSQL to generate a config with database_url and the corresponding Docker Compose snippet.

Environment Variable

ZEPH_DATABASE_URL overrides [memory] database_url at runtime. This is the recommended way to inject connection strings in containerised deployments rather than embedding credentials in config files:

ZEPH_DATABASE_URL=postgres://user:pass@db:5432/zeph zeph

SQLite remains the default when database_url is not set.

Age Vault (Encrypted Secrets)

# Mount key and vault files into container
docker compose -f docker/docker-compose.yml -f docker/docker-compose.vault.yml up

Override file paths via environment variables:

ZEPH_VAULT_KEY=./my-key.txt ZEPH_VAULT_PATH=./my-secrets.age \
  docker compose -f docker/docker-compose.yml -f docker/docker-compose.vault.yml up

The image must be built with vault-age feature enabled. For local builds, use CARGO_FEATURES=vault-age with docker/docker-compose.dev.yml.

Using Specific Version

# Use a specific release version
ZEPH_IMAGE=ghcr.io/bug-ops/zeph:v0.9.8 docker compose up

# Always pull latest
docker compose pull && docker compose up

Vulnerability Scanning

Scan the Docker image locally with Trivy before pushing:

# Scan the latest local image
trivy image ghcr.io/bug-ops/zeph:latest

# Scan a locally built dev image
trivy image zeph:dev

# Fail on HIGH/CRITICAL (useful in CI or pre-push checks)
trivy image --severity HIGH,CRITICAL --exit-code 1 ghcr.io/bug-ops/zeph:latest

Local Development

Full stack with debug tracing (builds from source via docker/Dockerfile.dev, uses host Ollama via host.docker.internal):

# Build and start Qdrant + Zeph with debug logging
docker compose -f docker/docker-compose.dev.yml up --build

# Build with optional features (e.g. vault-age, candle)
CARGO_FEATURES=vault-age docker compose -f docker/docker-compose.dev.yml up --build

# Build with vault-age and mount vault files
CARGO_FEATURES=vault-age \
  docker compose -f docker/docker-compose.dev.yml -f docker/docker-compose.vault.yml up --build

Dependencies only (run zeph natively on host):

# Start Qdrant
docker compose -f docker/docker-compose.deps.yml up

# Run zeph natively with debug tracing
RUST_LOG=zeph=debug,zeph_channels=trace cargo run

Daemon Mode

Run Zeph as a headless background agent with an A2A endpoint, then connect a TUI client for real-time interaction.

Prerequisites

Daemon mode requires the a2a feature flag:

cargo build --release --features a2a

To connect a TUI client, build with tui and a2a:

cargo build --release --features tui,a2a

Configuration

Run the interactive wizard to configure daemon settings:

zeph init

The wizard generates the [daemon] and [a2a] sections in config.toml:

[daemon]
enabled = true
pid_file = "~/.zeph/zeph.pid"
health_interval_secs = 30
max_restart_backoff_secs = 60

[a2a]
enabled = true
host = "0.0.0.0"
port = 3000
auth_token = "your-secret-token"

Starting the Daemon

zeph --daemon

The daemon:

1. Writes a PID file for instance detection
2. Bootstraps a full agent (provider, memory, skills, tools, MCP)
3. Starts the A2A JSON-RPC server on the configured host/port
4. Runs under DaemonSupervisor with health monitoring
5. Handles Ctrl-C for graceful shutdown (removes PID file)

The agent uses a LoopbackChannel internally, which auto-approves confirmation prompts and bridges I/O between the A2A task processor and the agent loop via tokio mpsc channels.

Connecting the TUI

From any machine that can reach the daemon:

zeph --connect http://localhost:3000

The TUI connects to the remote daemon via A2A SSE streaming. Tokens are rendered in real-time as they arrive from the agent. All standard TUI features (markdown rendering, command palette, file picker) work in connected mode.

Authentication

If the daemon has auth_token configured, set ZEPH_A2A_AUTH_TOKEN before connecting:

ZEPH_A2A_AUTH_TOKEN=your-secret-token zeph --connect http://localhost:3000

Architecture

+-------------------+       A2A SSE        +-------------------+
|   TUI Client      | <------------------> |   Daemon          |
|   (--connect)     |     JSON-RPC 2.0     |   (--daemon)      |
+-------------------+                      +-------------------+
                                           | LoopbackChannel   |
                                           |   input_tx/rx     |
                                           |   output_tx/rx    |
                                           +-------------------+
                                           | Agent Loop        |
                                           | LLM + Tools + MCP |
                                           +-------------------+

The LoopbackChannel implements the Channel trait with two linked mpsc pairs:

• input: the A2A task processor sends user messages to the agent
• output: the agent emits LoopbackEvent variants (Chunk, Flush, FullMessage, Status, ToolOutput) back to the processor

The TaskProcessor translates LoopbackEvent into ProcessorEvent::ArtifactChunk for SSE streaming to connected clients.

Daemon Management via Command Palette

When using TUI in connected mode, additional commands are available in the command palette (Ctrl+P):

Model Orchestrator

Tip: For simple fallback chains with adaptive routing (Thompson Sampling or EMA), use routing = "cascade" or routing = "thompson" in [llm] instead. See Adaptive Inference.

Route tasks to different LLM providers based on content classification. Each task type maps to a provider chain with automatic fallback. Use a multi-provider setup to combine local and cloud models — for example, embeddings via Ollama and chat via Claude.

Configuration

[llm]
routing = "task"   # task-based routing

[[llm.providers]]
name = "ollama"
type = "ollama"
model = "qwen3:8b"
embedding_model = "qwen3-embedding"
embed = true        # use this provider for all embedding operations

[[llm.providers]]
name = "claude"
type = "claude"
model = "claude-sonnet-4-6"
max_tokens = 4096
default = true      # default provider for chat

Provider Entry Fields

Each [[llm.providers]] entry supports:

Provider Selection

• default = true — provider used for chat when no other routing rule matches
• embed = true — provider used for all embedding operations (skill matching, semantic memory)

Task Classification

Task types are classified via keyword heuristics:

Fallback Chains

Routes define provider preference order. If the first provider fails, the next one in the list is tried automatically.

coding = ["local", "cloud"]  # try local first, fallback to cloud

Capability Delegation

SubProvider and ModelOrchestrator fully delegate capability queries to the underlying provider:

• context_window() — returns the actual context window size from the sub-provider. This is required for correct auto_budget, semantic recall sizing, and graph recall budget allocation when using the orchestrator.
• supports_vision() — returns true only when the active sub-provider supports image inputs.
• supports_structured_output() — returns the sub-provider’s actual value.
• last_usage() and last_cache_usage() — delegate to the last-used provider. Token metrics are accurate even when the orchestrator routes across multiple providers within a session.

Interactive Setup

Run zeph init and select Multi-provider as the LLM setup. The wizard prompts for:

1. Primary provider — select from Ollama, Claude, OpenAI, or Compatible. Provide the model name, base URL, and API key as needed.
2. Fallback provider — same selection. The fallback activates when the primary fails.
3. Embedding model — used for skill matching and semantic memory.

The wizard generates a complete [[llm.providers]] section with named entries and embed/default markers.

Multi-Instance Example

Two Ollama servers on different ports — one for chat, one for embeddings:

[llm]

[[llm.providers]]
name = "ollama-chat"
type = "ollama"
base_url = "http://localhost:11434"
model = "mistral:7b"
default = true

[[llm.providers]]
name = "ollama-embed"
type = "ollama"
base_url = "http://localhost:11435"       # second Ollama instance
embedding_model = "nomic-embed-text"      # dedicated embedding model
embed = true

SLM Provider Recommendations

Each Zeph subsystem that calls an LLM exposes a *_provider config field. Matching the model size to task complexity reduces cost and latency without sacrificing quality. The table below lists the recommended model tier for each subsystem:

A typical cost-optimized setup uses a local Ollama model (e.g., qwen3:1.7b) for all fast-tier subsystems and a cloud model (e.g., claude-sonnet-4-6) for quality-tier tasks:

[[llm.providers]]
name = "fast"
type = "ollama"
model = "qwen3:1.7b"
embed = true

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

# Route cheap subsystems to the local model
[memory.admission]
admission_provider = "fast"

[memory.tiers]
scene_provider = "fast"

[memory.compression]
compress_provider = "fast"

[llm.complexity_routing]
triage_provider = "fast"

[orchestration]
planner_provider = "quality"

Hybrid Setup Example

Embeddings via free local Ollama, chat via paid Claude API:

[llm]

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

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

Adaptive Inference

When multiple providers are configured and routing is set in [llm], Zeph routes each LLM request through the provider list. The routing strategy determines which provider is tried first. Four strategies are available:

Thompson Sampling

Thompson Sampling maintains a Beta(alpha, beta) distribution per provider. On each request the router samples all distributions and picks the provider with the highest sample. After the request completes:

• Success (provider returns a response): alpha += 1
• Failure (provider errors, triggers fallback): beta += 1

New providers start with a uniform prior Beta(1, 1). Over time, reliable providers accumulate higher alpha values and get selected more often, while unreliable providers are deprioritized. The stochastic sampling ensures occasional exploration of underperforming providers in case they recover.

Enabling Thompson Sampling

[llm]
routing = "thompson"
# thompson_state_path = "~/.zeph/router_thompson_state.json"  # optional

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

[[llm.providers]]
name = "openai"
type = "openai"
model = "gpt-4o"

[[llm.providers]]
name = "ollama"
type = "ollama"
model = "qwen3:8b"

State Persistence

Thompson state is saved to disk on agent shutdown and restored on startup. The default path is ~/.zeph/router_thompson_state.json.

• The file is written atomically (tmp + rename) with 0o600 permissions on Unix
• On startup, loaded values are clamped to [0.5, 1e9] and checked for finiteness to reject corrupt state files
• Providers removed from the chain config are pruned from the state file automatically
• Multiple concurrent Zeph instances will overwrite each other’s state on shutdown (known pre-1.0 limitation)

Override the path:

[llm]
thompson_state_path = "/path/to/custom-state.json"

Inspecting State

CLI:

# Show alpha/beta and mean success rate per provider
zeph router stats

# Use a custom state file
zeph router stats --state-path /path/to/state.json

# Reset to uniform priors (deletes the state file)
zeph router reset

Example output:

Thompson Sampling state: /Users/you/.zeph/router_thompson_state.json
Provider                            alpha     beta        Mean%
--------------------------------------------------------------
claude                              45.00     3.00        62.1%
ollama                              12.00     8.00        20.8%
openai                              30.00     5.00        17.1%

TUI:

Type /router stats in the TUI input or select “Show Thompson router alpha/beta per provider” from the command palette.

EMA Strategy

The default EMA strategy tracks latency per provider and periodically reorders the chain so faster providers are tried first. Configure via the top-level [llm] fields:

[llm]
routing = "ema"
router_ema_enabled = true
router_ema_alpha = 0.1          # smoothing factor, 0.0-1.0
router_reorder_interval = 10    # re-order every N requests

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

[[llm.providers]]
name = "openai"
type = "openai"
model = "gpt-4o"

[[llm.providers]]
name = "ollama"
type = "ollama"
model = "qwen3:8b"

Cascade Routing

The cascade strategy routes requests to the cheapest provider first and escalates only when the response is degenerate. This minimizes cost while maintaining quality.

Enabling Cascade Routing

[llm]
routing = "cascade"

[llm.cascade]
quality_threshold = 0.5        # score below this → escalate (default: 0.5)
max_escalations = 2            # max escalation steps per request (default: 2)
classifier_mode = "heuristic"  # "heuristic" (default) or "judge" (LLM-backed)
# max_cascade_tokens = 100000  # cumulative token cap across escalation levels (optional)
# cost_tiers = ["ollama", "claude"]  # explicit cost ordering (cheapest first)

[[llm.providers]]
name = "ollama"
type = "ollama"
model = "qwen3:8b"

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

cost_tiers

cost_tiers lets you override the escalation order without changing the [[llm.providers]] list order. It is applied once at construction time (no per-request cost). Providers listed in cost_tiers are reordered to match that sequence; any provider not mentioned is appended after the listed ones in the original order. Unknown names in cost_tiers are silently ignored.

[llm.cascade]
cost_tiers = ["ollama", "openai"]  # reorder to cheapest first; claude appended last

This separates the fallback chain definition (used by all strategies) from the cost ordering used specifically by cascade.

Note

cost_tiers only affects chat_stream / chat calls. chat_with_tools bypasses cascade entirely and uses the original chain order.

Classifier Modes

Behavior

• Network and API errors do not consume the escalation budget — only quality-based failures trigger escalation.
• When all escalation levels are exhausted, the best-seen response is returned (not an error).
• Cascade is intentionally skipped for chat_with_tools calls (tool use requires deterministic provider selection).
• Thompson/EMA outcome tracking is not contaminated by quality-based escalations.

Configuration Reference

[llm] routing fields:

[llm.cascade] fields (when routing = "cascade"):

EMA-specific fields live in [llm]:

Bandit Routing

The "bandit" strategy implements the PILOT LinUCB contextual bandit algorithm. Unlike Thompson Sampling (which tracks success/failure counts) or EMA (which tracks latency), the bandit embeds the current request as a feature vector and selects the provider that maximizes the upper confidence bound given observed cost-weighted rewards. This allows the router to learn which providers perform best for different types of requests, not just which provider is fastest or most reliable overall.

How It Works

1. The incoming request is embedded using embedding_provider to produce a context vector.
2. Each provider maintains a LinUCB model: a ridge regression matrix and a reward vector.
3. The router computes a UCB score for every provider: the estimated reward plus an exploration bonus scaled by alpha.
4. The provider with the highest score handles the request.
5. After the request completes, the reward (quality signal minus cost penalty) is used to update that provider’s model.
6. The decay_factor attenuates historical observations over time, allowing the bandit to adapt to changes in provider behavior.

Enabling Bandit Routing

[llm]
routing = "bandit"

[llm.router.bandit]
alpha = 1.0                          # Exploration bonus coefficient (default: 1.0)
dim = 64                             # Embedding dimension for context features (default: 64)
cost_weight = 0.1                    # Weight applied to token cost in the reward signal (default: 0.1)
decay_factor = 0.99                  # Per-request exponential decay of historical observations (default: 0.99)
embedding_provider = "fast"          # Provider name to use for request embedding
embedding_timeout_ms = 500           # Timeout for the embedding call in milliseconds (default: 500)
cache_size = 256                     # LRU cache size for repeated request embeddings (default: 256)

[[llm.providers]]
name = "fast"
type = "openai"
model = "gpt-4o-mini"
embed = true

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

State Persistence

Bandit model state (the per-provider LinUCB matrices) is saved on agent shutdown and restored on startup. The default path is ~/.config/zeph/router_bandit_state.json. Override with:

[llm]
bandit_state_path = "/path/to/custom-bandit-state.json"

The file is written atomically (tmp + rename) with 0o600 permissions on Unix. On startup, loaded matrices are validated for dimensionality consistency — mismatched dimensions (e.g., after changing dim) cause a clean reset to the uniform prior.

Configuration Reference

[llm.router.bandit] fields (active when routing = "bandit"):

Inspecting State

# Show per-provider bandit statistics
zeph router stats --strategy bandit

The output includes the estimated reward mean and uncertainty per provider, the number of observations, and the current alpha/decay_factor parameters.

Known Limitations

• Thompson success/failure is recorded at stream-open time, not on stream completion. A provider that opens a stream but fails mid-delivery still gets alpha += 1
• Multiple Zeph instances sharing the same state file will overwrite each other’s state
• The state file uses a predictable .tmp suffix during writes (symlink-race risk on shared directories)

Complexity Triage Routing

Complexity triage routing (routing = "triage") classifies each request before inference and routes it to the most appropriate provider tier based on difficulty. A cheap, fast model acts as the classifier; heavier models are reserved for genuinely difficult requests.

How It Works

On each request the router:

1. Sends the user’s message to the triage provider (a small, fast model).
2. The triage model returns a single word: simple, medium, complex, or expert.
3. The router looks up the configured provider for that tier and forwards the full request to it.
4. If triage times out or returns an unparseable response, the request falls back to the lowest configured tier (simple).

Context size is also considered: when a request’s message history exceeds the selected tier provider’s context window, the router automatically escalates to the next tier. This escalation count is tracked in the triage metrics.

Tier Definitions

Enabling Triage Routing

Set routing = "triage" in [llm] and add a [llm.complexity_routing] section:

[llm]
routing = "triage"

[llm.complexity_routing]
enabled = true
triage_provider = "fast"
bypass_single_provider = true
triage_timeout_secs = 5

[llm.complexity_routing.tiers]
simple = "fast"
medium = "default"
complex = "smart"
expert = "expert"

[[llm.providers]]
name = "fast"
type = "ollama"
model = "qwen3:1.7b"

[[llm.providers]]
name = "default"
type = "ollama"
model = "qwen3:8b"
default = true

[[llm.providers]]
name = "smart"
type = "claude"
model = "claude-haiku-4-5-20251001"

[[llm.providers]]
name = "expert"
type = "claude"
model = "claude-sonnet-4-6"

Each tier value must match a name field in one of the [[llm.providers]] entries. Tiers are optional — any omitted tier resolves to the first configured tier provider (simple).

Bypass Optimization

When bypass_single_provider = true (the default) and all configured tiers resolve to the same provider name, the triage call is skipped entirely. This avoids a redundant LLM call when, for example, only two tiers are configured and both point to the same model:

[llm.complexity_routing.tiers]
simple  = "fast"
medium  = "fast"   # same provider — triage is bypassed
complex = "smart"
# expert not set — resolves to "fast" (first tier)

Note

Bypass is evaluated at construction time. Changing tier assignments requires a config reload or restart.

Timeout and Fallback

The triage call is bounded by triage_timeout_secs (default: 5 seconds). When the triage model does not respond in time or returns an unrecognised label, the router falls back to the simple tier provider and increments the timeout_fallbacks metric counter.

[llm.complexity_routing]
triage_provider = "fast"
triage_timeout_secs = 3   # fail fast on slow local model

Hybrid Mode: Triage + Cascade

Setting fallback_strategy = "cascade" enables hybrid routing: triage selects the initial tier, and cascade quality escalation is applied on top. If the selected tier provider returns a degenerate response (empty, repetitive, incoherent), the router escalates to the next tier automatically.

[llm.complexity_routing]
triage_provider = "fast"
fallback_strategy = "cascade"

[llm.complexity_routing.tiers]
simple  = "fast"
medium  = "default"
complex = "smart"
expert  = "expert"

Note

fallback_strategy = "cascade" is the only supported value. This option is reserved for future expansion.

Configuration Reference

[llm.complexity_routing] fields (active when routing = "triage"):

[llm.complexity_routing.tiers] fields:

All tier fields are optional. Unset tiers fall back to simple; if simple is also unset, the first [[llm.providers]] entry is used.

Metrics

The triage router exposes counters accessible via the TUI metrics panel and the debug log:

Known Limitations

• Triage accuracy depends entirely on the quality of the classifier model. A weak or poorly-prompted model may mislabel requests.
• The triage call adds latency before every request when bypass is not active. Use a locally hosted small model (e.g. qwen3:1.7b via Ollama) to keep overhead below 500 ms.
• Multiple concurrent Zeph instances share no triage state — each instance classifies independently.

Self-Learning Skills

Zeph continuously improves its skills based on execution outcomes, user corrections, and provider performance. The self-learning system operates across four layers: failure classification, implicit feedback detection, Bayesian re-ranking, and hybrid search with EMA-based routing.

Overview

When a skill fails or a user implicitly corrects the agent, Zeph records the signal, re-ranks affected skills, and — when failures cross a threshold — generates an improved skill version via LLM reflection.

User message
     │
     ▼
Skill matching (BM25 + cosine → RRF fusion)
     │
     ▼
Skill execution → SkillOutcome recorded
     │
     ├─ Success → Wilson score updated, EMA updated
     │
     └─ Failure → FailureKind classified
                       │
                       ├─ FeedbackDetector checks next user turn
                       │        └─ UserCorrection stored in SQLite + Qdrant
                       │
                       └─ repeated failures → LLM generates improved version

Phase 1 — Failure Classification

Every skill invocation records a SkillOutcome. Tool failures now carry a FailureKind that distinguishes seven root causes:

The raw reason string is stored in the outcome_detail column (migration 018, skill_outcomes table) for later inspection and LLM-based improvement prompts.

Rejecting a Skill

Use /skill reject to record an explicit user rejection and immediately trigger the improvement pipeline:

/skill reject <name> <reason>

Example:

/skill reject web-search "always uses the wrong search engine"

This is equivalent to min_failures consecutive failures — the improvement loop starts on the next agent cycle.

Phase 2 — Implicit Feedback Detection

Zeph inspects each user turn for implicit corrections without requiring an explicit /feedback command. Two detection strategies are available, selected via detector_mode:

Regex Detector (default)

FeedbackDetector uses pattern matching only — zero LLM calls.

Detection signals:

1. Explicit rejection (confidence 0.85) — phrases like “no”, “wrong”, “that’s wrong”, “that didn’t work”, “bad answer”, “that’s incorrect”.
2. Self-correction — user corrects themselves (e.g., “I was wrong, the capital is Canberra”). Self-corrections are stored for analytics but do not penalize active skills.
3. Alternative request (confidence 0.70) — “instead use…”, “try a different approach”, “can you do it differently”.
4. Repetition (confidence 0.75) — Jaccard token overlap > 0.8 against the last 3 user messages.

Judge Detector (LLM-backed)

JudgeDetector uses an LLM call to classify borderline or missed cases. It is invoked only when regex confidence falls in the adaptive zone or regex returns no signal at all.

How the adaptive zone works:

The judge call runs in a background tokio::spawn task and does not block the agent response loop. A sliding-window rate limiter caps judge calls at 5 per 60 seconds to control cost.

Judge prompt design:

• System prompt classifies user satisfaction into explicit_rejection, alternative_request, repetition, or neutral.
• User message content is XML-escaped to mitigate prompt injection via </user_message> tags.
• Response is parsed as structured JSON (JudgeVerdict) with confidence clamping to [0.0, 1.0].

Multi-Language Support

FeedbackDetector matches correction patterns across 7 languages: