TL;DR đŚââŹ
Stellar Raven was rebuilt five times in under four weeks.
The first four versions used an internal AI agent, but it couldnât reliably recognize when its answers were incomplete or outdated. More reasoning only made it slower and more expensive.
Version five removed Ravenâs internal agent and turned it into a context engine that helps Claude, Codex, Cursor, and other agents retrieve and cross-reference current Stellar information.
Nearly 500 golden Q&As test whether Raven surfaces the right evidence and reveal gaps in the underlying sources.
The central lesson: better AI starts with better context and evaluation, not necessarily more AI.
This is the story of how Tyler van der Hoeven built Stellar Raven five times in under four weeks, and what the rebuilds can teach us all about context, reliability, and why adding more AI isnât always the answer.
Before we get into it, letâs talk about ravens. I read a story once about a group on a winter snowshoe trip who stopped to eat lunch. One man who had been robbed by a raven on his last trip up the mountain declared ânever again,â and pushed the remaining half of his sandwich deep into his backpack. A nearby raven simply waited. The moment the group was distracted, it darted in, plunged into the backpack, and flew off with the sandwich. It had identified the target, remembered where it was stored, and retrieved exactly what it wanted.
Stellar Raven was built to do something similar with information: identify relevant data, know where to find it, and retrieve it. As it turns out, finding the current truth across a fast-moving ecosystem is much harder than stealing half a sandwich.
The first four iterations of Raven were AI agents that answered questions about Stellar, each one choosing sources, gathering evidence, and synthesizing an answer. However, none were able to reliably tell when that answer was outdated or incomplete. And adding more internal reasoning only made Raven slower, more expensive, and, in Tylerâs words, âa sad, self-deprecating, doubtful machine.â
By the fifth version of Raven, the question was no longer how to make the agent smarter, but whether the agent was necessary at all.
Where it all began
The problem Raven would eventually tackle appeared well before Raven itself.
Building on Stellar traditionally required an intense manual research process: talking to subject-matter experts, reading documentation, inspecting repositories and examples, learning the underlying concepts, and eventually turning that knowledge into an SDK, game, prototype, or other project.
That process became especially difficult when the subject was complex, and the available information was fragmented. Passkeys were one example. Building passkey and smart-wallet tooling on Stellar required understanding WebAuthn, authentication flows, smart wallets, and how those concepts fit together. That research eventually led to Tylerâs Passkey Kit, which was later handed over to OpenZeppelin for continued development, but getting there required an enormous amount of manual discovery.
As AI became more capable, autonomous research tools such as Perplexity and Parallel offered another approach: rather than finding and reading every source manually, an agent could investigate the landscape, find important information, and organize what it found. But when questions turned Stellar-specific, these research tools sometimes referenced older implementations or missed newer ecosystem projects.
That limitation became the idea at the heart of Raven: before an AI agent can build something useful, it needs access to the right information. The quality of the build begins with the quality of the context.
The internet never forgets
Stellar has more than a decade of documentation, tutorials, repositories, blog posts, forum discussions, and working examples explaining how to build on the network. The network has also evolved significantly, especially with the introduction and continued development of smart contracts.
The recommended way to build something today may look very different from the recommended approach two years ago. Unfortunately, old tutorials do not remove themselves from search results when a better method becomes available. In addition, older guidance has usually accumulated more links, examples, and search authority, allowing it to overshadow a newer approach even when the newer one is officially preferred.
Contract constructors are a good example. Before Stellar introduced constructor support, initializing a contract required a factory contract, a referenced Wasm file, and a separate initialization function. At the time, this was a valid, widely taught pattern. Constructors collapsed all of that into deployment. But an AI model searching the internet will still find far more examples of the old approach, cite credible sources, and generate functioning code for an architecture the ecosystem has moved beyond. The answer wouldnât be false. It would be worse: technically valid, convincingly supported, and no longer relevant.
Raven therefore needed to do more than find information. It needed to help agents distinguish current recommendations from historical ones, surface potentially conflicting guidance, and identify the sources most relevant to what a developer was actually trying to build.
Four troublesome Ravens
Identifying the context problem was the first part of the journey; the next was figuring out what Raven should look like as a product.
Ideally, building on Stellar shouldnât require developers to install dozens of tools, learn a collection of new interfaces, or abandon the AI coding environment they already use. Raven needed to be lightweight, easy to install, and compatible with tools such as Claude, Codex, and Cursor. One MCP connection that gave users access to the ecosystemâs most useful sources.
Two ecosystem projects helped make this possible: LumenLoop and Stellar Light. LumenLoop collects current Stellar news, events, research, and ecosystem activity. Stellar Light catalogs projects, builders, repositories, Stellar Community Fund (SCF) information, and signals about project quality and relevance. Raven combines these with the Stellar developer documentation, Stellar Skills, and OpenZeppelin playbooks. Together, these resources give Raven roughly 80 internal operations. It can inspect repositories, explore SCF projects, retrieve specific documentation, find regional information, surface news and events, and more.
The first four iterations of Raven placed an AI agent between a userâs question and the answer. The agent received the userâs query, descriptions of Ravenâs capabilities, and instructions for using its tools, then assembled what it believed was a complete answer. Most often, Raven returned true information; it just wasnât the whole truth.
For example, you could ask which swapping protocols existed on Stellar, and Raven might answer confidently: the SDEX! That is a valid option, but presenting it as the only answer omitted other protocols, newer choices, and the context needed to select the right tool for a particular use case. Where the constructor problem was stale information presented as current guidance, this was different: partial information mistaken for complete information.
A knowledgeable human could spot the gap, but Raven had no reliable way to recognize the evidence it had failed to find, and additional self-review only made it more hesitant. It questioned its evidence, searched more sources, and reconsidered whether it knew enough. It could take around ten minutes to assemble an answer, and each added reasoning step increased cost without necessarily improving quality. By the end of version four, it was obvious that more reasoning did not improve answer quality and something more fundamental needed to change.
Version five: say bye to the AI!
This thought opened the door for a new consideration. Why pay for an internal AI agent when developers already had Claude, Codex, Cursor, or another capable agent? A userâs agent understood the project, wrote its code, and decided when it had enough information to proceed. A second model inside Raven only duplicated that reasoning while adding cost, latency, and more opportunities for failure.
So, it was removed, and Raven stopped trying to answer Stellar questions. Instead, Ravenâs job was to give developersâ existing agents access to Stellar context and a safe way to retrieve and combine it. All final reasoning stayed with the calling agent.
This also changed how agents used Ravenâs operations. Calling them individually required repeated tool selections and conversational round trips. Cloudflare Code Mode offered a more efficient pattern â let the agent write code instead â so Raven exposes just two primary capabilities: search and execute.
search acts as Ravenâs catalog. The agent describes what it needs, and Raven deterministically ranks the available operations, returning a small set of relevant options with typed instructions for using them. This avoids dumping Ravenâs entire API into the modelâs context at once.
execute lets the agent write retrieval code that calls those operations: searching several sources in parallel, filtering results, and cross-referencing evidence. The code can even discover and call another operation while it runs, avoiding additional round trips.
Because execute runs model-generated code, each request operates inside a fresh, networkless sandbox. External calls pass through Ravenâs host-side adapters, which hold the credentials, so agent-written code never sees a URL, header, or key. This gives the agent flexibility to orchestrate research without unrestricted access to Ravenâs underlying services.
The result is faster, richer research that can adapt as new information emerges. Most importantly, Raven no longer has to decide whether an answer is complete. It surfaces the evidence and lets the agent that already understands the user, conversation, and project make that determination.
Golden Q&As: Ravenâs answer key
Removing the internal agent solved one problem but raised another: how could the team verify that Raven was giving the calling agent the right context?
The answer was an evaluation system built on nearly 500 Stellar-related questions covering a wide variety of subjects across the ecosystem. Each question was categorized, scored, and paired with a deeply researched âgoldenâ answer.
These golden answers were not text for Raven to reproduce word for word. Instead, each identified the facts a strong answer should include, outdated recommendations it should avoid, sources that increased confidence, and conclusions that signaled an incomplete response.
Some answers took around an hour to research properly, which was impractical for a live request, but they established a standard against which faster responses could be measured. The same questions were then run through Raven using different calling models. When an answer fell short, Ravenâs chosen sources and operations were inspected, and catalog rankings, descriptions, schemas, or search terms were improved before the question was tested again, creating a measurable tuning loop.
The evaluations also revealed when the problem was not Raven at all. Sometimes Raven surfaced exactly the right source, only for that source to be outdated, incomplete, or in conflict with other guidance. In those cases, the team files an issue with the source owner so the underlying information can be corrected.
That feedback loop is nearly as valuable as the context engine itself. A weak answer can expose a documentation gap or an outdated example, and fixing it improves the foundation not just for Raven, but for every developer, search engine, and AI agent relying on the same information.
Context before intelligence
Raven ultimately became two connected systems: a context engine that helps agents find current Stellar information, and an evaluation system that reveals where that information falls short.
That combination matters more as agents make more decisions and write more code. The information guiding those decisions must be trustworthy.
The lesson is not to add more reasoning whenever an AI system struggles. Sometimes the better approach is to simplify the system, strengthen the context around it, and evaluate the result against researched truth.
Learn how to download Raven on the website.
Ask questions or provide feedback in the #raven channel in the Stellar Developer Discord or open an issue in the GitHub repo.
Disclaimer
Frontier Lab is published by the Stellar Development Foundation. Posts are for educational purposes only and are not financial, legal, or investment advice. The SDF Privacy Policy applies to this publicationâs subscriber list and comments. Substackâs Privacy Policy covers Substackâs own use of your Substack account data. Comments are subject to the Stellar Code of Conduct, and we may remove comments that are off-topic, promotional, or misleading.