Ask a coding agent to add a form alter to a Drupal module and you will often get a procedural function in the .module file, with the module name as a prefix. Ask it for a block plugin and the class arrives with an annotation in the docblock. These are conventions that modern Drupal has replaced with PHP attributes: in many cases the generated code still works, but it must be rewritten before review. Anyone working with an agentic-first approach to Drupal development is familiar with this recurring fix, because it reappears with every task and consumes part of the time that the agent was supposed to free up.
Luca Lusso1, Lead Developer at SparkFabrik, addressed this problem at DrupalCamp Italy 2026, an event co-organized by SparkFabrik, presenting DRI (Drupal RAG Intelligence). Luca described the talk as an experiment mixing Drupal, AI, and PHP in general. DRI is a tool designed to guide coding agents in generating modern Drupal code; it is an internal tool, used by the team on its own projects and not publicly available.
The flaw that DRI corrects originates in model training. The way an LLM learned Drupal, by reading public code accumulated over time, determines which conventions it proposes when no one shows it an alternative.
Why a coding agent writes outdated Drupal
Coding agents write outdated Drupal because that is how they learned it. According to Luca, models were trained on a massive amount of poorly written PHP and reproduce Drupal conventions that core has long since superseded. The reason lies in the composition of the models’ training data: contrib modules, forum answers, tutorials, and snippets mostly describe the previous way of doing things, while code using current APIs represents only a recent, minority portion of the corpus.
Two examples recur more than others in the talk. The first is procedural hooks in the .module file, instead of class methods marked with the Hook attribute; the second is annotations in plugin docblocks, instead of PHP attributes. Starting with Drupal 10.2, core uses PHP attributes for plugin discovery, and starting with Drupal 11.1, hooks can be implemented as class methods, with the Hook attribute declaring which hook the method implements2. The same shift applies to services, which older code retrieves through static calls to the container rather than receiving them via dependency injection.

The result is a model that mixes eras. It can produce a plugin with the correct attribute and, in the same module, a procedural-style hook, because to the model both represent valid Drupal. Core maintains backward compatibility with older conventions, so the code often runs without errors, but it introduces technical debt into a project that has adopted current standards and forces reviewers to rewrite it.
The most immediate response would be a longer prompt, with instructions such as “use attributes, not annotations.” However, a generic instruction competes with the frequency of patterns learned during training, takes up context window space, and describes the expected result without showing how to write it. Every new convention requires an additional rule, and a list of prohibitions grows faster than a team can keep it up to date.

DRI takes a different path. Instead of longer prompts, it provides the agent with examples drawn from the team’s project code. When it needs to write a hook, the agent retrieves hooks already written and reviewed within the projects, using the conventions the team has adopted. Hence the meaning of “memory” in the title: the agent’s RAG memory is the index of the team’s code, and the agent learns current conventions by reading real code rather than abstract rules.

At Talks On My Machine Drupal 2026, the event we organize, one talk focused on using a coding agent in Drupal beyond vibe coding. DRI addresses a specific aspect of that same topic: which code the agent takes as an example when writing Drupal.
How DRI builds code memory
If examples are the solution, the quality of the output depends on what goes into the index and how it is broken down. DRI indexes the internal codebase by combining three techniques: semantic RAG, Abstract Syntax Tree analysis, and structural metadata with Git references. Each solves a different problem in code retrieval.
Retrieval-augmented generation (RAG) is the mechanism by which the model, before generating output, receives context fragments retrieved from an index. The source material is split into chunks, each chunk is transformed into an embedding (a numerical vector representing its meaning), and semantic search returns the chunks closest to the request. The Abstract Syntax Tree (AST), on the other hand, represents code structure as parsed by a compiler. Classes, methods, functions, and attributes become nodes with explicit relationships, rather than plain lines of text.

DRI works along two pipelines. Indexing reads codebases, chunks them, and populates the index; querying answers the agent’s requests by retrieving relevant snippets.

The first challenge is deciding where to cut. A fixed-window text splitter breaks a file into blocks of predetermined length, which might cut a method in half or merge the tail of a class with the beginning of a Twig template. DRI uses the AST for semantic chunking. Code is divided by semantic units (classes, methods, hooks, and templates), ensuring that each chunk corresponds to a unit that a developer would naturally recognize as such.

The second challenge is lost context. A method extracted from its class no longer indicates which namespace it belongs to or which classes it imports. Without this information, the agent cannot tell whether that method uses a core service or an identically named class from another module. For this reason, DRI copies namespaces and use statements into every chunk: each fragment remains readable and usable even in isolation, and the resulting embedding represents the method alongside its dependencies.

