Stop Paying the Agent Context Tax

Open a fresh agent session and the tax starts immediately.

Explain the repo layout. Paste the docs. Describe the architecture. Mention the gotchas. Point it at the right files. Warn it about the test that lies.

Then hope it remembers long enough to be useful.

Most agent workflows don’t fail because the model can’t write code. They fail during orientation — every session starts cold, and you become the runtime context loader. You pay that tax again on the next session, and the one after that, because nothing the agent learned survived the run.

We’ve named this before: the memory problem. Every workaround — CLAUDE.md, project rules, copy-pasted prompts — treated your context as a file the agent might read instead of infrastructure the agent can search. Context doesn’t belong in a giant prompt. It belongs in searchable infrastructure.

Valdr 0.2.0 changes where the context lives. Instead of stuffing the workspace into the prompt, you attach the workspace to Valdr: repos, docs, runbooks, Valdr records, and memory notes become searchable local context agents can query before they act.

A feature list can explain that. A bug investigation shows why it matters. So let’s watch one session.

A bug report, two repos, and an agent that’s never seen either

Picture the kind of ticket every team has sitting in its backlog:

Bug: Request timeouts are wrong. Config says requestTimeoutMs: 60000, but slow calls die at ~30 seconds anyway. Started sometime in the last few releases. Can’t reproduce locally every time.

It’s the kind of bug that burns real engineering time: a vague symptom, an intermittent failure, and the likely cause sitting in a different repo from where the error appears. Exactly the investigation that used to require a human to hold both repos in their head and go spelunking.

We hand it to an executor agent — a Codex session, because it’s good at chewing through unfamiliar code. Two sources are attached to the project: the UI repo where the error appears, and the client/runtime repo where requests are made. The agent has never seen either. Before 0.2.0, that sentence would be the end of the story — you’d spend the next twenty minutes narrating the codebase. Instead:

1. It orients before it edits

The important part is what it doesn’t do: it doesn’t immediately start editing code. Good agents orient before they act. It starts by reading the workspace — searching the attached docs and runbooks for how timeouts are configured and where the value flows:

docs about request timeout configuration

It finds an architecture note explaining that timeouts are resolved centrally and passed down to the transport layer — and, critically, a runbook line nobody on the current team remembers writing: “defaults are applied in resolveTimeout; overrides are merged from project config.” Now the agent knows the right symbol to chase instead of grepping blind.

2. It follows the code the way you would

This is where code-aware navigation earns its keep. The agent asks source-shaped questions and walks the graph across both repos:

definition of resolveTimeout
callers of resolveTimeout
tests for resolveTimeout

The definition shows a function that merges project overrides into a defaults object. Its callers show something interesting: most pass the merged config straight through, but one call site — in the transport client, a different repo — re-applies a hardcoded DEFAULT_TIMEOUT_MS = 30000 after the override merge, clobbering the user’s 60-second value.

That’s the break in the case. The test query confirms it: tests for resolveTimeout returns coverage for the defaults path and the empty-config path, but nothing exercises the override-then-transport path. The bug lives exactly in the seam no test was watching.

The agent didn’t reconstruct this from a paragraph you pasted. It navigated your actual source, across a repository boundary, from a symbol it learned about in your own runbook.

Now count what that didn’t cost. The brute-force version of this hunt — grep across two repos, open a dozen files on a hunch, read each one in full into the context window, re-read after every wrong turn, reconstruct the call graph by hand — burns thousands of tokens and real wall-clock before the agent even forms a hypothesis. Cross-repo makes it worse: two trees to crawl, more dead ends, more whole files dragged into a context window that’s now too full to reason well. Workspace Knowledge returns the resolved symbol and the relevant chunk — targeted evidence, not the entire file — so the agent spends its token budget reasoning about the bug instead of rediscovering the filesystem. Faster, cheaper, and the context window stays clear for the part that matters.

3. It writes down what the next session shouldn’t have to rediscover

Here’s the part that compounds. The agent fixes the call site, adds the missing regression test — and before the session ends, it appends an entry to an Agent Memory Notebook:

Override-after-merge hazard: resolveTimeout merges project overrides correctly, but downstream transport clients can re-apply hardcoded defaults and silently clobber them. Any “config value ignored” bug should check for defaults applied after the merge. Regression test added in transport/__tests__/timeout.spec.ts.

That’s not a note for the agent. That’s operational memory for the workflow. It isn’t a chat message that scrolls away — it’s scoped, searchable context that lives in your workspace until you delete it.

4. The next session starts smarter than the last one ended

A week later a reviewer agent — this time a Claude session, your team’s pick for sign-off — picks up a related change to the same transport client. It isn’t told about any of this. But when it searches the workspace for context on the file it’s reviewing, the notebook entry surfaces — ranked below your canonical docs, but right there as a known hazard. The reviewer checks the override path on purpose, because a prior session learned it the hard way.

  SESSION 1 · Codex executor (week 1)
    └─ searches docs & runbooks
    └─ traces resolveTimeout across two repos
    └─ fixes the override-after-merge bug
    └─ saves a memory note
            │
            ▼  (lives in Valdr, not the model)
        WORKSPACE MEMORY NOTEBOOK
            │
            ▼  (surfaces on search)
  SESSION 2 · Claude reviewer (week 2)
    └─ never briefed
    └─ finds the note
    └─ checks the override path — no rediscovery

No one re-explained the codebase. No one pasted the same files. No one rediscovered the same seam.

The investigation became reusable.

The discovery doesn’t live in Codex. Or Claude. It lives in your workspace.

Look again at what just happened across providers. The bug hunt ran on Codex. The review ran on Claude. The discovery crossed between them without a hitch.

That’s not how provider-native memory works. A CLAUDE.md does nothing for a Codex agent. Codex’s own memory can’t brief a Claude reviewer. Each provider keeps its context in its own silo, so the moment you switch models — or run a team where different people prefer different ones — the investigation is trapped on the wrong side of a wall.

Valdr’s Agent Memory Notebooks live in your workspace, not in the model. So the discovery is portable: run the exploration with whatever model is best at exploration, review with whatever model your team trusts for sign-off, and the same investigation carries across both. One workspace memory, every provider.

Three things made that possible

None of them existed before 0.2.0:

• Source-aware search gave the agent workspace evidence instead of whatever fit in the prompt.
• Code-aware navigation let it follow definitions, callers, and tests across repositories.
• Agent Memory Notebooks made the discovery survive the session — and live in your workspace, not the model — so the next agent inherited the investigation instead of repeating it, no matter which provider ran it.

This isn’t a hypothetical

The scenario above is illustrative — the capability behind it isn’t. Here’s the unedited verdict from a Claude Code agent after it used Valdr’s code-aware navigation (code_map) to trace a real cross-repo bug: where a tag got its detail type, why it was dropped, and what the library affordance was to override it.

pm_knowledge code_map turned a multi-repo grep-and-read investigation into ~6 targeted queries plus 4 confirmatory file reads. The graph-vs-retrieval transparency, FQN resolution across project boundaries, and grouped result shape (definitions/references/tests/docs) all materially shortened the loop.

The tool’s biggest leverage is exactly the kind of question this was: a symbol I half-know, declared somewhere I don’t, referenced via a chain I haven’t seen. That’s where grep falls down and the persisted symbol graph wins.

Where I’d keep using grep: when the question is a literal string match (a magic value, a log message, a config key) rather than a symbol relationship. The MCP correctly punted to retrieval in those cases via the hybrid search path, but for those queries grep is simpler.

Net verdict for cross-project tracing: strong recommend. This bug would have taken me 10× longer with grep -rn.

— Claude Code, after a cross-repo trace with Valdr

Notice what makes that credible: the agent still reaches for grep when the question is a literal string. This isn’t “AI replaces search.” It’s the right tool for symbol relationships — a symbol I half-know, declared somewhere I don’t — which is exactly the cross-repo case that eats your afternoon. On those, the agent put the difference at 10× versus grep -rn.

The fix was small. The investigation was the work.

That’s the thing the feature list won’t tell you: on almost any real task, the implementation isn’t the expensive part. The investigation is. Figuring out where the behavior lives, which call site is lying, what the tests don’t cover, why the last person did it that way — that’s the work. And until now, that work was completely un-reusable. Every agent, every session, paid for it again from zero.

This is the real shift in 0.2.0, and it’s about agent economics, not AI memory. The first deep dive is cheaper — targeted retrieval instead of grepping two repos and dragging whole files through the context window — and then it’s free to run again, because the next agent inherits it instead of paying for it. The reviewer inherits the executor’s findings. The next investigation starts where the last one ended. Your workspace context stops evaporating into disconnected transcripts and starts compounding into a foundation.

And — to be precise, because precision is the point — this is working memory, not magic. It’s scoped to your projects, it’s searchable, your trusted docs always rank above lower-confidence notes, and everything lives in your workspace until you delete it. An agent that confidently trusts a stale note is worse than one with none; ranked trust is how Valdr keeps the deep dive an asset instead of a liability.

Stop narrating your codebase to every new session

You’ve explained the repo layout enough times. The placeholder scaffolding did its job; 0.2.0 replaces it with something agents can actually query.

Attach the repo. Attach the docs. Attach the runbooks. Let the agent search before it acts — then keep the discoveries that should survive the run.

See exactly what agents can do with it: Workspace Knowledge for AI Agents →

Valdr is a control plane for engineers who use AI agents in real work. It doesn’t just help agents remember — it makes expensive engineering investigation reusable. See how it works →