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, Gemini, 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 an 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 agent frameworks
• Installation — all installation methods (source, binaries, Docker)
• First Conversation — from zero to productive in 5 minutes

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

The fastest way to get Zeph running is the install script. Alternative methods (crates.io, source, binaries, Docker) are listed below.

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.18.5

Verify it works:

zeph --version

Then run the configuration wizard:

zeph init

See Configuration Wizard for a step-by-step walkthrough of zeph init.

From crates.io

cargo install zeph

With optional features:

cargo install zeph --features tui,a2a

From Source

Requires Rust 1.94+ (Edition 2024).

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.

Build with optional features for TUI, IDE integration, or server deployment:

cargo build --release --features desktop          # TUI dashboard
cargo build --release --features ide              # ACP for IDE integration
cargo build --release --features server           # HTTP gateway + A2A + OpenTelemetry
cargo build --release --features full             # all optional features

See Feature Flags for the complete list of build options.

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.18.5

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.

Next Steps

• Configuration Wizard — generate a config with zeph init
• First Conversation — send your first message

First Conversation

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

Prerequisites

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

Start the Agent

zeph

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

For the TUI dashboard with side panels showing skills, memory, and metrics:

zeph --tui

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 by cosine similarity
2. The skill’s instructions are injected into the prompt
3. The agent calls the list_directory or find_path tool
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. Destructive commands (rm, git push --force, drop table) require confirmation:

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 and answers from context without re-running any commands. With semantic memory enabled, Zeph recalls relevant context from past sessions too.

Project Instructions

Drop a zeph.md file in your project root to give Zeph standing context — coding conventions, domain knowledge, project rules. The content is injected into every prompt automatically.

# Project Instructions

- Language: TypeScript, strict mode
- Test framework: vitest
- Commit messages follow Conventional Commits
- Never modify files under `generated/`

See Instruction Files for provider-specific files and hot-reload behavior.

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
• Skills — how skill matching works
• Tools — shell, files, web, and MCP tools

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

Next Steps

• First Conversation — start talking to the agent
• 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
• Channel allowlist: skills can declare which I/O channels they are permitted to run on via x-channels in YAML frontmatter. When set, the skill is excluded from matching on channels not in the list. Omit to allow all channels.
• Description cap: skill descriptions are capped at 2048 characters to prevent oversized prompt injection from user-created skills
• Injection sanitization: skill bodies and /skill create inputs are sanitized against prompt injection. URL domains in skill bodies are checked against a configurable allowlist. Untrusted skill content has structural XML tags escaped before prompt injection

Natural Language Skill Generation

Use /skill create to generate a new skill from a natural language description:

/skill create "A skill that formats JSON files using jq"

Zeph generates a complete SKILL.md with frontmatter, instructions, and examples via LLM reflection. Skills can also be mined from GitHub repositories — Zeph analyzes repo structure and README to extract actionable skill definitions.

Duplicate detection prevents creating skills that overlap with existing ones by checking semantic similarity against the skill registry.

Semantic Confusability Mitigation

When multiple skills have overlapping descriptions, the matcher can confuse them. Zeph mitigates this with:

• Category grouping: skills are grouped by functional category, and matching considers category affinity alongside raw similarity
• Two-stage matching: an initial broad match is followed by a disambiguation stage that compares top candidates within the same category
• Use /skill confusability to generate a report showing which skills are at risk of being confused

Skill Mining

Skill mining automates discovery and generation of new skills by searching GitHub for relevant repositories and extracting SKILL.md descriptions from their READMEs and documentation. Configure via [skills.mining]:

[skills.mining]
queries             = ["topic:cli-tool language:rust stars:>100"]
max_repos_per_query = 20      # capped at 100 by the GitHub API
dedup_threshold     = 0.85    # cosine similarity threshold against existing skills
output_dir          = ""      # target directory; defaults to managed skills dir
generation_provider = ""      # provider for skill generation; falls back to primary
embedding_provider  = ""      # provider for embedding dedup; falls back to primary
rate_limit_rpm      = 25      # max GitHub search requests per minute

Mining searches GitHub using the configured queries, fetches each repo’s documentation, calls the generation_provider to produce a SKILL.md, then deduplicates against existing skills using embedding similarity. Skills with similarity above dedup_threshold to an existing skill are skipped. The GitHub API caps max_repos_per_query at 100.

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.

Next Steps

• Add Custom Skills — create your own skills
• Context Budgets — how BATS budget hints affect skill prompt modes
• Self-Learning Skills — how skills evolve through failure detection
• SkillOrchestra — RL-based adaptive skill routing
• NL Skill Generation — generate skills from descriptions or GitHub repos
• 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.

ClawVM Typed Pages and MemReader Quality Gate

Context compaction produces pages of different types — tool outputs, conversation turns, memory excerpts, system context — each with distinct fidelity requirements. ClawVM (Compact Low-Alignment View Machine) classifies every compacted page into a PageType enum and enforces per-type PageInvariant traits at compaction boundaries. This ensures that tool outputs preserve call/result pairs, conversation turns preserve multi-part messages, and memory excerpts preserve citations.

Page types:

When a page is compacted, Zeph appends an audit record to a bounded async sink, allowing external systems to verify that invariants were enforced.

MemReader quality gate scores candidate memories on three dimensions before admitting them into the vector store:

1. Information value — cosine similarity vs. recent context (avoid duplicates)
2. Reference completeness — pronoun/deictic heuristic (is meaning clear without context?)
3. Contradiction risk — graph edge conflicts (does it contradict known facts?)

The gate is fail-open: if embedding, LLM, or graph queries error out, neutral defaults are used and the message is admitted. Enable it in [memory.quality_gate]:

[memory.quality_gate]
enabled = true
information_value_threshold = 0.3       # Skip admission if similarity exceeds this
reference_completeness_threshold = 0.5  # Require non-empty pronouns in content
contradiction_risk_threshold = 0.7      # Flag if graph edges show conflict

Quality gate operates downstream of A-MAC admission, making both gates independent and composable.

APEX-MEM: Advanced Quality Gating

APEX-MEM (Adaptive Page Extraction and eXtension Memory) provides an advanced quality validation layer that runs during the memory write path. When enabled, candidate memories are validated using a multi-dimensional scoring system before being admitted into the vector store.

Key features:

• insert_or_supersede semantics — when a high-confidence fact contradicts an existing memory, the system promotes the newer fact and marks the older one as superseded rather than keeping both
• Multi-dimensional validation — scores candidates on information density (entropy), citation quality (reference completeness), and factual confidence
• Fail-open design — validation errors are logged but never block writes; the message is admitted with conservative default scores

Enable APEX-MEM in [memory.quality_gate]:

[memory.quality_gate]
enabled = true
use_advanced_scoring = true            # Enable APEX-MEM multi-dimensional validation (default: false)
information_value_threshold = 0.3      # Skip admission if similarity exceeds this
reference_completeness_threshold = 0.5 # Require pronoun/deictic clarity
contradiction_risk_threshold = 0.7     # Flag if graph edges show conflict

When use_advanced_scoring = true, each candidate message receives three independent scores:

The composite score is a weighted blend: 0.35 * density + 0.35 * citation + 0.30 * confidence. Messages scoring below information_value_threshold are rejected.

insert_or_supersede behavior:

When a new memory contradicts an existing one (detected via graph edge conflicts), APEX-MEM evaluates both the old and new facts:

1. If the new fact has higher confidence + information_density, it is inserted and the old fact is marked superseded_by = <new_id>
2. If the old fact scores higher, it is retained and the new fact is silently rejected
3. If scores are within contradiction_margin (default: 0.05), both are kept and a contradiction flag is set in the graph for later resolution

This enables natural knowledge evolution without vector index bloat from conflicting information.

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

Hebbian Reinforcement

Hebbian updates strengthen edge weights in the graph when facts are recalled. After retrieving a fact from the graph, the edges traversed during retrieval are incremented by a configurable learning rate, making frequently-used relationships stronger over time.

[memory.hebbian]
enabled = false                    # disabled by default; opt-in
hebbian_lr = 0.1                   # learning rate for weight increment

When enabled, the system records every graph retrieval and applies weight updates fire-and-forget in the background.

HeLa-Mem Spreading Activation Retrieval

HeLa-Mem (Hebbian-Latent Memory) extends graph retrieval with spreading activation: starting from the top-1 ANN anchor node, the system performs breadth-first search through the graph, propagating edge weights (path_weight = Π edge.weight). Each visited node is scored as path_weight × cosine(query, entity), with negative cosine clamped to 0.0. Multi-path convergence keeps the maximum path_weight.

[memory.hebbian]
spreading_activation = true        # enable spreading activation (default: false)
spread_depth = 3                   # BFS depth limit (default: 2)
spread_edge_types = ["related_to", "contradicts"]  # filter edges by type (empty = all)
step_budget_ms = 8                 # per-step timeout in milliseconds (default: 8)

An 8 ms circuit breaker emits a WARN log and returns empty results on budget exhaustion. Isolated anchors (no outgoing edges) fall back to a synthetic HelaFact scored by the real anchor cosine.

See Graph Memory for the full concept guide.

ReasoningBank — Distilled Reasoning Strategy Memory

After each assistant turn, a three-stage pipeline (self-judge → distillation → store) extracts reasoning strategies and stores them as a new kind of memory. A ≤3-sentence strategy summary captures how the agent solved a problem and can be retrieved in future turns.

[memory.reasoning]
enabled = false                   # disabled by default; opt-in
store_limit = 100                 # max entries in reasoning_strategies table (default: 100)
self_judge_window = 2             # messages to evaluate (default: 2 = final user+assistant exchange)
min_assistant_chars = 50          # skip trivial responses shorter than this (default: 50)

Strategies are stored in SQLite and retrieved at context-build time by embedding similarity. The system maintains an LRU eviction with hot-row protection: frequently-used strategies are kept even under eviction pressure.

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.

SleepGate Forgetting Pass

Over time, the vector index accumulates stale or low-value embeddings that dilute recall quality. SleepGate implements a periodic forgetting pass inspired by memory consolidation during sleep: it scans stored embeddings, scores them on recency, access frequency, and semantic density, then soft-deletes entries below the retention threshold.

