Why do AI agents need a special "begin" step for my knowledge base?

Because an agent that guesses at your setup from stale training data or an old cached copy will confidently act on wrong facts. A begin step forces it to read the current canonical state first — verifying the vault commit, loading the relevant pages — so it starts already knowing your lab as it actually is right now.

What does "fail closed" mean for an agent reading the vault?

It means that if the agent cannot verify it is reading the current canonical state — the vault is unreachable, or a derived index reports a different commit — it stops rather than proceeding on possibly-stale context. Failing closed prevents an agent from acting confidently on outdated or inconsistent information.

How should an agent write findings back to the vault?

Never directly. It persists outcomes through the same controlled-write contract a human uses — lock, validate, commit, refresh, verify, unlock — via an end step. That keeps agent writes atomic and validated, and stops a well-meaning agent from corrupting the authority with an unchecked edit.

Make Your AI Agents Read the Docs First, Every Time

On this page

The begin flow
The end flow: persist through the controlled writer
The swap-in box
What you have now

Here’s the payoff the whole series has been building toward: an AI agent that starts work already knowing your lab — not guessing from training data, but reading your current, authoritative brain. The trick is a disciplined cold start, because an agent confidently acting on stale context is worse than no agent at all.

The principle

An agent gets a revision-labeled cold start: it verifies the vault’s canonical commit, loads only the pages the task needs, and fails closed if it can’t confirm it’s reading current state. It persists outcomes through the same controlled-write contract a human uses. Two skills bracket the work: begin and end.

First: make these values your own

Paths like ~/wiki are examples — use your own vault location. begin/end are procedures you adapt to your own agent tool, not commands to copy blindly.

The begin flow

begin is a cold-start procedure, not a data dump. It reads the smallest current context that gives global awareness for the task.

1Record the canonical commit1 min

The first thing begin does is read and report the vault’s current commit. Everything the agent loads afterward is labeled with it, so its whole working context is pinned to one revision.

begin — step 1


git -C ~/wiki rev-parse HEAD        # record this; label all reads with it
git -C ~/wiki status --porcelain    # note any unexplained working-tree state

2Read the context digest — one file for global orientation2 min

Instead of reading AGENTS.md, a manifest, and a home page separately, the current system uses a single generated file: agents/context-digest.md. It contains region summaries, key guardrails, a RESUME pointer, and a full card-catalog of every vault page — all stamped with the canonical commit it was generated from.

One read gives the agent a map of the whole brain without loading the whole brain. The digest is not a replacement for canonical topic pages; it’s an index that tells you which ones to open next.

begin — step 2


# One file covers what used to require three separate reads
cat ~/wiki/agents/context-digest.md
# Check the "Canonical commit:" line in the digest matches step 1's HEAD

The digest is generated output, not a source of truth

The canonical commit line inside the digest lets you verify it was generated from the same revision you just read. If the digest’s commit doesn’t match HEAD, it’s stale — read it as a discovery aid, but rely on the canonical topic pages for decisions.

3Delta check — only read what changed1 min

The digest records the commit from the last /end. Run a quick git diff to see what actually changed since then. If nothing changed, you can skip re-reading the pages you already know — only load the changed canonical pages. This keeps cold starts cheap even as the vault grows.

begin — step 3 (delta check)


# Extract last-session commit from the digest's "Canonical commit:" line
LAST=$(grep 'Canonical commit:' ~/wiki/agents/context-digest.md | grep -oE '[0-9a-f]{7,40}')
git -C ~/wiki diff --stat "$LAST"..HEAD -- . ':!.obsidian'
# If the output is empty, the digest is still current — no re-read needed

4Load only the pages the task needs3 min

From the card-catalog in the digest, load the smallest connected set for the task: the relevant hub and canonical topic owner, linked decisions and runbooks that constrain the work, and dated evidence only when the topic page doesn’t settle a question.

If the vault has a semantic search index, use it to discover relevant pages — but use a two-stage approach: first run an unfiltered search to identify the region (the brain area the task lives in), then re-run scoped to that region for higher-quality hits. A broad unfiltered search across a large vault surfaces noise; knowing the region first cuts it dramatically.

begin — step 4 (two-stage semantic search)


# Stage 1: unfiltered — find the relevant region from top hits
node tools/canonical-vault/embeddings/query.mjs search "recover wiki projection" 5

# Stage 2: scoped — re-run with the winning region tag
node tools/canonical-vault/embeddings/query.mjs search "recover wiki projection" 10 region/second-brain

# Then follow the graph: expand from the best hit to its topic MOC + siblings
node tools/canonical-vault/embeddings/query.mjs graph "runbooks/wiki/import-pages.md"

5Fail closed on any mismatch + produce a start brief—

If the vault is unreachable, or a derived index (search, embeddings) reports a different commit than the status call, begin stops. It never proceeds on context it can’t prove is current. Once the context passes the check, begin ends by stating what it knows: the canonical commit and check time, current relevant state, the exact resume point, active guardrails, and the pages it loaded.

Fail closed, always

Stale-but-confident is the failure mode a knowledge base exists to prevent — don’t reintroduce it at the AI layer. If currency can’t be verified, the correct action is to stop and report the mismatch, not to guess. This is the fail-safe defaults principle from Saltzer and Schroeder’s foundational 1975 security paper: when in doubt, deny — base access on explicit permission, not on the absence of a reason to refuse.

The end flow: persist through the controlled writer

When the work produces a durable outcome, end writes it back — but only through the controlled-write contract. The agent never does a raw git commit on the authority.

The current write path has three verbs — preflight, write, verify — that collapse what used to be a multi-step manual procedure into three explicit commands, each returning a structured result:

end — streamlined vault.mjs path


# 1. Preflight: auto-regenerates the topic map, runs all audits,
#    emits the exact file list to stage. Fix any ok:false before proceeding.
node tools/canonical-vault/vault.mjs preflight

# 2. Write: one command does lock → commit → refresh → mirror → verify
node tools/canonical-vault/vault.mjs write --message 'feat: ...' --stage '<preflight stage_list>'

# 3. Verify: confirm all consumers and mirrors report the new HEAD
node tools/canonical-vault/vault.mjs verify

# After a successful write, regenerate the context digest as a follow-on commit
# so the next begin sees an accurate card-catalog and commit stamp
node tools/canonical-vault/generate-digest.mjs . --commit <new-sha> --date <today>
git add agents/context-digest.md
git commit -m 'chore: regenerate context digest'

The --stage argument is load-bearing

Pass the exact file list from preflight’s stage_list output. The --stage flag does not glob — if you pass a directory or a mismatched list, the write will silently stage nothing or the wrong files. Always use what preflight computed, not a hand-authored list.

A thin adapter per tool

begin/end are tool-agnostic procedures. Each AI tool (a CLI agent, a chat assistant, a background worker) gets a thin adapter that invokes the same skills — so every agent cold-starts and persists identically, regardless of which model or harness is driving.

The full begin/end skill outline and a thin adapter are in the paired playbook: AI Begin/End Skill + Adapter.

The swap-in box

On other tools

Claude Code / Cursor / other agent harnesses: implement begin/end as a slash-command, skill, or startup hook that runs the commit-check and context-load before the agent acts. RAG chatbots: make the retrieval layer return the source commit with every answer, and refuse to answer if the index is stale. The durable idea: no agent acts on your knowledge without first proving what revision it’s looking at — and no agent writes back except through your validated write path.

What you have now

Agents that start every task pinned to your current canonical state and persist results without ever corrupting the authority. But an agent on your laptop and an agent on the cluster reach the vault very differently — and getting that wrong reintroduces the split-brain we’ve fought all series. That’s multi-machine access without split-brain.

Related posts:

Why Auto-Syncing Your Notes Repo Will Corrupt It — the write path end uses
Share Your Vault Across Machines Without Split-Brain — how laptop vs. cluster agents reach the same authority
Semantic Search for Your Notes, Running Locally — the index begin consults to find relevant pages
Hermes Agent: Self-Hosted AI Agent with Fallback Model Chains — a self-hosted agent to wire begin/end into
Your Homelab Needs a Second Brain — Here’s Why — the payoff this post delivers
10 Mistakes I Made Building a Homelab Second Brain — the traps the happy-path docs don’t show

Comments

Comments are powered by GitHub Discussions — sign in with a GitHub account to join the conversation.