Indexar o código fora do repo: como economizar tokens sem jogar o projeto no contexto

Indexing code outside the repository: saving tokens without ruining the project

The agent struggled to find a symbol. One minute's work. They opened file after file, pasted test dumps into the prompt, and the window faded. Sometimes the bill also appeared. It wasn't a dumb model. The question changed. Instead of "which tool makes the agent understand the repo?", it became "what is domain memory, and what is the cost of reading code in this session?".

There's a second reason, and it's not just economy. A symbol index is a map of your system: who calls what, where the critical flow is. If that map lives in Git, CI cache, or a service the agent also writes, the blast radius isn't just tokens. It's surface area.

Two accounts, one prompt. Domain memory is political. What can be remembered, through which port, what is canonical. Notes, contracts, "where we decide X". Indexing code doesn't solve this. Cheap code-read is session cost. Finding a caller and symbol without dumping the working tree into the prompt. This shouldn't become your knowledge base.

I mixed them. The indexer became a knowledge base. The vault became a grep without a port. Both failed, and the session inflated like a balloon. Saving tokens here isn't swapping week-long models. It's separating a layer. And deciding where the map lives. What I changed on the table The symbol map left the working tree. Local cache, outside the repo, outside Git.

Reindex is a machine operation, not a PR. The agent consults the index; it doesn't need to re-read the monorepo to find "who calls this function?". Four questions I ask before indexing a repo (copy and paste into the setup README):

1. Does the index live in my machine or leave it (cloud, CI, shared cache)?

2. Does it enter the agent's context that also has a writing tool?

3. How do I delete and revoke?

4. Who else reads this? Index ≠ versioned source. Least privilege on what enters context still applies. After that, I stopped feeding the firehose of raw CLI commands. Test, build, git status turned into a soap opera. That noise in the context is fire, friend. Compress with a CLI wrapper or do a surgical read. Loud output: compress with a CLI wrapper, or do a surgical read.

Incident needing exact log line: then firehose. Lastly: one code-read per session. Stacking two indexers dilutes ROI and confuses the agent. Choose one. If it doesn't serve, switch. Don't skip. The index also ages. When it does, reindex. Otherwise, you've only changed the type of hallucination. What this still isn't It doesn't replace the memory contract.

Hubs, scopes, "don't answer with just grep" are other conversations. And honesty: I don't have "saved X% of tokens". Without measurement, without percentages. I have a less inflated session and a map that won't crash in PRs by accident. Artifact Token layers (coding agent)

1. Domain memory has its own owner. Indexer isn't a knowledge base.

2. Symbol index: outside the repo, outside Git.

3. Before indexing: where does it live, who reads it, who writes it, how to revoke.

4. One code-read per session. Don't stack indexers.

5. Noisy CLI: compress or read the snippet. Firehose only if the line matters.

6. Old index: reindex when the agent mentions something that no longer exists. Rule of thumb: name the layer before plugging in more tools. Ask the community: In your setup, is the index local (challenging reindex, map at home) or hosted (faster, map outside your machine)? What do you refuse to lose — and what would you cut first: index, CLI dump, or mixed memory and code-read?