[memory.forgetting]
enabled = true
interval_secs = 86400          # Run forgetting pass every N seconds (default: 86400 = 24h)
retention_threshold = 0.30     # Composite score below which entries are forgotten (default: 0.30)

Forgotten entries are soft-deleted (marked in SQLite, removed from the vector index) and can be restored manually if needed.

Multi-Vector Chunking

Long messages (tool outputs, code blocks, large paste operations) that exceed the embedding model’s token limit are automatically split into overlapping chunks, each embedded independently. During recall, chunk scores are aggregated back to the parent message using max-pooling, so a message is retrieved if any of its chunks is relevant.

This runs in the real-time embedding path — no configuration is needed. The chunk size and overlap are derived from the embedding model’s context window.

BATS Budget Hint

The Budget-Aware Token Steering (BATS) system injects a budget hint into the system prompt that tells the LLM how much context space remains. This helps the model produce appropriately-sized responses and make better decisions about when to use tools versus answering from context.

BATS also implements a utility-based 5-way action policy that evaluates each agent turn against five action categories (respond, search, tool-use, delegate, wait) and selects the action with the highest expected utility given the current context budget and conversation state.

Cost-Sensitive Store Routing

When multiple storage backends are available (SQLite vectors, Qdrant, graph store), the memory system routes write operations to the backend with the lowest cost for the given content type. Short factual statements are routed to the graph store, long narratives to vector storage, and structured data to SQLite key-value pairs.

[memory.routing]
cost_sensitive = true          # Enable cost-aware write routing (default: false)

Goal-Conditioned Write Gate

When enabled, the write gate evaluates whether a candidate memory entry is relevant to the user’s current goal before admitting it. This prevents the memory system from storing tangential information during long exploratory sessions.

The goal text is extracted from the most recent /plan goal or from the first user message in the session if no plan is active.

Kumiho Belief Revision

Kumiho implements belief revision for the graph memory store. When new information contradicts an existing entity-relationship fact, Kumiho evaluates the conflict using temporal recency and source reliability, then either updates the existing edge, creates a versioned override, or flags the conflict for user resolution.

This is paired with D-MEM RPE (Reward Prediction Error) routing for graph memory, which uses prediction errors from graph queries to adaptively weight the graph store’s contribution to hybrid recall.

Persona Memory

Persona memory extracts persistent user-preference and domain-knowledge facts from conversation history. Extracted facts are injected into context at assembly time, giving the agent a stable model of user expertise, goals, and preferences across sessions.

Facts are extracted by a fast LLM provider after the session accumulates enough user messages (controlled by min_messages). A self-referential heuristic gate skips extraction for agent-to-agent sessions. When conflicting facts are detected, the newer entry marks the older one via supersedes_id, preserving history without duplication.

[memory.persona]
enabled                 = false
persona_provider        = "fast"   # cheap extraction model; falls back to primary
min_confidence          = 0.6      # facts below this threshold are discarded
min_messages            = 3        # minimum user messages before first extraction
max_messages            = 10       # messages fed to LLM per extraction pass
extraction_timeout_secs = 10
context_budget_tokens   = 500

Key Facts Semantic Dedup

When storing key facts via memory_save, Zeph can skip near-duplicate entries that are already present in the Qdrant collection. Before each insert, the new fact’s embedding is compared to the nearest neighbour in zeph_key_facts. If the cosine similarity is at or above key_facts_dedup_threshold, the fact is silently discarded. This prevents the key-facts collection from accumulating paraphrased versions of the same information.

The check is fail-open: if the similarity search returns an error, the fact is stored rather than dropped.

[memory]
key_facts_dedup_threshold = 0.95   # Cosine similarity above which a near-duplicate is suppressed (default: 0.95)

Trajectory Memory

Trajectory memory captures procedural (“how to do X”) and episodic (“what happened in turn N”) entries from tool-call turns. Procedural entries are injected as “past experience” during context assembly, helping the agent reuse successful tool patterns across sessions.

Extraction runs after every turn that contains tool calls, using a fast LLM provider to classify and summarise each tool sequence. Only entries above min_confidence are stored.

[memory.trajectory]
enabled                 = false
trajectory_provider     = "fast"   # cheap extraction model; falls back to primary
context_budget_tokens   = 400      # token budget for trajectory hints in context
recall_top_k            = 5        # procedural entries retrieved per turn
min_confidence          = 0.6
max_messages            = 10
extraction_timeout_secs = 10

Category-Aware Memory

When enabled, messages are tagged with a category derived from the active skill or tool context. The category is stored in the messages.category column and used as a payload filter during Qdrant recall, scoping semantic search to the relevant topic area.

[memory.category]
enabled  = false
auto_tag = true    # derive category from active skill or tool type automatically

TiMem — Temporal-Hierarchical Memory Tree

TiMem organises memories as leaf nodes and periodically consolidates them into hierarchical summaries. Each sweep clusters similar leaves by cosine similarity and asks a fast LLM to produce a parent-level summary. Context assembly uses tree traversal for complex queries, returning a mix of leaf-level detail and higher-level summaries within the token budget.

[memory.tree]
enabled                = false
consolidation_provider = "fast"  # falls back to primary
sweep_interval_secs    = 300     # background consolidation interval
batch_size             = 20      # leaves processed per sweep
similarity_threshold   = 0.8     # cosine threshold for clustering
max_level              = 3       # maximum tree depth above leaves
context_budget_tokens  = 400
recall_top_k           = 5
min_cluster_size       = 2       # minimum cluster size to trigger LLM consolidation

Time-Based Microcompact

Microcompact clears stale low-value tool outputs from context when the session has been idle longer than gap_threshold_minutes. This is a zero-LLM-cost in-memory operation that reduces context pressure before compaction runs.

Cleared tool types: bash, shell, grep, rg, find, web_fetch, web_search, read, cat, list_directory. The keep_recent most recent entries from these tools are always preserved.

[memory.microcompact]
enabled               = false
gap_threshold_minutes = 60   # idle gap in minutes before clearing stale outputs
keep_recent           = 3    # most recent low-value tool outputs to preserve

autoDream Background Consolidation

autoDream runs a background memory consolidation sweep after a session ends, once both gates pass: at least min_sessions sessions have completed and at least min_hours have elapsed since the last consolidation. The sweep merges duplicate memories, updates stale facts, and removes redundant entries.

Gates are in-process only — they reset on restart. The first consolidation always passes the hours gate (no prior timestamp).

[memory.autodream]
enabled                = false
min_sessions           = 3     # sessions since last consolidation
min_hours              = 24    # hours since last consolidation
consolidation_provider = ""    # provider name; falls back to primary
max_iterations         = 8     # safety bound for the consolidation sweep

MagicDocs — Auto-Maintained Markdown

MagicDocs detects files containing a # MAGIC DOC: header when they are read by file tools, registers them in a per-session list, and periodically rewrites them via a background LLM call to keep them accurate.

Updates run every min_turns_between_updates tool-call turns. Only one background update runs at a time; if the previous update is still running the current trigger is skipped. The TUI status bar shows “Updating N magic doc(s)…” while an update is in progress.

To mark a file as auto-maintained, add # MAGIC DOC: <description> as the first line.

When MagicDocs is enabled, the file-read tools (read, file_read, cat, view, open) are automatically added to utility_scorer.exempt_tools, bypassing utility scoring so the files are always read and their content reaches the scanner. Any user-configured exempt_tools entries are preserved and merged.

[magic_docs]
enabled                   = false
min_turns_between_updates = 5    # turns between updates for the same file
update_provider           = ""   # provider name; falls back to primary
max_iterations            = 4    # max iterations per update call

Query Bias Correction

First-person queries (“What did I do last week?”) are shifted toward the user’s profile centroid embedding before vector search. This improves recall of past user-specific decisions and preferences.

[memory.retrieval]
query_bias_correction = true       # enable bias correction (default: false)
query_bias_profile_weight = 0.25   # blend weight: 0.25 = 25% centroid, 75% query (default: 0.25)

The profile centroid is cached with a 300-second TTL in a bounded RwLock. Computation failures are non-sticky: the system falls through to the previous cache or disables bias for that turn.

Store Routing

Store routing classifies each incoming query and routes it to the appropriate memory backend(s), avoiding unnecessary store lookups for simple requests.

[memory.store_routing]
enabled                      = false
strategy                     = "heuristic"   # "heuristic" | "llm" | "hybrid"
routing_classifier_provider  = ""            # provider name; falls back to primary
fallback_route               = "hybrid"      # route used when confidence < threshold
confidence_threshold         = 0.7

routing_classifier_provider should reference a cheap/fast provider (e.g., gpt-4o-mini) declared in [[llm.providers]]. Leave it empty to fall back to the primary provider.

fallback_route is the store used when the classifier cannot reach a confident decision (applies to hybrid strategy). The default value "hybrid" sends the query to all stores.

Store routing is disabled by default (enabled = false). When disabled, HeuristicRouter is used directly, which is equivalent to strategy = "heuristic" with routing always enabled.

Memory Tiers

The tier promotion system organises memories into a hierarchy of four conceptual tiers:

Promotion is driven by a background sweep that clusters near-duplicate episodic messages by cosine similarity. When a fact appears in at least promotion_min_sessions distinct sessions, the cluster is distilled into a single semantic-tier entry via an LLM call, and the source episodic entries are marked agent_visible = false.

The tier system is disabled by default. Enable it under [memory.tiers]:

[memory.tiers]
enabled                  = true
promotion_min_sessions   = 3      # distinct sessions a fact must appear in before promotion (>= 2)
similarity_threshold     = 0.92   # cosine similarity threshold for clustering episodic duplicates
sweep_interval_secs      = 3600   # how often the background sweep runs (seconds)
sweep_batch_size         = 100    # messages evaluated per sweep cycle (>= 1)

MemScene Consolidation

MemScene is a second-pass sweep that consolidates groups of semantically related semantic-tier messages into scene-level summaries. A scene covers a coherent sub-topic: its embedding captures the collective meaning of its member messages, compressing the vector space without discarding information. Scene summaries are indexed and searchable in future sessions.

