VANI
Sovereign Local-First Cognitive Operating System
A local-first cognitive OS designed to still boot in fifty years, with its architecture enforced by a static-analysis guardian.
- commits
- 4
- lines of source Python
- 13,772
- lab notes
- 21
- first commit
- 10 Jul 2026
- last commit
- 15 Jul 2026
Measured from the repository on 7 Oct 2026 (git rev-list, git ls-files over src/; note count from the Lab).
Abstract
Vani was engineered as a reaction against fragile cloud-dependent AI frameworks. Designed around a 50-year longevity mandate, it eliminated external Docker and cloud services in favor of pure SQLite, introduced an AST Architecture Guardian to make import violations impossible, and treated AI models as interchangeable fuel rather than core identity.
A cognitive operating system engineered for 50-year longevity with zero cloud infrastructure and an automated AST Architecture Guardian.
- Type
- Sovereign Local-First Cognitive OS
- Started
- 10 July 2026
- Status
- Completed Architecture Milestone · Evolved into ÆON
- Language
- Python 3.12 (Strict Typing / Mypy Strict)
- Domain
- Local-First AI / Long-Term Software Durability / Static Architecture Verification
- Architecture
- Layered Composition Root · AST-Enforced Layer Invariants · Clean Port Architecture
- Scale
- 13,772 Lines · Zero External Daemons · 100% Deterministic Boot
- Verification
- 100% Architecture Conformance via AST Static Analysis
- Materials
- Python 3.12SQLite 3Python AST Static AnalysisMypy StrictRuffPyTest
Background
The Fragility of Cloud AI & Framework Churn
“How do you design a personal cognitive operating system that will still boot, run, and read its memory 50 years from today without relying on proprietary cloud APIs, external database servers, or volatile third-party frameworks?”
Modern AI development is plagued by transient framework abstractions (LangChain, LlamaIndex) that change APIs monthly, hide prompts behind opaque wrappers, and force dependencies on complex microservices (Docker, Redis, Neo4j). If an external API changes its pricing, revokes a key, or shuts down, the user's personal companion dies with it.
Vani was created to correct the architectural drift discovered in Leo (where 281 violations bypassed memory gatekeepers). It established the principle: 'Architecture Before Implementation'.
Where earlier approaches fall short
- 01Reliance on cloud LLM APIs makes personal cognitive data vulnerable to vendor deprecation and privacy leaks.
- 02Polyglot database stacks (like Leo's Redis + Postgres + Neo4j) are impossible to maintain over decades.
- 03Third-party agent frameworks introduce leaky abstractions, infinite hidden retry loops, and security vulnerabilities.
- 04Architectural guidelines in past projects eroded because violations were not caught at compile time.
Working hypothesis
True sovereignty requires zero infrastructure dependencies. By building directly on Python and SQLite, enforcing strict import rules via a custom AST parser, and treating AI models as pluggable 'fuel' behind abstract ports, an AI companion can achieve multi-decade durability.
Summary
The 50-Year Longevity Mandate & Models as Fuel
A personal AI system's value is its accumulated memory and identity, not the specific neural network generating tokens. Neural models are interchangeable fuel (`AIPort`); the cognitive OS and its SQLite records must remain sovereign, local, and durable forever.
- 10
Deterministic Kernel Boot
The Composition Root initializes core subsystems in a strict, single-threaded boot sequence without background daemon dependencies.
- 20
AST Guardian CI Gate
Before any test runs, the AST Static Analysis Guardian parses every Python file into an Abstract Syntax Tree to ensure no illegal upward imports exist.
- 30
Event-Driven Cognitive Cycle
Perceptions and commands trigger typed events on an in-process, synchronous event bus with deterministic dispatching.
- 40
SQLite Sovereign Storage
Working, episodic, and associative semantic data are stored in a single SQLite file using relational property tables and recursive CTEs.
- 50
Pluggable AIPort Execution
Cognitive planning invokes the abstract `AIPort` protocol. If the local model changes or an API goes dark, a new adapter is swapped without modifying cognitive logic.
Description
Vani enforced a strict 4-tier layer hierarchy with an external AST Guardian running in CI to physically prevent the architectural violations that plagued Leo.
- Verified
- Implemented
Contracts & Port Protocols
102 · in 100 Foundation Contracts & Port Protocols
Defines abstract protocols (`AIPort`, `StoragePort`, `EventBusPort`) that higher layers program against.
- How it works
- Python `typing.Protocol` classes enforcing structural subtyping without runtime overhead.
- Trade-off
- Requires upfront interface design before writing any functional logic.
- Source
- src/runtime/contracts/
Reference numerals
100Foundation Contracts & Port Protocols
120Core Runtime Substrate
140Cognitive Kernel & Scheduler
160Pluggable AI Adapters (AIPort)
In operation
Execution Flow: Sovereign Knowledge Ingestion
How Vani ingests and indexes user information locally without contacting cloud services or spawning external database daemons.
Input · illustrative, not a captured log
User records personal preference: 'I prefer concise architectural summaries without conversational fluff.'
- 10
Input Normalization
Input Adapter
Wraps text into a typed `UserFactEvent` with SHA-256 integrity hash.
StateEvent emitted to Event Bus.
- 20
Event Routing
Event Bus
Synchronously delivers event to the Cognitive Loop and Knowledge Subsystem.
StateSubscribers activated deterministically.
- 30
Local Extraction
AIPort (Local SLM Adapter)
Local model extracts entity-attribute-value triple: `(User, preference_style, concise)`.
StateTriple validated against schema.
- 40
SQLite Persistence
SQLite Storage Engine
Writes triple into `property_graph` table and appends event to `audit_log` within a single ACID transaction.
StateSQLite WAL committed to disk.
- 50
Verification
Health Monitor
Verifies database integrity pragma (`PRAGMA quick_check;`) returns 'ok'.
StateSystem returns to IDLE state.
Output
Preference recorded locally in SQLite. Zero bytes transmitted over network. Database portable as a single file.
Claims
Mechanical Conformance & Zero-Violation Certification
- 1.
AST Architecture Violations: 0
Zero illegal imports across 13,000+ lines of Python code.
Evidence: Lab note V009 - 2.
External Runtime Daemons: 0
Runs directly on Python standard library + SQLite with zero Docker containers.
Evidence: Lab note V007
Reported, not re-measured
These figures come from the project's own records. They are not claimed here because there is no public note to check them against yet.
- Type Safety (Mypy Strict)
- 100%
- All contracts, events, and loop state machines pass strict static type analysis. Source: Vani project record; not re-measured.
- Database Longevity Score
- 50 Years
- SQLite storage format guaranteed readable across any OS platform indefinitely. Source: A design target, not a measurement.
Test suite
Method
Decisions
ADR-009
AST Architecture Guardian vs Written Architecture Guidelines
Leo's 281 architectural violations proved that written documentation, checklists, and code reviews inevitably fail under development pressure.
| Option | For | Against |
|---|---|---|
| More detailed architecture documentation and PR checklists | Zero engineering effort to write. | Ignored during rapid coding sessions; does not stop bad code from merging. |
| Python AST Static Analysis Guardian running in pre-commit and CI | Build breaks immediately if an unauthorized import occurs. Enforces 100% mechanical conformance. | Requires maintaining custom AST parsing logic in the repository. |
Chosen
Python AST Static Analysis Guardian
Why
Cost accepted
Evidence: lab-content/Vani/009-architecture-guardian-ast.md
ADR-014
Rejection of LangChain and LlamaIndex
Initial prototypes considered using established agent frameworks to accelerate development.
| Option | For | Against |
|---|---|---|
| Adopt LangChain / LlamaIndex | Off-the-shelf abstractions for chains, prompts, and vector search. | Massive dependency bloat (hundreds of transient packages), frequent breaking changes, hidden prompt injection surfaces, uncontrolled while-loops, difficult debugging. |
| Build Bespoke First-Principles Runtime on Python Standard Library | Zero bloat, complete control over prompt assembly and state transitions, multi-decade durability. | Must write custom event loops and prompt staging from scratch. |
Chosen
Bespoke First-Principles Runtime
Why
Cost accepted
Evidence: lab-content/Vani/014-rejecting-langchain.md
ADR-003
Rejection of Graph Databases (Neo4j) in Favor of SQLite Property Tables
Leo used Neo4j for semantic relationships. Maintaining Neo4j required a JVM, 1.5GB of RAM, and continuous Docker daemon management, violating the 50-year longevity mandate.
| Option | For | Against |
|---|---|---|
| Retain Neo4j | Native Cypher query language, optimized graph traversal algorithms. | JVM overhead, Docker dependency, difficult backups, risk of software obsolescence. |
| Relational Property Tables in SQLite with Recursive CTEs | Zero-configuration single file, runs on literally every operating system, guaranteed readable for decades, negligible memory footprint. | Writing multi-hop graph queries requires more complex SQL CTE syntax. |
Chosen
SQLite Relational Property Tables
Why
Cost accepted
Evidence: lab-content/Vani/003-graph-database-rejection.md
Deficiencies
What broke, why, and what changed because of it. These stay on the record next to everything that worked.
Phase 0 Documentation vs Implementation Desynchronization
GOVERNANCE DESYNCFailure
The project README stated that Vani was in 'Phase 0 (Skeleton: no active runtime)' when in reality 13,000+ lines of sophisticated event loops, schedulers, and storage modules were already implemented and tested.
Root cause
Rigorous adherence to 'Architecture Before Implementation' led to spending weeks crafting architectural governance documents while the README was neglected and remained frozen at day-one boilerplate.
First attempt
Periodic manual documentation reviews.
Fix that held
Instituted an automated documentation audit script that compares git commits and lines of code against claimed project status.
Lesson
Documentation debt is just as real as code debt. When engineering moves faster than docs, the repository lies to external observers about its actual state.
Evidence: lab-content/Vani/CLAIM_VERIFICATION.md
Hard problems
01Graph Traversal Without a Graph Database
Why it is hard
First approach
What failed
Final approach
Where it stands
02Model Obsolescence & The 'AIPort' Abstraction
Why it is hard
First approach
What failed
Final approach
Where it stands
History
Mid 2026
Phase 0 · completed
Constitution & AST Guardian Genesis
Established Foundation Laws, clean Port protocols, and the Python AST Static Analysis Guardian.
Why
Ensure that Leo's 281 architectural violations could never physically happen again.How
Created `tools/guardian` and defined `src/runtime/contracts/`.Result
100% mechanical enforcement of layer boundaries.Mid–Late 2026
Phase 1 · completed
Zero-Infrastructure Engine & SQLite Graph
Eliminated Neo4j and Docker; implemented recursive CTE property graph on SQLite.
Why
Achieve the 50-year longevity mandate with zero external service dependencies.How
Wrote custom SQLite migration engine and recursive query builders.Result
Single-file `.db` portability with sub-10ms graph queries.Late 2026
Phase 2 · pivot
Transition & Architectural Merge into ÆON
Synthesized Vani's AST rigor and SQLite longevity into the 28-package uv monorepo of ÆON.
Why
Expand scope to encompass local SLM inference, multimodality, and empirical soak testing.How
Migrated Vani's domain contracts into ÆON's foundation layers.Result
Vani archived as an architectural success; core DNA active in ÆON.
Measurements
ZERO VIOLATIONS (100% CONFORMANCE)
AST Guardian Static Analysis Audit
Confirmed that not a single higher-layer module was imported by lower-layer foundations, and direct database access was strictly isolated to storage adapters.
- README documentation lagged 13,000 lines behind actual codebase implementation.
Status
Vani completed its architectural mission and was superseded by ÆON. Its core design principles—AST enforcement, zero cloud bloat, and models as fuel—live on in ÆON's foundation layers.
Vani's architectural lineage continues directly in ÆON.
Works today
- AST Static Analysis Guardian with 100% layer enforcement.
- Zero-daemon cognitive event bus and SQLite property graph.
- Strictly typed `AIPort` protocol isolating model dependencies.
Incomplete
- High-level autonomous planning was intentionally deferred to Phase 2 (which occurred inside ÆON).
Remaining
- Serves as an architectural textbook and clean template for sovereign, local-first Python software.
I would change today
- I would integrate local SLM inference (llama.cpp) earlier in the prototyping phase.
Next
ÆON Monorepo Evolution
planned
Vani's AST layer enforcement evolved into ÆON's automated `test_substrate_architecture_invariants.py`.
Key Contributions to Software Longevity
Developed a complete zero-cloud cognitive substrate with SQLite-backed property graphs and AST import gatekeeping.
Directions under study
- 50-Year Portable Cognitive Spec: Standardizing personal cognitive archives into self-describing SQLite schemas.
- Compiler-enforced architectural governance for solo engineers.
Possible contributions
- Demonstration of replacing heavy graph databases (Neo4j) with recursive CTEs in personal knowledge systems.
“If software cannot run without a cloud subscription or Docker orchestrator, it does not belong to you. True intelligence systems must be built to last decades, not sprint cycles.”
Longevity Requires Radical Simplicity
Every external service you add (Redis, Neo4j, Docker) is a timer counting down to an operational failure. SQLite and the standard library survive when everything else breaks.
The AST Guardian Works
Leo had 281 architectural violations; Vani had zero. The difference was entirely mechanical: Leo used documentation, Vani used a Python AST parser that broke the build.
Models Are Fuel, Architecture Is Engine
Never couple your system's core identity or memory to a specific LLM API. Decouple reasoning from token generation through strict port protocols.
Prior art
SHEET 12 / 12The critical transitional bridge where architectural discipline, static verification, and local-first sovereignty became non-negotiable foundations.
- Cites Leo
- Vani was created directly to eliminate Leo's 281 architectural violations and database sprawl.
- Cited by ÆON
- ÆON expanded Vani's sovereign architecture into a 28-package uv monorepo with local SLM execution.