Archived

This project has been archived by its maintainers, and is no longer receiving any updates.

z3rno-core

⚠️ Deprecated — full rewrite in progress

z3rno is being rewritten from the ground up as a single open-source Rust monorepo (Apache 2.0), following direct feedback from enterprise users that the current architecture is too complex.

Maintenance mode only — bug fixes, no new features.

Existing installs keep working. Nothing here is being yanked, archived, or removed.

The new monorepo lands at the-ai-project-co/z3rno.

Track progress: https://github.com/the-ai-project-co/z3rno-core/issues/5

Core memory engine for Z3rno -- PostgreSQL schema, SQLAlchemy models, Alembic migrations, and the store/recall/forget/audit library.

Features

7 relational tables -- tenants, API keys, agents, memories, memory relationships, lifecycle policies, audit log
15 Alembic migrations -- fully versioned schema evolution
Row-Level Security (RLS) -- multi-tenant isolation at the database level
SCD Type 2 versioning -- temporal history for every memory mutation
pgvector HNSW indexing -- fast approximate nearest-neighbor vector search
Apache AGE graph layer -- entity and relationship traversal via Cypher queries
Hash-chained audit log -- tamper-evident record of every store, recall, forget, and update

Quickstart

Run migrations

# Set your database URL
export DATABASE_URL="postgresql://z3rno:password@localhost:5432/z3rno"

# Install
pip install -e .

# Apply all migrations
alembic upgrade head

Use the engine

from sqlalchemy.ext.asyncio import create_async_engine, async_sessionmaker
from z3rno_core.engine import store, recall, forget, audit

engine = create_async_engine("postgresql+asyncpg://z3rno:password@localhost/z3rno")
Session = async_sessionmaker(engine)

async with Session() as db:
    # Store a memory
    memory = await store(db, org_id=org_id, agent_id="agent-1", content="User prefers dark mode")

    # Recall by semantic similarity
    results = await recall(db, org_id=org_id, agent_id="agent-1", query="user preferences", top_k=5)

    # Soft-delete a memory
    await forget(db, org_id=org_id, memory_id=memory.id)

    # Query the audit trail
    entries = await audit(db, org_id=org_id, agent_id="agent-1")

For a detailed step-by-step setup, see QUICKSTART.md.

Full documentation: astron-bb4261fd.mintlify.app

Architecture

The schema follows a strict dependency order:

tenants -> api_keys -> agents -> memories -> memory_relationships
                                    |
                                    +-> lifecycle_policies
                                    +-> audit_log

All engine functions operate within a single async SQLAlchemy session and respect RLS via SET LOCAL on the org context.

Documentation

SCHEMA.md -- full table and column reference
MULTI_TENANCY.md -- RLS design and tenant isolation
Architecture Decision Records -- design rationale

Development

uv sync --dev
uv run ruff check .
uv run mypy .
uv run pytest

See CONTRIBUTING.md for the full workflow.

License

Apache 2.0 -- see LICENSE.

Metadata

Release files for z3rno-core 0.22.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for z3rno-core 0.22.1
File	Size	Uploaded
z3rno_core-0.22.1.tar.gz	357.3 kB	Sep 7, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for z3rno-core 0.22.1
File	Interpreter	ABI	Platform	Reset
z3rno_core-0.22.1-py3-none-any.whl 311.0 kB Sep 7, 2026	Python 3	none	any	Details

Total release size: 668.3 kB

Release files / z3rno_core-0.22.1.tar.gz

Download URL	z3rno_core-0.22.1.tar.gz
Size	357.3 kB
Tags	Source
SHA-256 checksum How to use checksums	`934d9134d67d15c99abb3b6a956bf54f318b4b59f912353adcb7c3fb18ed07e9`
BLAKE2b-256 checksum How to use checksums	`8bb336f3fda7ee41ad2af069871f10f2e80953d8ebd5573cc0984249f6e57d86`
Upload date	Sep 7, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Release files / z3rno_core-0.22.1-py3-none-any.whl

Download URL	z3rno_core-0.22.1-py3-none-any.whl
Size	311.0 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`8abe4bcea162058d8298532c5cdff8428cc639f0862822d251bd10afaa3ea189`
BLAKE2b-256 checksum How to use checksums	`3da95de3eff099f63efe1e8931300f5bb18bb621d10ce86f5a37f190a37a1c5b`
Upload date	Sep 7, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.13.14`