# Agent Knowledge Base (org-roam) Applies to: `**/*` Craig's org-roam knowledge base is the shared, cross-project store for durable agent knowledge. It lives at `~/org/roam/` — a git repo (origin `cjennings@cjennings.net:git/roam.git`), auto-synced on Craig's machines by the `roam-sync` systemd timer. Per-project harness memory stays the fast capture layer; durable facts get promoted here. ## Reading (any project) Before relying on a remembered project fact, a prior decision, or reference material, search the KB first. The interface is plain files — never the org-roam SQLite cache: ```sh # content/tag search rg --glob '*.org' --glob '!*sync-conflict*' '' ~/org/roam/ # follow an [[id:UUID]] link to its node rg --glob '*.org' --glob '!*sync-conflict*' ':ID:[[:space:]]+' ~/org/roam/ ``` Pull before querying (`git -C ~/org/roam pull --ff-only`); skip silently if offline. If `~/org/roam/` doesn't exist on this machine, proceed without the KB and say so — never fabricate recall. ## Writing (personal projects only) Classify the project before any write. The source of truth is the work-root denylist below — never inference from remotes, names, or task content: - **Work** — project root is, or sits under, a denylisted root. No KB write, ever. Record durable facts per that project's own conventions. - **Personal** — project root sits under `~/code/`, `~/projects/`, or `~/.emacs.d` and is not denylisted. KB writes allowed. - **Unknown** — anything else. No KB write. Work-root denylist (confirmed by Craig, 2026-06-10): `~/projects/work` **Refusal contract** (work and unknown alike): state the classification, name the durable fact in a one-line redacted summary, and say where it was or wasn't written — so Craig can re-route it deliberately instead of losing it silently. **Scope of the denylist — durable KB-node writes only.** The work-denylist governs one thing: promoting a durable fact into a new `agents/` node. It is a confidentiality guard so work-confidential material doesn't land in the personal cross-machine store. It is *not* a general "don't touch roam from a work project" boundary. Roam is a *shared resource*, not another project's product scope. Reading it (any project) and *tidying the shared roam inbox* — processing, routing, and filing the capture items in `~/org/roam/inbox.org`, e.g. via inbox-zero — are allowed from any project session, work included; that is housekeeping on a shared resource, not a durable-fact write. Only the durable-node promotion stays work-denylisted. Do not park roam-inbox tidying as a cross-project boundary crossing (a sentry inbox-zero pass did exactly that on 2026-07-19 — the error this note closes). A write is one node per fact, under `agents/`, roam-valid so Craig's org-roam indexes it: ``` ~/org/roam/agents/YYYYMMDDHHMMSS-.org --- :PROPERTIES: :ID: :END: #+title: #+filetags: :agent:: ``` Pull before writing (`git -C ~/org/roam pull --ff-only`, read-only). Then acquire the roam-write lock, write the node, and trigger roam-sync to commit and push — roam-sync stays the roam repo's only committer (the 2026-06-24 one-git-owner rule). The tree is chronically dirty from live captures, so an agent's own `git add -A && commit` could sweep an in-flight capture into a stray commit; edit-plus-trigger avoids that. Never edit Craig's hand-authored nodes; link to them. This write autonomy is scoped to the KB alone — it is not permission to send email, comment on tickets, or post to any public or external channel. The write block, with the lock and the trigger: ```sh # Acquire the roam-write lock so a concurrent sentry pass or inbox writer can't # race this write. Callers pass a name; agent-lock owns the path (tmpfs). if [ -x .ai/scripts/agent-lock ]; then if ! .ai/scripts/agent-lock acquire roam-write --wait; then # Busy after the bounded wait — surface and stop, don't write unlocked. echo "roam-write lock held by another writer; try again shortly" >&2 exit 1 fi fi # ... write ~/org/roam/agents/-.org ... systemctl --user start roam-sync.service # roam-sync commits + pushes [ -x .ai/scripts/agent-lock ] && .ai/scripts/agent-lock release roam-write ``` Degrade gracefully when `agent-lock` isn't installed (an older checkout mid-sync): the guard above is skipped and the write proceeds unlocked — today's behavior. Only a *present* helper reporting the lock busy after its bounded wait stops the write; an *absent* helper never blocks it. ## What goes in, what stays out **In:** durable facts with cross-project or cross-machine value — decisions and their why, environment and tooling gotchas, reference pointers (URLs, dashboards, key paths), lessons that transfer beyond the project that learned them. **Out:** anything the repo already records (code structure, git history, CLAUDE.md content), session state, task state (todo.org owns that), high-churn facts that will be stale in a month, secrets and credentials, anything work-confidential. ## Capture, then promote Harness memory (`~/.claude/projects//memory/`) remains the per-project capture layer: fast, automatic, allowed to be at-risk. An agent running without harness memory (a non-Claude runtime) captures into its session log instead and promotes from there — the promotion discipline is the same. At wrap-up (or a task audit, or an explicit prompt), promote facts that meet the inclusion bar into the KB as nodes. The wrap-up workflow asks; answer it honestly — promotion discipline is what keeps the capture layer from silting up. ## Inventory `rg '#\+filetags:.*:agent:' ~/org/roam/` lists everything agents ever wrote; the git log is the per-write audit trail. Craig prunes at will — deletion or revert of an `:agent:` node is never something to argue with.