aletheia-os

AletheiaOS

简体中文

A repo-native falsifiable truth tree layer for AI-assisted research and engineering.

One repo. One falsifiable truth tree. Many agents.

AletheiaOS = Root-based Truth Tree + Scientific Method Loop + Repo-native Memory + Agent Governance.

AletheiaOS uses .aletheia/ to maintain the single trusted fact source for a complex project: root objective, current state, system graph, project skeleton, tree governance rules, architecture constraints, research evidence, decision records, interface contracts, risks, and agent attribution. It is not just a repo-native truth layer, and it is not a generic project documentation system. It organizes project facts as a reviewable, falsifiable, evolvable truth tree.

The falsifiable truth tree layer is the upgraded form of a repo-native truth layer: the repo-native truth layer stores project facts, while truth tree governance constrains how those facts grow, get falsified, get promoted, and get refactored.

AletheiaOS maintains complex projects as a root-based truth tree:

• The root defines the core objective or research question.
• The trunk defines core objects, main theories, or the system skeleton.
• Branches hold sub-theories, subsystems, architecture directions, or research paths.
• Leaves hold concrete evidence, hypotheses, decisions, contracts, implementation, and tasks.
• Unmounted material enters the orphan/incubator for review, attachment, splitting, merging, or archival.

The tree evolves through a scientific-method loop: observation -> hypothesis -> evidence -> falsification criteria -> decision -> engineering -> feedback -> tree refactor.

In AletheiaOS, truth means the current most trusted, reviewable, falsifiable project facts. It does not mean absolute truth.

AletheiaOS is for long-running research and engineering projects where theory, implementation, evidence, risk, and optimization evolve together, and where local implementation findings can overturn top-level assumptions. AletheiaOS does not replace Codex, Claude Code, OpenSpec, Superpowers, gstack, Compound, or other AI coding workflows. It gives them the same repo-native project truth.

Why AletheiaOS Exists

AI agents are good at local execution, but fragile at long-term consistency. AletheiaOS is not solving a missing-folder problem. It addresses unstructured growth in complex AI-assisted development:

• agents keep adding code, features, docs, and conclusions without tying them back to a root objective;
• new ideas have no clear trunk, branch, or parent node;
• local implementation, research findings, and architecture decisions drift apart or override parent constraints;
• important claims lack evidence strength, falsification criteria, downgrade conditions, or follow-up decisions;
• weakened or falsified hypotheses keep supporting active decisions;
• multiple agents or tools work from different versions of project truth;
• developers and researchers keep optimizing low-weight leaves while drifting away from the trunk.

AletheiaOS reduces this drift by making project facts explicit, tree-shaped, verifiable, and version-controlled. It makes agents locate the root objective, active node, parent constraints, and evidence state before deciding whether new material belongs in the main tree, the orphan/incubator, or a tree refactor.

Who Should Use It

AletheiaOS fits developers who use AI agents to maintain complex research and engineering projects, especially when:

• project goals and constraints must survive over time;
• architecture keeps evolving;
• research findings and design tradeoffs must become evidence and decisions;
• claims, evidence, decisions, and implementation need clear boundaries;
• multiple agents should orient from the same project facts before each work session;
• important project state should not live only in chat context.

Features