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 core has no third-party runtime dependencies.

Source version: 0.0.4, pre-alpha. This describes the checked-out source, not a claim that 0.0.4 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[accel]"

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. The [accel] extra adds native CRC-32C and NumPy. NumPy vector math/page codec require explicit selectors; installing the extra does not select them automatically.

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 general hot-backup/restore 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.