A knowledge database engine built for agents. Every fact — person, place, module, decision, task — is a typed entity in one uniform envelope, wired into a graph, deduplicated by name, and queryable in milliseconds. Runs entirely on your machine.
🚀 Release candidate (v1.0.0rc1). Battle-tested inside Aethvion Suite and now a standalone package. The storage format is committed and migrated forward across releases; the
/api/v1surface is stable.
# From a checkout (editable install)
pip install -e ".[dev]"
# Run the HTTP API (defaults to 127.0.0.1:7475)
aethviondb-server
# docs at http://127.0.0.1:7475/docs
# API at http://127.0.0.1:7475/api/v1Data is stored under ~/.aethvion/aethviondb by default (override with the
AETHVIONDB_DATA_DIR environment variable). Use it as a library, too:
from aethviondb import EntityWriter
w = EntityWriter() # default database
entity, created = w.create("Ada Lovelace", entity_type="person")
print(w.get_by_name("Ada Lovelace")["id"])The optional intelligence features (distill text → entity, generate embeddings) require an injected LLM/embedding backend — the deterministic core (entities, graph, search, validation) works without one.
AethvionDB is a local, file-backed knowledge store designed from the start for agentic use — for AI agents and local models to read and write structured knowledge against a single shared source of truth.
Unlike a wiki (documents) or a vector store (opaque chunks), AethvionDB keeps typed entities with explicit relationships. Nothing is duplicated: facts are stored once and referenced by ID, so the knowledge stays a graph rather than a pile of copies.
Where Aethvion Project Mapper maps a single codebase, AethvionDB is the general-purpose knowledge layer: the brain of the workspace that many agents and systems can share.
Every entity shares one envelope:
A global name index is consulted before any entity is created, so the same
real-world thing never gets two records. Relationships are first-class and
typed (depends_on, parent_of, calls, created_by, related_to, …),
making the store a true knowledge graph.
The on-disk format is versioned (schema_version) and migrated forward across
releases — see docs/STORAGE_FORMAT.md for the full
layout and stability policy.
- Typed entities + typed relations — one schema for everything, graph-native.
- Name-index deduplication — atomic get-or-create; no duplicate records.
- Distillation — extract a structured entity from raw text (optional; needs an injected LLM backend).
- Live change feed — SSE stream of every write, with actor attribution.
- Hybrid + vector search — keyword and embedding similarity over entities.
- Graph queries — traverse, neighbors, and shortest-path between entities.
- Validation — schema + cross-entity consistency (duplicates, orphan stubs, broken relations, timeline ordering).
- Baking — export curated, flattened snapshots for downstream consumers.
- Backups — point-in-time copies with restore.
- Multiple databases — each an independent directory; switch freely.
- HTTP API — a versioned REST surface (
/api/v1) with API keys, batch operations, cursor pagination, and section projection.
AethvionDB serves reads from an in-memory cache backed by a single-file
snapshot, with an O(1) generation counter for freshness (no per-file stat()
scans). Measured on a 30,352-entity / 36 MB database:
| Operation | Time |
|---|---|
| Warm entity list | ~4 ms |
| Cold load (snapshot) | ~350 ms (off the event loop) |
| Freshness check | ~0.1 ms |
| Single write | O(1) — patches the cache, no full rebuild |
The list view is served a lightweight projection; full entity bodies load on demand. Writes patch the cache in place and bump the generation, so a single write never triggers a full rebuild.
Reproduce it yourself: python benchmarks/bench.py [N] builds a throwaway
N-entity database and times these operations. Large-scale correctness checks
live in the test suite under pytest --runslow.
aethviondb/
├── entity_schema.py — the entity envelope (versioned) + structural validation
├── name_index.py — name → ID index (dedup gate; cross-process safe)
├── entity_writer.py — create / read / update / delete, atomic writes, locking
├── snapshot.py — in-memory + on-disk cache, O(1) freshness
├── db_registry.py — named-database registry
├── settings_store.py — host settings (provider keys, default model)
├── validator.py — semantic / cross-entity consistency checks
├── kind_registry.py — per-type ontology (kinds + required properties)
├── vectorizer.py — embeddings for similarity search
├── baker.py — export flattened snapshots
├── backup.py — backup / restore
├── events.py — realtime change feed (SSE pub/sub)
├── client.py — dependency-free Python client (AethvionClient)
├── cli.py — `aethviondb` command-line interface
├── distiller.py — LLM text → structured entity (optional)
├── importers/ — external-source importers (SQLite, .snapshot)
└── api_v1/ — versioned HTTP API (raw / baked / keys)
├── raw_routes.py live CRUD, search, graph, batch
├── baked_routes.py snapshot operations
└── auth.py API-key auth
- Quickstart — install, run, first entity, import.
- HTTP API reference — every endpoint, the response envelope, auth.
- Library guide — use the engine in-process.
- Agents & the live feed — multiple agents working live.
- Storage format — on-disk layout, versioning, concurrency.
Done: typed entity store, dedup, snapshots, search, graph, import/export
(SQLite + .snapshot), baking, realtime change feed (live multi-agent
dashboard), versioned storage format, cross-process write safety, backups.
Toward a stable release:
- First tagged release on PyPI +
aethviondbCLI - Per-type schema / ontology enforcement
- MCP server — expose distill / upsert / search / graph as agent tools
The direction is to prove the engine through real use first, then package and expose it more broadly — the same path Aethvion Project Mapper took.
Open-source core: GNU AGPL v3 Free to use, modify, and self-host. Network use requires open-sourcing your modifications.
Commercial license: COMMERCIAL_LICENSE.md Available for teams that need a proprietary license, SLA, or integration support.
Built with care by the Aethvion team.
{ "schema_version": 1, // on-disk format version (migrated forward across releases) "id": "ws_<hex>", // stable, content-independent ID "type": "person|place|module|service|decision|goal|...", "kind": "software.module", // optional fine-grained sub-type "name": "Canonical Name", // aliases live in core.aliases; deduped by name "status": "active|stub|deleted|planned|deprecated|experimental", "version": 1, // mutation counter — incremented on every write "created": "ISO-8601", "updated": "ISO-8601", "source": "manual|import|distilled|<agent>", "sections": { "core": { "summary": "", "aliases": [], "categories": [], "tags": [] }, "timeline": [ { "date": "...", "event": "...", "ref_ids": ["ws_..."] } ], "relations": [ { "kind": "depends_on", "target_id": "ws_...", "note": "" } ], "properties": { /* type-specific structured facts */ }, "stubs": [ "Sub-topic that deserves its own entity" ] } }