Raven: A Pre-Alpha Agent Harness That Puts Memory and Tracing Before Automation

What Raven Actually Solves Today

Raven is positioned as a self-improving agent harness, but the current public release is narrower than that slogan. The README is explicit: the Harness of Harnesses, the multi-agent ecosystem with an All-Domain Collaboration Network, is a next-version direction, not a capability of the runnable code. What you get today is a terminal-first system that ties together long-term memory, skills, evaluation, reusable workflows, and local tracing for long-running AI work. The target user is an engineer or researcher who wants to run agents for hours or days, inspect what the agent did, and let it improve across sessions. The memory component is not a bolt-on; it is EverOS long-term memory, which the onboarding wizard configures. This is not a library you import into a script. It is a harness you run from a terminal, with a TUI that appears on first launch. The distinction matters: Raven aims to be the environment where agents live, not a function you call.

The Mechanism: TUI, Onboarding, and the Six-Config Wizard

The core mechanism is a session-based loop. You run `raven` with no configuration, and the tool walks you through setup, then opens the TUI in the same session. The onboarding wizard covers six areas: LLM provider and model, sandbox or execution location, chat channels, EverOS long-term memory, Deep Research, and cold-start import from other AI tools. Each provider setup includes an in-step connectivity check, which is a practical touch for a tool that depends on external APIs. Optional steps can be skipped and configured later. If something is incomplete, `raven doctor` diagnoses it. The design choice is to avoid manual edits to `~/.raven/config.json`, which is good for new users but makes advanced configuration less discoverable. The README does not document the JSON schema, so if you need to tweak a setting that the wizard does not expose, you are on your own. The session concept is central: each `session.turn` becomes a trace tree, and that tree is what makes Raven different from a simple agent loop. The trace tree records LLM calls, token usage, cost, latency, tool inputs and outputs, subagent runs, skill reads, and memory operations. This is not a black box; it is a debugger for agent behavior.

Getting It Running: Commands and Config Keys

Installation is a one-liner for Linux, macOS, or WSL2: `curl -fsSL https://raven.evermind.ai/install.sh | bash`. Native Windows PowerShell uses `irm https://raven.evermind.ai/install.ps1 | iex`, with a note that PowerShell 5.1 may reject the redirect, so you might need the direct URL from the repository. After install, `raven` starts the onboarding and then the TUI. To reconfigure later, `raven onboard`. Upgrades are explicit: `raven upgrade --check` then `raven upgrade`. Upgrades preserve configuration, sessions, and memory, and there is no automatic update, which is a deliberate control point. For Deep Research, the commands are `raven deep-research enable` and `raven deep-research get`. Tracing has its own command, `raven tracing`, which opens a local dashboard. The tracing state directory defaults to `~/.raven/traces/logs/audit-spans.log`, and you can move it with `RAVEN_TRACING_DIR` or disable recording with `RAVEN_TRACING=0`. These are the only config keys mentioned in the README. The absence of a documented config schema is a limitation for anyone who wants to automate setup beyond the wizard.

Deep Research: MiroThinker and the Cost Gate

Deep Research is a separate path for open-ended questions that need broad web search, source reading, and multi-source cross-checking. It uses MiroThinker, an external service from miromind.ai. The README says Raven can invoke `deep_research` when a task needs more than a quick lookup. The key mechanism is the cost gate: before a paid, minute-scale run, interactive surfaces ask whether to use Deep Research or regular search. This is a sensible guardrail, because a deep research run is not a single API call; it is a multi-step process that can take minutes and cost real money. Delivery adapts to the surface: in CLI and TUI, progress streams inline and the completed report is shown directly without being rewritten by the main model. In gateway channels, the run continues in the background and the report is delivered to the originating conversation. Every completed result is saved under `<workspace>/deep_research/`. The README advises using regular search for a single fact or URL, and Deep Research for comparisons, landscape reviews, and technical investigations. The limitation is that Deep Research depends on MiroThinker, which is a third-party service, not something Raven controls. If MiroThinker is down or changes its API, Raven's deep research path breaks. The cost gate mitigates surprise charges, but it does not eliminate the dependency.

Tracing: The Local Audit Trail

