One knowledge base for all your AI agents

When I started using Claude Code seriously, I did what everyone does: I created a CLAUDE.md in each repo with project conventions, stack notes, and gotchas. It worked, mostly. But something kept frustrating me.

Every new session, the agent would rediscover the same things. MusicKit doesn’t work in the simulator - again. CloudKit requires optional properties on every @Model - again. The Ansible vault is a single encrypted blob that git can’t merge - again. I was writing the same comments in my issue tracker over and over, or relying on the agent to remember things it couldn’t.

The problem is that CLAUDE.md is the wrong tool for this. It’s great for stable project conventions: architecture decisions, directory structure, build commands. It’s bad at accumulating the messy, earned knowledge you build up during actual work - rate limit behavior you observed, a caching strategy that worked, a gotcha that cost you two hours.

That knowledge needs to live somewhere an agent can find it on the next session, without you having to stuff it all into the file that’s supposed to be a conventions doc.

The pattern: one vault, many projects

I set up a single git-backed Obsidian vault at ~/Repos/vdaluz-kb/. Every project points to it. Notes use YAML frontmatter with a projects: field to record provenance:

---
date: 2026-06-06
type: source
source: MusicKit / Apple Music catalog
tags: [musickit, apple-music, ios, swift]
projects: [deep-cut-atlas]
---

The projects: field is provenance, not a scope filter. An agent in any repo can grep -ri "musickit" and find the note, regardless of which project originally wrote it. Cross-cutting patterns (Ansible vault merge behavior, SSH key rotation) live there too - tagged with all affected projects.

The structure is simple:

vdaluz-kb/
  patterns/       # recurring patterns and data source quirks
  infrastructure/ # service gotchas, runbooks, host-specific notes
  alerts/         # daily alert review findings

No per-project directories. Provenance lives in frontmatter, not in the folder tree.

Wiring a project in

Each project’s CLAUDE.md gets a short KB section:

## Knowledge base
Durable findings live in the central KB at ~/Repos/vdaluz-kb/.

- Before implementing anything: grep -ri "<topic>" ~/Repos/vdaluz-kb/
- Saving new findings: write to ~/Repos/vdaluz-kb/patterns/<slug>.md
  with frontmatter projects: [this-project], then commit and push
- Issue-scoped notes: go in the issue tracker, not the KB

That’s the full integration. The agent knows to check before implementing, and knows where to save when it learns something worth keeping.

What goes in the KB vs the tracker vs CLAUDE.md

This took me a while to get right. The rule I landed on: CLAUDE.md holds stable conventions (architecture, stack, build commands, critical constraints) and changes rarely. The KB holds durable-but-discovered knowledge - gotchas, rate limit behavior, known failure modes, patterns that recur across issues - and changes when you learn something new. The issue tracker holds issue-scoped notes - decisions, investigation steps, evidence for a specific piece of work - and is ephemeral by design.

A good test: “Would someone touching this six months from now need to know this?” If yes, KB. If it’s only relevant to the work you’re doing right now, it stays on the issue.

The fragmentation trap

The issue that prompted this originally asked me to build a per-repo Obsidian vault inside the Deep Cut Atlas iOS project, mirroring what I’d done for the homelab. But by the time I got to it, the homelab’s per-project vault had already been consolidated into the central KB. Building a second per-repo vault would have re-fragmented exactly what I’d just unified.

The right fix was to wire Deep Cut Atlas into the existing KB and seed it with what I already knew from earlier spikes. Two files, two commits, done.

The lesson: when you have multiple active projects, per-repo knowledge stores are a maintenance burden. One vault is enough. Frontmatter provenance beats folder structure every time.