Okto Grafx

Embedded, local-first graph database for Python, with concurrent readers and writers, snapshot isolation, WAL-backed durability, verification and fail-closed recovery. No database server is required. The base installation includes NumPy and native CRC-32C; engine/domain mechanisms remain isolated behind ports.

Source version: 0.0.6, pre-alpha — in development. Latest published release: 0.0.5. See the publication receipt. API and persistent-format compatibility must be checked before upgrading; see operations.

Development procedures now support explicit native schema authority, including flexible CREATE/MERGE and catalog-v2 index/DML composition within the caller's transaction. See qualification and the roadmap for remaining parity and deployment work.

Install and start

Development typed collection columns add the types summarized in the consolidated support/refusal matrix. The implementation includes LIST/MAP element types, fixed ARRAY length and named STRUCT fields, including nested nullability, decimals and temporals. Native DDL/writes, schema, history, copy and logical transfer preserve descriptors. Exact JSON/CSV/JSONL/SQLite collection interchange now uses explicit schemas/tags and whole-call rollback. Exact nested columnar interchange adds Arrow/Pandas/Polars/Parquet with owned descriptors, full type metadata and bounded atomic imports. Installed type readers and native label-format readers are qualified for their recorded candidates. The complete V3 query profile passes all 3,896 required cases; final integrated delivery status remains in the roadmap.

The final complete regression passes 25,077 tests with 19 attributed skips and all 20 native supplemental maps. Isolated installed Pulse API/UI/MCP checks also pass. Neo4j comparative execution was explicitly deferred by the user and does not block this delivery; this is not a released version, full upstream conformance or an unrestricted Cypher claim.

The 0.0.6 development line also has native decimal storage. It includes exact decimal query arithmetic, aggregation, ordering/grouping and typed equality-index seeks, plus exact history/copy/logical transfer. CLI JSON, typed local text/SQLite imports and registered procedure values now have an exact decimal interface contract. Arrow, Pandas, Polars and Parquet also support exact decimal128 interchange through ArrowDecimalType(p,s), with explicit metadata and atomic native imports. The combined type-package qualification covers installed codecs, durable recovery and old-reader refusal. Supported and refused consumers are explicit in the type matrix; this is not full Cypher parity.

Python 3.11–3.13; local Windows and POSIX filesystems.

pip install okto-grafx

This installs the release available from your configured package index. For this source revision, use pip install -e ".[dev,accel]" in a checkout. okto-grafx is the distribution name; okto_grafx is the Python import; oktografx is the CLI. Since 0.0.5, native CRC-32C and NumPy are base dependencies. The [accel] name remains a compatibility alias. New connections default to codec="numpy", vector_math="numpy" and checksum="auto". Explicit pure selectors remain available; vector auto retains its existing pure semantics. Earlier published releases may still require [accel] and explicit NumPy selectors.

from okto_grafx import connect

with connect(":memory:") as db:
    with db.begin("write") as txn:
        txn.execute("CREATE NODE TABLE Person(id INT64, name STRING, PRIMARY KEY(id))")
        txn.execute("CREATE (:Person {id: $id, name: $name})", {"id": 1, "name": "Ada"})
    result = db.execute("MATCH (p:Person) RETURN p.id, p.name")
    assert result.rows == ((1, "Ada"),)

Use a directory instead of :memory: for persistent data. db.execute() is a read-only autocommit door; writes use explicit transactions. A normal transaction context exit commits, and an exceptional exit rolls back. See the integration tutorial for relationships and durable reopen.

What is available

Concurrent transactions do not imply lock-free commits: publication has an exclusive section, different rows can conflict on physical pages, and operations may wait or time out. Recovery repairs only states that the WAL and durable identity prove safe; it does not silently rebuild or discard damaged authoritative data.

There is no native async/HTTP/MCP server, SQLAlchemy backend, valid-time/bitemporal API or no-pause streaming hot-backup API in this release surface. Proposed capabilities are explicitly separated in the roadmap.

Current measured performance

Latest recorded real-consumer sample: September 8, 2026, Grafx 0.0.4@fa8f188 with [accel], Pulse 0.3.3, Windows/Python 3.13. This is not a benchmark of the later GX-CAP-1 recovery checkpoint or a universal latency promise.

These are one-sample observations, not p50/p99 statistics or an identical-input comparison with Ladybug. Latest full KG UI cold/warm latency at the current source checkpoint is not measured. Native component measurements and their limitations are in performance; no marginal timing gate blocks delivery.

Documentation

Start with the documentation index. It separates tutorials, consumer references, operational procedures, implementation specifications and historical evidence; integrating the library does not require reading the latter.

• Getting started
• Integration: services, workers, cursors and agents
• Public API and result types
• Configuration
• Query language
• Native temporal values: query functions, operators, Python API and persistence
• Composable queries, CALL/YIELD and migration semantics
• Fixed Cypher compatibility target and TCK evidence
• Operations, concurrency, errors and upgrades
• Performance and measurement boundaries
• Feature comparison: Grafx vs Ladybug vs Neo4j
• Roadmap: evolution, known limitations and corrective work — the sole active backlog
• Changelog, contributing, security
• Repository governance and public-release checklist

Deployment and license

The host application owns authorization, input policy and filesystem permissions. Do not place live database files on cloud-sync/network filesystems or replace them while participants are using them. OpenMetrics has no authentication/TLS; remote binding requires explicit consent. See operational safety.

Licensed under Elastic License 2.0 with the SaaS/Branding Addendum. This is a custom, source-available license, not unmodified ELv2 and not an OSI-approved open-source license. The addendum remains part of the terms; making the repository public does not remove it. Check the complete license before embedding, redistributing or offering a hosted service.