Brain Template

A practical Markdown-based "brain" for keeping durable context, goals, project knowledge, research, and AI-agent memory separate from application source code.

The agent instructions are designed and tested with Codex. The underlying Markdown structure will likely also work with Claude Code and Gemini CLI, but those agents are currently untested and may interpret the contract differently.

It creates a Git-ready ~/brain repository and keeps application repositories in ~/code. The resulting brain works well with Codex and Obsidian, but the files remain ordinary Markdown and can be used with any editor.

Coming soon

This template will be accompanied by a Duckroll walkthrough and YouTube tutorial. Links will be added here when they are published.

What gets created

~/brain/                  durable knowledge and operational context
├── AGENTS.md             instructions for AI agents
├── HOME.md               starting point for orientation
├── INDEX.md              generated navigation index
├── goals/                outcomes and generated active-goals rollup
├── memory/               provenance-tagged durable facts
├── connections/          technical platform and service integrations
├── research/             reusable reference notes
├── daily/YYYY/MM/        dated activity notes
├── projects/             project knowledge (default personal mode)
└── <organisation>/       optional organisation strategy and projects

~/code/                   separate application/source repositories

Project notes can refer to code with frontmatter such as repo: ~/code/my-project; the two directories are separate Git histories.

Requirements

• Ubuntu or Debian with apt-get
• Internet access
• A user account that can run sudo when not running as root

The bootstrap installs Git, common command-line tools, NVM, the current Node.js LTS, and the Codex CLI. Review the scripts before running them: they modify your system and home directory.

Quick start

Clone this repository, then run the complete bootstrap:

PROJECTS="saas api" ./bootstrap-brain.sh

Or run the pieces separately:

./post-install.sh
PROJECTS="saas api" ./create-brain.sh
BRAIN_DIR="$HOME/brain" ./create-automation.sh

Open a fresh shell after installation, then start Codex from the brain:

cd ~/brain
codex

Optional organisation mode

By default, projects are created directly under projects/. Set ORG_NAME only when you want an organisation layer with strategy, goals, a website area, and projects under <organisation>/projects/:

ORG_NAME=my-company PROJECTS="saas api" ./bootstrap-brain.sh

After bootstrap: GitHub and commit signing

As an early Codex exercise, ask your agent to inspect and run setup-github-auth.sh. It creates or reuses a dedicated GitHub SSH key, configures Git identity and SSH access, and enables SSH commit signing. Read its header for all environment variables and side effects before running it.

For example:

GIT_NAME="Your Name" \
GIT_EMAIL="you@example.com" \
GITHUB_USERNAME="your-github-name" \
REPO_DIR="$HOME/brain" \
GITHUB_REPO_SSH="git@github.com:your-github-name/brain.git" \
./setup-github-auth.sh

The script does not push commits. Uploading a key requires an authenticated GitHub CLI, or you can add the printed public key manually in GitHub settings.

Generated rollups

INDEX.md and goals/ACTIVE.md are generated files. Update the underlying notes, then run:

~/brain/tools/scripts/generate-rollups.sh ~/brain

The index lists durable Markdown notes. The active-goals rollup collects bullets from ## Active sections in project GOALS.md files and notes under goals/areas/.

Optional inbox automation scaffold

Run create-automation.sh to add the minimum folder contract for a durable, file-based inbox worker. It creates the queues and compact failure CSV, but does not install an agent, Discord integration, or background service.

See AUTOMATION.md for the lifecycle, worker contract, and a practical order for implementing triage, execution, clarification, Discord, and systemd timers.

Customisation

Variable	Default	Purpose
BRAIN_DIR	~/brain	Where the brain is created
CODE_DIR	~/code	Where code repositories live
ORG_NAME	unset	Optional organisation area; omit for projects/ at the brain root
PROJECTS	saas api	Space-separated project names
NVM_VERSION	v0.40.6	NVM version installed by post-install.sh

Security

Do not put credentials, tokens, private keys, recovery codes, or .env contents in the brain. See SECURITY.md for reporting guidance.

Obsidian Sync

The brain can be synced from a headless Linux host using Obsidian's official Headless client and a user-level systemd service. See OBSIDIAN-SYNC.md for setup and operational tips.

Licence

Released under the MIT License.