Configure TypeDB¶

TypeDB support is in progress. In ZettelForge 2.8.0, the public package reads TypeDB connection settings, but ZETTELFORGE_BACKEND=typedb still creates a SQLiteBackend and uses the built-in KnowledgeGraph. ThreatRecall.ai lists a TypeDB upgrade path in one pricing tier, but its current runtime uses PostgreSQL and does not run TypeDB. Do not plan production TypeDB storage in either product yet.

This guide lets you inspect the shipped configuration and confirm the current runtime boundary yourself.

Verified storage path

Use SQLite + LanceDB with ZettelForge. Use the managed PostgreSQL-backed graph with ThreatRecall.ai. Both paths work without a TypeDB server.

Prerequisites¶

ZettelForge 2.8.0 installed with Python 3.10 or later.
A ZettelForge 2.8.0 source checkout and Docker Compose if you want to inspect the checked-in TypeDB service definition.

Steps¶

1. Keep ZettelForge on SQLite¶

Keep the verified backend in config.yaml:

backend: sqlite

The TypeDB connection block can remain in the file. ZettelForge reads those fields, but they do not activate a TypeDB storage backend.

2. Review the TypeDB connection fields¶

ZettelForge 2.8.0 defines these fields and environment overrides:

Config key	Environment variable	Default	Purpose
`typedb.host`	`TYPEDB_HOST`	`localhost`	TypeDB host
`typedb.port`	`TYPEDB_PORT`	`1729`	TypeDB gRPC port
`typedb.database`	`TYPEDB_DATABASE`	`zettelforge`	Database name
`typedb.username`	`TYPEDB_USERNAME`	`""`	Authentication username
`typedb.password`	`TYPEDB_PASSWORD`	`""`	Authentication password; redacted in config display
`backend`	`ZETTELFORGE_BACKEND`	`sqlite`	Parsed selection; `typedb` does not activate a TypeDB storage backend

Environment variables take priority over config.yaml. Keep credentials out of version control even though the current backend does not use them.

3. Validate the Compose definition¶

From the ZettelForge 2.8.0 source root, render the checked-in service definition:

docker compose -f docker/docker-compose.yml config

The rendered definition publishes TypeDB gRPC on host port 1729 and maps the container health endpoint on port 8000 to host port 8100. It uses the unversioned typedb/typedb:latest image. This command validates Compose syntax; it does not pull the image, start TypeDB, or prove ZettelForge integration.

4. Confirm the runtime boundary¶

Run this probe in the environment where ZettelForge 2.8.0 is installed:

ZETTELFORGE_LOG_LEVEL=critical \
ZETTELFORGE_BACKEND=typedb \
python3 - <<'PY'
from importlib.metadata import version
from tempfile import TemporaryDirectory

from zettelforge.backend_factory import get_storage_backend
from zettelforge.knowledge_graph import get_knowledge_graph

with TemporaryDirectory() as data_dir:
    backend = get_storage_backend(data_dir=data_dir)
    backend.initialize()
    print(version("zettelforge"))
    print(type(backend).__name__)
    print(backend.health_check()["backend"])
    print(type(get_knowledge_graph()).__name__)
    backend.close()
PY

Verified output for the official 2.8.0 wheel:

2.8.0
SQLiteBackend
SQLiteBackend
KnowledgeGraph

The configuration accepts typedb, but the storage factory returns SQLite and the graph factory returns the built-in graph. Treat a different result as a software-version change that requires a fresh integration test.

5. Choose the working path¶

For ZettelForge, keep backend: sqlite. The checked-in Compose file is useful for development inspection, but it does not make TypeDB a working backend.

For ThreatRecall.ai, use its managed graph as provided. The SaaS plan metadata labels TypeDB as an upgrade path, while the current implementation keeps PostgreSQL as its authority of record. TypeDB setup for ThreatRecall.ai remains in progress, so there is no verified customer setup procedure.

Troubleshooting¶

`backend: typedb` returns `SQLiteBackend`¶

This is the verified ZettelForge 2.8.0 behavior. Keep backend: sqlite and do not treat the TypeDB connection fields as backend activation.

Compose validation fails¶

Run the command from the ZettelForge source root and confirm that docker/docker-compose.yml comes from the 2.8.0 tag.

The TypeDB container starts but ZettelForge still uses SQLite¶

The container and the application backend are separate. Starting the shipped service does not add a TypeDB client or change the storage factory. Stop at the runtime probe and keep TypeDB-dependent work marked in progress.