Website · 中文

Raven

Raven is the open-source, self-improving Agent Harness you can run today. It brings terminal-first execution, local tracing, long-term memory, skills, evaluation, and reusable workflows into one system for long-running AI work.

The Harness of Harnesses

As AI agents move from narrow tasks toward long-running, cross-domain work, manually designing a single, ever-larger harness stops scaling. A harness optimized for one model or domain also cannot provide every capability needed for general intelligence.

Raven also names the broader research and ecosystem direction behind this work: The Harness of Harnesses. It aims to automatically build and improve Agent Harnesses for specific models and domains, then compose their heterogeneous execution capabilities into an All-Domain Collaboration Network.

Trusted	Persistent	Evolving
Capability is earned through verified performance, not self-declared labels.	Verified results, task state, and long-term memory carry across executors.	Every real run improves capability profiles, skills, routing, and the network itself.

Raven does not treat a model and its harness as a fixed pair. Through a continuous evaluation -> execution -> verification -> memory -> feedback loop, it discovers, composes, and improves the right capabilities for each task. Validated work becomes reusable experience, allowing both individual agents and the wider capability network to evolve.

The Raven evaluation spans 22 Agent benchmark tasks across task quality, cost, and key mechanism gains. The reported results show broad performance and efficiency improvements over existing agent systems while advancing the quality-cost Pareto frontier.

Raven names both the runnable open-source harness in this repository and the broader multi-agent research and ecosystem direction described above.

Raven is pre-alpha. Interfaces and configuration may change quickly.

Benchmarks

Benchmark	Raven Result	Comparison
Efficiency	56.7% at 27B; 58.1% at 397B	Hermes 46.8% / 47.9%; +9.9pp at 27B
Self-evolution	Ranked #1 on EvoAgentBench	+6.2pp over the next result across four methods
Proactivity	0.60 F1 on ProAgentBench	2.4x Hermes/OpenClaw at 0.253

Results describe the published test configurations; model, task set, and evaluation protocol all affect outcomes.

otty-raven-onboarding.mp4

Quick Start

Install

Linux, macOS, or WSL2:

curl -fsSL https://raven.evermind.ai/install.sh | bash

Native Windows PowerShell:

irm https://raven.evermind.ai/install.ps1 | iex

Windows PowerShell 5.1 may reject the redirect. Use the direct installer URL instead:

irm https://raw.githubusercontent.com/EverMind-AI/Raven/refs/heads/main/install.ps1 | iex

Onboard and run

raven

That is the whole first run: with nothing configured yet, raven walks you through setup and then opens the TUI in the same session. To reconfigure later, run raven onboard explicitly.

The bilingual onboarding wizard configures six areas without requiring manual edits to ~/.raven/config.json:

1. LLM provider and model
2. Sandbox or execution location
3. Chat channels
4. EverOS long-term memory
5. Deep Research
6. Cold-start import from other AI tools

Provider setup includes an in-step connectivity check. Optional steps can be skipped and configured later. If setup is incomplete, run:

raven doctor

Upgrade

raven upgrade --check
raven upgrade

Upgrades preserve configuration, sessions, and memory. Raven does not update automatically.

Deep Research

Deep Research gives Raven a dedicated path for open-ended questions that require broad web search, source reading, analysis, and multi-source cross-checking. It uses MiroThinker and returns a self-contained answer with inline citations and references.

Configure it during onboarding or later:

raven deep-research enable
raven deep-research get

Once configured, Raven can invoke deep_research when a task needs more than a quick lookup. Before a paid, minute-scale run, interactive surfaces ask whether to use Deep Research or regular search for that query.

Delivery adapts to where Raven is running:

• CLI and TUI: progress streams inline while Raven searches, reads pages, and runs analysis. The completed report is shown directly without being rewritten by the main model.
• Gateway channels: the run continues in the background and the completed report is delivered back to the originating conversation.
• Local archive: every completed result is saved under <workspace>/deep_research/ for later use.

Use regular search for a single fact or URL. Use Deep Research for comparisons, landscape reviews, technical investigations, and questions where source agreement matters.

Tracing

Tracing makes Raven's reasoning path inspectable without sending trace data to a hosted service. Open the local dashboard with:

raven tracing

Each session.turn becomes a trace tree containing the work that happened beneath it:

