Configure TypeDB¶

TypeDB is an optional knowledge graph layer for ZettelForge. The default backend is SQLite + LanceDB, which requires no external server. TypeDB adds a schema-enforced STIX 2.1 ontology with inference rules; this capability ships with ThreatRecall.ai SaaS.

This guide covers the configuration keys and Docker Compose setup that ship in the OSS repository. Activating the TypeDB backend requires an additional extension included with ThreatRecall.ai SaaS.

Default backend

If you are running ZettelForge OSS without ThreatRecall.ai SaaS, keep backend: sqlite. You do not need TypeDB for standard CTI ingestion, recall, and synthesis.

Prerequisites¶

Docker and Docker Compose installed
ZettelForge installed: pip install zettelforge
ThreatRecall.ai SaaS subscription (required to activate the TypeDB backend)

Steps¶

1. Start TypeDB with Docker Compose¶

The OSS repository ships a docker/docker-compose.yml for TypeDB. From the ZettelForge project root:

docker compose -f docker/docker-compose.yml up -d

Verify the container is running:

docker compose -f docker/docker-compose.yml ps

Expected output:

NAME              IMAGE                STATUS
docker-typedb-1   typedb/typedb:latest Up (healthy)

TypeDB exposes port 1729 for gRPC connections. Data persists in the typedb-data Docker volume across restarts.

Verify the health endpoint from your host:

curl -f http://localhost:8100/health

The docker-compose.yml maps host port 8100 to container port 8000 (8100:8000). The host-accessible health URL is http://localhost:8100/health.

2. Configure `config.yaml`¶

Add or update the TypeDB block in your config.yaml:

typedb:
  host: localhost
  port: 1729
  database: zettelforge
  username: ${TYPEDB_USERNAME}
  password: ${TYPEDB_PASSWORD}

backend: typedb

Do not commit credentials to version control. Use ${TYPEDB_USERNAME} and ${TYPEDB_PASSWORD} placeholders, and supply values as environment variables.

3. Set environment variables¶

export TYPEDB_HOST=localhost
export TYPEDB_PORT=1729
export TYPEDB_DATABASE=zettelforge
export TYPEDB_USERNAME=<your-typedb-username>
export TYPEDB_PASSWORD=<your-password>
export ZETTELFORGE_BACKEND=typedb

Environment variables take priority over config.yaml. Use them for secrets; use config.yaml for structural settings like host and port.

4. Verify the configuration¶

Confirm ZettelForge reads your TypeDB settings correctly:

from zettelforge.config import get_config

cfg = get_config()
print(cfg.typedb)
# TypeDBConfig(host='localhost', port=1729, database='zettelforge',
#              username='admin', password='***')
print(f"Backend: {cfg.backend}")
# Backend: typedb

5. Activate the TypeDB backend (requires ThreatRecall.ai SaaS extension)¶

With ZETTELFORGE_BACKEND=typedb set, get_knowledge_graph() loads TypeDB when the extension is present:

from zettelforge.knowledge_graph import get_knowledge_graph

kg = get_knowledge_graph()
print(type(kg).__name__)
# TypeDBKnowledgeGraph  — extension present (ThreatRecall.ai SaaS)
# KnowledgeGraph        — extension absent (OSS fallback, JSONL-backed)

Without the extension, ZettelForge logs a typedb_unavailable_fallback_jsonl warning and falls back to the JSONL-backed KnowledgeGraph. Ingestion and recall continue using the OSS backend; TypeDB-specific features (STIX ontology, inference rules) are not available in this mode.

Configuration reference¶

Config key	Env var	Default	Description
`typedb.host`	`TYPEDB_HOST`	`localhost`	TypeDB server hostname or IP
`typedb.port`	`TYPEDB_PORT`	`1729`	TypeDB gRPC port
`typedb.database`	`TYPEDB_DATABASE`	`zettelforge`	TypeDB database name
`typedb.username`	`TYPEDB_USERNAME`	`""`	TypeDB username (empty string disables auth)
`typedb.password`	`TYPEDB_PASSWORD`	`""`	TypeDB password
`backend`	`ZETTELFORGE_BACKEND`	`sqlite`	Storage backend: `sqlite` or `typedb`

Configuration precedence (highest first):

Environment variables (TYPEDB_HOST, TYPEDB_PORT, …)
config.yaml in the current working directory
config.yaml in the project root
config.default.yaml in the project root
Hardcoded defaults in config.py

Troubleshooting¶

TypeDB container fails to start

docker compose -f docker/docker-compose.yml logs typedb

Common causes:

Port 1729 already in use: lsof -i :1729
Insufficient memory: TypeDB requires approximately 1 GB RAM minimum

Connection refused on port 1729

docker compose -f docker/docker-compose.yml restart typedb

Wait for the container health check to pass (interval 10 s, up to 5 retries) before starting ZettelForge.

Backend does not activate

ZettelForge silently falls back if the extension is absent or TypeDB is unreachable. Run with structured logging to see the warning:

ZETTELFORGE_LOG_LEVEL=debug python -c "from zettelforge.knowledge_graph import get_knowledge_graph; get_knowledge_graph()"

Look for typedb_unavailable_fallback_jsonl in the output. If you see it, either TypeDB is not reachable on port 1729, or the ThreatRecall.ai SaaS extension is not installed.

Remote TypeDB server

Update typedb.host (or TYPEDB_HOST) to the server address:

typedb:
  host: 192.168.1.50
  port: 1729
  database: zettelforge
  username: ${TYPEDB_USERNAME}
  password: ${TYPEDB_PASSWORD}