---
title: "Inside the Argo engine rebuild: one manifest per feature, addons off by default, one memory"
description: "How the Argo engine was rebuilt around feature manifests: a base, six core features, opt-in addons, generated config and units, and one memory store."
date: 2026-11-14
reading_time: "13 min read"
url: https://myargoquest.com/blog/engine-core-v2-architecture
markdown: https://myargoquest.com/blog/engine-core-v2-architecture.md
publisher: Argo (myargoquest.com)
---

# Inside the Argo engine rebuild: one manifest per feature, addons off by default, one memory

Last week's post, [From an empty folder to a company of agents](https://myargoquest.com/blog/engine-v2-onboarding), walked through the new on-ramp: the installer, `init`, and a skill that sets up a vault for you. This post is about what sits underneath that on-ramp: how the engine itself was rebuilt, one feature at a time, and why each piece is shaped the way it is.

The engine is the open-source app that indexes your markdown, runs the board and the project tracker, and hosts the agents that work in your notes. It grew fast. Each new feature arrived as a new surface: a route here, a page there, a timer file, a launcher subcommand, a paragraph in four separate docs. Nothing was ever removed. By early November the design notes counted 15 modules with five different lists of them in the docs, 26 command-line entry points, and 17 services plus 15 timers checked in by hand.

None of that was a missing feature. The cost was that adding one thing meant editing six places that all had to agree, and they drifted. The rebuild, which we called core v2, set out to give every feature exactly one place where it is wired, and to make everything else read from that place. A follow-up round, which we call r2, then started cutting what core v2 had exposed.

## What are the layers now?

The engine now has three layers, stacked on top of your vault.

