SAKO Brain

What it is

SAKO — Structured Augmented Knowledge Orchestrator.
Structured knowledge, projects, decisions, timeline and context;
Augmented by AI, tooling, indexing and automation;
Knowledge and context at the core; an
Orchestrator that coordinates knowledge, rules, context and the tools and agents that use them.

It is an open-source project in its own right, not a write-up of a private setup. The engine is public under the AGPL, installable, and built to run on anyone’s vault — it has never contained mine. What this page adds is the evidence: I run it daily, so the claims below are measured on a real working system rather than a demo.

A local, file-based system that holds the state of my work: what each project is, where it got to, what was decided and why, what is unresolved, and what happens next. Plain Markdown files with a small structured header, a rebuildable search index, a command-line tool, and a set of rules that govern how an AI assistant is allowed to read and write to it.

The line that explains it best:

The repository contains the project. The Brain contains the state required to work on it.

Every figure on this page carries the date it was verified — a working system’s counts move every week.

Where my work starts

This is the part most descriptions of a “second brain” get wrong. It is not an archive I visit after the work is done. It is normally where the work begins.

A typical piece of project work runs in this order:

1. Start in the Brain. What is this project’s current state? What did the last session leave unresolved? What was already decided, so I don’t relitigate it? What is the next action?
2. Move into the actual project repository and do the work there. The code has never lived in the Brain and never will — the Brain stores knowledge about projects, and references their paths.
3. Come back and record what is durable: what changed, what was decided, what is still open, what the next session should do first.

Step three is what makes step one possible next time. Without it, every session opens with archaeology — reading diffs and guessing intent — instead of a briefing.

One Brain, many projects

One system, not one folder per tool. It holds 150+ notes covering 20 registered projects, alongside decisions, dated events, people and reference knowledge. Snapshot: 9 September 2026.

The top level is deliberately boring:

There are other directories — personal areas of life among them — which is exactly why this page shows the shape and not the contents.

Because it is one system, a project is never orphaned by the tool it was built with. The record for a website, a security platform and a calculator all sit in the same place, in the same format, readable by the same commands.

How a session picks up where the last one stopped

Each project can carry a handoff document: one file per project that a session appends to, newest first. It never overwrites. A handoff section records what was attempted, what changed, the current working state, what is unresolved, and the single next action.

The handoff for this website has 27 dated sections — verified 9 September 2026. That is twenty-seven working sessions on one project, each of which could open with the state rather than reconstruct it.

The mechanism earns its keep most when time passes. One project in the Brain has handoff entries from late May, then nothing until late July — a nine-week gap — then a continuous run through August. Resuming after nine weeks was reading one document, not re-deriving a codebase.

Decisions outlive conversations

70+ recorded decisions — snapshot: 9 September 2026. A decision gets its own note — what was decided, what was rejected, and the reasoning — because the reasoning is the part that evaporates first. Six months later the code shows what was chosen; only the record shows what the alternatives were and why they lost.

Decisions are not edited when they change. A new record supersedes the old one and the old one is marked superseded, so the history of a changing view stays intact rather than being quietly rewritten. The health checker validates that every supersession points at a note that actually exists.

Honestly: that supersession chain has been exercised exactly once so far. The mechanism is built and checked; it is not heavily used yet.

Markdown is canonical

Every note is a Markdown file. The search index is SQLite with full-text search over it — and it is a cache, never a source of truth. It can be deleted and rebuilt from the files at any time. If the index and the Markdown ever disagree, the Markdown wins.

There is no vector database, no cloud database and no embeddings. That is a deliberate constraint rather than a missing feature: it keeps every note readable and editable in a plain text editor, on a laptop, with no AI running and no service to sign into. Search is full-text with field weighting, which is unglamorous and entirely sufficient at this scale.

AI is a client, not the memory

This is the load-bearing idea.

The assistant does not contain the memory. It reads and writes files through a documented interface, governed by rules that live in the repository as text. Those rules are provider-neutral by design — they are written for “any agent”, not for one vendor — so the Brain survives changing model, changing tool, or dropping AI entirely.

Your AI is not your memory. The model is a client. The files remain yours.

What it refuses to write silently

An assistant with write access to your knowledge base is a liability unless it is constrained. The write policy has three levels:

• Write directly — the agent’s own project work: what it changed, milestones, decisions made explicitly in the session.
• Queue for review — durable personal information mentioned in passing, which lands in a pending queue rather than becoming an authoritative record on the strength of one remark.
• Never automatically — sensitive categories, which require explicit intent and are stored separately with a sensitivity marker.

Every note carries a sensitivity level, and the rules forbid storing credentials of any kind anywhere in the system. Whenever an agent changes anything, it must report what it changed — the point being that memory should never move silently.

Checking and protecting itself

A knowledge system that cannot be verified is a system you have to trust on faith. This one has a health checker with twelve classes of check, runnable in seconds:

• duplicate or reused IDs
• internal links that don’t resolve to a real note
• registered projects whose directory has disappeared
• invalid status or sensitivity values, malformed frontmatter
• supersession pointing at a note that doesn’t exist
• credential-shaped strings anywhere in the vault
• the backup location being mistaken for the canonical one

It reports; it never deletes or silently fixes. As of 9 September 2026 it runs clean across all 150+ notes: no duplicate IDs, no broken links, no registry errors.

Underneath that: 512 automated tests, all passing on Python 3.11 and 3.13 — the suite that covers the command-line tool itself, measured in the released package’s own CI at v0.2.0 (verified 10 September 2026). That figure describes the software, not the notes: it is not a count of anything in a vault. Local version history for every change, and encrypted, versioned off-machine backups, verified by a full integrity check reporting no errors.

What this looks like in practice

This website is managed through it. The project record, the architecture decisions, the public-surface rules and the 19-section handoff all live in the Brain, and are what carried this site’s redesign across separate working sessions. Not “AI built my website” — the sessions did the work; the Brain is why session four didn’t start from zero.

It caught a public page that had gone quietly wrong. The public page for another of my projects sat eight development stages out of date while remaining, sentence by sentence, true. Nothing was false, so nothing raised an alarm. The mismatch only became visible by comparing what the page claimed against the project’s real state in the Brain. The outcome was a durable rule: closing a development stage now requires explicitly recording whether the public page needs updating — including when the answer is “no change”, because an unstated answer is indistinguishable from nobody having looked.

That is the honest argument for this system. Not that it makes me faster on any given day, but that it makes a specific class of slow, silent decay visible.

From personal system to open source

The generic engine is now public. The first release, v0.1.0, shipped on 8 September 2026 under the GNU AGPL-3.0-or-later; the current release is v0.2.0, on 10 September 2026. You can build your own local Brain without needing mine.

The separation is the whole design, and it held:

One rule was fixed from the start, because getting it wrong is unrecoverable: the public project was never produced by sanitising my vault and publishing the result. Sanitising content does not remove the shape of a life — project names, timings and the structure of the areas themselves leak. The public repository starts from a clean baseline and ships a purpose-built synthetic example vault with fictional projects instead. brain init --demo creates it.

It ships with the philosophy it already ran on: local-first, files-first, CLI-first, AI-optional. Your data stays on your machine, in files you can read without any of it.

Getting there took five stages of work that were mostly removal: separating code from vault, pulling every environment-specific assumption out of the engine, proving it runs on a synthetic vault under a scrubbed environment, packaging it, and only then publishing. The interesting part was not writing new features — it was discovering how much of a personal tool is quietly welded to one person’s machine.

What it is not

• Not AGI, and not intelligence of any kind. There is no model inside it. It is files, a schema, an index and rules.
• Not a memory product or a hosted service. Nothing is uploaded anywhere. There is no account and no server.
• Not an autonomous agent. It does not act. It stores state that an agent — or a person with a text editor — reads and writes under stated constraints.
• Not a replacement for judgement. It records what was decided and why. It has never decided anything.
• Not finished. The local-model integration and the tool-server layer are built and tested but not part of daily use, and this page says so rather than counting them as features.

Where it stands

Active and in near-daily use — the operating layer behind how I work across projects — and, since 8 September 2026, open source.

v0.2.0 is the current release: a wheel and a source distribution on GitHub, Python 3.11 or newer, one runtime dependency. Linux is tested; macOS is not yet tested and Windows is not supported. It is pre-1.0, so the command line and configuration may still change — your notes will not, because they are Markdown files.

Pre-1.0 is meant literally, and v0.2.0 shows what it buys. That release changed a default: brain init no longer writes an AGENTS.md, because agent rules are a client’s concern and the tool should not assume an agent is involved at all. Anyone who wants the file runs brain agents-doc --write. The old flag still works, so scripts written against v0.1.0 keep running. 1.0.0 is reserved for the point where the command line, configuration and install contract stop moving.

It is not on PyPI, there is no hosted service, and support is best-effort. What there is, is the actual thing, installable, with a brain init --demo that builds a small fictional vault you can explore before committing to one of your own.