Tracing is where Raven shows its strongest design. Every `session.turn` becomes a trace tree that records the work beneath it: LLM calls with 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 are stored as out-of-line artifacts, which keeps the trace file from bloating. Tracing is enabled by default and is designed to never interrupt control flow. The spans are stored locally at `~/.raven/traces/logs/audit-spans.log`. You can move the directory with `RAVEN_TRACING_DIR` or disable recording with `RAVEN_TRACING=0`. The dashboard opens with `raven tracing`. The schema follows a small, versioned semantic contract, documented in `docs/TRACING_STANDARD_API.md`. This is a genuine advantage for debugging agent behavior, especially for long-running tasks where you need to know what the agent actually did, not just what it said. The trade-off is storage growth: with tracing on by default, a long session with many tool calls and large artifacts could fill disk. The README does not mention rotation or retention policies, so you may need to manage that yourself.

The Limits: Pre-Alpha, the Harness of Harnesses Gap, and Benchmark Caveats

The README is unusually honest about what Raven is not. It says Raven is pre-alpha and that interfaces and configuration may change quickly. The Harness of Harnesses is explicitly not in the current release. The benchmark table in the README reports results from an internal research prototype, not the public release. The efficiency numbers, the EvoAgentBench ranking, and the ProAgentBench F1 scores all come from that prototype. The README even lists the confounders: model, task set, and evaluation protocol all affect outcomes. This is a critical distinction. If you read the benchmarks and assume the current Raven will give you a 2.4x proactivity gain or a #1 EvoAgentBench rank, you will be disappointed. The research prototype is a separate system. The public release is a harness with memory, tracing, and deep research, but the self-improving loop that the benchmarks describe is not fully implemented yet. The wrong tool case is clear: if you need a stable, production-grade agent framework with a mature API, Raven is not it. The version history shows a release every week or two (v0.1.11, v0.1.12, v0.1.13), which suggests rapid iteration but also instability.

Alternatives and the Real Difference in Approach

The README names Hermes and OpenClaw as comparisons in the benchmark table, but those are research baselines, not direct alternatives. For a practical comparison, the closest alternative is a framework like LangGraph or AutoGen, which also build agent loops with memory and tool use. The difference in approach is structural. LangGraph gives you a graph-based state machine where you define nodes and edges explicitly; you control the flow. Raven is a harness that wraps the flow for you, with a TUI and a wizard. You do not write a graph; you configure a system. That is a trade-off. If you need fine-grained control over the agent's decision points, a graph framework is better. If you want a ready-made loop with tracing and memory built in, Raven is closer to that. The other difference is local-first: Raven's tracing is local and does not send data to a hosted service, whereas some hosted agent platforms send traces to their cloud. The README does not compare Raven to LangGraph directly, so this is inference from the material, but the design choices are visible: Raven has a TUI, a doctor command, and a deep-research gate, none of which are typical in a graph library.

Maintenance, Upgrades, and License

The project is Apache-2.0 licensed, which is permissive for commercial use, but the README does not discuss contribution guidelines or a code of conduct, so the maintenance model is unclear. The release cadence is active: v0.1.13 was pushed on 2026-08-25, with v0.1.12 a week earlier and v0.1.11 two weeks before that. That suggests a team that is shipping quickly, but it also means you should expect breaking changes. The upgrade mechanism is explicit: `raven upgrade --check` and `raven upgrade`, and the README states that upgrades preserve configuration, sessions, and memory. There is no automatic update, which is a control point for stability. The cost of maintenance is that you will need to track releases and test your workflows against each new version. The tracing schema is versioned, which helps, but the README warns that interfaces may change quickly. For a pre-alpha project, that is the expected trade-off. The license is permissive, but the project depends on MiroThinker for deep research, which is a separate service with its own terms; the README does not detail those terms, so you should check them before relying on that path.

Editorial conclusion

Adopt Raven if you want a local-first agent harness with inspectable tracing, long-term memory through EverOS, and a built-in deep research path, and you can tolerate pre-alpha instability. Do not adopt it if you need production reliability, a stable API, or the Harness of Harnesses features promised for the next version, which are not in the current release. Before using it, verify that your LLM provider is supported by the onboarding wizard, that your sandbox or execution location meets the security requirements for running untrusted code, and that the tracing schema version matches what your tooling expects. Also check the upgrade path: upgrades preserve config and memory, but the README warns that interfaces and configuration may change quickly, so pin your version if you depend on a specific behavior.

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes