Giving an AI agent more files does not automatically give it better understanding. It can increase noise, expose private information, and make it harder to see why the model reached a conclusion. Nerva’s planned context manager should build the smallest useful context for each task.

This matters for a local-first agent because local context can include both ordinary source code and high-risk material such as .env files, private keys, customer exports, or uncommitted experiments.

Start with the user’s target

If a developer points to src/worker.ts and a failing test, those should be the first context candidates. The manager can then inspect imports, referenced types, nearby tests, and the relevant log lines. It should explain why each additional file was included.

Requested: explain failing worker test
Included: src/worker.ts, src/worker.test.ts, src/queue.ts
Included because: imported function and test fixture are referenced
Excluded: .env, node_modules, unrelated services

The point is not to create a perfect dependency graph. It is to make context selection narrow, understandable, and easy to correct.

Context should have a budget

A context budget can be measured in files, characters, tokens, or a simple user-approved scope. When the budget is exceeded, Nerva should ask whether to summarize, select fewer files, or use a model with a larger context window. It should not quietly attach the whole workspace.

Focused context also improves answers. A model that sees a route handler, its test, and the error is less likely to spend attention on unrelated documentation or generated output.

Local and cloud context are different decisions

The context manager should prepare a request before the model router chooses a destination. If the task contains sensitive paths, the local route may be the only automatic option. If the user chooses a cloud provider, the preview should show the exact files and redactions.

For real backend debugging, this separation is valuable: a developer can share a sanitized error and implementation while keeping credentials and customer data on the device. Context selection is therefore both a quality feature and a privacy control.

The useful design question

The useful question here is not whether an AI agent can produce an impressive demo. It is whether the workflow stays understandable when the task is incomplete, the repository is messy, or the model is wrong. For this part of Nerva, the focus is building a small, explainable context set. That means each state should have a visible owner, a small input, and a result that another part of the system can inspect.

A concrete scenario

Consider a worker file, its imported queue module, one test, and the exact error log. A good Nerva run would first state the scope, identify the files or operation it needs, and show the next proposed step. It would keep the original request separate from model-generated instructions. If an action needs approval, the user would see what will happen before it happens. Afterward, the task history would retain the command, result, and verification status instead of reducing everything to a confident paragraph.

This approach also makes a failure useful. A denied permission, unavailable provider, missing package, or changed file is information about the task state. Nerva should preserve it and explain the smallest recovery option. It should not silently broaden the request, retry a side effect, or claim completion because a model supplied plausible-looking text.

What I would test first

For an early implementation, I would test three paths: a normal successful run, a denied action, and an interrupted run resumed after the workspace changes. The key test is whether every selected file earns its place in the prompt. In each path, the interface should make clear what Nerva knows, what it proposed, what actually ran, and what remains unverified.

Useful acceptance checks include:

  • the user can inspect the selected context before model execution;
  • sensitive paths and credentials are excluded or redacted;
  • every side effect has a narrow permission decision;
  • failures remain attached to the step that caused them;
  • a final answer links to evidence instead of implying that unrun work succeeded.

Nerva is still an upcoming project, so these are design and implementation goals rather than claims that a finished product already provides them. That distinction matters: a trustworthy agent should earn confidence through observable behavior, not through a feature list.

The boundary that matters in production

Context selection should be inspectable in both directions. Nerva can show why a file was included, but it should also let the user remove it before execution. Generated files, dependency folders, secrets, and unrelated services should be excluded by default. For a monorepo, the resolver can start at the selected package rather than treating the repository root as the context boundary.

For the first vertical slice, keep the boundary small enough to explain in a code review. Define the input, the decision, the side effect, and the evidence for completion. Add a test for the denied path as well as the successful path. This is where a local-first design earns trust: the user can inspect the context and history on the device, see when a provider is involved, and stop before an action crosses the permission boundary. The design should remain honest about its limits. Nerva is planned software, not a claim that every workflow can be made safe automatically. A clear “cannot verify” state is more useful than a polished but unsupported success message.

The design is informed by the boundaries I have had to think through in CryptoEx and SentinelFi: backend work becomes easier to review when context, permissions, side effects, and verification are explicit.