OpenKyrozen distinguishes durable facts and event history from retrieval indexes. SQLite is the authoritative store for v2 sessions, events, memory claims, durable tasks, usage, schedules, and learning state. ChromaDB and Graphify data are derived indexes that can be rebuilt from their inputs; rebuilding them does not replace the SQLite source of truth.
| Data | Default or configuration | Role |
|---|---|---|
| Global workspace | ~/.kyrozen/workspace |
Default working directory for a bare installed kyrozen launch. |
| User state | ~/.kyrozen/v2/openkyrozen.sqlite3 |
SQLite-backed durable runtime state. |
| Encrypted provider config | ~/.kyrozen_config.json |
User provider credential settings. Protect the file and its home directory. |
| Vector index | A chroma_index_v2 sibling of the database by default; KYROZEN_VECTOR_PATH overrides it |
Optional derived semantic-retrieval index. |
| SQLite database | KYROZEN_DB_PATH overrides the database path |
Durable authoritative records. |
| Audit log | KYROZEN_AUDIT_LOG overrides the default log destination |
Local security and integration audit events. |
| Server actor | KYROZEN_SERVER_ACTOR |
Actor identity assigned to web requests; invalid values fall back to local. |
| Workspace root | --project PATH or KYROZEN_WORKSPACE_ROOT |
Root for project-bound operations, subject to launch-context checks. |
| Legacy source-checkout memory | ./chroma_memory/ when migrating older installs |
Migration input; not the active v2 vector index. |
The exact home-directory layout can evolve. Use kyrozen --help and the current database configuration in openkyrozen/persistence/database.py before writing scripts that assume internal paths. A Docker deployment sets KYROZEN_DB_PATH=/data/openkyrozen.sqlite3 and KYROZEN_VECTOR_PATH=/data/chroma_index; mount the named volume at /data to retain state between container replacements.
Memory claims can have owners, speakers, audiences, channels, visibility, and workspace/session scopes. Retrieval filters against those properties; multi-party records retain attribution so private statements are not generalized into shared facts. Personal memory retains a global personal scope. Project source snapshots and project history use project/session scope. A web session is actor-scoped. Do not assume deleting one conversation erases a global memory claim or learning event.
Model providers receive the context sent for a request. Local storage does not imply that model inference or browser/network operations are local. Review provider privacy terms and keep secrets and unrelated private data out of prompts. See security.
Stop the running process before taking a simple file copy of the SQLite database. Preserve the database and its adjacent SQLite WAL/SHM files together if present; an application-level SQLite backup API or a clean shutdown is preferable to copying an actively written database file. Keep credentials, workspace files, browser data, vector indexes, and history snapshots in a backup only when your retention policy requires them, and store the backup privately.
On startup, OpenKyrozen applies recognized SQLite schema migrations in order and creates an adjacent *.backup.<timestamp> file before changing an existing database. The backup uses SQLite's backup API, includes committed WAL data, and is created with owner-only permissions. Startup reports its path without printing database contents. Unknown future versions and inconsistent core tables stop startup before the database is changed. Keep the reported backup until the upgraded application has been verified.
Permission decisions are stored as versioned, workspace/session-scoped audit history with operation fingerprints and a summary of argument names. They do not contain argument values or credentials, and no approval grant or permission mode is restored from these events.
To restore or downgrade, stop OpenKyrozen, copy the reported backup to a private location, set KYROZEN_DB_PATH to that file, and run a version that supports its schema. The application never runs a downgrade automatically. Verify the expected sessions and claims before removing the prior copy. Do not merge two live database files with a filesystem copy.
If semantic retrieval fails while SQLite remains readable, first check disk permissions and the configured vector path. The agent can fall back to authoritative stored data when the vector index is unavailable. A rebuildable index can be removed and recreated after the corresponding runtime is stopped. Project Graphify indexes have their own /graph refresh lifecycle; rebuild a project graph only when its source project is available.
The compatibility command accepts the source directory as an optional argument and writes to KYROZEN_DB_PATH or the default database:
KYROZEN_DB_PATH="$HOME/.kyrozen/v2/openkyrozen.sqlite3" \
kyrozen migrate v1 ./chroma_memoryReview the migration JSON summary and preserve an original backup until the imported claims have been checked. Migration is not a merge strategy for an already-initialized destination. For implementation-level recovery evidence, read the architecture and development guide.