• LLM calls, models, token usage, cost, latency, and errors
• Tool inputs and outputs
• Subagent runs and parent-child relationships
• Skill reads and injections
• Memory recall, storage, extraction, and consolidation
• Large prompts and results stored as out-of-line artifacts

Tracing is enabled by default and is designed to never interrupt Raven's control flow. Spans are stored locally at ~/.raven/traces/logs/audit-spans.log; set RAVEN_TRACING_DIR to move the state directory or RAVEN_TRACING=0 to disable recording.

The schema follows a small, versioned semantic contract. See the Tracing Standard API for span names, attributes, artifact behavior, and extension rules.

Core Systems

System	What it adds
EverOS memory	Durable user memory, agent memory, and world knowledge across sessions
Context Engine	Explicit token budgets and a unified assembly pipeline that preserves the most useful context
Proactivity	Sentinel observations, scheduled work, nudge policy, and deferred decisions
SkillForge	Built-in, workspace, EverOS, and mirrored skills with retrieval, feedback, and evolution
Evolver	Reproducible evaluation loops for improving agents and reusable procedures
Agent Templates	Shareable starting points for specialized digital workers built on the same harness

Providers and Gateways

Raven supports API-key, OAuth, local, and OpenAI-compatible providers. The onboarding catalog includes OpenRouter, OpenAI, Anthropic, Gemini, MiniMax, DeepSeek, Z.ai, DashScope, Moonshot, VolcEngine, SiliconFlow, Groq, AiHubMix, Azure OpenAI, GitHub Copilot OAuth, OpenAI Codex OAuth, Ollama, and hosted vLLM.

Twelve gateway adapters connect Raven to Telegram, Slack, Discord, WhatsApp, Matrix, Feishu, WeCom, Mochat, QQ, DingTalk, Email, and WeChat.

raven channels list
raven channels enable <adapter>
raven gateway

Command Reference

Command	Purpose
raven or raven tui	Launch the terminal UI
raven agent -m "..."	Run a one-shot task
raven onboard	Configure providers, sandboxing, channels, memory, research, and import
raven status	Show configuration and runtime status
raven doctor	Diagnose provider and environment problems
raven tracing	Open the local trace dashboard
raven sessions list	Browse, resume, fork, export, or delete sessions
raven skill list	Inspect the local SkillForge catalog
raven sentinel status	Inspect proactive memory and scheduled nudges
raven cron list	Inspect scheduled jobs
raven gateway	Run messaging gateways
raven upgrade	Upgrade a managed installation

Run raven --help or raven <command> --help for the complete CLI surface.

Documentation

• Documentation index
• Developer workflow
• Tracing Standard API
• Sandbox usage
• Memory plugin architecture
• Self-evolution loop mapping
• Proactivity implementation

Architecture

CLI / TUI / Messaging Gateways
              |
              v
          TUI-RPC / Spine
              |
              v
           Agent Loop
      +-------+-------+
      |       |       |
  Providers  Tools  Subagents
      |       |       |
      +--- Context Engine ---+
              |
      +-------+--------+
      |                |
 EverOS Memory     SkillForge
      |                |
      +--- Proactivity + Evolver

The Python runtime and React/Ink TUI communicate only through typed TUI-RPC. The Spine carries runtime events, while the Agent Loop coordinates providers, tools, context, memory, skills, subagents, and proactive work.

Key directories:

raven/agent/             agent loop, tools, and subagents
raven/channels/          messaging adapters
raven/context_engine/    context assembly and token budgeting
raven/memory_engine/     EverOS integration and local skill memory
raven/proactive_engine/  sentinel, scheduling, and nudges
raven/providers/         model providers and routing
raven/skill_hub/         external skill retrieval
raven/tracing/           instrumentation, storage, and viewer
raven/tui_rpc/           typed runtime-to-TUI boundary
ui-tui/                  React/Ink terminal interface

EverMind Ecosystem

Raven is part of the EverMind open-source ecosystem. Explore EverOS, EverAlgo, HyperMem, EvoAgentBench, EverMemBench, and EverMe.

Contributing

Issues and pull requests are welcome. Start with the developer workflow, follow AGENTS.md for repository rules, and use GitHub Discussions for design conversations.

License

Apache License 2.0