The Agentic Second Brain

A second brain is not a note system. It is a distributed system, and it has to be engineered like one.

---

An agent that writes to your files on a schedule is not a chatbot with file access. It is a distributed system: several writers, shared mutable state, no transactions, and partial failure as the normal case. Treated as a note-taking setup, it produces a convincing demo that quietly rots. Treated as infrastructure, it produces something you can rely on for years.

The difference is not which agent you pick. It is that the data format is the contract, the runtimes are replaceable clients, the rules live in files, and the failures that matter exit zero — so you build something that watches for them.

This guide is the architecture, the code, and the operational practice. Twenty-nine chapters, all written.

Scale

Properties of a running installation, given to set the size of what follows.

The architecture

        AUTONOMOUS                        COLLABORATIVE
        (runs without you)                (runs with you)

  ┌────────────────────────┐        ┌────────────────────────┐
  │ Agent runtime on a VPS │        │ Coding agent, local    │
  │  · scheduled jobs      │        │  · builds capabilities │
  │  · device and API syncs│        │  · refactors the vault │
  │  · health checks       │        │  · edits the rules     │
  │  · chat interface      │        │ Desktop agent with MCP │
  │                        │        │  · reads live systems  │
  └───────────┬────────────┘        └───────────┬────────────┘
              │                                 │
              └───────────────┬─────────────────┘
                              │
                  ┌───────────▼────────────┐
                  │   THE VAULT            │  ← the only contract
                  │   plain Markdown       │
                  │   YAML frontmatter     │
                  │   append-only JSONL    │
                  │   git + file sync      │
                  └───────────┬────────────┘
                              │
                  ┌───────────▼────────────┐
                  │ Obsidian (you, reading)│
                  └────────────────────────┘

No arrow runs from one runtime to the other. Everything meets in the file tree, which is what makes any single runtime replaceable without touching the rest. The remaining diagrams — the capture pipeline, the sensor loop, the watchdog’s position — are in assets/architecture.md.

Three ways to read this

Quickstart

Stage 0: thirty minutes, no server, no scheduler. At the end an agent files your notes for you.

mkdir -p secondbrain/{00_Start/Inbox,05_Wisdom,10_Journal,11_Readings,20_Areas,30_Life,40_Network/People,90_Archive,99_Assets/Templates,memory,skills}
cd secondbrain
git init && git add -A && git commit -m "Empty vault skeleton"

Write two rule files at the root — IDENTITY.md for voice and refusals, SECURITY.md for read-only zones, never-delete and stop-on-ambiguity. Add 99_Assets/Templates/CONVENTIONS.md with the filename and frontmatter contract. Add one skill directory, skills/quick-capture/SKILL.md, that routes prefixed messages. Point your coding agent at the root with a CLAUDE.md telling it to read those files first.

Then:

n: the two-layer split is the thing I keep having to re-explain
t: write the freshness check before adding another integration
p: Jane Doe, head of platform at Acme, met at the meetup

Three messages, three files in the right places with valid frontmatter.

Chapter 05 has the full contents of every file above, and the integrity check to run afterwards.

That is the destination built, and nothing running on a schedule yet. The rest of this section is the autonomous layer.

The full install

An always-on host, an agent runtime, a chat interface reachable from a phone, and scheduled jobs. This is the part that makes the system produce things you did not ask for that morning. Chapter 06 does it properly — hardening first, with the reasoning; below is the shape.

Harden before anything runs. A non-root user, key-only SSH, a closed firewall, unattended security updates. Do not defer this: the window between provisioning and hardening is the one that gets used, and the machine holds a decade of your notes plus a model API key.

Secrets outside the repository, root-owned and mode 0600:

sudo install -m 600 -o root -g root /dev/null /etc/vault-secrets.env
sudo tee /etc/vault-secrets.env > /dev/null <<'EOF'
MODEL_API_KEY=...
CHAT_BOT_TOKEN=...
CHAT_ALLOWED_ID=...
EOF

The runtime, with the vault mounted as its workspace:

services:
  agent:
    image: ghcr.io/openclaw/openclaw:latest
    container_name: agent
    restart: unless-stopped
    env_file:
      - /etc/vault-secrets.env        # never inline secrets in this file
    volumes:
      - /opt/vault:/workspace         # the vault, read-write
      - ./config:/config
    ports:
      - "127.0.0.1:3578:3578"         # loopback only — see below
    healthcheck:
      test: ["CMD", "curl", "-fsS", "http://localhost:3578/health"]
      interval: 60s
      timeout: 5s
      retries: 3

docker compose up -d && docker compose ps

Two details that are not cosmetic:

The 127.0.0.1: prefix on the port. Docker publishes ports by editing the firewall directly, so - "3578:3578" exposes the service to the internet past your ufw rules. Binding to loopback is what keeps it private, and this is the most common way a self-hosted agent ends up reachable by strangers.

An allow-list of exactly your own account ID on the chat bot. A bot with no sender check is an open door to everything in the vault.

Then exactly two scheduled jobs, not six:

0 7  * * * docker exec agent /usr/local/bin/run-skill morning-briefing >> /var/log/agent-cron.log 2>&1
0 21 * * * docker exec agent /usr/local/bin/run-skill evening-weave   >> /var/log/agent-cron.log 2>&1

The evening job writes a completion marker into the day’s note. That marker is what the health checks in chapter 21 assert on, and until something writes it there is nothing to check.

From here the system can fail without telling you. Two jobs and a couple of days of reading the output is manageable by eye; six is not. If you add nothing else, add the watchdog before the third scheduled job — that is the whole argument of Part 5.

Getting the vault onto your laptop and phone without the two copies fighting is chapter 07 — a headless editor on the server as a sync peer, plus the split that keeps the governance files off your devices entirely.

Contents

Prerequisites

What this is not

• Not a hosted product. Nothing here is installed for you.
• Not a plugin. It is a directory layout, a set of rules, and some scripts.
• Not zero-maintenance. You become the operator. Chapter 04 puts numbers on that, and chapter 27 says what is still broken.
• Not a replacement for deciding what matters. It removes friction from capture and retrieval. The thinking stays yours.

Support

If this saved you time, there is a tip jar.

Contributing

Corrections and additions are welcome by issue or pull request. Note that this repository runs a publication check before every commit; if it blocks your change, read the reported rule.

License

MIT. Use it, adapt it, ship your own.

---

Guide v1 is archived unedited under v1/ and tagged v1.0. Its original filenames still resolve.