Documentation

Everything needed to run secondbrain and to understand what the agent on the other end is allowed to do. For reverse proxies and backups see the deployment guide; the German specification in spezifikation.md is authoritative where this page and it disagree.

Quick start

mkdir -p ./data && sudo chown -R 65532:65532 ./data

docker run -d --name secondbrain -p 2020:2020 \
  -v "$PWD/data:/data" \
  -e SECONDBRAIN_PUBLIC_URL=https://brain.example.com \
  -e SECONDBRAIN_USERNAME=andreas \
  -e SECONDBRAIN_PASSWORD='bcrypt:$2a$12$...' \
  --user 65532:65532 --cap-drop ALL \
  ghcr.io/andreaskasper/secondbrain:latest

Or with Compose:

services:
  secondbrain:
    image: ghcr.io/andreaskasper/secondbrain:latest
    ports: ["2020:2020"]
    volumes:
      - ./data:/data
    environment:
      SECONDBRAIN_PUBLIC_URL: https://brain.example.com
      SECONDBRAIN_USERNAME: andreas
      SECONDBRAIN_PASSWORD: "bcrypt:$2a$12$..."
    user: "65532:65532"
    cap_drop: [ALL]
    security_opt: ["no-new-privileges:true"]
    restart: unless-stopped

Then point an MCP client at https://brain.example.com/mcp. The client discovers the OAuth endpoints, registers itself and opens the login page in a browser.

Building from source instead:

git clone https://github.com/andreaskasper/secondbrain
cd secondbrain/src
CGO_ENABLED=0 go build -o secondbrain .
SECONDBRAIN_DATA=../data \
SECONDBRAIN_PUBLIC_URL=http://localhost:2020 \
SECONDBRAIN_USERNAME=andreas SECONDBRAIN_PASSWORD=secret ./secondbrain

Go 1.25, no framework, CGO_ENABLED=0. SQLite is modernc.org/sqlite, a pure-Go implementation, so the binary is static and the image is distroless.

Environment

Environment first. A single user with a single vault needs three variables and nothing else. A config file is only necessary when there is more than one user — and if a config file defines users, it wins outright and the two username variables are ignored.

Password prefixes

The same four forms are accepted everywhere a password appears, in the environment and in the config file.

config.yaml

The config file exists for one reason: more than one user. Each user carries the vaults it may open and whether it may write, so the question that matters — what exactly can this login reach? — is answered by reading one contiguous block.

# Every setting is top level. There is no server: block - the file mirrors
# the environment variables one for one, minus the SECONDBRAIN_ prefix.
listen: ":2020"
public_url: "https://brain.example.com"   # required
data_dir: "/data"
default_vault: "personal"
max_response_bytes: 262144
token_ttl: "12h"
trash_retention: "720h"
login_rate_limit: "10/m"
git: true
metrics: false
metrics_path: "/metrics"
metrics_key: "file:/run/secrets/metrics_key"   # at least 16 characters
metrics_listen: ":9090"                        # a port you do not publish

users:
  # Full access to every vault on the server.
  - name: andreas
    password: "bcrypt:$2a$12$..."
    vaults: []            # empty means all
    read_only: false

  # A second agent that may read everything but change nothing.
  - name: reviewer
    password: "env:REVIEWER_PASSWORD"
    vaults: []
    read_only: true

  # A work assistant that never sees the private vault.
  - name: work
    password: "file:/run/secrets/work_password"
    vaults: [work]
    read_only: false

Three properties of that file are worth stating explicitly.

• vaults: [] means every vault, including vaults created later. Naming vaults explicitly is the safer habit, because a vault created next month is then not automatically reachable by an old login.
• A read-only user is not offered the mutating tools at all. They are absent from tools/list, not refused on call. A model cannot be talked into using a tool it was never shown.
• The file wins. If it defines users, SECONDBRAIN_USERNAME and SECONDBRAIN_PASSWORD are ignored rather than merged, so there is never a second, forgotten login.

Validate before restarting anything:

docker run --rm -v "$PWD/config.yaml:/etc/secondbrain/config.yaml:ro" \
  ghcr.io/andreaskasper/secondbrain validate /etc/secondbrain/config.yaml

CLI

The binary is the server. The subcommands are the few things you need to do around it.

Metrics

A Prometheus endpoint, off by default. A knowledge base is not a public service, and an endpoint that reports how many notes somebody has and when they last wrote one is not something to expose unasked. SECONDBRAIN_METRICS=true turns it on, and secondbrain validate prints the resulting state — the path, the address it is served on, and whether anything is guarding it.

There is no Prometheus client library behind it. The exposition format is a dozen lines of text, and pulling in a dependency tree to produce it is a poor trade in a container that holds somebody's private notes, so the registry is hand-rolled like the rest of the server.

SECONDBRAIN_METRICS=true
SECONDBRAIN_METRICS_LISTEN=:9090
SECONDBRAIN_METRICS_KEY=file:/run/secrets/metrics_key

Keeping it private

Two mechanisms, independent of one another, and they compose.

• A shared key. SECONDBRAIN_METRICS_KEY, presented by the scraper as Authorization: Bearer <key> or as X-API-Key, compared in constant time. It takes the same env: and file: prefixes as a password, and it is refused below sixteen characters.
• A separate listener. SECONDBRAIN_METRICS_LISTEN=":9090" serves the endpoint, and a second /healthz beside it, on an address of its own. This is the stronger of the two: a port bound inside the Docker network and never mapped cannot be reached from outside whatever the key is, whereas a key is only ever as good as the file it sits in on the scraping host.

With metrics on and neither of them set, the server logs metrics_unprotected once at startup, naming the path and hinting at both fixes. It does not refuse to start — on loopback an open endpoint is reasonable — but the line is there so that an accident is visible in the log rather than only on the network.

The endpoint has its own rate limit bucket, sixty requests a minute per source IP. It is deliberately not the login bucket: a scraper with the wrong key can then neither be used as a timing oracle nor exhaust the budget that protects the login page.

What is exposed

Everything below is a count or a gauge over something the server already knows. No metric carries a note path, a title, a tag or a line of content, and the route label on secondbrain_http_requests_total is drawn from a fixed list of known routes rather than from r.URL.Path, so a caller cannot mint labels by requesting invented URLs. The low cardinality is a privacy property and also the difference between a time series database that works and one that falls over.

Gauges

Counters

The vault gauges come from the search index rather than from the files, so a scrape is a handful of counting queries against SQLite and not a walk of the filesystem. Scraping every fifteen seconds costs nothing worth measuring.

What to actually watch

The vault gauges are the operationally interesting ones, because they describe the health of the knowledge base rather than the health of the process. secondbrain_vault_broken_links and secondbrain_vault_orphans climbing steadily over weeks is a knowledge base decaying — notes being written that nothing points at, links left behind by renames — and that is invisible from inside any single note. secondbrain_vault_notes flat while secondbrain_writes_total climbs means an agent is editing but never creating, which is usually a conventions problem in instructions.md rather than a fault. secondbrain_truncated_results_total rising means max_response_bytes is too small for the way the vault is being queried, and the agent is working from clipped results. On the process side, secondbrain_git_failures_total above zero means the off-site copy has quietly stopped happening, and secondbrain_logins_total{outcome="failed"} is the series to alert on.

The Prometheus side of it — publishing the port only inside the Compose network, generating the key and the scrape config that reads it — is in the deployment guide.

Storage

One directory per vault under the data root. A vault name must match ^[a-z0-9][a-z0-9_-]{0,63}$, which keeps it a valid directory name on every filesystem and a valid path segment in a tool argument.

/data/
  personal/
    inbox/
    wiki/
      postgres.md
    journal/2026/2026-07-30.md
    attachments/
    .secondbrain/
      index.db            # SQLite + FTS5, a cache
      trash/              # timestamped copies, purged after retention
      instructions.md     # sent to the client on initialize
    .git/                 # one repository per vault
  work/
    ...

Everything in .secondbrain/ is disposable. Delete the directory and the next start rebuilds the index from the files; you lose the trash and the vault instructions, and nothing else. That is the whole point: the notes are the product.

Path safety

Path handling is structural rather than a blacklist. After cleaning, a path must satisfy three conditions:

• it is relative, not absolute;
• it stays inside the vault after resolution, so no .. can climb out;
• no component begins with a dot.

The third rule is doing more work than it looks. It makes .git, .obsidian and .secondbrain unreachable through every tool, present and future, without anyone having to remember to add them to a list. A rule that cannot be forgotten is worth more than a list that can.

Writes

Every write goes to a temporary file in the same directory and is then renamed over the target. A crash mid-write leaves either the old file or the new one, never half of either. The rename is followed by the git commit, so history and disk agree.

Vault layouts

vault_create takes a layout, creates the directories and writes .secondbrain/instructions.md describing them. Those instructions are handed to the client in the MCP initialize response, which is how a vault teaches an agent its own conventions without anything living in a system prompt somewhere else.

Every layout uses the same journal convention: journal/YYYY/YYYY-MM-DD.md. daily_note and daily_range depend on it, so it is the one path shape that is not yours to change.

Notes and links

A note is a Markdown file with optional YAML frontmatter. The dialect is Obsidian's, because that is the editor most likely to be open on the same directory.

---
title: PostgreSQL
tags: [database, ops]
aliases: [postgres, pg]
created: 2026-03-11
updated: 2026-07-30
---

# PostgreSQL

Notes on running it, not on using it. See [[Connection pooling]] and
[[wiki/backups#postgres|the backup section]].

## Connection pooling

Pool size is per process, not per host. #ops

- [ ] measure the real ceiling on the reporting box
- [x] move pgbouncer to transaction mode

That last rule is deliberate and occasionally surprising. If you keep a plain file with no frontmatter, this server will not quietly add three lines of YAML to the top of it the first time an agent appends a sentence. Files you wrote by hand keep looking like files you wrote by hand.

Search

Full-text search is SQLite FTS5 in <vault>/.secondbrain/index.db, ranked with BM25 and returned with a snippet per hit. The index is reconciled against the filesystem at startup and then kept current by an fsnotify watcher with a 400 ms debounce.

That combination is what makes external editing normal rather than dangerous. Obsidian saving a file, a git pull, an rsync from a laptop — each is just a file event, and the index catches up within half a second. Nothing owns the directory.

FTS5 tokenises words, which means it cannot find a URL, a code fragment, a partial identifier or a piece of punctuation. That is what vault_grep is for: a regular expression over the raw text of every note, slower and unranked, correct when note_search is the wrong shape of tool.

Authentication

OAuth 2.1 with dynamic client registration and PKCE (S256), the same implementation as aegis. The client discovers everything it needs from the two well-known documents and registers itself; you type a password into an HTML login page served by the container, and nothing else is configured on either side.

Clients, codes and tokens live in memory only. Restarting the container invalidates every session, which is a real cost and an accepted one: a process that holds credentials to a private knowledge base and writes none of them to disk leaves nothing behind for anyone who later gets the volume.

Hashes and dry runs

Four conventions run through every mutating tool. They are the reason this project has more tools than a naive read-and-write server would need.

content_hash

note_read returns a content_hash alongside the content. note_write — the only tool that replaces a whole note — requires it. If the file changed since you read it, the write is refused with the current hash rather than applied. Every other mutating tool accepts content_hash optionally, and passing it turns a hopeful edit into a checked one.

This matters more here than in a code repository. Another agent, Obsidian on a phone, or a git pull can all have touched the note between the read and the write, and the failure would be a silent revert of somebody else's paragraph.

-> note_write
{ "path": "wiki/postgres.md",
  "content": "...",
  "content_hash": "sha256:9f2c..." }

<- error
{ "error": "stale_content_hash",
  "message": "wiki/postgres.md changed since it was read",
  "content_hash": "sha256:41ab..." }

dry_run

Every mutating tool takes dry_run. With it set, nothing is written and the tool returns the unified diff it would have applied. Two tools default it to true, because their blast radius is a whole vault rather than a note: vault_replace and tag_rename. Getting a diff back when you expected a write is the intended experience there.

Trash

Nothing is ever removed. Deletions and overwrites put a timestamped copy in <vault>/.secondbrain/trash/, purged after SECONDBRAIN_TRASH_RETENTION. This is independent of git, and deliberately so: git protects committed history, the trash protects the thirty seconds before somebody notices.

Git

With versioning on, every write is a commit whose message names the tool and the path — note_section_edit: wiki/postgres.md. That gives three tools their material (note_history, note_diff, note_restore) and gives you an answer to "what did the agent actually change last Tuesday" that does not depend on this software at all.

The audit line

One structured line per tool call on stdout: user, vault, tool, path, bytes, duration. Never note content, at any log level, including debug. An audit log of a private knowledge base that quotes the knowledge base is a second copy of it with worse access control.

Section edits

note_section_edit is the tool an agent should reach for most often. It changes a note relative to one of its headings, so a long note can be added to without being read and rewritten — which removes both the token cost and the opportunity to lose a paragraph on the way back.

A section runs from its heading to the next heading of the same or higher level, subsections included. Under ## Connection pooling, a following ### Pool size is part of the section; the next ## Backups ends it.

With create: true a missing heading is added rather than reported, at the end of the note. Without it, editing a section that does not exist is an error — which is usually the more useful answer, because it means the agent's model of the note is out of date.

{
  "path": "wiki/postgres.md",
  "mode": "append_to_section",
  "heading": "Connection pooling",
  "content": "PgBouncer in transaction mode; session mode\nholds a backend per client and defeats the point.",
  "create": true,
  "content_hash": "sha256:9f2c...",
  "dry_run": false
}

All 34 tools

The full surface, grouped the way the server groups it. Arguments marked * are required; everything else has a default. A read-only user is offered only the tools marked read — the writing tools are absent from tools/list entirely.

Every tool except vault_list and vault_create takes an optional vault string in addition to the arguments listed below. It is added to each schema by the server rather than declared per tool, which is why it is documented here once. Omitting it uses SECONDBRAIN_DEFAULT_VAULT.

Discovery

{
  "query": "\"connection pool\" OR pgbouncer",
  "tags": ["ops"],
  "prefix": "wiki/",
  "modified_after": "2026-01-01",
  "limit": 10
}

Reading

-> { "path": "wiki/postgres.md", "heading": "Connection pooling" }

<- {
  "path": "wiki/postgres.md",
  "content": "## Connection pooling\n\nPool size is per process...",
  "content_hash": "sha256:9f2c...",
  "frontmatter": { "title": "PostgreSQL", "tags": ["database","ops"] }
}

Writing

{
  "path": "wiki/postgres.md",
  "old_string": "Pool size is per process, not per host.",
  "new_string": "Pool size is per process, not per host, and pgbouncer\ncounts as one process per pool.",
  "dry_run": true
}

{
  "path": "wiki/postgres.md",
  "set": { "status": "reviewed" },
  "add_tags": ["ops", "database"],
  "remove_tags": ["todo"],
  "add_aliases": ["pg"]
}

Capture

{
  "date": "2026-07-30",
  "heading": "Log",
  "append": "- 14:20 upgraded the reporting box to PG 17"
}

Curation

Tasks

Refactoring and attachments

-> { "pattern": "old-domain\\.example",
     "replace": "example.com",
     "regex": true,
     "prefix": "wiki/" }

<- { "dry_run": true, "notes": 23, "diff": "--- wiki/dns.md\n+++ ..." }

History

-> note_history { "path": "wiki/postgres.md", "limit": 3 }
<- [ { "revision": "8c41af2", "tool": "note_write",        "ts": "2026-07-30T14:02:11Z" },
     { "revision": "1d9e07b", "tool": "note_section_edit", "ts": "2026-07-28T09:41:55Z" } ]

-> note_diff    { "path": "wiki/postgres.md", "from": "1d9e07b" }
-> note_restore { "path": "wiki/postgres.md", "revision": "1d9e07b", "dry_run": true }