OntoDAG

Associative memory and categories based on a directed acyclic graph data structure

Documentation

• User Guide — tutorial and how-to: installation, Python, command line, web app/REST, AI agents, troubleshooting. Start here.
• Reference — every command, setting, kind, endpoint and tool, compact; its tables are pinned to the code by the test suite.
• How It Works Inside — the design in plain language (canonical form, query planning, content-addressed persistence, verifiable answers).
• Changelog — what each release added, with registry migration notes.
• The contract — what programs (and AI agents) built on OntoDAG may rely on: the guarantees, versioned.
• docs/README.md — the full documentation map: design records (docs/) and discussion drafts / future directions (docs/plans/, including the Roadmap).

See also ontodag-fs: any OntoDAG store can be browsed as a filesystem — paths are category queries, files are classified objects stored on Swarm, FUSE-mountable (odag-fs, which shares odag's store settings).

Specification

A Directed Acyclic Graph (DAG) associative storage and category manager in Python. You can store items into a ontodag and recall items from it. To store or "put" an item into a ontodag, you give it a name and a set of other names of already existing items that are its supercategories. To recall or "get", you specify a set of item names to get all items that are subcategories of all these items; alternatives are one word away (odag get Flight Japan or Hotel, get_any in Python).

File a flight confirmation under both Flight and Japan, the boarding pass under the flight itself, and odag get Japan returns the whole trip — including the boarding pass you never filed under the trip. No folder had to be chosen.

Categories can also carry typed values: declare time as a dimension and time(2026-08-15) becomes an ordinary category whose ordering OntoDAG computes — odag get Flight 'time(2026-06-01..2026-08-31)' finds last summer's flights with no edge ever stored between them, at any range, with exact arithmetic — values are rationals of the SI anchor units, so every exactly defined unit works: all of SI, pounds and psi, TB and TiB, even Celsius and Fahrenheit (mapped exactly onto the kelvin scale: temperature(24C)) built in, and unit packs one merge away (odag pack crypto-core for BTC/ETH/BZZ, fiat-iso4217 for ~150 national currencies, crypto-majors for the market's top coins — or declare your own: vocabulary is graph data that travels with the store, no release needed). odag prelude declares the everyday dimensions in one command. Weights and sizes (weight(..5kg)), hierarchical codes like geohash cells, and does-it-fit tuples all work the same way. See User Guide §4.7 and the design record docs/DIMENSIONS.md.

Values are stored in an exact canonical form and shown to you in a friendly one: on a terminal odag prints time(2026) and weight(3kg), while pipes and files always get the exact bytes, so odag get ... | odag round-trips (--render/--raw override; odag canon TERM shows what any spelling actually stores). The same split governs how much you get: a terminal stops at 50 results with a note saying how many were withheld, a pipe is never truncated. A query with no terms at all is the empty intersection — no constraints, so every item (odag count gives just the size).

For AI agents

Serve any store to an agent over MCP with odag-mcp (claude mcp add odag -- odag-mcp): query, fits-within, overlap candidates, per-item description, canonical echo, and an about tool that says what the store contains — read-only by default; --write adds a propose→confirm write surface where every change carries a signed provenance record (who asserted what, against which state) and a review tool computes each claim's standing under your trust list: claims merge, acceptance is policy. Every answer cites the root — a fingerprint of the store's entire content — and is_below answers can carry a certificate that anyone holding only that fingerprint can verify, with no access to the store (ontodag.certificates.verify_below). Equal knowledge yields an equal fingerprint, so two parties can prove they agree — and a disagreement shows up as structure, not prose. The guarantees an agent (or any program) may rely on are written down and versioned in docs/CONTRACT.md; the tool shapes in docs/AGENT_SURFACE.md.

Roadmap

The roadmap — what is done, what is queued next, what is parked and why — is in docs/plans/ROADMAP.md. Longer-term goals for the database direction (and the features deliberately not built yet) are in docs/plans/DATABASE_DIRECTION.md; the day-to-day task list is in CLAUDE.md.

Potential Applications

• Using the ontology graph for content categorization instead of folders
• Replace content tags with a more structured ontology
• Access control (ACT) groups
• Memberships in organizations and gate content based on membership
• Communication channel groups defined by the ontology
• Fostering deals within a universal marketplace for services and goods