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