Laravel Boost: Markdown Index vs Semantic AI Memory | Mohamed Said [ ![Mohamed Said](https://cdn.msaied.com/01KT78WE565VEMM3PSNQAAB0MH.png) Mohamed Said Laravel Backend Engineer ](https://msaied.com) [ Home ](https://msaied.com) [ Projects ](https://msaied.com/projects) [ Articles ](https://msaied.com/articles) [ Certificates ](https://msaied.com/certificates) [ Contact ](https://msaied.com#contact-section) [ ](https://github.com/EG-Mohamed) [ Home ](https://msaied.com) [ Projects ](https://msaied.com/projects) [ Articles ](https://msaied.com/articles) [ Certificates ](https://msaied.com/certificates) [ Contact ](https://msaied.com#contact-section) [ home ](https://msaied.com) [ articles ](https://msaied.com/articles) Semantic Memory or Just Markdown? How Laravel Boost Manages AI Agent Project Rules On this page 1. [ The Problem: AI Agents That Forget Your Conventions ](#the-problem-ai-agents-that-forget-your-conventions) 2. [ Why Semantic Search Was Deleted After Five Days ](#why-semantic-search-was-deleted-after-five-days) 3. [ The Solution: A Generated Two-Column Index ](#the-solution-a-generated-two-column-index) 4. [ Path Lookup Plus Grep ](#path-lookup-plus-grep) 5. [ Writing and Reviewing Rules ](#writing-and-reviewing-rules) 6. [ Key Takeaways ](#key-takeaways) ![Semantic Memory or Just Markdown? How Laravel Boost Manages AI Agent Project Rules](https://cdn.msaied.com/627/b162933f96fd615f3165bfe167816018.png) [ Laravel ](https://msaied.com/articles?category=laravel) [ AI ](https://msaied.com/articles?category=ai) #Laravel Boost #AI Agents #Context Engineering #CLAUDE.md #Project Rules Semantic Memory or Just Markdown? How Laravel Boost Manages AI Agent Project Rules ==================================================================================== 3 Sep 2026 4 min read ![Mohamed Said](https://cdn.msaied.com/01KT78WE565VEMM3PSNQAAB0MJ.jpg) Mohamed Said Table of contents 1. [ 01 The Problem: AI Agents That Forget Your Conventions ](#the-problem-ai-agents-that-forget-your-conventions) 2. [ 02 Why Semantic Search Was Deleted After Five Days ](#why-semantic-search-was-deleted-after-five-days) 3. [ 03 The Solution: A Generated Two-Column Index ](#the-solution-a-generated-two-column-index) 4. [ 04 Path Lookup Plus Grep ](#path-lookup-plus-grep) 5. [ 05 Writing and Reviewing Rules ](#writing-and-reviewing-rules) 6. [ 06 Key Takeaways ](#key-takeaways) The Problem: AI Agents That Forget Your Conventions --------------------------------------------------- Every team using an AI coding agent eventually watches it repeat a mistake the team already fixed. The agent extends the wrong base controller, reaches for `float` when the project stores money as integer cents, or re-introduces a repository layer the team removed two years ago. The root cause is the same every time: the project has implicit conventions accumulated over its history, but the agent has no durable memory of them. [Laravel Boost](https://laravel.com/framework/docs/boost) already writes Laravel-specific guidelines into `AGENTS.md` or `CLAUDE.md`. Teams add their own conventions to the same file. Six months later, every prompt pays a context tax for rules that rarely apply to the task at hand — database migration rules loaded during Livewire work, backend testing rules loaded while editing a frontend component. [GitHub issue #606](https://github.com/laravel/boost/issues/606) captured the complaint clearly: Boost was putting too much into `CLAUDE.md`. Anthropic's own guidance recommends keeping that file under roughly 200 lines; longer files consume more context and reduce instruction adherence. Why Semantic Search Was Deleted After Five Days ----------------------------------------------- The first attempt to solve the problem was a semantic memory layer: two MCP tools (`memory-search` and `memory-write`) backed by a 359-line `MemoryRepository` with embeddings and a vector index. It was deleted five days later. A mature Laravel application accumulates a few dozen short convention files. A few dozen files do not justify the overhead of embeddings, a vector index, and an invalidation strategy. The index can drift from the Markdown source. Every coding agent already knows how to list files and run `grep`. Anthropics's Agent SDK guidance recommends starting with agentic search and adding semantic retrieval only 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. The Solution: A Generated Two-Column Index ------------------------------------------ The version that worked is simpler. Boost stores conventions as Markdown files under `.ai/rules/`. Each file declares the glob paths it covers. After every rule write, Boost regenerates `.ai/rules/index.md` — a short two-column table mapping glob patterns to rule file names. The lookup the agent performs has four steps: 1. Identify the file being edited. 2. Match its path against the first column of the index. 3. Read the rule file named in the second column. 4. Apply those rules while planning and editing. The index is small enough to include in the starting instructions. Detailed rules stay in their files until the task reaches a matching path. This progressive-disclosure shape keeps the starting context lean while ensuring relevant conventions load at the right moment. Path Lookup Plus Grep --------------------- Glob matching handles conventions tied to a specific part of the directory tree. Some conventions — like storing money as integer cents — apply across models, actions, requests, and tests. For those, Boost instructs the agent to run `grep -rin` over `.ai/rules`. The two routes together cover the cases seen in practice: - **Index lookup** for path-scoped conventions. - **Grep** for concepts that cross directory boundaries. Writing and Reviewing Rules --------------------------- Boost records conventions through an MCP tool named `record-rule`, which accepts a `glob`, `title`, and `note`. Internally, `RuleRepository::write()` derives an area from the glob, finds or creates the rule file, merges the glob into its frontmatter, appends the rule, and rebuilds `index.md` atomically. Because the output is plain Markdown, the team can read every convention and review changes in a pull request — no opaque database required. Key Takeaways ------------- - Bloated instruction files reduce AI agent adherence; keep `CLAUDE.md` concise. - Embeddings and vector indexes are overkill for a few dozen short convention files. - A generated two-column glob-to-file index gives agents a scannable map without loading every rule upfront. - Grep handles cross-cutting concepts that glob patterns cannot scope. - Plain Markdown keeps conventions human-readable and pull-request reviewable. - Staleness remains an open problem; pull-request review helps but does not fully solve drift. [Project rules are enabled by default in Laravel Boost](https://laravel.com/framework/docs/boost#project-rules). --- *Source: [Semantic memory or just Markdown? — Laravel Blog](https://laravel.com/blog/semantic-memory-or-just-markdown)* Found this useful? [ ](https://twitter.com/intent/tweet?url=https%3A%2F%2Fmsaied.com%2Farticles%2Fsemantic-memory-or-just-markdown-how-laravel-boost-manages-ai-agent-project-rules&text=Semantic+Memory+or+Just+Markdown%3F+How+Laravel+Boost+Manages+AI+Agent+Project+Rules) [ ](https://www.linkedin.com/sharing/share-offsite/?url=https%3A%2F%2Fmsaied.com%2Farticles%2Fsemantic-memory-or-just-markdown-how-laravel-boost-manages-ai-agent-project-rules) Frequently Asked Questions ---------------------------- 3 questions Q01 Why did Laravel Boost remove the semantic search layer for AI agent memory? A typical Laravel project accumulates only a few dozen short convention files. Building embeddings, a vector index, and an invalidation strategy for that volume adds unnecessary complexity and introduces a staleness failure mode. Standard file listing and grep handle the same retrieval task reliably without the overhead. Q02 How does the generated index in Laravel Boost work? After every rule write, Boost rebuilds `.ai/rules/index.md` as a two-column table mapping glob patterns to rule file names. The agent matches the path of the file it plans to edit against the first column, then reads the corresponding rule file. This keeps the starting context small while loading detailed conventions only when they are relevant. Q03 How should teams handle project conventions that apply across multiple directories? Boost instructs the agent to run `grep -rin` over `.ai/rules` for concepts that are not tied to a specific path — for example, a rule about storing money as integer cents that applies in models, actions, requests, and tests. Grep complements the glob-based index for these cross-cutting conventions. Continue reading More Articles --------------- [ View all ](https://msaied.com/articles) [ ![Laravel New in 13: Features, Helpers, and Upgrade Notes](https://cdn.msaied.com/625/629cfac34ade7206a215809c0438c5ae.png) laravel php upgrade ### Laravel New in 13: Features, Helpers, and Upgrade Notes Laravel 13 ships with async-first primitives, tightened type contracts, and quality-of-life helpers that rewar... ![Mohamed Said](https://cdn.msaied.com/01KT78WE565VEMM3PSNQAAB0MJ.jpg) Mohamed Said 3 Sep 2026 3 min read Read ](https://msaied.com/articles/laravel-new-in-13-features-helpers-and-upgrade-notes) [ ![Group Adjacent Collection Items in Laravel with chunkBy()](https://cdn.msaied.com/626/8cc4b384a3f740d25d1f8ff8520d36a0.png) Laravel Collections LazyCollection ### Group Adjacent Collection Items in Laravel with chunkBy() Laravel 13.30 adds chunkBy(), a clean shorthand for chunkWhile() that groups consecutive collection items shar... ![Mohamed Said](https://cdn.msaied.com/01KT78WE565VEMM3PSNQAAB0MJ.jpg) Mohamed Said 3 Sep 2026 3 min read Read ](https://msaied.com/articles/group-adjacent-collection-items-in-laravel-with-chunkby) [ ![Statamic Sidecar: Edit Markdown Sites from the Control Panel Without Migration](https://cdn.msaied.com/624/6df15b406d700ea26fb98c6ad4779195.png) Statamic Markdown CMS ### Statamic Sidecar: Edit Markdown Sites from the Control Panel Without Migration Statamic's new Sidecar product lets you manage any static site generator's Markdown files through the Statamic... ![Mohamed Said](https://cdn.msaied.com/01KT78WE565VEMM3PSNQAAB0MJ.jpg) Mohamed Said 2 Sep 2026 3 min read Read ](https://msaied.com/articles/statamic-sidecar-edit-markdown-sites-from-the-control-panel-without-migration) [ ![Mohamed Said](https://cdn.msaied.com/01KT78WE565VEMM3PSNQAAB0MH.png) Mohamed Said Laravel Backend Engineer ](https://msaied.com)Senior Backend Engineer specializing in Laravel, scalable SaaS platforms, APIs, and cloud infrastructure. I build secure, high-performance web applications that help businesses grow. Explore - [Home](https://msaied.com) - [Projects](https://msaied.com/projects) - [Articles](https://msaied.com/articles) - [Certificates](https://msaied.com/certificates) - [Contact](https://msaied.com#contact-section) Connect - [ hello@msaied.com ](mailto:hello@msaied.com) - [ +20 109 461 9204 ](tel:+201094619204) © 2026 Mohamed Said. All rights reserved. [ ](https://github.com/EG-Mohamed) [ ](https://www.linkedin.com/in/msaiedm/) [ ](https://wa.me/201094619204) [ ](mailto:hello@msaied.com) [ ](https://drive.google.com/file/u/0/d/1MF20IPRJyzfy32mhEutjL5EpSls0w2Q8/view)