![Three stacked layers: seventeen addons off until listed, six core features on in every vault, and a base of vault index, search, editor, auth and the doctor, all over a markdown vault](https://myargoquest.com/blog/engine-core-v2-architecture-1.jpg)
*The engine after the rebuild: a base, six core features, and seventeen addons that stay off until secondbrain.json lists them*

- **Base:** what every vault needs to be a vault at all. The index over your markdown, keyword and vector search, the editor, login, and the health checks.
- **Core features:** six features that ship on in every vault. They are `projects` (the tracker), `memory`, `org` (your roster of agents), `board` (the kanban board), `usage` (what each run cost) and `summaries` (a short summary per finished agent session).
- **Addons:** optional features, seventeen of them, from the map and voice to social metrics and the dispatcher that wakes agents. Every addon is off until your `secondbrain.json` names it.

The line between core and addon was a decision, made before any code moved. The first plan had five core features; usage was added as the sixth when the plan was reviewed, and the dispatcher was confirmed as an addon because it is still a pilot.

## What is a manifest?

A manifest is a small file, one per feature, that describes the feature as plain data: its name, whether it is core, its links in the navigation, its commands, its scheduled jobs, the tables it needs, the settings it reads, and where its docs live. Think of it as the label on a moving box. Whoever handles the box reads the label; nobody has to open the box to know where it goes.

The engine's own source says it in one sentence, at the top of the type that every manifest uses.

![The features/types.ts file on GitHub with the comment that says a feature manifest is the one place a feature is wired highlighted](https://myargoquest.com/blog/engine-core-v2-architecture-2.jpg)
*The rule in the code itself: a manifest is the one place a feature is wired (github.com/kon-rad/argo)*

The manifest is deliberately pure data. It imports no server code, so a command-line tool or a deploy step can read every manifest without starting the app or connecting to a database. Here is the board's, trimmed:

```
export default defineFeature({
  name: 'board',
  core: true,
  nav: [{ section: 'Work', label: 'Board', path: '/board' }],
  cli: [{ command: 'board', entry: 'cli-board.js', summary: 'the kanban board' } /* and review */],
  timers: [{ unit: 'secondbrain-board-reclaim', calendar: '*:0/5', command: 'board reclaim' }],
  wrappers: ['cli-board'],
  health: { label: 'the board tables answer', tables: ['boards', 'cards', 'card_comments', 'card_events', 'card_deps', 'card_runs'] },
  docs: 'docs/kanban-board.md',
});
```

Six different parts of the system read that one object.

![The board manifest in the middle with arrows to six readers: app.ts mounts routes, the meta API serves nav, the launcher dispatches commands, plan and apply generate systemd units, PATH wrappers, and doctor checks tables](https://myargoquest.com/blog/engine-core-v2-architecture-3.jpg)
*One manifest, six readers. Before the rebuild the same facts lived in app.ts, App.tsx, deploy.sh, the launcher, env.example and four docs*

- **The server** mounts the feature's routes from it.
- **The web app** asks the server for its menu, and the server builds that menu from the manifests of the features that are on.
- **The launcher**, the one `secondbrain` command, looks up any word it does not know in the manifests' command lists, so `secondbrain board` and `secondbrain memory` need no special code in the launcher.
- **The config generator** turns each timer into a systemd service and timer pair. systemd is the Linux service manager that runs jobs on a schedule.
- **The wrapper step** writes the small `cli-board`-style scripts that put each command on the machine's path.
- **The doctor**, a command that checks an installation is healthy, confirms that every table a feature names exists, so a feature whose database migration never ran fails loudly in `secondbrain doctor` and `/api/health` instead of erroring on its first request.

The manifests were built first, before any other phase, because every later piece reads them. That ordering is the main reason the rest of the rebuild went quickly.

## How do addons stay out of the way?

A registry file lists the six core manifests and then every addon manifest, as one combined list. Every reader filters that list by what your vault has turned on. A fresh vault therefore sees only the six core features: no addon routes are mounted, no addon timers are installed, and no addon links appear in the menu. Turning on two addons is one line in `secondbrain.json`:

```
{ "addons": ["map", "social"] }
```

Moving the addons behind their manifests deleted twelve hand-written "is this module on?" blocks from the server's startup file, and the web app's hard-coded menu went with them.

Round 2 pushed the boundary further. The largest addon was an event app built for a conference, with its own contracts, wallet code and eleven test configurations, and it was the only addon the base startup knew by name. It now lives in its own self-contained package. Addons gained optional `boot` and `close` hooks, so the engine loads that package only when the addon is on, and its web page is loaded only when someone opens it. A vault that never turns it on builds and starts without any of its dependencies. Paths under the app that mention it went from 71 to 6.

## How does one settings file become a running server?

Before the rebuild, a server's configuration was spread over an environment file, a settings file, hand-written unit files and a deploy script that decided which units to install with its own list of module checks. Now there is one path.

![A left to right flow: secondbrain.json with its server and addons blocks, one settings loader that validates each section, secondbrain plan which writes nothing, and secondbrain apply which writes the env file and units, with doctor and the health endpoint below](https://myargoquest.com/blog/engine-core-v2-architecture-4.jpg)
*Config flow: one settings file, one loader, plan shows the change, apply writes it, doctor checks it*

- **`secondbrain.json`** gained a `server` block: the host, the system user, the install and vault folders, and the backup settings.
- **One loader** reads that file. Round 2 found three different readers of it, and one bad field anywhere silently reset every setting to its defaults. Now there is a single loader, and each section is checked on its own: a broken `social` block falls back to its own defaults, the doctor names the bad field, and the rest of your settings load normally.
- **`secondbrain plan`** reads the enabled manifests, renders the environment file and every unit, compares them with what is on disk, and writes nothing.
- **`secondbrain apply`** writes them. `secondbrain upgrade` does the same but is a dry run unless you pass `--yes`.

The analogy is a building plan and a builder. `plan` is the drawing with the changes marked; `apply` is the builder doing exactly what the drawing shows. Read the plan before you apply it.

Round 2 then made the manifests the only source of scheduled jobs. Every feature and addon timer moved into its owning manifest, the three jobs that belong to no feature (the database backup, the vault sync and the embedding run) are declared once in the generator, and the deploy script calls `apply` instead of copying files. Seventeen hand-written timer files were deleted. The move also surfaced real drift: one usage sync timer ran every minute while its manifest said every five minutes. The generated version follows the manifest.

The doctor closes the loop. `secondbrain doctor` and the `/api/health` endpoint run the same checks: the database answers, the vector extension is installed, no migrations are pending, every enabled feature's tables exist, and the settings file passes its schema. Against an empty database during testing it reported three errors (the vector extension missing, migrations pending, the board's tables absent) and exited non-zero, which is the point: it fails before a user does.

## Why did memory get rebuilt?

Memory was the one core feature that was not shaped like a feature. Agents had a store of their own per-agent notes, a generated prose file per agent that was injected when it woke up, a separate reflect model call that fed it, and, alongside all of it, a shared table of facts with no record of which agent a fact belonged to. Recall and remember were verbs hidden inside the org command.

![Before and after panels: on the left a per-agent memory table, a core.md file per bot, a reflect step, untagged facts and recall inside the org CLI; on the right one fact table tagged by agent, the episodes table, vault markdown, and the secondbrain memory command](https://myargoquest.com/blog/engine-core-v2-architecture-5.jpg)
*Memory before and after: the persona store was exported into memory_facts, then dropped, in one migration*

Now memory is one core feature with one store. Each fact is a single claim with a source, tagged with the agent it belongs to. A second table keeps one row per finished agent run, and the vault's own markdown stays searchable through recall. When an agent wakes, it gets the facts tagged with its own name instead of a prose file. Everything is reachable from one command, `secondbrain memory recall|remember|list|retire|stats`, and from a `/memory` page that lists facts, pending candidates and a retire button.

The risky part was deleting the old store without losing what agents had learned. The answer was a single migration: it copies every old row into the fact table, tagged with its agent, and drops the old table in the same transaction. If the copy fails, nothing is dropped. The module that held the old store went from 899 lines to 129.

## Where does a feature's code live now?

Manifests fixed where a feature is wired, but not where its code lives. A review after core v2 found that one feature could still be spread over up to five places, and that the browser kept a single 1,476-line file retyping every server response by hand.

Round 2 has started on both, one slice at a time. For the board and the tracker, the router, the domain logic and the command now live in the feature's own folder beside its manifest. The old file paths remain as two-line forwarding stubs for one release, so nothing that imports them breaks.

On the browser side, search, the board and the tracker now each have their own small client, and their request and response shapes are defined once, as shared schemas that both the server and the browser compile against. For those three, a changed response shape now shows up as a type error in the build rather than a broken page. Writing those shared schemas found fields the server already returned that the browser's hand-written types had never listed. The shared browser file is down from 1,476 lines to 1,173.

## How fast did it go, and how was it checked?

Core v2 merged in three days, November 3 to 5, as a series of small pull requests, one or a few per phase. Round 2's first five items merged between November 12 and 14.

![A dot chart of merge dates: core v2 phases 0 to 7 and the fallback model merged between November 3 and 5, and five round 2 items merged between November 12 and 14](https://myargoquest.com/blog/engine-core-v2-architecture-6.jpg)
*Merge dates of every pull request in both rounds, November 2026 (UTC)*

Two pieces from those days are worth naming. The org compiler, which turns your roster files into the agent definitions each tool reads, was ported from Python to TypeScript so the engine needs no Python for it. It was checked against a real 34-agent roster, and its output matched the old compiler's exactly. And the dispatcher gained a fallback model: if an agent's model runs on a computer at home and that computer stops answering, the dispatcher runs the agent on a configured backup model instead, and retries a run once if it died on a provider error.

The build logs record a full test-suite count for each phase from 0 through the org compiler, from runs on the branch or on merged main.

![Left, a line of passing tests rising from 1,311 to 1,381 across the phases, then 1,367 after the persona tests were removed; right, before and after bars for settings readers, env reads, timer files, browser api.ts lines and event app paths](https://myargoquest.com/blog/engine-core-v2-architecture-7.jpg)
*Tests passing per phase from the build logs (branch or merged-main runs); the final dip is 14 tests deleted with the old memory store. Right: what round 2 removed*

The count rose from 1,311 passing tests at phase 0 to 1,381 after the org compiler, then dropped to 1,367 on purpose: the old memory store's 14 tests were deleted together with the store they tested. Nothing that remained failed. On the right are the round 2 measurements each pull request recorded: settings readers from three to one, direct environment reads outside the config schema from 62 to 10 (the remaining ten are deliberate and documented), hand-written timer files from 17 to none.

## What's built and what's next

Built and merged: all eight core v2 phases and the dispatcher fallback, plus five of the ten round 2 items, all described above.

Still a plan, stated plainly:

- **Feature folders and shared browser schemas are first slices.** Only the board and the tracker have moved into their folders, and only search, the board and the tracker have shared schemas. The org feature, the largest, is next.
- **Round 2 items 6 to 10 have not started:** one guard (the program that checks each agent action before it runs) instead of two copies that can drift apart, one Search page, a feature page that shows its cards, one test layout with a fast lane that needs no database, and docs generated from the manifests.
- **The fallback model has not been exercised in a live outage.** Today it is covered by tests and configuration only.
- **The fifteen-minute fresh install is a target,** not a measured time on a clean machine, and the onboarding docs have not yet shrunk to the two pages the design calls for.

## What to take away

If you build a system that keeps growing, the cheapest structural change we found was to write down, per feature, the facts every other part needs, in one plain-data file, and make everything read it. Once that existed, deleting things became safe, and most of this rebuild was deleting things.

The engine is open source at [github.com/kon-rad/argo](https://github.com/kon-rad/argo); start with `app/server/src/features/` to see the manifests. More of this writing goes to [x.com/myargoquest](https://x.com/myargoquest).
