Where this idea came from

I asked Claude for a breakdown of what I actually use it for, by category because I wanted to know where I could hand it more context and get more back. I read my real prompt history: 575 substantive requests over eleven months, across 48 project directories.

The top category surprised me. It was some version of "I changed X in the user service, now update the client library, the CLI, the MCP tools, and the integration tests." Roughly a fifth of everything I ask. And nearly every one of those started with me re-establishing which repo was which.

‍

What I ask for, by category

Shares are approximate and sum past 100 — a single prompt often lands in more than one category. Counts are derived from the share, not counted separately.

‍

Problem: the map was the one file nobody had written

I work out of a directory with about 48 sibling checkouts. Most of the important repos already had a good agent doc inside them. What didn't exist anywhere was a file describing how they relate to each other — which repo is which layer, and what order a change has to travel in.

I spent a lot of time supplying the same things by hand:

• Where things are. I've literally typed "Sorry, the user-service code is in…" as a correction.
• How to run things. The same test and CLI invocations retyped dozens of times.
• What not to do. "Don't commit." "Don't deploy." "That infrastructure is applied centrally — don't run it locally." Re-stated prompt after prompt.
• Vocabulary. We're mid-rename in a couple of places, so the old and new terms both exist in the tree at once. Explaining which one is correct where, again and again.

None of that is hard to say. It's just that saying it every time is where mistakes come from, and it's context that should have been sitting somewhere readable.

‍

Steps to solve: what we actually did, in order

1. Asked for the category breakdown from actual history.
2. Set a constraint up front: don't scatter agent files into the repos themselves. Those are team repos; dropping context files into them means committing my agent setup into shared branches. We used the workspace root instead, which isn't a git repo. So nothing written there could leak into a team branch.
3. Split the content by how often it's needed. One short file that loads every session (the hard rules and the propagation order), and three longer reference docs: the repo map, how to run and test each thing, and the vocabulary plus API invariants.
4. Wrote the three reference docs into Fulcra as the source of truth. Kept a local copy as a cache so sessions without the MCP connected still work, plus a small sync script — pull, push, diff.
5. Verified across two paths. The docs went in through the MCP server and were read back through the CLI. Byte-identical. Two different code paths, same store.
6. Then made it automatic. A session-start hook that checks Fulcra for a doc matching whatever repo I've opened — any repo on the machine, not just this workspace — and loads it if one exists. Silent if not.
7. Made it cheap and safe to leave on. About 1.2 seconds on a cold fetch, 0.09 warm. Twelve-hour cache on hits, six on misses. It fails open: if Fulcra is unreachable I get no extra context, never a broken session.
8. Testing caught a real bug before it ever ran. A cached "no doc here" marker was short-circuiting ahead of the stale-copy check, which meant a repo could go quiet for hours after a single failed fetch. Fixed in place.

‍

Solution: a thin always-on file, and everything else in Fulcra

A short file for the handful of rules that apply everywhere, three reference docs in Fulcra for the rest, and per-repo docs at /agents/repos/<name>.md that get fetched automatically when I open that repo.

Fulcra is the source of truth; the local copy is a cache, not a second independent document.

‍

Result: any connected agent, not just this one

Any agent that can reach Fulcra now picks up the right context for a repo without me supplying it. And the thing I keep coming back to is this is exactly the kind of context worth keeping somewhere durable and portable. It outlives any one session, any one machine, and any one vendor's memory feature. We should all do it.