The AST also serves to identify Drupal patterns. For example, DRI distinguishes an old-style hook declared as a function in the .module file from a hook declared as a method with the Hook attribute, recording this difference in the chunk metadata. This connects indexing directly to the original issue, because the index knows which convention each fragment follows, providing retrieval with information that similarity alone cannot supply.
Structural metadata comes from Git and GitLab, including commit messages. Code shows what a method does, while the commit that introduced it often explains why: that a certain implementation replaces a deprecated hook, or that it fixes behavior in an edge case. Associating these references with each chunk adds provenance and intent, two pieces of information that source code alone does not convey.

The DRI index lives on Firestore, used as a vector database. The indexed codebase is audited using PHPStan, PHPCS, and Rector, covering static analysis, coding standards compliance, and modernization rules. Without these checks, the index would reproduce the same flaws present in the training data, and the agent would receive them as team-approved examples.
CLI, skills, and what the blind test revealed
The index is queried through a natural language CLI. Users describe what they are looking for, such as an implementation of a form alter hook or a field plugin with validation, and receive the most relevant chunks with their metadata. A key point from the talk applies to any tool provided to an agent: the CLI alone is not enough. It requires a skill, meaning a set of instructions explaining to the agent how to use the CLI, when to consult the index, and how to apply the results.
An agent with access to a CLI command without understanding its purpose tends to ignore it and write code from its parametric memory, relying on the very training data that DRI attempts to correct. Alternatively, it queries it with overly generic requests that return fragments of little use for the task. The skill turns access into a repeatable practice, ensuring that before writing Drupal code, the agent checks how the team has already written it. (At DrupalCamp Italy 2026 and DrupalCon Rotterdam 2026, we also presented another application of skills in a Drupal project, covering atomic skills and AI agents applied to a migration.)
This principle aligns with our perspective on AI native software engineering: agents work better when tool usage rules are written explicitly rather than left to the model’s discretion. In DRI’s case, that rule concerns a single tool, but it determines its usefulness and effectiveness.
To evaluate the impact, Luca presented a blind comparative test with 4 developers and 8 tasks, comparing solutions produced with DRI against those produced without it. For each task, developers indicated which solution they preferred, resulting in the following distribution of votes:
| With DRI | Without DRI | Tie |
|---|---|---|
| 21 | 9 | 2 |
The sample is small, so the result does not prove that code produced with DRI is universally better. However, the preference is clear: solutions using DRI received more than double the votes of those produced without it.
The talk also detailed the trade-offs of this approach. With DRI, each task incurred higher costs, and solutions required roughly twice the tokens and twice the execution time. Every retrieval from the index adds steps to the agent’s workflow: querying the CLI, reading returned chunks, and comparing them with the code to be written. Every fragment enters the context window and costs tokens, and every lookup extends runtime.
For a team, the balance is measured against total time. The additional token cost must be weighed against the time a developer would spend during review rewriting a procedural hook or an annotated plugin, a factor not measured in the test. The evaluation therefore remains on a case-by-case basis, tied to the volume of Drupal code the agent produces and the current burden of manual corrections.
Limits of vector search and lessons on chunking and context
The talk concluded with a critical analysis of the current limits of vector search and the lessons learned while developing DRI regarding semantic chunking and context management. These limitations apply to any RAG system built on source code.
The first concerns the gap between proximity and correctness. Embedding similarity measures how closely two fragments address the same topic, saying nothing about which one follows current conventions: a procedural hook altering a form and the same hook declared with the Hook attribute occupy very close positions in vector space, because they perform the same function using nearly identical names and logic.
The second involves exact identifiers. Class names, service IDs, function names, and hook names are precise strings that vector search treats as approximate meaning, whereas lexical or hybrid search finds them more reliably.
A widespread response, also highlighted in the talk, is two-stage retrieval. An initial KNN stage retrieves candidates closest to the query embedding, followed by a reranker that reorders them by evaluating the query and candidate together. While result ordering improves, the second stage can only work on candidates identified by the first.

