Raven is The Self-Improving Agent Harness, built on EverOS.
Raven helps agents improve across runs by continuously refining the systems around them: tools, skills, memory, code execution, policies, and working environment. EverOS provides durable user memory, agent memory, and world knowledge across sessions, so successful workflows can evolve into reusable Agent Templates and digital workers.
Table of Contents
- Quick Install
- What You Can Do in 2 Minutes
- Messaging Gateways
- Why Raven
- What Raven Is Built For
- Agent Templates
- Useful Commands
- Docs by Goal
- Architecture
- Developer Workflow
- Status
- Star Us
- EverMind Ecosystem
- Contributing
curl -fsSL https://raven.evermind.ai/install.sh | bashHeads up: Native Windows runs Raven without WSL. CLI, TUI, gateway, and tools install natively. If you would rather use WSL2, the Linux/macOS one-liner above works there too.
Run this in PowerShell:
irm https://raven.evermind.ai/install.ps1 | iexThe installer handles everything: uv, Python 3.12, Node.js 22, and Raven.
Open a new terminal. On Linux, macOS, or WSL2, you can also reload your current shell:
source ~/.bashrc # or: source ~/.zshrcThen run:
raven onboard
ravenRaven supports OpenRouter, OpenAI, Anthropic, Gemini, DeepSeek, GitHub Copilot, OpenAI Codex OAuth, and custom OpenAI-compatible endpoints.
If setup fails or a provider is not ready, run:
raven doctor- Start the Raven harness in a terminal-native TUI with
ravenorraven tui. - Run a one-shot shell task with
raven agent -m "...". - Configure providers, sandboxing, channels, and memory with
raven onboard. - Browse built-in and local SkillForge skills with
raven skill list. - Resume, fork, export, or delete previous work with
raven sessions list. - Check proactive memory and scheduled nudges with
raven sentinel status.
Raven currently ships 12 gateway adapters. Use raven channels list to see the
adapters available in your local install and raven gateway to run the gateway
daemon.
| Gateway | Adapter id | Notes |
|---|---|---|
| Telegram | telegram |
Bot-based messaging |
| Slack | slack |
Workspace messaging |
| Discord | discord |
Server and bot messaging |
whatsapp |
Uses the bundled TypeScript bridge | |
| Matrix | matrix |
Matrix rooms and direct messages |
| Feishu | feishu |
Lark/Feishu app integration |
| WeCom | wecom |
WeCom group and app messaging |
| Mochat | mochat |
API/socket-based messaging |
qq |
QQ bot integration | |
| DingTalk | dingtalk |
DingTalk stream integration |
email |
IMAP/SMTP mailbox integration | |
weixin |
Personal WeChat adapter; weixin is the current CLI id |
Most agent tools stop at "LLM + tools + loop." That works for demos, but it breaks down when the agent becomes part of your daily environment:
- Long sessions overflow context and lose important details.
- Every turn re-sends the same system prompt, skills, and tool definitions.
- The agent waits passively even when it can see something that needs action.
- Useful workflows stay trapped in chat history instead of becoming reusable skills.
Raven treats the harness around the agent as the product, not a thin wrapper or an edge case.
Raven's self-improving harness is built around three product bets:
- Memory-first harness: user memory, agent memory, and world knowledge stay separate, durable, and reusable across sessions.
- Self-improving skills: repeated workflows can become skills, collect feedback, and evolve instead of staying buried in chat history.
- Agent Templates: builders can start from Raven, define an agent for a scenario, and share it without rebuilding the harness layer.
| Capability | Raven | Typical tool-based agent |
|---|---|---|
| Native terminal product | Interactive TUI, CLI, gateway mode, and typed RPC between Python and React/Ink | Usually a thin command wrapper around a chat loop |
| Long memory | EverOS-backed memory, local skills, session history, and workspace templates | Usually transient context or provider-side chat history |
| Context control | Curator and legacy context engines with explicit token budgets and fail-safes | Usually truncation, summarization, or hidden prompt heuristics |
| Proactivity | Sentinel, scheduler, nudge policy, and deferred decision flow | Usually waits until the user types again |
| Skill evolution | Detects reusable procedures, materializes skills, tracks feedback, and evolves them | Usually static markdown prompts or manually installed plugins |
Raven is designed for the workflows where ordinary chat agents and static tool loops feel too small.
Raven can run the harness as a native TUI, a direct CLI entry point, or a gateway-backed runtime. The TUI is not a web shell: it is a React/Ink application talking to Raven's Python runtime through a typed RPC protocol.
Raven connects the harness to EverOS for long-term user and agent memory. Sessions, procedures, and reusable patterns can be turned into local skill material instead of disappearing into old transcripts.
The context stack has a legacy path and a Curator path. Under pressure, the harness can archive, retrieve, and assemble context with explicit budgets instead of blindly clipping the oldest messages.
Sentinel watches events, schedules checks, evaluates whether a nudge is useful, and routes proactive actions through guardrails. The point is not noisy notifications; the point is an agent harness that can notice.
SkillForge treats skills as procedural memory. It can detect reusable workflows, write skill files, track execution feedback, and evolve instructions when they stop working.
Raven is an Apache-2.0 licensed, self-improving agent harness built by EverMind. It provides the runtime, memory layer, tools, and Agent Templates for building custom agents and digital workers.
Use an Agent Template when you want Raven's harness layer but your own scenario, personality, workflow policy, skills, integrations, or distribution model. A template can start as one person's agent and later become a repeatable digital worker for a team or community.
Agents, templates, skills, workflows, and modules created with Raven belong to their creators. Builders may use, modify, commercialize, and share agents built with Raven or based on Raven Agent Templates under the Apache-2.0 license.
We encourage builders to say "Built with Raven" and link back to this repository. The Raven and EverMind names and logos may not be used to imply official endorsement unless explicitly approved by EverMind.
| Goal | Command |
|---|---|
| Start the native TUI | raven or raven tui |
| Check the TUI runtime | raven tui --check |
| Configure Raven | raven onboard |
| Run a one-shot shell task | raven agent -m "..." |
| Review providers | raven provider list |
| List messaging channels | raven channels list |
| Start the messaging gateway | raven gateway |
| Manage sessions | raven sessions list |
| Inspect scheduled jobs | raven cron list |
| Browse skills | raven skill list |
| Inspect proactive state | raven sentinel status |
| Show plugins and memory backend | raven plugins |
| Debug sandbox VMs | raven sandbox list |
| Show local status | raven status |
| Diagnose setup | raven doctor |
| Goal | Start here |
|---|---|
| First-time install and setup | Quick Install |
| Source-based development | Developer Workflow and docs/dev.md |
| Memory and plugin architecture | docs/memory-plugin-architecture.md |
| Sandbox usage and debugging | docs/sandbox/usage.md |
| Proactivity design | docs/Proactivity-Plan.md |
| Detailed design notes | docs/README.md |
Every turn flows through the Spine: one entry (submit), one exit (emit),
and per-conversation lanes for ordering and cancellation. Feature engines plug
into the agent loop through explicit handoffs instead of importing each other.
Channels / TUI / Gateway
|
v
Raven Spine
submit -> lanes -> emit
|
v
Agent Loop
tools · skills · providers
|
+--> Context Engine legacy / curator
+--> Memory Engine EverOS / local skills / SkillForge
+--> Proactive Engine Sentinel / scheduler / nudge policy
+--> TokenWise usage tracking / cache placement / routing
+--> Eval Engine task judgement and coordination
raven/
├── spine/ # Per-turn backbone: submit -> lanes -> emit
├── agent/ # Agent loop, tools, hooks, subagents, context builder
├── channels/ # Telegram, Discord, Slack, Matrix, WhatsApp, WeCom, ...
├── tui_rpc/ # Python side of the native TUI protocol
├── providers/ # LLM provider adapters
├── context_engine/ # Context assembly and Curator path
├── proactive_engine/ # Sentinel, scheduler, nudges, feedback
├── memory_engine/ # EverOS memory, local skills, SkillForge
├── token_wise/ # Usage tracking, cache placement, routing
├── sandbox/ # Isolated command execution
├── security/ # Trust boundaries and network checks
├── cli/ # `raven` command line entry point
└── config/ # Config schema and update helpers
ui-tui/ # React/Ink native terminal UI
bridge/ # WhatsApp TypeScript bridge
Source setup, focused checks, and PR rules live in
CONTRIBUTING.md and docs/dev.md.
AI-collaboration rules live in AGENTS.md; CLAUDE.md is kept as a
compatibility entry point.
Raven is pre-alpha and moving quickly. APIs can change without notice, but the core product surfaces are already in the repository.
| Layer | Status |
|---|---|
| Native TUI + CLI | Functional |
| Spine runtime | Functional |
| Base agent loop, tools, providers | Functional |
| Context engine | Implemented, still evolving |
| Sentinel proactivity | Implemented, still evolving |
| TokenWise strategies | Implemented |
| SkillForge | Implemented |
| Eval engine | Partial |
If Raven is the kind of agent harness you want to exist, star the repo. It helps more builders of self-improving agents discover the project and gives the EverMind ecosystem a stronger signal to keep investing in open agents.
EverMind is an open-source ecosystem for long-term memory, self-evolving agents, AI-native interfaces, and memory evaluation.
| EverMind Open-Source Ecosystem | |
|---|---|
| Self-Improving Agent Harness | Raven - the terminal-native agent harness for tools, skills, memory, proactivity, context control, and reusable Agent Templates. |
| Memory Runtime | EverOS - the memory substrate Raven uses for durable user memory, agent memory, case extraction, skill extraction, and multimodal parsing. |
| Algorithm Engine | EverAlgo - stateless extraction, ranking, parsing, and memory operators that power EverOS. |
| Hypergraph Memory | HyperMem - hypergraph memory for long-term conversations, with benchmark-backed topic -> episode -> fact retrieval. |
| Benchmarks | EverMemBench · EvoAgentBench - evaluation suites for conversational memory and agent self-evolution. |
| Long-Context Research | MSA - Memory Sparse Attention for scalable latent memory and 100M-token contexts. |
| Personal Memory Layer | EverMe - CLI and agent plugin suite for cross-device, cross-agent personal memory. |
| Developer Integrations | evermem-claude-code · everos-plugins - plugins, skills, and migration tooling for AI coding agents. |
Together, these repositories form EverMind's research-to-runtime stack: memory methods, reusable algorithms, benchmark evidence, native agent products, and practical developer integrations.
Raven is early, and useful contributions are welcome across runtime architecture, TUI polish, provider support, memory workflows, proactivity, benchmarks, documentation, and issue reports.
Before opening a PR:
- Read AGENTS.md.
- Keep the change scoped.
- Add or update tests for behavior changes.
- Run the relevant
maketargets. - Use a Conventional Commit title.
Raven is licensed under the Apache License 2.0. Portions of the runtime and TUI layer originated from MIT-licensed upstream projects; their copyright notices and license texts are retained in NOTICES.md and LICENSES.