MemScene is configured alongside the tier system:

[memory.tiers]
enabled                       = true
scene_enabled                 = true
scene_similarity_threshold    = 0.80   # cosine similarity threshold for scene grouping (in [0.5, 1.0])
scene_batch_size              = 50     # unassigned semantic messages processed per sweep (>= 1)
scene_provider                = "fast" # [[llm.providers]] name for scene label/summary generation
scene_sweep_interval_secs     = 7200   # how often the scene consolidation sweep runs (seconds)

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

Note

scene_similarity_threshold is validated to be in [0.5, 1.0] and scene_batch_size must be >= 1. Invalid values are rejected at startup.

MemCoT: Semantic State Accumulation

MemCoT (Memory Chain-of-Thought) tracks the agent’s semantic understanding state across turns via incremental entity and value updates. Instead of storing discrete messages, MemCoT accumulates fact streams that represent how the agent’s model of the world evolves — capturing decisions, contradiction resolutions, and inferred conclusions.

The SemanticStateAccumulator maintains:

• Entity snapshots — current values for tracked entities (project status, decision state, file paths)
• Contradiction flags — when the agent detects conflicting information, flags the conflict and records the resolution
• Decision ledger — explicit decisions made by the user or agent (e.g., “switched from vim to neovim”, “decided to use Claude instead of Ollama”)
• Inferred states — conclusions drawn from multiple facts (e.g., “auth module is now stable” inferred from “all tests pass + no open issues”)

MemCoT is complementary to traditional semantic recall: while vector search finds similar messages, MemCoT finds related state transitions. This is particularly useful for:

• Long explorations — tracking how a codebase design evolved over 50+ turns
• Decision audits — “why did we choose X?” answered by the decision ledger
• Contradiction resolution — detecting when the agent’s context drifts and needs correction

Zoom-In / Zoom-Out Recall Views

MemCoT supports two complementary query patterns for state retrieval:

Zoom-in — Retrieve the full derivation chain for a specific fact. Given a state like “auth module is stable”, the zoom-in view returns:

1. The current fact value (“auth module is stable on commit abc123”)
2. All intermediate facts that contributed to this inference (“all tests pass”, “no open issues”, “PR #42 merged”)
3. The contradiction resolution history if this fact superseded an earlier conflicting state
4. The decision events that led to the conclusion (e.g., “user confirmed code review complete”)

The depth is bounded by zoom_in_max_depth to prevent returning derivation chains deeper than human working memory can follow.

Zoom-out — Retrieve only high-level state transitions without intermediate details. Given 50 turns of development, zoom-out returns:

• Aggregation level 1 (facts) — all state transitions with equal weight
• Aggregation level 2 (decisions) — only explicit user or agent decisions (default)
• Aggregation level 3 (milestones) — major milestone decisions (e.g., “architecture chosen”, “first deploy”)

The aggregation level is set via zoom_out_level. Higher levels reduce token usage by suppressing intermediate inferences and focusing on decision points.

Configuration:

[memory.memcot]
enabled = true
accumulator_provider = "fast"      # Provider for state summarization; falls back to primary
zoom_in_max_depth = 5              # Max steps in derivation chain (>= 1)
zoom_out_level = 2                 # Aggregation level: 1=facts, 2=decisions, 3=milestones

Injection into context:

When enabled, MemCoT state snapshots are stored in SQLite with timestamps and source facts. At context assembly time, both zoom views are injected before semantic recall results:

1. Zoom-in for facts matching the current query (deep causality view)
2. Zoom-out for recent state transitions (high-level summary view)

The dual-recall design allows the agent to answer both deep “why did we choose X?” questions (via zoom-in derivations) and strategic “what’s changed since last session?” questions (via zoom-out aggregates).

Examples:

Zoom-in query: "Why is the payment module blocked?"
Returns: payment module is blocked (current) ← pending legal review ← GDPR compliance ← user decision to add GDPR
(4 steps: decision → inference → inference → current)

Zoom-out query: "What happened in this session?"
Returns: (Decision) switched from SQLite to PostgreSQL; (Milestone) schema v3 deployed; (Decision) enabled read replicas
(3 decision-level events, intermediate facts hidden)

Memory Retrieval Failure Logging

When a semantic memory search returns zero results or falls below the confidence threshold, Zeph optionally records this in the memory_retrieval_failures table. This supports the OmniMem self-improvement loop: by analyzing patterns in no-hit turns, the memory admission and recall systems can be tuned to improve coverage.

Enable failure logging in [memory]:

[memory]
log_retrieval_failures = true       # Record no-hit recalls for analysis

Logged failures include the query, timestamp, applied filters, and confidence score. A background analyzer can use these logs to detect categories of questions your memory system fails on and adjust admission strategies accordingly.

Next Steps

• Set Up Semantic Memory — Qdrant setup guide
• Context Budgets — BATS budget hints and allocation strategy
• SleepGate — automatic memory forgetting and index hygiene
• 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.

Using a Dedicated Provider for Extraction

Graph extraction tasks produce JSON-structured responses that have low prompt/response cosine similarity (~0.55–0.70). When a routing quality gate is active (via [llm.router] quality_gate), extraction calls may be systematically rejected by the gate and rerouted through fallback providers, adding unnecessary latency.

To avoid quality gate false positives, dedicate a provider to graph extraction tasks:

[[llm.providers]]
name = "fast"
type = "ollama"
model = "qwen3:8b"

[memory.graph]
enabled = true
extract_provider = "fast"        # Use the "fast" provider for extraction, bypassing quality gate
max_entities_per_message = 10
max_edges_per_message = 15

When extract_provider is set to a named provider, graph extraction (and downstream note linking and community summarization) use that provider without routing signals or quality gates applied. When empty (default), the system uses the agent’s primary provider.

Tip

For best results, match extract_provider to the provider name used by extract_model. If extract_model = "gpt-4o-mini", use a provider entry with type = "openai" and model = "gpt-4o-mini", then set extract_provider to that provider’s name.

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]
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.

BeliefMem: Probabilistic Edge Layer

BeliefMem (Belief Memory) extends graph memory with a probabilistic layer for uncertain facts. Instead of immediately committing facts as edges, BeliefMem accumulates evidence and tracks confidence scores before promotion to the committed graph.

Use cases:

• Track emerging patterns that haven’t yet been confirmed
• Handle contradictory or uncertain information gracefully
• Preserve uncertainty in retrieval — avoid treating unconfirmed facts as ground truth

How It Works

BeliefMem maintains two parallel layers:

1. Pending beliefs — candidate facts with probability weights from initial extraction
2. Belief evidence — evidence accumulation via Noisy-OR with optional temporal decay

When evidence for a fact accumulates and crosses a promotion threshold (default: 0.85 confidence), the pending belief is promoted to a committed edge in the main graph.

Example workflow:

• Extraction observes: “User might prefer Rust” (confidence: 0.6)
• Extraction later observes: “User uses Rust for most projects” (confidence: 0.7)
• Evidence combines via Noisy-OR: ~0.88 confidence
• Belief is promoted and becomes a committed graph edge

Configuration

Enable BeliefMem under [memory.graph.belief_mem]:

[memory.graph.belief_mem]
enabled = true              # Enable probabilistic belief layer (default: false)
promote_threshold = 0.85    # Min confidence for promotion to committed edge (default: 0.85)
belief_decay_rate = 0.0     # Temporal decay on pending beliefs; 0.0 = disabled (default)
                            # Range: [0.0, 10.0]. Formula: 1/(1 + age_days * rate)
max_pending_beliefs = 1000  # Cap on pending beliefs to prevent unbounded growth

Uncertainty-Preserving Retrieval

When BeliefMem is enabled and graph recall finds no committed edge between two entities, Zeph automatically queries pending beliefs and returns top-K candidates ranked by confidence. This provides graceful fallback behavior when facts are still being accumulated.

Storage

BeliefMem uses two new SQLite tables (created by migration 084):

• pending_beliefs — candidate facts with probability scores
• belief_evidence — evidence records supporting promotion

These tables are independent of the main graph layer and are automatically cleaned up during graph eviction.

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
extract_provider = ""        # Provider name for extraction (bypasses quality gate)
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.belief_mem]
enabled = false                   # Enable probabilistic belief layer (default: false)
promote_threshold = 0.85          # Confidence threshold for edge promotion (default: 0.85)
belief_decay_rate = 0.0           # Temporal decay on pending beliefs (default: 0.0)
max_pending_beliefs = 1000        # Max pending beliefs before eviction (default: 1000)

[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

Belief Revision

Belief revision (Kumiho AGM-inspired) handles the case where a newly extracted fact contradicts an existing one. Without revision, the graph accumulates conflicting beliefs indefinitely.

When belief_revision.enabled = true, each new edge is compared against existing active edges for the same source/target entity pair using embedding cosine similarity. If the similarity exceeds similarity_threshold, the new fact is considered a contradiction of the existing one:

1. The existing edge is invalidated — valid_until and expired_at are set, and a superseded_by pointer is written linking the old edge to its replacement.
2. The new edge is inserted as the current belief.

Both the old and new edges are preserved for temporal queries. The old edge is visible via edge_history() but excluded from active recall.

[memory.graph.belief_revision]
enabled = false              # Enable contradiction detection and revision (default: false)
similarity_threshold = 0.85  # Cosine similarity threshold for conflict detection (default: 0.85)

Belief revision requires an embedding store (qdrant or sqlite vector backend). On any embedding failure the revision step is skipped and the new edge is inserted normally.

Note Linking

Note linking (A-MEM) automatically creates similar_to edges between semantically similar entities after each extraction pass. This builds a secondary similarity layer on top of the explicitly extracted relation edges, enabling retrieval to traverse conceptual proximity even when no direct relation was stated.

After each extraction completes, every newly extracted entity is compared against the existing entity embedding collection. Entity pairs with cosine similarity above similarity_threshold receive a bidirectional similar_to edge. The number of links per entity is capped by top_k to prevent high-degree hubs.

[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)

Note linking requires an embedding store. It runs non-blocking after each extraction and is bounded by timeout_secs to prevent slow searches from stalling the pipeline.

RPE Gate

The RPE (Relevance/Prediction Error) gate is a D-MEM inspired cost-reduction mechanism. Graph extraction via an LLM call is expensive; many conversational turns carry little new factual content. The RPE gate estimates how “surprising” each turn is and skips extraction for low-surprise turns.

Surprise is measured as the divergence between the expected response pattern (rolling average of recent turns) and the actual response. Turns with RPE below threshold skip the MAGMA extraction pipeline entirely. A consecutive-skip safety valve (max_skip_turns) ensures no turn is silently skipped indefinitely — after max_skip_turns consecutive skips, the next turn always triggers extraction regardless of its RPE score.

[memory.graph.rpe]
enabled = false       # Enable RPE-based extraction gating (default: false)
threshold = 0.3       # RPE below this value skips extraction; range [0.0, 1.0] (default: 0.3)
max_skip_turns = 5    # Max consecutive turns to skip before forcing extraction (default: 5)

When enabled = false (the default), every turn triggers extraction as before.

Link Weight Decay

The A-MEM link weight decay mechanism prevents retrieval_count from growing without bound. Without decay, edges traversed early in a conversation permanently dominate recall scoring regardless of how stale they become.

A background task runs periodically and multiplies retrieval_count by link_weight_decay_lambda for all edges that were not traversed since the last decay pass:

new_retrieval_count = retrieval_count * link_weight_decay_lambda

With the default lambda = 0.95, each decay pass reduces unused edge counts by 5%. Over 14 daily passes an edge that was never traversed again decays to roughly half its original count. Set lambda = 1.0 to disable decay.

These fields live directly under [memory.graph], not under a subsection:

[memory.graph]
link_weight_decay_lambda = 0.95       # Multiplicative decay per interval, (0.0, 1.0] (default: 0.95)
link_weight_decay_interval_secs = 86400  # Seconds between decay passes (default: 86400 = 24h)

Decay interacts with the A-MEM evolved weight formula (see A-MEM Link Weight Evolution): decay reduces the effective boost of stale edges while recent retrievals continue to accumulate their count normally.

Episode Nodes

Every conversation is represented as an episode node in the graph. When graph memory is enabled, Zeph calls ensure_episode(conversation_id) at the start of each session to create or retrieve an episode record in the graph_episodes table. The call is idempotent — repeated calls for the same conversation return the same episode ID.

Entity Linking

As entities are extracted during a conversation, each entity is linked to the current episode via link_entity_to_episode(episode_id, entity_id), stored in the graph_episode_entities join table. This link uses INSERT OR IGNORE so re-extracted entities never produce duplicates.

The reverse lookup — all episodes in which a given entity appeared — is available via episodes_for_entity(entity_id). This enables time-aware queries: “which sessions mentioned this entity?”, “what entities appeared in the last three sessions?”, or “when did we first discuss this concept?”

Schema

Two tables support episode tracking:

graph_episodes (
    id              INTEGER PRIMARY KEY,
    conversation_id INTEGER NOT NULL UNIQUE,  -- FK → conversations.id
    created_at      DATETIME DEFAULT CURRENT_TIMESTAMP
)

graph_episode_entities (
    episode_id  INTEGER NOT NULL,  -- FK → graph_episodes.id
    entity_id   INTEGER NOT NULL,  -- FK → graph_entities.id
    PRIMARY KEY (episode_id, entity_id)
)

Uses

Episode boundaries are the foundation for temporal reasoning over the knowledge graph:

• Freshness scoring — facts from the current episode are more salient than facts from older episodes, complementing the bi-temporal edge timestamps.
• Session-scoped recall — retrieve only entities observed in recent sessions without full BFS traversal.
• Temporal queries — combine episodes_for_entity with edges_at_timestamp to reconstruct the agent’s knowledge state at any past session boundary.

No configuration is required — episode tracking is always active when memory.graph.enabled = true.

APEX-MEM: Append-Only Property Graph with Temporal Supersession

APEX-MEM (Append-only PrEperty graph with eXtensional semantics) replaces the mutable edge model with an immutable, timestamped audit trail. Facts do not get deleted or updated; instead, when new information contradicts an existing edge, a supersession is recorded: the old edge remains in the table with an expired_at timestamp and a supersedes_id pointer, and a new edge is inserted with the current timestamp.

This design preserves the full history of belief states while providing efficient queries for “what do we believe now?”. The supersession chain depth is capped at 64 hops to prevent unbounded traversal on extremely long chains of corrections.

Supersession Example:

Turn 1: User says "I prefer vim"
  → Edge A (active): user prefers vim (valid_from: T0, valid_until: NULL, expired_at: NULL)

Turn 2: User says "Actually, I switched to neovim"
  → Edge A (inactive): user prefers vim (valid_from: T0, valid_until: T2, expired_at: T2, supersedes_id: NULL)
  → Edge B (active): user prefers neovim (valid_from: T2, valid_until: NULL, expired_at: NULL, supersedes_id: A.id)

Both edges are stored. Queries for “current user preferences” skip expired edges; queries for “user preference history” see both.

Conflict Resolution

When a graph extraction LLM produces a fact that logically conflicts with an existing active edge, a ConflictResolver evaluates the conflict using three strategies:

The default recency strategy is fast (no extra API call) and suitable for most use cases. Set conflict_resolution_strategy to change:

[memory.graph]
conflict_resolution_strategy = "recency"  # "recency", "confidence", or "llm" (default: "recency")

Conflicts are defined as edges where (source_entity_id, target_entity_id) match an active edge, indicating the same relationship exists but with different relation semantics or contradictory facts.

Ontology Normalization

The graph extraction LLM may use varying relation names (prefers, prefer, preferred, likes) for semantically identical relationships. An OntologyTable with LRU caching normalizes predicate names:

Input relation: "prefers"
Canonical form: "prefers"  (cached after first normalization)

Input relation: "prefer"
Cached normalization: "prefers"  (next call returns immediately)

The cache holds 4096 entries with O(1) lookup. When cache misses occur (rare, on novel predicates), an LLM call produces the canonical form and caches the result. The cache is guarded by ArcSwap, allowing non-blocking reads during background normalization.

Advanced Tuning

The following fields under [memory.graph] control performance and resource usage. They rarely need adjustment in typical deployments.

[memory.graph]
community_summary_max_prompt_bytes = 8192
community_summary_concurrency = 4
lpa_edge_chunk_size = 10000
pool_size = 3

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

Gonka (native):

zeph vault set ZEPH_GONKA_PRIVATE_KEY <secp256k1-hex-key>
zeph init  # select "Gonka (native)" when prompted

Gonka (GonkaGate):

zeph vault set ZEPH_COMPATIBLE_GONKAGATE_API_KEY gp-...
zeph init  # select "Gonka (GonkaGate)" when prompted

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, gonka, candle, compatible
model = "claude-sonnet-4-6"

At runtime, use the /provider <name> command to switch providers:

> /provider claude
Switched to Claude (claude-sonnet-4-6)

The chosen provider is now the active provider for this channel. On the next session start, Zeph automatically restores the last-used provider for that channel.

Provider Persistence

Zeph remembers the last provider you used per channel (CLI, TUI, Telegram). When you restart or switch channels, your preferred provider is restored automatically:

• CLI/TUI: last provider is saved globally (both share the same channel_id = "")
• Telegram: last provider is saved per chat (when configured with per-chat wiring)

Enable persistence with:

[session]
provider_persistence = true     # default: enabled

Disable it to always start with the default provider:

[session]
provider_persistence = false

Provider preferences are stored in SQLite alongside session metadata. If you switch providers and the session crashes before a successful turn, the previous provider preference is restored on the next session start.

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.

Per-Subsystem Embedding Providers

Every subsystem that generates vector embeddings has its own embed_provider or embedding_provider config field. Pointing these at a dedicated embedding provider (e.g., a local Ollama model) prevents embedding requests from saturating the chat provider’s connection pool or triggering guardrails.

When a field is empty or omitted, the subsystem falls back to the agent’s primary LLM provider. For deployments using Claude (which does not support embeddings) or any cloud provider where embedding volume is significant, set all five fields to a dedicated embedding provider:

[[llm.providers]]
name = "embed"
type = "ollama"
model = "nomic-embed-text"
embed = true

[memory.semantic]
embed_provider = "embed"

[skills]
embedding_provider = "embed"

[skills.mining]
embedding_provider = "embed"

[index]
embed_provider = "embed"

[mcp.tool_discovery]
embedding_provider = "embed"

This ensures that a burst of embedding requests (e.g., during code indexing or skill hot-reload) does not compete with ongoing chat inference.

Next Steps

• 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
• SkillOrchestra — RL-based adaptive routing that learns from execution outcomes
• 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
• Structured output envelope: shell results include exit code, stdout, stderr as separate fields for reliable parsing
• Transactional execution: when enabled, the shell executor snapshots the working directory before execution and can rollback on failure. Configure max_snapshot_bytes to limit snapshot size
• Credential scrubbing: environment variables matching credential patterns are scrubbed from subprocess environments
• 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).

Adversarial Policy Agent

The adversarial policy agent is an optional pre-execution validation layer that uses an LLM to evaluate tool calls before they run. When enabled, each tool call is sent to a lightweight LLM that assesses whether the call is safe, appropriate, and aligned with the user’s intent. Suspicious calls are blocked or flagged for confirmation.

[tools.adversarial_policy]
enabled = true
provider = "fast"              # Provider name for validation LLM
block_on_reject = true         # Block rejected calls (false = warn only)

The adversarial policy agent is distinct from the permission system — permissions are pattern-based and static, while the policy agent uses LLM reasoning to evaluate context-dependent risk.

File Read Sandbox

File read operations are controlled by a configurable per-path sandbox in [tools.file]:

[tools.file]
allowed_paths = ["/home/user/project"]   # Sandbox directories (empty = cwd only)

This is independent of the shell sandbox ([tools.shell].allowed_paths). File tools and shell tools can have different access scopes.

Deep Dives

• Tool System — full reference with filter pipeline, iteration control, and error taxonomy
• 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.

load_skill is registered alongside other tools (shell, file, web scrape, etc.) and exposed to the LLM via the standard native tool catalog on all providers.

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
}

CLI Subcommand

Manage scheduled jobs outside the agent session using the zeph schedule subcommand (requires the scheduler feature). All commands operate on the same SQLite database used by the running agent.

# List all jobs
zeph schedule list

# Add a recurring job (cron expression + prompt)
zeph schedule add "0 3 * * *" "run memory cleanup" --name daily-cleanup --kind memory_cleanup

# Show details of a single job
zeph schedule show daily-cleanup

# Remove a job
zeph schedule remove daily-cleanup

schedule add accepts any valid 5-field or 6-field cron expression. The --kind flag defaults to custom if omitted. The --name flag is optional — if omitted, a name is auto-generated from the BLAKE3 hash of the prompt.

See CLI Reference — zeph schedule for the full flag list.

Listing Tasks

Use any of the following to view all scheduled tasks:

• CLI subcommand: zeph schedule list — prints a table with NAME, KIND, MODE, NEXT RUN, and CRON columns. Works outside of an agent session.
• 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; TaskGraphStore 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

Context Budgets

Zeph manages how much of the LLM’s context window is used for each category of information. When context_budget_tokens is set, the available space is divided proportionally so that no single category dominates the prompt.

Budget Allocation

The remaining space is used for the system prompt, active skills, graph memory facts (4% when enabled), and tool schemas.

[agent]
context_budget_tokens = 128000   # 0 = auto-detect (default)

When left at 0, Zeph queries the provider for its context window size and uses that as the budget. If the provider does not report a context window (e.g., some local models), Zeph falls back to 128,000 tokens as a safe default. This fallback also applies during reload_config() to prevent unbounded memory growth. Set this value explicitly to override auto-detection (e.g., 128000 for a 200K-token model with margin for the response).

BATS Budget Hints

Budget-Aware Token Steering (BATS) injects a hint into the system prompt that tells the LLM how much context space remains. This helps the model:

• Produce appropriately-sized responses instead of exhausting the remaining budget
• Decide whether to call a tool (which adds tokens) or answer from existing context
• Choose concise tool arguments when budget is tight

BATS also implements a utility-based action policy that evaluates each turn against five action categories:

The action with the highest expected utility given the current budget and conversation state is selected. This prevents the agent from making expensive tool calls when the budget is nearly exhausted.

Skill Prompt Modes

When context budget is tight, skill injection adapts automatically:

[skills]
prompt_mode = "auto"   # "auto", "compact", or "full"

In compact mode, only the skill name, description, and trigger phrases are included — the full body is omitted. This keeps skill matching functional even when the context window is nearly full.

Compaction Tiers

When messages exceed the budget, Zeph applies two tiers of compression:

1. Soft compaction (at 70% of budget) — prunes old tool outputs and applies pre-computed deferred summaries. No LLM call needed.
2. Hard compaction (at 90% of budget) — runs chunked LLM-based summarization. Messages are split into ~4096-token chunks, summarized in parallel, then merged.

Both tiers use dual-visibility flags: original messages become hidden from the LLM but remain visible in the UI. Summaries are visible to the LLM but hidden from the UI.

[memory]
soft_compaction_threshold = 0.70   # fraction of budget (default: 0.70)
hard_compaction_threshold = 0.90   # fraction of budget (default: 0.90)

Next Steps

• Context Engineering — full compaction pipeline, proactive compression, and tuning
• Memory and Context — how memory and context work together
• Token Efficiency — how tokens are counted and optimized

Database Abstraction

Zeph uses the zeph-db crate as a unified database abstraction layer. All SQL operations go through typed query builders instead of raw SQL strings, eliminating sqlx leaks and dynamic query injection vectors.

Supported Backends

The backend is selected at build time via feature flags. All query interfaces are identical regardless of backend — application code does not branch on database type.

Migration

Database schema migrations are managed by zeph-db and applied automatically on startup. You can also run them manually:

zeph db migrate                    # apply pending migrations
zeph db migrate --status           # show migration status

The migrate-config wizard detects backend changes and generates the appropriate connection string.

Configuration

SQLite (default):

[memory]
database_url = "sqlite://~/.zeph/data/zeph.db"

PostgreSQL:

[memory]
database_url = "postgres://user:pass@localhost/zeph"

Store the PostgreSQL connection string in the vault for production use:

zeph vault set ZEPH_DATABASE_URL "postgres://user:pass@localhost/zeph"

Security Hardening

• All queries use parameterized statements — no string interpolation
• Dynamic column/table names are validated against an allowlist at compile time
• Connection pool settings are tuned per-backend (SQLite: single writer, PostgreSQL: configurable pool size)

Reactive Hooks

Zeph can run shell commands automatically in response to environment changes and tool execution events. Four hook events are supported: working directory changes, file system changes, tool execution before/after.

Hook Types

pre_tool_use and post_tool_use

Fires before and after a tool is executed. Useful for logging, monitoring, security auditing, or modifying the environment before/after tool runs.

Pre-execution (before tool runs):

[[hooks.pre_tool_use]]
tools = "shell|bash|sh"              # Pipe-separated tool name patterns (glob matching)
command = "echo"
args = ["About to run: $ZEPH_TOOL_NAME with args: $ZEPH_TOOL_ARGS_JSON"]

Post-execution (after tool runs):

[[hooks.post_tool_use]]
tools = "write_file|edit_file"       # File write tools
command = "git"
args = ["add", "$ZEPH_TOOL_NAME"]
fail_closed = false                  # If true, hook failure aborts the tool chain (default: false)

Environment variables available to hook processes:

Hook firing order:

Pre-hooks fire before utility gate and permission checks. This means observers can see all tool invocations, including those that would be blocked by policies. Post-hooks fire after successful execution.

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

# Pre-tool-use hooks — run before any tool execution
[[hooks.pre_tool_use]]
tools = "shell|bash|sh"           # Tool name pattern (pipe-separated, glob matching)
command = "echo"
args = ["Running: $ZEPH_TOOL_NAME"]
fail_closed = false               # If true, hook failure aborts the tool (default: false)

# Post-tool-use hooks — run after tool execution completes
[[hooks.post_tool_use]]
tools = "write_file"
command = "git"
args = ["add", "$ZEPH_TOOL_NAME"]
fail_closed = false               # If true, hook failure blocks subsequent tools

# 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"]

Tool Pattern Matching

Tool name patterns support pipe-separated patterns and glob matching:

# Match exact tool names
tools = "shell"                     # Only the shell tool

# Match multiple tools
tools = "shell|bash|sh"             # Any shell variant

# Glob patterns (glob syntax)
tools = "write_*"                   # write_file, write_dir, etc.

# Combine exact and globs
tools = "shell|*_file"              # shell tool or any *_file tool

Patterns are matched case-sensitively. An empty pattern matches no tools.

Hook Tracing and Instrumentation

All hook execution is instrumented with distributed tracing. Each hook invocation generates:

• zeph.hooks.cwd_changed span — execution of a cwd_changed hook
• zeph.hooks.file_changed span — execution of a file_changed hook

Spans include:

Traces are exported to your configured telemetry backend (local Chrome JSON or Jaeger OTLP) and are visible in profiling tools like Perfetto. This allows you to identify slow hooks and optimize them.

Hook Propagation on Config Reload

When zeph reload-config is called (or config changes are hot-reloaded), hooks are immediately re-parsed and re-registered. The TUI and scheduler receive hook update notifications so they can reconfigure watchers without restarting.

For file_changed hooks:

1. Old watchers are stopped
2. New watch paths are parsed from the updated config
3. Handlers are registered with the new watcher
4. The next file modification triggers the updated hooks

For cwd_changed hooks:

1. The hook list is updated in memory
2. The next working directory change fires the new hooks

This enables configuration updates without restarting the agent process.

Reactive Events

Zeph fires reactive events when the environment changes beneath the agent. Events are processed synchronously before the next agent turn, ensuring hooks complete before the LLM sees the updated context.

CwdChanged

Fires after every tool execution turn when std::env::current_dir() differs from the directory recorded at the start of the turn. This covers both explicit set_working_directory calls and any side effects from shell commands that change the process cwd.

Hook commands receive the old and new paths via environment variables:

Use cases:

• Auto-run git status when switching into a different repo
• Reload environment variables (e.g., .envrc) when entering a project directory
• Notify external tools (e.g., tmux pane title, status bar) of the active project

[[hooks.cwd_changed]]
type         = "command"
command      = "git"
args         = ["status", "--short"]
timeout_secs = 10
fail_closed  = false

[[hooks.cwd_changed]]
type         = "command"
command      = "echo"
args         = ["Entered $ZEPH_NEW_CWD"]
timeout_secs = 5
fail_closed  = false

FileChanged

Fires when a file under one of the configured watch_paths is modified. The watcher uses notify-debouncer-mini with a configurable debounce window (default: 500 ms), so rapid successive writes produce a single event.

The changed file path is passed to hook commands via:

Use cases:

• Run cargo check on every save during a coding session
• Regenerate documentation when a source file changes
• Invalidate a cache or restart a development server

Configure glob patterns for watch_paths and add one or more handler commands:

[hooks.file_changed]
watch_paths  = ["src/", "tests/", "Cargo.toml"]
debounce_ms  = 300

[[hooks.file_changed.hooks]]
type         = "command"
command      = "cargo"
args         = ["check", "--quiet"]
timeout_secs = 30
fail_closed  = false

[[hooks.file_changed.hooks]]
type         = "command"
command      = "echo"
args         = ["Changed: $ZEPH_CHANGED_PATH"]
timeout_secs = 5
fail_closed  = false

watch_paths accepts relative paths (resolved from the agent’s working directory at startup) or absolute paths. Directories are watched recursively.

Hook Execution Model

Each hook definition (HookDef) carries:

Multiple hooks for the same event are executed in declaration order. If fail_closed = true on any hook, a failure in that hook stops execution of subsequent hooks for that event.

TurnComplete

Fires after each agent turn completes. This hook does not block the turn — it runs fire-and-forget in the background and allows notification integrations, logging, or external system updates to happen after the agent responds.

Hook commands receive environment variables describing the turn outcome:

Use cases:

• Send a custom notification via a webhook
• Log turn metrics to an external service
• Sync agent state to an external system after each turn

[[hooks.turn_complete]]
type         = "command"
command      = "curl"
args         = ["-X", "POST", "http://localhost:9999/webhook", "-d", "status=$ZEPH_TURN_STATUS"]
timeout_secs = 5
fail_closed  = false

When a [notifications] block is configured, turn_complete hooks share the same should_fire gate — the hook only runs if notifications are also configured to fire. When [notifications] is absent or enabled = false, turn_complete hooks fire on every turn.

PermissionDenied

Fires when a tool execution is blocked by any gate check: policy gates, sandbox restrictions, permission layers, rate limiters, quota limits, utility action restrictions, or dependency failures. This comprehensive hook allows you to log or audit all blocked tool calls before they reach the user or external systems.

Hook commands receive:

Denial reasons include:

• quota exceeded — tool execution quota exhausted
• policy gate: <name> — blocked by a named policy gate
• sandbox violation: <type> — sandbox restriction violated
• rate limit exceeded — API rate limit hit
• dependency failed — dependent tool or resource unavailable
• utility action: <action> — blocked by a utility gate (e.g., ModelSwitch, ConfigReload)
• blocked by before_tool layer — pre-execution permission check

Use cases:

• Log security audit events to a central system
• Alert on suspicious tool invocation patterns
• Track which policies are enforcing restrictions
• Monitor quota exhaustion

[[hooks.permission_denied]]
type         = "command"
command      = "logger"
args         = ["-t", "zeph-security", "Denied tool: $ZEPH_DENIED_TOOL - $ZEPH_DENY_REASON"]
timeout_secs = 5
fail_closed  = false

MCP Tool Hooks

Hooks support direct MCP tool invocation via type = "mcp_tool". When type = "mcp_tool", the hook invokes a tool on a connected MCP server instead of spawning a subprocess.

[[hooks.cwd_changed]]
type     = "mcp_tool"
server   = "filesystem"        # MCP server id
tool     = "write_file"        # MCP tool name
args     = {"path": "/tmp/log", "contents": "Changed to $ZEPH_NEW_CWD"}
fail_closed = false            # ignored if server unavailable

MCP tool hooks require the MCP manager to be active. If the server is unavailable, the hook result depends on fail_closed:

• fail_closed = false (default): error is logged and the turn continues
• fail_closed = true: turn is blocked until the tool succeeds or timeout expires

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.

Gonka AI Provider

Gonka is a decentralized AI inference network built on a Cosmos-SDK chain that routes LLM requests to a peer-to-peer pool of GPU operators. Zeph supports two access paths.

Gonka is particularly useful for:

• Privacy-preserving inference — Requests are signed with your key; no account credentials stored on Gonka servers
• Cost control — Direct token consumption with no markup or subscription fees
• Decentralization — Work is distributed across independent GPU operators

Path A: GonkaGate (Recommended for quick start)

GonkaGate is a hosted gateway to the Gonka network with USD-denominated billing — no token staking required.

Setup:

1. Sign up at https://gonkagate.com/en/register and create a gp-... API key.
2. Store the key in the Zeph vault:

   zeph vault set ZEPH_COMPATIBLE_GONKAGATE_API_KEY gp-...
   

3. Run zeph init and select “Gonka (decentralized — via GonkaGate)” when prompted for a provider.

Resulting config:

[[llm.providers]]
type = "compatible"
name = "gonkagate"
base_url = "https://api.gonkagate.com/v1"
model = "gpt-4o"

Pricing: USD-denominated. Top up at https://gonkagate.com.

Path B: Native Gonka Network (Requires GNK staking)

The native path connects directly to Gonka inference nodes over a signed transport. Requests are authenticated with a secp256k1 key and GNK tokens are consumed per inference.

Prerequisites:

• Download and install inferenced CLI from https://github.com/gonka-ai/gonka/releases.
• Acquire GNK tokens and fund your address.

Setup:

1. Create a key with inferenced:

   inferenced keys add zeph
   

2. Store the signing key in the Zeph vault:

   zeph vault set ZEPH_GONKA_PRIVATE_KEY <your-hex-encoded-secp256k1-key>
   zeph vault set ZEPH_GONKA_ADDRESS <your-bech32-address>  # optional, for validation
   

3. Run zeph init and select “Gonka (native — requires GNK staking)”.

Resulting config:

[[llm.providers]]
type = "gonka"
name = "gonka-mainnet"
model = "gpt-4o"
gonka_chain_prefix = "gonka"

[[llm.providers.gonka_nodes]]
url = "https://node1.gonka.ai"
address = "gonka1..."

[[llm.providers.gonka_nodes]]
url = "https://node2.gonka.ai"
address = "gonka1..."

[[llm.providers.gonka_nodes]]
url = "https://node3.gonka.ai"
address = "gonka1..."

Pricing: GNK token consumption per inference.

How GonkaProvider Works

The native Gonka integration (Path B) uses three components working together:

RequestSigner

RequestSigner handles request authentication using your secp256k1 private key. Every request is signed with:

1. Request serialization — The message payload (chat parameters, tools, etc.) is serialized to JSON
2. Signing — The payload is signed using secp256k1 ECDSA with your private key
3. Envelope — The signature and public key are included in the request headers

EndpointPool

EndpointPool manages multiple Gonka nodes for redundancy and load distribution:

• Maintains a pool of healthy node endpoints from [[llm.providers.gonka_nodes]] entries
• Performs health checks to detect unavailable nodes
• Routes requests round-robin across available nodes
• Falls back to alternative nodes on failure

Capabilities

GonkaProvider supports all standard Zeph LLM capabilities:

Configuration Details

Full Native Gonka Config Example

[llm]

[[llm.providers]]
type = "gonka"
name = "gonka-mainnet"
model = "gpt-4o"
gonka_chain_prefix = "gonka"
max_tokens = 4096

# List of available inference nodes
[[llm.providers.gonka_nodes]]
url = "https://node1.gonka.ai"
address = "gonka1acnx3cpm8cz5nqu24aql4cqx5fxqm9w4vf2hqr"

[[llm.providers.gonka_nodes]]
url = "https://node2.gonka.ai"
address = "gonka1bcx3cpm8cz5nqu24aql4cqx5fxqm9w4vf2xyz"

[[llm.providers.gonka_nodes]]
url = "https://node3.gonka.ai"
address = "gonka1ccx3cpm8cz5nqu24aql4cqx5fxqm9w4vf2abc"

Combining Gonka with Local Embeddings

If you want Gonka for chat but prefer local embeddings for cost reasons:

[[llm.providers]]
type = "gonka"
name = "gonka-chat"
model = "gpt-4o"
gonka_chain_prefix = "gonka"
default = true          # use for chat

[[llm.providers]]
type = "ollama"
name = "local-embed"
embedding_model = "nomic-embed-text"
embed = true            # use for embeddings

[memory.semantic]
embed_provider = "local-embed"

[skills]
embedding_provider = "local-embed"

Troubleshooting

Run the built-in diagnostic tool to check credentials and node reachability:

zeph gonka doctor
# or for machine-readable JSON output:
zeph gonka doctor --json

The doctor prints [OK], [WARN], or [FAIL] for each check: vault key resolution, signer construction, and per-node HTTP probes with latency. Exit code is 0 on success, 1 on failures.

Migrating from GonkaGate to Native

Run zeph migrate-config — it will add advisory comments to your config pointing to the fields that need updating. Then:

1. Install inferenced and fund your GNK address.
2. Store ZEPH_GONKA_PRIVATE_KEY in the vault.
3. Update [[llm.providers]] in your config: change type = "compatible" to type = "gonka" and add [[llm.providers.gonka_nodes]] entries.

Cocoon Decentralized TEE Provider

Cocoon is a decentralized inference network that executes LLM requests in Trusted Execution Environments (TEEs) on a peer-to-peer network of secure nodes. Zeph supports native integration with optional speech-to-text transcription via the Cocoon sidecar.

Cocoon is particularly useful for:

• Confidential inference — Requests execute in hardware-isolated TEEs; no server-side model access
• Privacy compliance — End-to-end encrypted communication path with zero-knowledge server operations
• Flexible deployment — Run locally with a sidecar or connect to public Cocoon nodes
• Multi-modal support — Text chat, tool use, and STT transcription in one provider

Setup

Prerequisites

1. Install the Cocoon sidecar (local deployment only):

   # Download from https://cocoon.org or build from source
   cocoon --version
   

2. Start the sidecar on the default port (8765):

   cocoon serve
   # Or on a custom port:
   cocoon serve --port 9000
   

Configuration

Add a Cocoon provider entry to your config:

[[llm.providers]]
type = "cocoon"
name = "cocoon-local"
base_url = "http://localhost:8765"  # Sidecar endpoint
model = "llama2-7b"                 # Available model on sidecar

Or store the base URL in the vault for security:

zeph vault set ZEPH_COCOON_CLIENT_URL "http://localhost:8765"

Then reference it in config:

[[llm.providers]]
type = "cocoon"
name = "cocoon-local"
base_url = "${ZEPH_COCOON_CLIENT_URL}"
model = "llama2-7b"

Features

Chat and Streaming

Cocoon supports both single-turn and streaming chat:

[[llm.providers]]
type = "cocoon"
name = "cocoon"
base_url = "http://localhost:8765"
model = "llama2-7b"
max_tokens = 2048
temperature = 0.7

Tool Use (Function Calling)

Cocoon fully supports tool definitions and structured function calling:

• Define tools in your skills and system prompt
• Zeph automatically formats tool calls for Cocoon
• Streaming tool use is supported with incremental JSON parsing

Speech-to-Text (STT)

The Cocoon sidecar includes a Whisper-compatible STT endpoint at /v1/audio/transcriptions. Configure Zeph to use it:

[[llm.providers]]
type = "cocoon"
name = "cocoon-stt"
stt_model = "whisper-1"  # Enable STT on this provider

When configured, Zeph automatically transcribes voice messages and Telegram audio notes using this provider. See Audio & Vision for more details.

Per-Token Pricing (Cocoon Models)

