SAKO Brain

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.

An open-source knowledge system for organizing projects, decisions, context and AI-assisted workflows — a local-first personal knowledge and project-management CLI. Your notes are plain Markdown files with YAML frontmatter, in directories you can read, edit and back up with anything. The search index, integrity manifests and logs are a rebuildable cache that lives outside your notes — so the vault stays Markdown and configuration, and nothing else.

It works from a plain text editor with no AI, no account and no network.

Current release: 0.24.1. Pre-1.0 means the command line and configuration format may still change; your notes will not — they are text.

Why it exists

Notes accumulate faster than structure does. Most tools answer this by owning your data: a database, a sync service, an account. That trade buys convenience and costs control — you cannot grep it, you cannot diff it, and you cannot take it somewhere else without an export feature someone else maintains.

Sako Brain takes the other side. The files are the system. Everything the program adds — full-text search, link and integrity checking, project records, decision records, a timeline, session handoffs — is derived from those files and can be thrown away and rebuilt with one command. If the program disappears tomorrow, you still have a directory of Markdown.

It also assumes AI agents will read and write your notes, and treats that as a client concern rather than a feature. brain agents-doc --write generates an AGENTS.md describing the vault's data model and rules in a provider-neutral way, which any agent — or person — can read. It is opt-in: nothing about the vault assumes an agent is involved, and brain init does not create one.

What it does not do

Being explicit, because these are reasonable things to expect and none of them is true:

• No cloud service, no account, no telemetry. Nothing leaves your machine.
• No sync. Put your vault in whatever you already sync, or don't.
• No web or graphical interface. It is a command-line tool.
• No AI built in. It produces context for agents; it does not call one.
• Not a note-taking editor. Use your own; the files are ordinary Markdown.
• No automatic backup. Backup is opt-in and unconfigured until you set it up.

Requirements

• Python 3.11 or newer. Tested on 3.11 and 3.14.
• SQLite built with FTS5, which powers search. Present in essentially every mainstream build; brain doctor reports it if missing. It is a property of your Python's sqlite3 module and cannot be installed by pip.

Platform support

Linux	Supported and tested.
macOS	Expected to work but not tested. Reports welcome.
Windows	Not supported. File permissions rely on POSIX mode bits.
Scheduled backups	Linux with systemd only.

Optional external tools

None is a Python dependency, and pip will never install them. Each enables one feature; without it, that feature says so and everything else works.

Tool	Enables
git	brain git — local version history for your vault
restic (and rclone for remote destinations)	brain backup — encrypted, versioned backups
systemd	scheduled backup and maintenance timers

Install

Sako Brain is not on PyPI. Install the wheel from the latest release:

pipx install ./sako_brain-0.24.1-py3-none-any.whl

Each release lists the SHA-256 of its artefacts, so you can check what you downloaded:

sha256sum ./sako_brain-0.14.4-py3-none-any.whl

Or build from source:

git clone https://github.com/Sako404/sako-brain.git
cd sako-brain
python -m build
pipx install ./dist/sako_brain-0.14.4-py3-none-any.whl

pipx puts brain on your PATH and keeps it isolated. A plain virtualenv works too:

python -m venv ~/.venvs/brain
~/.venvs/brain/bin/pip install ./dist/sako_brain-0.14.4-py3-none-any.whl

Either way, exactly one dependency is installed: PyYAML.

Update and uninstall

pipx install --force ./dist/sako_brain-0.14.4-py3-none-any.whl
pipx uninstall sako-brain

Uninstalling removes the program. It never touches a vault, its runtime state or its backups.

First run

brain init ~/brain

Creates the vault, its directories and a commented configuration file, then runs brain doctor and prints the result. It does not create an AGENTS.md — see below.

It never overwrites anything. Run it again on an existing vault and it refuses; with --force it fills in only what is missing and still leaves your configuration and notes untouched.

Useful flags: --git also initialises version history. --no-agents is accepted but does nothing — it is kept only so scripts written against 0.1.0 keep working.

Agent rules are opt-in

brain agents-doc --write

Writes AGENTS.md at the vault root, rendered from that vault's own configuration, describing the data model and rules in a provider-neutral way. Run it whenever you want one; nothing else needs it, and a vault without one is complete and passes brain doctor.

Look around first

brain init --demo /tmp/example-brain
brain --vault /tmp/example-brain index
brain --vault /tmp/example-brain search observatory

Creates a small synthetic vault — fictional content, a deliberately different directory layout, a custom note type — so you can see the shape of the thing before committing to one. Safe to delete. Do not use --demo for a vault you intend to keep.

This is the beginning of the README. Read the rest at the original. Read the full README ↗