aidos

aidos

AI diary OS — the control-plane CLI for an agentic harness. Index your roadmaps, keep knowledge graphs fresh, and stand up new modules, all from one command.

What it does

aidos is the operations layer that sits above a multi-module workspace and manages the shared machinery your agent depends on:

• Roadmap index — parse a roadmap markdown into identified items (stable UUIDs), classify them done / active / deferred, and build a SQLite FTS5 keyword index for fast search. The markdown stays the source of truth; the index is derived.
• Graph reindex — discover every subproject's knowledge graphs, report freshness, and rebuild them in the correct virtualenv. It never kills your MCP servers — it reports which ones need a restart.
• Module setup — a reproducible recipe (and script) to make a new Python module a first-class citizen: its own venv, its own code + docs graphs, and wiring into the shared portal.

It is CLI-first: all logic lives behind plain functions, so it is testable and scriptable without a server. A future control MCP wraps the same CLI.

The name is a nod to aidiary (the AI diary memory system): aidos is the OS layer around it.

Install

Requires: Python 3.12+

pip install aidos

Building a module's own knowledge graphs additionally uses aidiary[graphs] (installed editable in dev):

pip install "aidiary[graphs]"

Quick start

1. Check graph freshness across the workspace

aidos status

Lists each subproject's graph layers (code / docs / …) with a ✓ fresh / ⚠ stale / ✗ missing badge based on graph.json mtime vs. newest source.

2. Index a roadmap and search it

aidos roadmap index path/to/ProjectRoadmap.md
aidos roadmap search "graph reindex" --db output/aidos/ProjectRoadmap.db

index assigns a stable UUID to every item and writes a SQLite FTS5 index + a JSON sidecar. search is instant keyword retrieval — no embeddings, no LLM.

3. Preview a done / active split (non-destructive)

aidos roadmap split path/to/ProjectRoadmap.md

Writes *-archive.md (done) and *-active.md (active + deferred) previews. The original file is never modified — you review first.

4. Rebuild knowledge graphs

aidos reindex --dry-run          # show what would rebuild
aidos reindex --subproject aidos # rebuild one subproject's code graph

Any rebuilt layer is reported as restart_required — restart those MCP servers through your editor (or your restart script), never by killing the process.

Directory layout

my-module/
├── pyproject.toml
├── config/graphs.toml        # graphs.code (src/, ast) + graphs.docs (docs/, semantic)
├── src/<pkg>/                # your package
├── docs/                     # concept docs (feed the docs graph)
└── output/                   # generated artifacts
    ├── aidos/                # roadmap index db + json sidecar
    └── graphs/{code,docs}/   # graph.json + graph.html

Command reference

Design principles

• Markdown / files stay the source of truth — every index, db, and graph is a derived artifact. Producers and consumers connect via files on disk, not imports.
• Keyword over embeddings — on a few-hundred-item corpus, SQLite FTS5 is instant and sufficient; vector search is deferred until the data demands it.
• Never kill a stdio MCP server — reindex reports restart_required; it does not respawn processes.

What's new

0.0.1

First cut — the Developer-Control plane CLI

• roadmap — index (parse → stable UUIDs → done/active/deferred → SQLite FTS5 + JSON sidecar), search (FTS5 keyword), split (non-destructive done/active preview).
• reindex — discover subproject graphs, report freshness, rebuild via each subproject's aidiary-graphs; reports restart_required (never kills MCP servers).
• status — workspace-wide graph freshness.
• Reproducible module setup — idempotent setup.sh (venv + editable installs + graphs) and a documented "make a module a first-class harness citizen" guide.
• Typer CLI, stdlib-only core (plus Typer); builds to sdist + wheel.