Unlike cloud providers, Cocoon models may not be in Zeph’s built-in pricing table. Configure per-1K-token pricing for accurate cost tracking:

[[llm.providers]]
type = "cocoon"
name = "cocoon-custom"
base_url = "http://localhost:8765"
model = "my-custom-model"

# Per-1K-token pricing in cents (prompt + completion)
cocoon_pricing = { prompt_cents = 1, completion_cents = 2 }

This enables the cost tracker to report accurate token consumption and pricing for your Cocoon inference.

Multi-Model Routing

Combine Cocoon with other providers for cost-effective multi-tier inference:

[[llm.providers]]
type = "cocoon"
name = "cocoon-smart"
base_url = "http://localhost:8765"
model = "llama2-13b"

[[llm.providers]]
type = "ollama"
name = "ollama-fast"
base_url = "http://localhost:11434"
model = "qwen3:1.7b"

[llm]
routing = "triage"  # Route by complexity

[llm.complexity_routing]
triage_provider = "ollama-fast"
simple = "ollama-fast"      # Quick questions → fast model
medium = "ollama-fast"      # Moderate tasks → fast model
complex = "cocoon-smart"    # Complex reasoning → TEE
expert = "cocoon-smart"     # Expert tasks → TEE

Diagnostics

Use the zeph cocoon doctor command to verify sidecar health and configuration:

zeph cocoon doctor

Output example:

Cocoon Diagnostics
==================
Config entry:           [OK] cocoon-local present in config
Sidecar reachability:   [OK] http://localhost:8765/stats
Proxy connection:       [OK] Direct connection established
Worker count:           [OK] 4 workers available
Model listing:          [OK] 7 models available
Vault key resolution:   [OK] ZEPH_COCOON_CLIENT_URL resolved

JSON Output

For automation and scripting, use --json:

zeph cocoon doctor --json

TUI Integration

When using the TUI dashboard with Cocoon enabled, check sidecar status and available models:

• /cocoon status — Display sidecar health, worker count, and TON balance
• /cocoon models — List all available models on the sidecar

Status updates automatically every 30 seconds in the background.

Configuration Reference

Troubleshooting

Sidecar Not Reachable

If you see Cocoon: sidecar unreachable in the TUI status bar:

1. Verify the sidecar is running:

   curl -s http://localhost:8765/stats | jq .
   

2. Check the base URL matches your sidecar port

3. Ensure network connectivity (if sidecar is on a different machine)

Vault Key Issues

If zeph cocoon doctor reports vault key errors:

# Set the URL in the vault
zeph vault set ZEPH_COCOON_CLIENT_URL "http://localhost:8765"

# Verify it resolves
zeph vault get ZEPH_COCOON_CLIENT_URL

STT Not Working

Verify the Whisper endpoint is available on the sidecar:

curl -s http://localhost:8765/v1/audio/transcriptions -X OPTIONS

If it returns 405 or 404, the sidecar may not have STT support compiled in.

See Also

• Audio & Vision — Configure STT backends and vision models
• LLM Providers — Overview of all supported providers
• Configuration Reference — Full config file documentation

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.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, user whitelisting, and support for Guest Mode and Bot-to-Bot communication.

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 and Response Updates

Telegram has API rate limits, so streaming works differently from CLI. Zeph batches response chunks and updates them on a configurable interval:

• First chunk sends a new message immediately
• Subsequent chunks accumulate and edit the existing message in-place
• Edit interval is configurable via stream_interval_ms (default 3000ms, minimum 500ms)
• Long messages (>4096 chars) are automatically split
• MarkdownV2 formatting is applied automatically

Configuring Stream Interval

Adjust the streaming update frequency to match your network conditions:

[telegram]
stream_interval_ms = 3000  # Edit every 3 seconds (default)
# For slower connections, increase the interval:
# stream_interval_ms = 5000  # Edit every 5 seconds
# For faster feedback, decrease it:
# stream_interval_ms = 1000  # Edit every 1 second (minimum 500ms)

Lower values provide more responsive feedback but consume more API quota. Higher values reduce API calls but responses appear less fluid. Start with the default and adjust based on your network speed and API rate limit tolerance.

Guest Mode and Bot-to-Bot Communication

Zeph supports advanced Telegram modes for integration with other bots and guest users.

Guest Mode

Guest Mode allows Zeph to receive messages from guest users who interact via a unique link without having a Telegram account. The bot acts as a transparent proxy for guest queries:

Use cases:

• Allow non-Telegram users to chat with Zeph via a web portal
• Integrate Zeph into public-facing applications
• Avoid requiring users to create Telegram accounts

Configuration:

[telegram]
guest_mode = true

When enabled, Zeph spawns a local HTTP proxy that intercepts getUpdates responses and extracts guest messages. Guest users see a system prompt annotation indicating their guest context, and responses are accumulated before being sent as a single reply.

Bot-to-Bot Communication

Bot-to-Bot mode allows Zeph to receive and respond to messages relayed from other Telegram bots. This is useful for cascading bot workflows where one bot routes requests to Zeph for specialized processing.

Use cases:

• Route specific request types from a primary bot to Zeph for expert processing
• Build bot pipelines where Zeph acts as a specialist in a workflow
• Avoid API conflicts when multiple bots are active in the same chat

Configuration:

[telegram]
bot_to_bot = true
allowed_bots = ["@specialist_bot", "@analyzer_bot"]
max_bot_chain_depth = 3

Fields:

When enabled, Zeph registers with Telegram via setManagedBotAccessSettings on startup and tracks consecutive bot-to-bot reply depth to prevent circular loops. Messages from unauthorized bots are silently rejected.

Reaction Moderation Tools

Group admins can remove reactions from messages using two tools. Both require the bot to be a group admin and will gracefully degrade to warnings if the admin check fails.

telegram_delete_reaction

Remove a specific reaction from a message. The reaction field must be a non-empty string of up to 10 characters.

# Example tool invocation in agent code
[tool.telegram_delete_reaction]
chat_id = "-1001234567890"
message_id = 123
reaction = "👍"

telegram_delete_all_reactions

Remove all reactions from a message.

# Remove all reactions from a message
[tool.telegram_delete_all_reactions]
chat_id = "-1001234567890"
message_id = 123

Both tools require:

• Bot to be a member of the group
• Bot to have admin privileges in the group
• Valid chat ID and message ID

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

Network Timeouts

All Telegram API client connections are subject to a 30-second timeout. This ensures that slow or unresponsive server connections fail fast rather than blocking indefinitely. If you experience timeout errors, check your network connectivity and Telegram’s API status at Telegram Bot API Changelog.

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.

Channel Allowlist

Restrict a skill to specific I/O channels with x-channels. When set, the skill is excluded from matching on channels not in the list:

---
name: deploy-prod
description: Production deployment via kubectl.
x-channels: cli
---

This skill only activates in CLI mode — it is invisible in Telegram or TUI. Omit x-channels to allow all channels. Multiple channels are comma-separated: x-channels: cli, tui.

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.

Plugin Packages

For distributing and managing multiple related skills, utilities, and configurations together, Zeph supports plugin packages. A plugin is a directory containing a plugin.toml manifest that bundles:

• Multiple skill directories
• MCP server entries
• Configuration overlays (tighten-only: you can only restrict, not expand permissions)

Plugin Structure

my-plugin/
├── plugin.toml                 # Manifest file
├── skills/
│   ├── skill-one/
│   │   └── SKILL.md
│   └── skill-two/
│       └── SKILL.md
└── config/
    └── overlay.toml            # Optional config tightening rules

plugin.toml Format

[plugin]
name = "my-plugin"
version = "1.0.0"
description = "My plugin description"

# Skills bundled with this plugin (relative paths from plugin root)
[[plugin.skills]]
name = "skill-one"
path = "skills/skill-one"

[[plugin.skills]]
name = "skill-two"
path = "skills/skill-two"

# MCP servers managed by this plugin (optional)
[[plugin.mcp_servers]]
id = "my-mcp-server"
command = "python"
args = ["-m", "my_mcp_module"]

# Configuration overlay — restrictive only (default: empty)
[plugin.config_overlay]
# Union of blocked patterns:
tools.blocked_commands = ["dangerous_pattern"]

# Intersection of allowed patterns (if base is empty, stays empty):
# tools.allowed_commands = ["safe_pattern"]

# Maximum for numeric fields:
# skills.disambiguation_threshold = 0.1

Installing Plugins

Use zeph plugin add to install a plugin from a local path:

# From local directory
zeph plugin add /path/to/my-plugin

# List installed plugins
zeph plugin list

# Show the active plugin overlay (which plugins are active/skipped and why)
zeph plugin list --overlay

# Remove a plugin
zeph plugin remove my-plugin

Plugins are installed to ~/.local/share/zeph/plugins/<name>/ (XDG standard location). All bundled skills are automatically discovered and hot-reloaded without restart.

In TUI mode, use the /plugins commands:

/plugins list              # Show installed plugins
/plugins list --overlay    # Show the active plugin overlay
/plugins overlay           # Show the active plugin overlay (alias)
/plugins add <path>        # Install a plugin
/plugins remove <name>     # Remove a plugin

Plugin Integrity Check

When you install a plugin, Zeph records a sha256 digest of its .plugin.toml manifest in ~/.local/share/zeph/.plugin-integrity.toml. At startup and when hot-reloading, Zeph verifies this digest to detect if a plugin manifest has been modified outside of Zeph’s control.

If a manifest is tampered with:

• The plugin is skipped with an “integrity mismatch” reason
• You can see the skipped plugin and reason with zeph plugin list --overlay or /plugins overlay
• To re-protect the plugin, reinstall it: zeph plugin remove my-plugin && zeph plugin add /path/to/my-plugin

This provides basic tampering detection. The integrity check is not cryptographically signed, and concurrent installs may race (last writer wins).

Hot-Reload Behavior

Plugin config overlays — restrictions on tool access and embedding thresholds — are applied immediately when a plugin is installed or when you reload config mid-session. However, different overlay fields hot-reload differently:

Hot-reloads live (no restart needed):

• tools.blocked_commands — shell commands blocked by the agent are updated atomically on the next execution

Require agent restart:

• tools.allowed_commands — restrictions on allowed paths are applied at executor setup time. Zeph emits a RESTART REQUIRED warning when you change this setting

You do not need to restart Zeph when modifying blocked_commands — the agent picks up the new blocklist immediately. If you modify allowed_commands, you must restart Zeph for the change to take effect.

Plugin Security

• Path traversal defense: skill paths in the manifest are canonicalized and must resolve within the plugin root directory
• Config overlay validation: only tools.blocked_commands, tools.allowed_commands, and skills.disambiguation_threshold are permitted; other keys are rejected
• Trust escalation filter: bundled skills are assigned the Trusted trust level automatically at startup, bypassing the default quarantined level that external skills receive

See Skill Trust Levels for how trust levels control tool access.

Agent-Invocable Skills

Skills are typically matched to user queries automatically via semantic embedding. With the invoke_skill tool, the agent can explicitly fetch and execute any registered skill by name at runtime. This is useful for:

• Skills that should only run when explicitly requested
• Composing multiple skills in a single response
• Overriding the default embedding-based matching

Using invoke_skill in the LLM Response

When the agent needs to reference or use a skill, it calls the invoke_skill tool:

I'll use the "git-workflow" skill to help you:
<invoke_skill>
{
  "skill_name": "git-workflow",
  "args": "--verbose"
}
</invoke_skill>

The tool returns the skill body with security-aware sanitization:

• Blocked skills: refused with an error message
• Trusted skills: body returned as-is
• Quarantined skills: body wrapped with a quarantine warning

CLI Usage

Invoke skills from the command line:

zeph skill invoke git-workflow --verbose
zeph skill invoke deploy-prod --environment staging

Catalog

The agent sees an invoke_skill catalog during context assembly that lists all available skills with their names and descriptions. Use /skills in TUI or CLI to see the full registry.

Generate a Skill from a Description

Instead of writing SKILL.md manually, use /skill create with a natural language description:

/skill create "A skill that manages systemd services — start, stop, restart, status"

Zeph generates a complete SKILL.md with frontmatter, instructions, and examples. The skill is saved to your skills directory and hot-reloaded immediately. Duplicate detection prevents creating skills that overlap with existing ones.

Generated skills are scored on correctness, reusability, and specificity before being written to disk. A separate critic LLM evaluates the skill and filters out low-quality generations.

Skill Evaluation Configuration

Control how generated skills are evaluated:

[skills.evaluation]
enabled = true                    # enable external critic (default: true)
correctness_weight = 0.50         # importance of correctness (0.0-1.0)
reusability_weight = 0.25         # importance of broad applicability
specificity_weight = 0.25         # importance of precise instruction
pass_threshold = 0.60             # minimum score to accept (0.0-1.0)

When a generated skill scores below pass_threshold, it is rejected and the generation process is retried. If enabled = false, all generated skills are accepted without evaluation (fail-open).

Evaluation is disabled by default for generated skills from --init to keep initial setup fast; enable it in your config if you want quality gates on all subsequent /skill create commands.

See NL Skill Generation for details on generation from descriptions and GitHub repository mining.

Next Steps

• Skills — how embedding-based matching works
• Self-Learning Skills — automatic skill evolution
• NL Skill Generation — generate skills from descriptions or repos
• 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.

MCP Server Startup and Retry

When Zeph starts, it attempts to connect to all configured MCP servers in parallel. Servers that fail to start (e.g., missing binary, network timeout, or slow startup) are automatically retried with exponential backoff.

Retry behavior:

1. Initial connection attempt — each server gets startup_timeout seconds to respond (default: 30 seconds)
2. Failure detection — if the server fails to initialize, auto-retry begins
3. Exponential backoff — subsequent attempts wait 1s, 2s, 4s, 8s, etc. up to max_retry_interval_secs
4. Eventual availability — servers are marked unavailable after max_retries attempts, but Zeph continues running without them
5. Runtime reconnection — if a server was unavailable at startup but comes online later, the agent can manually reconnect via /mcp add

Configuration:

[mcp]
startup_timeout_secs = 30          # Max time to wait for server initialization (default: 30)
max_retries = 5                    # Max reconnection attempts before giving up (default: 5)
initial_retry_interval_secs = 1    # Starting backoff interval (default: 1)
max_retry_interval_secs = 60       # Max backoff interval (default: 60)

Example timeline:

Start → stdio server fails (can't find binary)
  → Retry 1: wait 1s, attempt 2 fails
  → Retry 2: wait 2s, attempt 3 fails
  → Retry 3: wait 4s, attempt 4 succeeds ✓

OR

Start → stdio server fails (timeout)
  → Retry 1: wait 1s, attempt 2 fails
  → Retry 2: wait 2s, attempt 3 fails
  → Retry 3: wait 4s, attempt 4 fails
  → Retry 4: wait 8s, attempt 5 fails
  → Retry 5: wait 16s, attempt 6 fails
  → Server marked unavailable; Zeph continues without it
  → User can retry: /mcp add filesystem ...

Failed servers are logged with their error messages. Check RUST_LOG=debug to see detailed retry logs:

2025-05-06T10:30:15Z DEBUG mcp.startup: initializing server id=filesystem attempt=1
2025-05-06T10:30:16Z WARN mcp.startup: server filesystem failed: timeout after 30s; will retry
2025-05-06T10:30:17Z DEBUG mcp.startup: initializing server id=filesystem attempt=2 retry_interval=1s

Skipping slow servers:

If a particular server is slow to start but necessary for your workflow, increase its personal timeout:

[[mcp.servers]]
id = "slow-analyzer"
command = "python3"
args = ["-m", "my_mcp_server"]
startup_timeout = 60   # give this server 60 seconds instead of 30

Tip

Exponential backoff prevents the agent startup from hanging indefinitely on flaky servers. If a server consistently fails, consider whether it’s essential. If not, remove it from the config to speed up startup.

Native Tool Integration (Claude / OpenAI)

MCP tools are exposed as native ToolDefinitions alongside built-in tools. All providers use the same structured tool calling path.

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. The provider sees the current tool set on every turn without requiring a restart.

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.

Note

Elicitation is an unstable ACP extension compiled in via the unstable-elicitation feature flag in zeph-acp. Standard release builds include it. If you built Zeph without this feature, the elicitation/create method is not handled and requests from servers are silently ignored.

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.

Session Recap on Resume

When resuming a stored conversation via zeph (without --config-path specifying a new database), Zeph can auto-generate a recap of the prior session to refresh context. This is helpful for long sessions where context was compacted or when returning to a project days later.

Enable auto-recap in [session.recap]:

[session.recap]
on_resume = true              # Auto-generate recap on resume (default: true)
recap_provider = "fast"       # Provider for recap generation; empty = primary
max_tokens = 500              # Max tokens for the recap summary (default: 500)
max_input_messages = 50       # Max prior messages included in recap (default: 50)

You can also request a recap on-demand during an active session via the /recap slash command:

> /recap

A recap is skipped if:

• A session summary already exists in SQLite (from prior hard compaction or auto-recap at shutdown)
• max_input_messages = 0 (disabled)
• The recap LLM call times out (5-second timeout, logged as a warning, does not break the turn)

Recap context is shown as a visible system message so you can review what was recalled before resuming active work.

MCP Roots Protocol

Zeph implements the MCP Roots protocol, which allows MCP servers to discover the project root directory and workspace structure. When a server requests roots, Zeph responds with the current working directory and any configured project paths.

Tool descriptions from MCP servers are capped at a configurable limit to prevent oversized prompt injection from servers with verbose tool descriptions.

Server Instructions

MCP servers can provide a plain-text instructions field in their initialize response. When present, Zeph injects these instructions as a dedicated block in the system prompt so the LLM understands how to use the server’s tools effectively.

Instructions from all connected servers are concatenated (sorted by server ID for determinism) and injected once per turn. Each server’s instructions are separated by a blank line.

Note

Without server instructions the LLM must infer tool behavior from schema descriptions alone, which can lead to incorrect parameter choices or missed capabilities. Well-written server instructions significantly improve tool selection accuracy.

Instructions are sanitized at registration using the same 17-pattern injection scanner applied to tool descriptions. Patterns are replaced with [sanitized] — the instructions are still injected, but malicious payloads are neutralised.

Tool Call Quota

Limit the total number of tool calls the agent may make in a single session:

[tools]
max_tool_calls_per_session = 100   # default: unlimited

When the quota is exhausted, further tool calls are blocked and the agent is informed via a quota_blocked error. Retries of a failed call do not consume additional quota — only the first attempt counts. Set to null or omit the field to disable the limit.

OAP Authorization

On-Arrival Processing (OAP) is a declarative authorization layer that evaluates tool calls against capability-based rules before execution. OAP rules are appended after [tools.policy] rules using first-match-wins semantics, so existing deny rules in [tools.policy] always take precedence.

[tools.authorization]
enabled = true

[[tools.authorization.rules]]
action = "allow"
tools = ["read_file", "list_directory"]
comment = "Read-only filesystem access"

[[tools.authorization.rules]]
action = "deny"
tools = ["shell"]
comment = "Shell execution not permitted in this deployment"

OAP is disabled by default (enabled = false). Rules are merged into PolicyEnforcer at startup. Use [tools.policy] for safety-critical deny rules; use [tools.authorization] for capability grants that layer on top.

Structured Error Codes

MCP tool call failures include a typed McpErrorCode that the agent uses for retry and recovery decisions:

Timeouts and connection errors automatically map to transient. Policy violations (SSRF, command blocklist, OAP deny) map to policy_blocked. The error code is surfaced in logs and debug dumps alongside the server ID and tool name.

Caller Identity Propagation

Tool calls carry an optional caller_id field that identifies the originating agent or sub-agent. This field is set automatically when a sub-agent dispatches a tool call and is recorded in the tool audit log. Operators can use caller_id to trace which agent issued a specific tool call in multi-agent deployments.

Tool Output Schema

MCP servers can declare the structure of their tool outputs via the optional outputSchema field in a tool definition. Zeph automatically forwards this schema to LLM tool calls (Claude, OpenAI, Gemini, Ollama, and compatible servers), enabling the LLM to better understand and process structured tool results.

Benefits: