Why Part of Our Agent Knowledge Base Runs on Subversion

Part of our internal knowledge base now runs on Subversion instead of Git. Private documents first, in 2026, on purpose. The reason is narrow and worth stating plainly: a knowledge base that AI agents read from and write to needs per-folder permissions and one central history, and Git gives you neither natively. Our source code did not move and is not going to. A parallel Git mirror has been running since day one. This is a bet in progress, not a migration story, and it is the kind of decision I would rather publish while it is still reversible than after it has been sanded into a case study.

This expands on the LinkedIn post I published on August 21 about moving part of our knowledge base off Git.

Key Takeaways

• A prompt is documentation when a human reads it and code when an agent executes it. The same file is both, and neither of its traditional homes fits: shared documents drift under manual copying, and Git was designed around assumptions that a knowledge base breaks.
• Two specific Git limits drove the decision. Git's permission unit is the repository, while knowledge needs permissions per folder. And removing a bad commit means rewriting history that other people already hold on their own machines.
• Subversion happens to fit both. It has documented path-based access control down to the individual file, and one central history rather than a copy per clone.
• Subversion is not the clean winner here. It has no reliable way to erase committed data either, and centralization trades away the resilience that made Git the default. We took that trade knowingly.
• Source code stays on GitHub. This applies to knowledge documents only, and it is written down as a signed non-goal so nobody quietly widens the scope later.
• Ergonomics stopped being the deciding vote. Agents do most of the committing to this repository now, and agents do not complain about a clunkier client.

The File That Is Both Documentation and Code

Start with the artifact, because the storage question only makes sense once you know what you are storing.

A prompt is documentation when a human reads it and code when an agent executes it. So is a routing rule, a metric definition, a naming convention, an onboarding checklist. Two years ago these lived in a shared document because their only reader was a person. Now they have a second reader that executes them literally, at volume, without asking a clarifying question when the wording is ambiguous.

That second reader changes the requirements. A document that an agent executes needs a version history, because when behavior changes you have to know which line changed and when. It needs review, because a one-word edit is a behavior change. It needs access control, because the file describing how we handle a customer's data should not be readable by everyone who can read the file describing our blog style. Those are the properties of a code repository, applied to prose.

This is the operational half of a point I made in context engineering versus prompt engineering: the work is getting decisions written into a place agents read, versioned when they change, and retired when they stop being true. Once you accept that framing, you own a versioning problem you did not have before, and the place you put those files becomes an architecture decision rather than a filing preference.

Shared cloud documents fail the moment the same policy is duplicated into three folders and two of them fall behind. That failure mode is well understood and it is why we reached for a repository at all. The question was which one.

Where Git Strained

Git is the correct default for source code and it remains our default for source code. The two limits below are not defects. They are consequences of a design that optimizes for distributed code collaboration, and a knowledge base is a different workload.

The permission unit is the repository

Git has no native concept of "this team can read this folder and not that one." Access is granted at the repository, and the common workarounds are all worse than they sound: split the knowledge base into many repositories and lose cross-linking, or accept that everyone with access reads everything.

Subversion treats this as a first-class feature. The Subversion book's chapter on path-based authorization describes granting one set of users write access to a given directory while another directory is readable only by a few, and notes that because files are paths too, access can be restricted "on a per file basis." It is configured through a single access file, mapping paths to read or read-write for users and groups, with no access as the default when a user is not mentioned at all.

The Subversion book also warns that path-based restrictions carry a performance cost and can inhibit collaboration. Both are true and we accepted them, because for a knowledge base holding HR material, security policies and customer-specific runbooks, per-folder access is the requirement rather than an optimization.

Bad commits are distributed

The second limit is the one people underestimate until it happens. Something lands in a knowledge base that should not have: a credential pasted into a runbook, a customer name in an example, a salary figure in a draft. In Git you cannot simply delete it.

