Semantic memory or just Markdown? | Laravel - The clean stack for Artisans and agents

Why Laravel Boost project rules use a generated Markdown index after we deleted semantic search.
Every team using an AI coding agent eventually sees it repeat a mistake the team already corrected.
The agent will extend the framework controller and miss the application's tenant scope. It reaches for a float type even though the project stores money as integer cents. It adds a repository layer on top of the ORM, despite the team having removed it two years ago.
All three failures come from the fact that the project has implicit conventions built up over the history of the codebase, but the agent has no durable way to remember them. It has no memory.
In this post, “memory” means the conventions a team commits, reviews, and shares through its repository.
Laravel Boost already writes Laravel guidelines into AGENTS.md or CLAUDE.md. Teams would add their own instructions and conventions to the same file. Six months later, every time you fire up an agent, you pay the context-tax for rules that rarely apply to the task at hand.
My first attempt to solve this was a semantic search tool. I deleted it five days later.
The version that finally worked was far simpler: markdown files and a generated two-column index.
At Laravel, both internally and for our users, we care about correct code per token spent and that the code looks like it belongs in this particular application.
Laravel-supplied guidelines cover the framework side, but project conventions need to cover choices such as base controllers, money storage, domain layers, and testing structure.
The instruction file was the obvious place to put those choices, but every addition then became part of every prompt:
database migration rules loaded during Livewire work
backend testing rules loaded while the agent edited a frontend component
The context grew unnecessarily with the team's knowledge.
Issue #606 is the clearest version of the complaint, and it was right: Boost put too much into CLAUDE.md.
Claude Code's documentation recommends keeping CLAUDE.md concise, with 200 lines as a general target. Longer files consume more context and reduce adherence. Anthropic's context-engineering guidance makes the same practical point: use the smallest set of high-signal tokens that improves the outcome.
IFScale offers supporting evidence with a caveat. It measures instruction following in business reports and provides only indirect evidence for coding agents. In its 500-instruction condition, the strongest frontier models followed 68% of the requested instructions. A large pile of good instructions still creates competition for attention.
Scoping the instructions more intelligently, which is a simple system, lets us preserve the project knowledge and control when it enters the prompt.
When we built project rules, Boost supported 13 agent integrations. I read through the instruction systems for all of them. They agree on almost nothing.
Some supported glob-scoped files. Some loaded nested instruction files after the agent entered a directory. Some offered only an always-loaded project file. The trigger behavior varied enough that the same rule would load differently from one harness to the next.
Maintaining 13 implementations would have become its own product. Boost already had a portable surface in each integration: the instruction file it writes during installation. That file could point every agent toward plain Markdown in the repository.
The rules therefore had to work through files, globs, and ordinary agent tools.
The first version I built was the clever “semantic memory” layer that exposed two MCP tools, memory-search and memory-write, backed by a 359-line MemoryRepository. The agent could record a convention and run semantic search later.
Five days after building it, I removed the search layer. It was overcomplicated and ineffective for the size of memory most teams are actually working with.
A mature Laravel application may accumulate a few dozen short convention files. A few dozen files don’t justify the coordination costs: embeddings, a vector index, and invalidation. The index could become stale and drift from the correct Markdown. It’s only a few dozen files!
Every coding agent knows how to list files and run grep.
Anthropic's Agent SDK guidance recommends starting with agentic search and adding semantic retrieval when scale or variation demands it. Boris Cherny described a similar experience building Claude Code: the team tried vector databases, ran into stale indexes and permission complexity, and found glob and grep more useful for code.
Our rule corpus fit comfortably inside the file system.
Building embeddings, an index, and an invalidation strategy for forty short Markdown files is just over-engineering. It adds a staleness failure mode to something ls or grep can just handle itself.
The next version stored Markdown under .ai/rules. Each file declared the paths it covered:
Boost told the agent to read relevant rules before planning or editing.
In exploratory testing, agents followed that instruction inconsistently, especially on smaller models. I kept rewriting the sentence. The models kept skipping the directory.
The first action required the agent to judge relevance before it had seen the available rules. The agent knew .ai/rules existed. Its contents stayed hidden until the agent chose to inspect them. I needed to put the choices in front of it. "Check whether any rules are relevant" asks the agent to decide what relevant means, about a directory it hasn't read, before it has done anything.
So I gave it something to look at, at a different resolution. A higher-level index.
Instead of expecting it to read all the rules to see what applied, I gave it a generated two-column table that gets rebuilt on every update to the rules. Small enough to be functionally free.
Boost now rebuilds .ai/rules/index.md after every rule write:
The index is short enough to include in the starting instructions. The detailed rules stay in their files until the ta