humemdb 0.1.0.dev1

Embedded multi-model database orchestration over SQLite, DuckDB, Cypher, and exact and ANN vector search

HumemDB

Multi-model embedded data orchestration for SQL, Cypher, and vector search.

---

✨ What HumemDB is

HumemDB is a Python-first embedded runtime that keeps each engine doing the job it is already good at.

• SQLite for OLTP.
• DuckDB for OLAP.
• Cypher support over SQL-backed graph storage.
• Exact and ANN vector search, with the default runtime path starting from an exact SQLite-plus-NumPy baseline today.
• LanceDB later where the benchmark justifies an indexed ANN path.

Today, it starts as a thin Python orchestration layer over embedded engines. The longer-term goal is a single embedded system that supports standard SQL, Cypher, and vector search without forcing one engine to do every job.

The goal is not to force SQL, graph, and vector workloads through one backend just because that sounds clean. The goal is a simple, explicit orchestration layer with clear routing and defensible tradeoffs.

✅ Current status

HumemDB already ships a real v0 surface for three query modes:

• HumemSQL v0
• HumemCypher v0
• HumemVector v0

Current behavior is intentionally explicit:

• Route: sqlite or duckdb
• Query type: sql, cypher, or vector
• Writes go to SQLite
• DuckDB is the analytical read path
• Vector search starts from the exact baseline path today

🔗 Documentation

• HumemDB docs

Install

Install from source:

uv pip install .

Install in editable mode for development:

uv pip install -e .

For contributors, use:

uv sync

uv sync makes the local environment match the project exactly using pyproject.toml and uv.lock.

When dependencies change:

uv lock
uv sync

uv lock updates the lockfile with exact resolved versions. uv sync installs that exact environment.

🧠 What is supported today

SQL

• PostgreSQL-like portable subset translated with sqlglot
• statement coverage: SELECT, INSERT, UPDATE, DELETE, CREATE
• recursive CTEs intentionally unsupported in v0

Cypher

• narrow CREATE and MATCH flows
• labeled nodes and single directed relationships
• relationship aliases and reverse-edge matches
• simple WHERE ... AND ... equality filtering
• ORDER BY and LIMIT

Vector

• SQLite-backed vector storage
• exact NumPy baseline path
• bucket filtering
• benchmark path toward indexed ANN where justified

⚡ Quick example

from humemdb import HumemDB

with HumemDB("app.sqlite3", "analytics.duckdb") as db:
    db.query(
        "CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT NOT NULL)",
        route="sqlite",
    )

    with db.transaction(route="sqlite"):
        db.query(
            "INSERT INTO users (name) VALUES (?)",
            route="sqlite",
            params=("Alice",),
        )

    result = db.query(
        "SELECT id, name FROM users",
        route="sqlite",
    )

    print(result.rows)

More examples live in examples/ and in the docs site.

🔗 Quick links

• Docs: docs.humem.ai/humemdb
• Repository: github.com/humemai/humemdb
• Issues: github.com/humemai/humemdb/issues
• Internal phase tracking: things-to-do.md

📦 Packaging

HumemDB itself is a pure Python package today. It does not ship platform-specific project binaries, even though some dependencies may install native wheels on the user side.

🗺️ Planning

The detailed internal roadmap and phase tracking now live in things-to-do.md instead of this README.

📄 License

MIT.