GitHub's own documentation on removing sensitive data is unusually blunt about why. The fix requires rewriting the repository's history locally and force-pushing the rewrite. GitHub then warns that it is easy to make a bigger mess: if a colleague still holds a clone from before the rewrite and simply pulls and pushes, the sensitive data comes back. And it states the sentence that settles the argument for a knowledge base, that you "cannot remove sensitive data from other users' clones." You have to send them instructions instead. Forks keep the commit until their owners act, and removing cached views requires opening a support ticket.

None of that is a bug. It is what distributed version control means. Every clone is a complete copy, so a deletion is a request rather than an operation.

What Subversion Gives Us, Including What It Does Not

Here is the part I want to get right, because the tidy version of this story is wrong and I have seen it repeated.

Subversion does not let you erase a bad commit either. The Subversion book says plainly that "Subversion generally doesn't provide an easy way to remove that data," and notes that an obliterate feature has been one of the most requested Subversion features for years. The documented route is to dump the repository, filter the unwanted paths out of the dump stream, and load the result into a fresh repository.

So the real difference is not deletion versus no deletion. It is where the work lives and whether you can finish it. In Subversion that procedure is one server-side operation performed once by an administrator, after which everyone checks out from the corrected repository. In Git the equivalent is an operation you perform on your own copy and then ask every other holder of a clone or fork to repeat, with no way to confirm they did. For a knowledge base whose contents are increasingly written by agents rather than reviewed line by line by humans, "the fix is centrally enforceable" is worth more than "the fix is elegant."

Two smaller properties matter as well. One central history means the working copy is a single revision rather than the entire past, so large attachments are unremarkable rather than a thing you plan around. And the repository has one audit trail rather than a canonical branch plus an unknown number of divergent copies.

Now the honest cost. Centralization concentrates risk in a way Git deliberately does not. A distributed repository survives its server evaporating because every clone is a backup; a central one does not. It is the same objection I answered when we argued for consolidating agent access behind a single MCP gateway, where the section addressing it opens by conceding that centralizing access concentrates risk, and says we took the trade deliberately on the view that one audited boundary beats many unreviewed ones. The concession holds here and the argument is weaker here, because a knowledge base has no equivalent of fifty ad hoc servers to compare against. Which is exactly why the mirror below is not optional.

What We Did Not Do

Three constraints are written into the architecture, and they exist so that this decision cannot quietly become a bigger one.

• Source code stays on GitHub. Our implementation plan requires a signed non-goal committed to the root of the vault before the first change ships. Its text says the vault hosts knowledge documents and is not a replacement for Git, not a code repository, and not a CI/CD substrate. A written non-goal is cheap and it is the only thing that reliably stops scope creep a year later, when nobody remembers why the line was drawn.
• A parallel Git mirror runs from day one. A post-commit hook exports the Subversion repository and pushes it to a private Git mirror on every commit. It went live before any user traffic did. If every hosted service we depend on disappeared tomorrow, a complete browsable copy of the knowledge base still exists in Git. That is the disaster-recovery floor that makes the centralization trade acceptable, and it is a hard gate in the plan rather than a nice-to-have.
• A named owner for twelve months. One person committed in writing to owning this through the following year. If nobody had volunteered, the more ambitious half of the plan was cancelled by default.

I am saying this precisely because "we moved off Git" is the version of this story that travels, and it is not true. We moved one workload, kept the mirror, and wrote down what we are not doing.

Talk to an expert if your agents are reading from a knowledge layer nobody has decided how to govern yet.

What the Adoption Numbers Actually Say

Git holds roughly nine in ten of the developer vote, and it is worth knowing exactly how that number is sourced, because it is older than most people assume.

The cleanest measurement is the Stack Overflow Developer Survey 2022, which asked respondents which version control systems they primarily use. Across 71,379 responses, Git came in at 93.87 percent and Subversion at 5.18 percent. Among professional developers specifically, 53,374 responses, Git was 96.65 percent and Subversion 5.96 percent. Note the question allowed multiple selections, so those columns describe use rather than exclusive use.

