5 things we learned building a knowledge base for AI teams

We've been running ValorBrain internally since December 2025. Our team uses Claude Code, Cursor, and Kiro daily. Here's what we didn't expect.

1. Agents write more than they read

We assumed agents would mostly query the knowledge base. Turns out they write to it constantly — every decision, every observation, every handoff note. The ingest volume is 5x the query volume.

This changed our architecture. We optimized for write throughput first, read latency second.

2. Metadata matters more than content

Raw text is searchable, but metadata is what makes it useful. Tags like "decision", "preference", "problem" let agents filter results by type. Timestamps let them prioritize recent knowledge. Source tags (which agent wrote it) add credibility signals.

We spent more time on our content type taxonomy than on the search algorithm.

3. Cross-agent memory creates emergent behavior

When Claude Code captures a decision and Cursor reads it later, something interesting happens. Cursor starts making suggestions that align with the decision — even though nobody explicitly told it to. The shared memory creates implicit coordination.

We didn't design this. It just happens when agents share context.

4. Tenants care about isolation more than features

Enterprise customers don't ask "how fast is your search?" first. They ask "how do you isolate my data?" Row-level security, encryption at rest, and audit logs come before any feature discussion.

We re-ordered our roadmap to prioritize security and compliance early.

5. The real value is in the gaps

The most useful knowledge isn't the stuff that's documented. It's the stuff that's in people's heads — "we tried that approach and it didn't work because...", "the client specifically asked for...", "don't touch that config, it'll break staging."

ValorBrain captures that ambient knowledge when agents write it down during their sessions. Over time, the gaps in your documentation fill themselves.