Skip to main content

Agent instructions — machine brain

Agent instructions — machine brain

This repo is Conor's long-term memory: journals, system facts, settings and reference notes.

The canonical copy now lives in BookStack, at https://pdb.seabee.me/shelves/ai-brain (shelf ai-brain, book AI Brain, book id 22). Read and write there through the API — see the bookstack skill. That is deliberate: several bots share this brain, and the wiki gives them one live copy with per-page revisions instead of N stale checkouts.

This repo is now a snapshot, useful for rg, for git history, and for re-importing. ~/.hermes/scripts/brain-to-bookstack.py pushes files from here into the book idempotently (matching on a brain-path tag), so a fresh clone can be re-imported without duplicating pages.

Read order

  1. BookStack book AI Brain — the live copy. GET /api/pages?… then the page body; search by name or the brain-path tag.
  2. index.md / llms.txt here — the same map, if you are already on disk.
  3. rg -n "<term>" for anything not in the wiki yet.

Rules for editing

  • BookStack is the source of truth from 2026-11-06. Write new brain content as pages in the AI Brain book. Do not create a note here and only here — the file would be invisible to every other bot.

  • Keep this repo as a snapshot of the wiki, not a second canonical copy. When a note changes in the wiki, re-run brain-to-bookstack.py --dry-run to see the drift, or edit the file here and push it up. Never leave the only copy of a new note in a web app that has no file, and never leave it only on disk.

  • Do not duplicate project repos. 30-projects/<name>.md is a hub note; code and long-form project docs stay in their own repos. Link to them.

  • One topic per note, named for the topic, with YAML frontmatter:

    ---
title: Short title
updated: 2026-11-05
tags: [systems, mail]
---

  • Record decisions, not just outcomes. Append to 10-journal/decisions.md with the date, the choice, the alternatives rejected and why.

  • Journal entries are append-only. Add a new entry at the top of 10-journal/ops-journal.md; do not rewrite history.

  • Cite the evidence. Exact paths, commands, hostnames, IPs, URLs and dates. "It was fixed" is not an entry.

  • Keep secrets out. Reference Passwords.kdbx, .env files and tokens by location; never paste credentials or keys into a note.

  • Commit your change with a short message (journal: ..., systems: ...).

What belongs here

  • Ops incidents, root causes and preventions.
  • Machine/service facts that are expensive to rediscover.
  • Account/domain/subdomain maps, ports, paths.
  • Personal reference: health notes, photography settings, vendor contacts.
  • Project hub notes and open questions.

What does not

  • Credentials, private keys, API tokens.
  • Large binaries (PDFs, photos, model files). Link to them instead.
  • Generated artefacts, node_modules, logs.
Back to top