Two caveats, both of which cut against overreading it. Stack Overflow added that question for the first time in 2022 and dropped it again the following year, so 2022 is the most recent clean reading available rather than a current one. And a developer survey measures developers, which is the population least likely to be storing a knowledge base.

What I will not do is attach a number to the claim that the remaining Subversion base skews toward the largest enterprises. I believe it, and the reasoning is straightforward: the shops that never left are disproportionately the ones with the constraints described above, namely fine-grained access requirements, heavy binary assets and a single auditable trail. But I could not find a primary source that measures it cleanly, and the vendor install-base trackers that publish such counts do not show their method. A number I cannot trace is worse than an argument I can defend, so it is an argument.

For context on the software itself: Apache Subversion 1.14 is the current long-term support line, first released in 2020, with 1.15 in progress. That is a maintained project moving slowly, which is a fair description of both its condition and its appeal.

Ergonomics Stopped Being the Deciding Vote

Subversion is clunkier for engineers than Git. Branching is a convention rather than a native strength, the tooling ecosystem is a fraction of the size, and every developer we hire already knows Git.

That used to be decisive, and it stopped being decisive for one reason: agents do most of the committing to this repository now. When a human writes three documents a week and an agent writes forty, the interface cost falls mostly on something that does not experience interface cost. The properties that survive that shift are the structural ones, which are access control, auditability and central enforceability, and those are the ones we optimized for.

This connects to a failure mode worth naming, because it is the reason the knowledge base exists at all. An agent without a durable place to read from and write back to rediscovers the same context every session, which we broke down in the hidden costs of AI agents. The fix is a knowledge layer with memory rather than a bigger context window, a distinction I pulled apart in AI agent memory versus search. Version control is the unglamorous plumbing under that layer, and getting it wrong shows up as agents acting on a policy that was corrected three weeks ago.

Maybe I am wrong about this and we are back on Git in a year. If your agents write to a shared knowledge base, the question worth asking today is what it is versioned with, and whether that is holding.

Talk to an expert about building a governed data foundation your agents can read from and write back to.

Frequently Asked Questions

Did Improvado move off Git?

No. Part of our internal knowledge base, private documents first, moved to Subversion. Source code stays on GitHub, and that boundary is written into the plan as a signed non-goal. A parallel Git mirror of the knowledge base also runs continuously, so the content exists in both systems.

Why not just use separate Git repositories for each permission level?

Because a knowledge base is valuable in proportion to how densely it is cross-linked, and splitting it along permission lines cuts exactly those links. You would also multiply the number of repositories every agent has to be configured to reach. Path-based authorization solves it in one access file against one repository.

Can Subversion permanently delete a bad commit?

Not directly. Subversion has no obliterate command, and the Subversion book acknowledges it as a long-requested missing feature. The documented route is to dump the repository, filter out the unwanted paths, and load the result into a new repository. The advantage over Git is that this is one server-side operation an administrator can actually complete, rather than a rewrite every clone holder must repeat.

What happens if the central Subversion server goes down?

Centralization is the real cost of this choice, and it is why the parallel Git mirror is a hard requirement rather than a convenience. A post-commit hook pushes every commit to a private Git mirror, so a complete copy of the knowledge base exists independently of the Subversion service.

Is Subversion still maintained?

Yes. Apache Subversion 1.14, first released in 2020, is the current long-term support line, and 1.15 is in progress. It is a slow-moving project rather than an abandoned one.

Does this mean marketing teams should switch to Subversion?

No. The decision that generalizes is not the tool, it is asking what your agent-readable knowledge is versioned with and whether that system can enforce a correction. For most teams the honest answer today is that those files live in a shared drive with no history at all, and moving them into any reviewed repository is a bigger improvement than choosing between Git and Subversion.

How do agents commit to it?

The same way a person does, through the repository's own interface, with the commit attributed and the change reviewable in the central history. That attribution is the point: when an agent's behavior changes because a document changed, the history is where you find out which document and when.