I’ve discovered ‘searchable anchors’ in prompts, coding agents cheat code

context window fills up. compaction hits. agent forgets what it did. forgets what other agents did. starts wrecking stuff.

agent 1 works great. agent 10 is lost. agent 20 is hallucinating paths that don't exist.

found a fix so simple it feels like cheating.

the setup:

1. create a /docs/ folder in ur project
2. create /docs/ANCHOR_MANIFEST.md — lightweight index of all anchors
3. add these rules to ur AGENTS.md or claude memory:

​

ANCHOR PROTOCOL:

before starting any task:
1. read /docs/ANCHOR_MANIFEST.md
2. grep /docs/ for anchors related to ur task
3. read the files that match

after completing any task:
1. create or update a .md file in /docs/ with what u did
2. include a searchable anchor at the top of each section
3. update ANCHOR_MANIFEST.md with new anchors

anchor format:
<!-- anchor: feature-area-specific-thing -->

anchor rules:
- lowercase, hyphenated, no spaces
- max 5 words
- descriptive enough to search blindly
- one anchor per logical unit
- unique across entire project

doc file rules:
- include all file paths touched
- include function/class names that matter
- include key implementation decisions
- not verbose, not minimal — informative
- someone reading this should know WHAT exists, WHERE it lives, and HOW it connects

that's the whole system.

what a good doc file looks like:

<!-- anchor: auth-jwt-implementation -->
## JWT Authentication

**files:**
- /src/auth/jwt.js — token generation and verification
- /src/auth/refresh.js — refresh token logic
- /src/middleware/authGuard.js — route protection middleware

**implementation:**
- using jsonwebtoken library
- access token: 15min expiry, signed with ACCESS_SECRET
- refresh token: 7d expiry, stored in httpOnly cookie
- authGuard middleware extracts token from Authorization header, verifies, attaches user to req.user

**connections:**
- refresh.js calls jwt.js → generateAccessToken()
- authGuard.js calls jwt.js → verifyToken()
- /src/routes/protected/* all use authGuard middleware

**decisions:**
- chose cookie storage for refresh tokens over localStorage (XSS protection)
- no token blacklist — short expiry + refresh rotation instead

what a bad doc file looks like:

too vague:

## Auth
added auth stuff. jwt tokens work now.

too verbose:

## Auth
so basically I started by researching jwt libraries and jsonwebtoken seemed like the best option because it has a lot of downloads and good documentation. then I created a file called jwt.js where I wrote a function that takes a user object and returns a signed token using the sign method from the library...
[400 more lines]

the rule: someone reading ur doc should know what exists, where it lives, how it connects — in under 30 seconds.

what happens now:

agent 1 works on auth → creates /docs/auth-setup.md with paths, functions, decisions → updates manifest

agent 15 needs to touch auth → reads manifest → greps → finds the doc → sees exact files, exact functions, exact connections → knows what to extend without reading entire codebase

agent 47 adds oauth flow → greps → sees jwt doc → knows refresh.js exists, knows authGuard pattern → adds oauth.js following same pattern → updates doc with new section → updates manifest

agent 200? same workflow. full history. zero context loss.

why this works:

1. manifest is the map — lightweight index, always current
2. docs are informative not bloated — paths, functions, connections, decisions
3. grep is the memory — no vector db, just search
4. compaction doesn't kill context — agent searches fresh every time
5. agent 1 = agent 500 — same access to full history
6. agents build on each other — each one extends the docs, next one benefits

what u get:

• no more re-prompting after compaction
• no more agents contradicting each other
• no more "what did the last agent do?"
• no more hallucinated file paths
• 60 files or 600 files — same workflow

it's like giving every agent a shared brain. except the brain is just markdown + grep + discipline.

built 20+ agents around this pattern. open sourced the whole system if u want to steal it.