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.5 development, pre-alpha. This describes the checked-out source, not a claim that 0.0.5 is already published on PyPI. API and persistent-format compatibility must be checked before upgrading; see operations.

Install and start

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. In this 0.0.5 development revision, 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, public time-travel 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
• Operations, concurrency, errors and upgrades
• Performance and measurement boundaries
• Roadmap: evolution, known limitations and corrective work — the sole active backlog
• Changelog, contributing, security

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. Check those terms before offering a hosted service.