DRI’s approach to code chunking serves a clear purpose. When a chunk corresponds to a single semantic unit, such as an individual method, its embedding represents one discrete concept, making it easy for search to find for relevant queries. Conversely, a chunk cut at arbitrary line counts may contain the end of one method and the start of another. The vector blurs two distinct meanings and fails to sit close to either, preventing search from retrieving it effectively for either query.
AST analysis partially compensates for the limitations of pure similarity. Where an embedding sees two nearly identical hooks, structural metadata distinguishes the legacy style from the attribute-based one.
Regarding context management, the lessons align with three architectural choices already in place:
- Targeted examples instead of long prompts: a few relevant snippets demonstrate current conventions better than a list of rules, occupying context only when needed for the task.
- A skill for the tool: access to the index is valuable only if the agent knows when to query it and how to use the results.
- Cost as a direct consequence: doubling token usage and execution time stems directly from the additional context brought in by each retrieval.
For anyone designing a similar system, this is the core operational trade-off, as every retrieved fragment occupies context window space and carries a cost. Retrieving fewer but more relevant chunks that are self-contained and tagged with their respective conventions reduces wasted context while preserving the impact of concrete examples.
Code-focused RAG has different requirements than RAG applied to website content. SparkFabrik contributed to integrating Search API Typesense as a vector database for Drupal, enabling RAG and semantic search over indexed Drupal content.3 The Drupal AI module supports several vector databases to extend LLM knowledge to proprietary data, a topic which we cover in our overview of the Drupal AI ecosystem. In that scenario, chunks are editorial text; with DRI, they are code units, complete with namespaces, dependencies, and conventions that a parser can read and that an embedding alone captures only partially.
What it takes to give an agent code memory
The principle behind DRI applies to any stack where models know legacy conventions better than those adopted by the team, a common scenario across the PHP ecosystem. The results and limitations highlighted in the talk provide practical guidelines for teams looking to implement this approach:
- Index only audited code: pass the codebase through PHPStan, PHPCS, and Rector before it enters the index, because every chunk becomes an example for the agent.
- Split by semantic units: classes, methods, hooks, and templates, repeating namespace and use statements in every chunk.
- Teach tool usage: pair the CLI with a skill that instructs the agent on when and how to query the index.
- Budget for more tokens and time: per-task costs increase and must be weighed against time saved in code review.
- Do not rely on similarity alone: use structural analysis to distinguish current code from deprecated implementations.
Within our team, DRI remains an internal tool, used across projects to evaluate where code memory justifies its cost. Luca’s complete presentation, featuring detailed architectural breakdowns and discussion on vector search limitations, is available in the video of the talk at DrupalCamp Italy 2026.
If you want to apply the same principle to your Drupal projects, with agents working from examples of your own code, explicitly documented tool usage rules, and static checks across your codebase, the AI Native Journey is our framework for guiding teams through AI adoption in development workflows. It is supported by our Drupal team, working directly on project codebases and conventions.
Frequently asked questions
What is DRI?
DRI (Drupal RAG Intelligence) is an internal tool developed by SparkFabrik. It indexes our team’s project code and makes it searchable for a coding agent. Its purpose is to guide the agent toward modern Drupal practices by referencing examples from our own code rather than the outdated conventions the model encountered during training.
Why do coding agents write outdated Drupal code?
Models are trained on large volumes of legacy PHP and outdated Drupal conventions. This leads to code that ignores modern practices, such as writing hooks in the .module file or using annotations instead of attributes. Without updated examples, the agent tends to reproduce the patterns it has seen most frequently.
What did the blind test show?
Four developers evaluated solutions for 8 tasks in a blind test, comparing outputs produced with and without DRI. The result: 21 votes for solutions with DRI, 9 for those without, and 2 ties. While the sample is too small to be statistically significant, the preference for DRI solutions is clear.
How much does it cost to use DRI?
Tasks performed with DRI cost more than those run without it, because the agent makes additional calls to the index and each response adds context to process. This added overhead must be factored in: in return, it delivers code closer to modern Drupal standards, which developers clearly preferred in the blind test.
Is DRI available?
No. DRI is an internal SparkFabrik tool and is not publicly available. However, its core principle can be applied to other Drupal projects: provide the agent with examples from your own code, define explicit rules for using tools, and enforce static checks across the codebase.
Notes and sources
Luca Lusso, profile on Drupal.org: https://www.drupal.org/u/lussoluca ↩︎
“Introduced in version: 11.1.0” (source: www.drupal.org/node/3442349) ↩︎
Search API Typesense, project page on Drupal.org: https://www.drupal.org/project/search_api_typesense ↩︎
Video source
This article is based on the video “Incorporare un decennio di esperienza Drupal nella memoria di un coding agent | Luca Lusso”.














