A second brain starts tidy. You pick a method, PARA in our case (Projects, Areas, Resources, Archives: four folders sorted by how actionable a note is, not by topic), and for a few weeks every note lands where it belongs. Then life happens. A project finishes and its folder stays in Projects. A note gets saved at the top of Research because you were in a hurry. A folder gets created with a capital letter and a space in its name. Seven weeks in, our own vault had 38 folders under Projects while the project tracker said we were running 7 projects, 9 loose notes sitting in the vault root, and an Archives folder that was nearly empty because nothing ever moved there.
None of that is a failure of the method. In PARA, live folders hold only live work. It just has no way to enforce it, and a human who is busy enough to need a second brain is too busy to file it every night.
This post explains the vault gardener, secondbrain garden, the part of our open-source Second Brain engine that now does the filing. Its nightly timer went live on our production server on 4 November 2026, Tokyo time. The interesting parts are not the moves themselves but the three things that make an agent safe to let loose on your notes: one small header it obeys, a short list of things it never does, and a ladder of three modes it climbs one rung at a time.
Why a second brain rots
Two forces work against a tidy vault. The first is that finishing is quiet. When a project ends you stop writing in its folder; nobody writes "this is done" anywhere, so the folder looks exactly like a live one. The second is that filing is a tax on capture. If saving a note means deciding where it goes, you save it at the root and promise to sort it later.
We had tried the obvious fix before this: a nightly agent on a local model that looked at the last 24 hours of changes and filed what it could. It ran twice and moved nothing. It had no catalog of what existed, no rules for what "stale" meant, and by design it could not archive or rename anything. The lesson was that the gap was not a missing cron job. It was a missing control surface and missing rules.
What a shelf is
The gardener treats every top-level folder under Projects, Areas and Research as a shelf. A shelf is a folder the gardener has one place to read and write the state of: its README.md, with a small header in frontmatter (the block of key: value lines between --- markers at the top of a markdown file).

The header is seven lines:
---
shelf: Projects/demo
status: active
project: none
kind: project
last_reviewed: 2026-11-03
archive_after: default
pin: false
---Each line has one owner. shelf and last_reviewed belong to the gardener: the path is always rewritten from the real folder, and the date is set on every run that writes. kind comes from the root folder: a shelf under Projects is a project, under Areas an area, under Research a resource. The other four are yours. status is active, dormant or archived. project names the project this shelf belongs to in the engine's tracker, or none; when a folder's name matches a tracker project, the gardener fills it in. archive_after is default, a number of days such as 120d, or never. And pin: true means never archive, never propose, never rename this shelf.
The rule that makes this work is in the docs in one sentence: the owner edits a line; the gardener obeys it on the next run. A hand-set value always wins. The gardener only fills blanks. Any other key you keep in that frontmatter (title, tags, anything) is left in place, and the body of the note is never rewritten, except for one generated block at its end between <!-- shelf:start --> and <!-- shelf:end --> markers: status, project, the design doc, the next action from the folder's dev log, the newest and most-linked notes, and sibling shelves. Hand-written prose above the markers is never touched.

The analogy is a library's card catalog. Every shelf gets a card, the cards are what you edit, and the shelving follows the cards. The analogy stops at one point: in a library the librarian writes the cards; here the gardener writes most of them and you only correct the ones that matter.
What a nightly run reads and decides
A run reads four things. The shelf headers. The git history, specifically the date of the last commit under each folder, which is the gardener's definition of "touched". The project tracker, a table of projects and their stage in the engine's database, so a project that is parked or done can be recognised even if someone edited a file in it yesterday. And the list of files with uncommitted changes, because those belong to whoever is editing them right now.
If the tracker is unreachable the run does not stop; it carries on with no stage for any project, and a missing stage can never cause an archive. That is the general shape of the rules: a missing input leads to less action, not more.

From those inputs the run plans one action per shelf, with the rules checked in order:
- Pinned, or already archived: nothing.
- A project shelf whose tracker project is parked or done, or with no commit in
archive_afterdays, or with no git history at all, becomes an archive candidate, which apply mode will turn into a move toArchives/<quarter>/projects/<name>andstatus: archived. - An area shelf with no tracker project and no commit in the area threshold is proposed in the report, never moved. An area is a standard you maintain (health, finances, a house), so a quiet one is not a dead one. Projects, which end, are archived automatically; areas are only ever proposed. That split is the PARA-correct one, and it is the single decision in this design most likely to be wrong for someone else's vault, which is why both thresholds are settings.
- A research shelf is never archived by age. Reference material does not expire because you stopped reading it.
- A folder whose name is not lowercase kebab-case is renamed (
Models Researchbecomesmodels-research), at most 5 a night.
Notes sitting loose directly in a root folder, such as Research/x.md, are not moved at all yet. They are listed in the report under "Needs a human", along with anything over a cap. The vault root itself is yours and is not scanned. Routing loose notes with a model is a later step; for now a human files them.
The planning step is written as pure functions: a list of shelves in, a list of actions out, with the dates and the tracker stages passed in as functions. That is what lets the rules be tested without git or a database. The engine's test suite covers 32 cases across seven files, with names like "parked project archives even if touched", "area is proposed not moved" and "refuses when a file under the source is dirty".
What it writes, and what it never touches
Writing is where an organising agent earns or loses trust, so it is worth being exact.
The report is always written: a markdown file named by date with five sections, Would archive, Proposed (areas), Would rename, Needs a human, and Skipped: uncommitted changes. In write mode it also writes the shelf headers (creating a README.md where a shelf has none), the generated block, and the catalog, a file with one row per shelf. In apply mode it also moves and renames.
Every move is a git mv, never a plain filesystem move and never a delete, so one night's changes are one revertable commit. A move is refused, not forced, when its target already exists, when its source is gone, or when any file under it has uncommitted changes. The shelf note and the catalog are skipped when they themselves are uncommitted. After a move, links in every other note that carry the old folder's path (wikilinks with the full path, markdown link targets, and the same path in backticks) are rewritten; a wikilink that names only the note's file name resolves by that name and keeps working, so it is left alone. At most 25 archive moves run in one night; the rest wait. Nothing under hidden folders (names starting with a dot), nested git repositories or node_modules is ever a shelf.
One more thing the gardener never does: commit. It changes files and stops. Your vault's sync timer, or you, commit what it changed, so the report is sitting there to read before anything is permanent, and a bad night in apply mode is a single git revert.
Shadow, write, apply
The three modes are the part of the design we would reuse for any agent that changes files you care about. They are a ladder, and each rung adds exactly one kind of write.

- Shadow (
secondbrain garden) reads everything, plans the whole night, and writes only the report. Nothing else on disk changes. You read what it would have done. - Write (
secondbrain garden --write) adds the shelf headers, the generated block and the catalog. Still no moves and no renames. The vault gains its catalog; nothing is relocated. - Apply (
secondbrain garden --apply, or"garden": { "apply": true }in the settings file) adds the moves and renames, with the caps and refusals above.
The plan is identical on every rung. The only difference is how much of it is allowed to happen, which means seven nights of shadow or write reports show you exactly what the first apply night will do, with the same code that will do it. The engine's docs put the advice plainly: set apply to true once a week of reports looks right, and the same timer starts moving files.
On a server, the engine's deploy script installs a systemd timer when the garden module is enabled. It runs write mode at 04:30 Tokyo time, with a random delay of up to two minutes, before the morning routines that read the vault.

What the first production run looked like
The gardener was built and run on a Mac checkout of our vault on 3 November 2026. That first write run gave 105 shelves their header (94 README files created, 21 existing ones kept their prose and gained the header and the block), produced the catalog, and reported 1 archive candidate, 10 area proposals, 5 renames and 14 items for a human (8 renames over the nightly cap and 6 loose notes at the top of Research). A second write run straight after changed nothing, which is the test that the output is stable.
Two things were wrong on the first pass and are worth knowing if you run this on your own vault. Our vault's git history is under two months old, so no folder could be 90 days stale by commit date and the engine's default thresholds found nothing; our settings use 45 days for both thresholds for now, while the engine defaults stay at 90 days for projects and 180 for areas. And the shelf header originally baked archive_after: 90d into every project shelf, which silently overrode those settings; it now writes default, which means "use the settings at plan time".
The pull request merged on 3 November. Hours later, on 4 November Tokyo time, the module was enabled on the server and the gardener was run by hand in shadow mode exactly as the timer would run it: same user, same environment file. It exited cleanly with 111 shelves, 1 archive candidate, 0 area proposals, 5 renames and 17 items for a human, and moved nothing. The vault had grown by six shelves since the Mac run the day before.

The drop from 10 proposals to 0 is the kind of thing shadow mode exists to surface. The most likely cause is that the Mac's write run committed a header into every shelf's README, and the age rule reads the last commit date under the folder, so every shelf looked touched yesterday. That is our inference, not a confirmed finding. If it holds, the gardener's own writes reset the clock it measures with, and the fix is to measure age by commits that are not its own.
What's built and what's next
Built and running: the garden module in the engine, merged on 3 November 2026 as pull request 104 (28 files, 1,359 lines added), with shadow, write and apply modes, the shelf header, the generated block, the catalog, the report, the caps and refusals, link rewriting on moves, and the nightly timer. Our server has run it in shadow mode once, and its timer is set to run write mode every night from 4 November.

Not yet on: apply mode. garden.apply is false in our settings until a week of nightly reports reads right. The first apply night, from the current reports, would move one project folder and rename five.
Known open items: the report file is named by the UTC date and the timer fires at 19:30 UTC, so every nightly report carries the previous day's date, and the first nightly run overwrites the report from the hand run on 3 November. That wants a small engine change to name reports by the timer's local date. The proposals question above is the second. And still a plan rather than code: routing loose research notes into shelves with a local model, approving a proposal with one word from a chat message, and the same nightly check applied to the kanban board and the tracker.
To try it on your own vault, enable the module and run it in shadow mode first:
secondbrain gardenThen read the report, pin what the rules got wrong, and climb one rung.
The engine is open source at https://github.com/kon-rad/argo, with the gardener documented in docs/garden.md. Follow the build on this blog or at https://x.com/myargoquest.