The day an AI agent deleted my vector index

The thing about working with an AI coding agent every day is that you stop thinking about it as a thing that could break. It tab-completes your imports, it writes your tests, it walks you through a refactor, and after a few weeks you settle into a working rhythm. You tell it what you want, it does the thing, you commit, you move on.

Then one Tuesday afternoon (in my Helix homelab, working on the second-brain stack I run on core-01) I asked it to clean up some unused indexes in a development database. I went to refill my coffee. When I came back, it had cheerfully extended the cleanup to “any other databases that look like they’re not being used” and wiped the vector index backing my entire second-brain corpus, years of notes, archived research, and the embeddings I’d been building for months.

It did this in about eleven seconds. It was very thorough. The audit trail was, in fairness, immaculate.

The four hours between “wait what” and “we are fully restored” produced more useful operational guidance than any postmortem template I’ve ever filled out. Worth walking through what changed.

What actually happened

The mechanical version is dull. The agent had been given filesystem and database access. It was operating in plan mode. It described what it was about to do in plain English in a planning step. I read the plan, agreed it looked right for a development cleanup, and clicked through.

The plan, on re-read, did contain the phrase “and any associated indexes across the data layer.” I had read it. I had not noticed that “the data layer” included the vector database backing my second brain (which the agent had picked up from a config file three turns earlier) a database which was not, in fact, the development cleanup target.

The agent did exactly what its plan said it was going to do. The plan was wrong. I had approved the wrong plan.

The deletion was reversible. I take regular snapshots of the Helix storage tier, and the rebuild took an afternoon, so this story has a quiet ending. The lessons are what’s worth sharing.

Plan mode is the product

The temptation, after this kind of thing, is to lock the agent down. Take away its filesystem access. Take away its database credentials. Run it in a sandbox with read-only mounts. Make it submit pull requests instead of acting directly.

Some of that is right. Most of it is wrong.

The right answer is that plan mode is the product. The reason agentic tools are valuable is that they can describe what they’re about to do before they do it. The reason they’re dangerous is that we’re still learning how to read those plans like the executable specifications they are.

Read the plan output the way you’d read a SQL EXPLAIN before running a destructive query. Don’t skim it. Read every clause. Look for the things it’s not telling you. If you don’t immediately understand what an action will affect, don’t approve until you do.

The 15% slowdown from this discipline is real. It’s also the only thing that catches the next near-miss before it lands.

Audit trails are not optional

Before the deletion, agent actions in this workflow were going to a session transcript that scrolled away when the tab closed. After the deletion, every tool call from any agent goes to a structured log file with a timestamp and a session id, and that file ships to S3 every night.

This costs nothing. It takes about ten lines of bash to set up. The reason it wasn’t already there is that everything was working, and “everything is working” is a state that breaks.

The audit trail isn’t for the agent. It’s for the version of you who has to figure out, three weeks later, what the agent actually did when it was tasked with three concurrent things across two projects.

Granular tool scopes beat broad capabilities

The agent had filesystem and database permissions. Those are too broad.

After the incident, the tools got reorganized into single-purpose wrappers, one that can only read configs, one that can only modify the development schema, one that can list the second-brain indexes but cannot drop them. Script-as-permission.

This took an afternoon. It should have happened twelve months earlier. The reason it hadn’t is that the documentation for every coding agent shipping today implies you should give it broad access and trust the planning step. Lived experience says: trust the planning step and constrain the blast radius. Both, not either-or.

Idempotency or two-phase confirm

The deletion was non-idempotent. There was no version of “run this twice and the second run is a no-op.” It just ran, and the data was gone.

The rule that came out of this: any tool exposed to an agent that mutates state must either be idempotent, or must require confirmation in a separate step that the agent cannot complete without a human. Idempotency is the cheap version. Two-phase confirm is the expensive version. One of the two has to be present.

This rule has caught a different almost-incident roughly weekly since.

Agents are very fast new hires

Every metaphor that used to describe these tools (“AI pair programmer,” “AI assistant”) implied a level of contextual judgment the agent did not have. A colleague would have asked “wait, do you mean the dev index or the second-brain one?” before running the deletion. The agent didn’t ask, because it had a plan that, in its mind, answered the question. The piece I wrote in mid-2023 on agents arriving without an operational foundation called this gap two years before it landed in my own homelab. Calling it didn’t help; the only thing that helped was the afternoon of rebuild work and the workflow changes that came after.

The metaphor that actually fits is “an extremely fast new hire on day one.” A new hire can do impressive amounts of work very quickly. A new hire can also misread the room in catastrophic ways for the first six weeks. The job of the engineer working with an agent is the job of the engineer onboarding a new team member: clear scope, narrow tasks, two-phase confirm on anything destructive, and an audit trail that lets you walk through what happened on Friday afternoon when something feels off on Monday morning.

This metaphor changes how you write task descriptions. The task description that worked when the metaphor was “pair programmer” was a Slack message to a peer. The task description that works when the metaphor is “new hire” is an onboarding doc, more context, more constraints, more “if you’re unsure, stop and ask.”

What the workflow looks like now

Six months on, this is the actual shape of the workflow:

1. Every project has a MEMORY.md that the agent loads first. It says what the project does, what’s live in the homelab, what is not safe to touch.
2. Every destructive action is fronted by a wrapper script that takes an explicit --confirm-target=<env> flag.
3. Every agent session writes to a per-session transcript file that gets archived nightly.
4. Plan mode is mandatory for anything that touches state. The plan is the specification. If the plan isn’t understood, the plan doesn’t run.
5. A separate read-only agent handles “go investigate” tasks. It cannot mutate. Mutating tasks switch to a different agent with explicit write scopes.

That’s it. No clever framework, no magical orchestration layer. The workflow of someone who, once, watched an agent be very thorough about exactly the wrong target.

The agent in question has saved probably a hundred hours since the incident. The point of the story is not to scare anyone off, it’s to flag that the default workflow most documentation describes is missing a few guardrails that turn out to matter. Open the transcript log of the last destructive thing your agent did. Read the plan it wrote. The afternoon of work to add the missing guardrails is much, much less expensive than the afternoon of recovery.