shellbrain 0.1.0__tar.gz

shellbrain-0.1.0/PKG-INFO

@@ -0,0 +1,130 @@
+Metadata-Version: 2.4
+Name: shellbrain
+Version: 0.1.0
+Summary: Repo-scoped Shellbrain CLI with explicit evidence-backed writes.
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: SQLAlchemy<3.0,>=2.0
+Requires-Dist: alembic<2.0,>=1.13
+Requires-Dist: pydantic<3.0,>=2.7
+Requires-Dist: PyYAML<7.0,>=6.0
+Requires-Dist: psycopg[binary]<4.0,>=3.1
+Requires-Dist: pgvector<1.0,>=0.3
+Requires-Dist: sentence-transformers<4.0,>=3.0
+
+# Building a Brain
+
+`shellbrain` is a repo-scoped long-term context system for agent sessions.
+
+Think of it as a case-based memory system with two layers:
+
+- durable memories:
+  - `problem`
+  - `solution`
+  - `failed_tactic`
+  - `fact`
+  - `preference`
+  - `change`
+- episodic evidence:
+  - transcript-derived `episode_event` records that ground writes
+
+It exposes four agent-facing operations:
+
+- `read` recalls durable memories related to the current problem or subproblem
+- `events` inspects recent episodic evidence
+- `create` adds new durable Shellbrain entries with explicit `evidence_refs`
+- `update` records utility, links, and lifecycle changes on existing entries
+
+## Install Once Per Machine
+
+Treat `shellbrain` as a machine-level CLI, not a per-repo dependency. The normal product path is a one-time global install, then `shellbrain init` from any repo you want to register.
+
+Preferred install with `pipx`:
+
+```bash
+pipx install shellbrain
+```
+
+Secondary install path:
+
+```bash
+python3 -m pip install shellbrain
+```
+
+Editable installs remain a development/operator path and are intentionally omitted from the normal user-facing flow.
+
+## Bootstrap
+
+From the repo you are working in:
+
+```bash
+shellbrain init
+shellbrain admin doctor
+```
+
+`shellbrain init` is the normal bootstrap and repair path. In the managed-local happy path it owns Docker, Postgres provisioning, migrations, grants, embedding prewarm, repo registration, and Claude integration when eligible.
+
+**Claude integration is conservative.** Shellbrain installs the repo-local Claude hook automatically only when the repo looks Claude-managed *and* `init` is running with a real Claude runtime signal. Otherwise it does nothing unless you pass `--host claude`.
+
+When running Shellbrain from Codex Desktop or a similar tool shell, if direct calls fail in the current session, retry through a login shell first:
+
+```bash
+zsh -lc 'source ~/.zprofile >/dev/null 2>&1; shellbrain --help'
+```
+
+Then use the same wrapper shape for actual invocations if needed:
+
+```bash
+zsh -lc "source ~/.zprofile >/dev/null 2>&1; shellbrain read --json '{\"query\":\"Have we seen this migration lock timeout before?\",\"kinds\":[\"problem\",\"solution\",\"failed_tactic\"]}'"
+```
+
+If `doctor` reports `repair_needed`, rerun `shellbrain init`.
+
+## Typical Workflow
+
+1. Start with focused retrieval queries about the concrete problem, subsystem, constraint, or decision you are working on. Do not start with vague prompts like "what should I know about this repo?"
+2. Use `read` again during the task whenever the search shifts or a memory might become useful midway through the work.
+3. Before every evidence-bearing write, run `shellbrain events --json '{"limit":10}'` so you can inspect concrete `episode_event` ids.
+4. At session end, normalize what happened into durable memories:
+   - the `problem`
+   - each `failed_tactic`
+   - the `solution`
+   - any durable `fact`, `preference`, or `change`
+   - `utility_vote` updates for memories that helped or misled, using a `-1.0` to `1.0` scale where negative votes mean unhelpful and positive votes mean helpful
+
+Never invent `evidence_refs`. If `events` returns nothing useful or the evidence is ambiguous, skip the write and try again later.
+
+Use `--repo-root` when your current working directory is not the repo you want to target.
+
+**Repo identity is remote-first.** Shellbrain prefers the normalized `origin` fetch URL. If `origin` is absent but there is exactly one remote, it uses that. If there are multiple remotes and none is `origin`, `init` stops and asks for `--repo-id`. If there is no usable remote, Shellbrain falls back to a weak-local identity tied to the current path.
+
+## Backups and Recovery
+
+Shellbrain exposes first-class logical backups:
+
+```bash
+shellbrain admin backup create
+shellbrain admin backup list
+shellbrain admin backup verify
+shellbrain admin backup restore --target-db shellbrain_restore_001
+shellbrain admin doctor
+```
+
+Backups default to `$SHELLBRAIN_HOME/backups`, which is `~/.shellbrain/backups` unless `SHELLBRAIN_HOME` is set. The Docker bind-mounted Postgres data dir protects against container loss, but it is not a backup strategy by itself.
+
+## Advanced / Operator Notes
+
+The normal product path should not require users to think about:
+
+- raw DSNs
+- manual `docker compose up`
+- manual `shellbrain admin migrate`
+- editable installs
+- manual Claude hook edits
+
+Those topics belong in the advanced/operator guide: [`docs/external-quickstart.md`](docs/external-quickstart.md)
+
+## More
+
+- Advanced/operator guide: [`docs/external-quickstart.md`](docs/external-quickstart.md)
+- Session-start skill: [`skills/shellbrain-session-start/SKILL.md`](skills/shellbrain-session-start/SKILL.md)

shellbrain-0.1.0/README.md

@@ -0,0 +1,116 @@
+# Building a Brain
+
+`shellbrain` is a repo-scoped long-term context system for agent sessions.
+
+Think of it as a case-based memory system with two layers:
+
+- durable memories:
+  - `problem`
+  - `solution`
+  - `failed_tactic`
+  - `fact`
+  - `preference`
+  - `change`
+- episodic evidence:
+  - transcript-derived `episode_event` records that ground writes
+
+It exposes four agent-facing operations:
+
+- `read` recalls durable memories related to the current problem or subproblem
+- `events` inspects recent episodic evidence
+- `create` adds new durable Shellbrain entries with explicit `evidence_refs`
+- `update` records utility, links, and lifecycle changes on existing entries
+
+## Install Once Per Machine
+
+Treat `shellbrain` as a machine-level CLI, not a per-repo dependency. The normal product path is a one-time global install, then `shellbrain init` from any repo you want to register.
+
+Preferred install with `pipx`:
+
+```bash
+pipx install shellbrain
+```
+
+Secondary install path:
+
+```bash
+python3 -m pip install shellbrain
+```
+
+Editable installs remain a development/operator path and are intentionally omitted from the normal user-facing flow.
+
+## Bootstrap
+
+From the repo you are working in:
+
+```bash
+shellbrain init
+shellbrain admin doctor
+```
+
+`shellbrain init` is the normal bootstrap and repair path. In the managed-local happy path it owns Docker, Postgres provisioning, migrations, grants, embedding prewarm, repo registration, and Claude integration when eligible.
+
+**Claude integration is conservative.** Shellbrain installs the repo-local Claude hook automatically only when the repo looks Claude-managed *and* `init` is running with a real Claude runtime signal. Otherwise it does nothing unless you pass `--host claude`.
+
+When running Shellbrain from Codex Desktop or a similar tool shell, if direct calls fail in the current session, retry through a login shell first:
+
+```bash
+zsh -lc 'source ~/.zprofile >/dev/null 2>&1; shellbrain --help'
+```
+
+Then use the same wrapper shape for actual invocations if needed:
+
+```bash
+zsh -lc "source ~/.zprofile >/dev/null 2>&1; shellbrain read --json '{\"query\":\"Have we seen this migration lock timeout before?\",\"kinds\":[\"problem\",\"solution\",\"failed_tactic\"]}'"
+```
+
+If `doctor` reports `repair_needed`, rerun `shellbrain init`.
+
+## Typical Workflow
+
+1. Start with focused retrieval queries about the concrete problem, subsystem, constraint, or decision you are working on. Do not start with vague prompts like "what should I know about this repo?"
+2. Use `read` again during the task whenever the search shifts or a memory might become useful midway through the work.
+3. Before every evidence-bearing write, run `shellbrain events --json '{"limit":10}'` so you can inspect concrete `episode_event` ids.
+4. At session end, normalize what happened into durable memories:
+   - the `problem`
+   - each `failed_tactic`
+   - the `solution`
+   - any durable `fact`, `preference`, or `change`
+   - `utility_vote` updates for memories that helped or misled, using a `-1.0` to `1.0` scale where negative votes mean unhelpful and positive votes mean helpful
+
+Never invent `evidence_refs`. If `events` returns nothing useful or the evidence is ambiguous, skip the write and try again later.
+
+Use `--repo-root` when your current working directory is not the repo you want to target.
+
+**Repo identity is remote-first.** Shellbrain prefers the normalized `origin` fetch URL. If `origin` is absent but there is exactly one remote, it uses that. If there are multiple remotes and none is `origin`, `init` stops and asks for `--repo-id`. If there is no usable remote, Shellbrain falls back to a weak-local identity tied to the current path.
+
+## Backups and Recovery
+
+Shellbrain exposes first-class logical backups:
+
+```bash
+shellbrain admin backup create
+shellbrain admin backup list
+shellbrain admin backup verify
+shellbrain admin backup restore --target-db shellbrain_restore_001
+shellbrain admin doctor
+```
+
+Backups default to `$SHELLBRAIN_HOME/backups`, which is `~/.shellbrain/backups` unless `SHELLBRAIN_HOME` is set. The Docker bind-mounted Postgres data dir protects against container loss, but it is not a backup strategy by itself.
+
+## Advanced / Operator Notes
+
+The normal product path should not require users to think about:
+
+- raw DSNs
+- manual `docker compose up`
+- manual `shellbrain admin migrate`
+- editable installs
+- manual Claude hook edits
+
+Those topics belong in the advanced/operator guide: [`docs/external-quickstart.md`](docs/external-quickstart.md)
+
+## More
+
+- Advanced/operator guide: [`docs/external-quickstart.md`](docs/external-quickstart.md)
+- Session-start skill: [`skills/shellbrain-session-start/SKILL.md`](skills/shellbrain-session-start/SKILL.md)

shellbrain-0.1.0/app/__init__.py

@@ -0,0 +1 @@
+"""This package contains the shellbrain system application code."""

shellbrain-0.1.0/app/__main__.py

@@ -0,0 +1,7 @@
+"""Allow `python -m app` to invoke the public CLI."""
+
+from app.periphery.cli.main import main
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

shellbrain-0.1.0/app/boot/__init__.py

@@ -0,0 +1 @@
+"""This package contains factory functions that wire core to periphery."""

shellbrain-0.1.0/app/boot/admin_db.py

@@ -0,0 +1,88 @@
+"""Boot helpers for privileged admin database actions and safety settings."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+from app.boot.config import get_config_provider
+from app.boot.home import get_machine_backups_dir
+from app.periphery.admin.machine_state import try_load_machine_config
+
+
+def get_admin_db_dsn() -> str:
+    """Resolve the privileged admin DSN from environment-backed runtime config."""
+
+    machine_config, machine_error = try_load_machine_config()
+    if machine_error:
+        raise RuntimeError(
+            "Shellbrain machine config is unreadable. Rerun `shellbrain init` to repair it."
+        )
+    if machine_config is not None:
+        return machine_config.database.admin_dsn
+
+    runtime = get_config_provider().get_runtime()
+    database = runtime.get("database")
+    if not isinstance(database, dict):
+        raise RuntimeError("runtime.database must be configured")
+    admin_dsn_env = database.get("admin_dsn_env")
+    if not isinstance(admin_dsn_env, str) or not admin_dsn_env:
+        raise RuntimeError("runtime.database.admin_dsn_env must be configured")
+    dsn = os.getenv(admin_dsn_env)
+    if not dsn:
+        raise RuntimeError(f"{admin_dsn_env} is not set")
+    return dsn
+
+
+def get_optional_admin_db_dsn() -> str | None:
+    """Resolve the privileged admin DSN when present, otherwise return None."""
+
+    machine_config, machine_error = try_load_machine_config()
+    if machine_error:
+        return None
+    if machine_config is not None:
+        return machine_config.database.admin_dsn
+
+    runtime = get_config_provider().get_runtime()
+    database = runtime.get("database")
+    if not isinstance(database, dict):
+        return None
+    admin_dsn_env = database.get("admin_dsn_env")
+    if not isinstance(admin_dsn_env, str) or not admin_dsn_env:
+        return None
+    return os.getenv(admin_dsn_env)
+
+
+def get_backup_dir() -> Path:
+    """Resolve the on-disk backup directory, defaulting outside the repo tree."""
+
+    machine_config, machine_error = try_load_machine_config()
+    if machine_error:
+        return get_machine_backups_dir()
+    if machine_config is not None:
+        return Path(machine_config.backups.root).expanduser().resolve()
+    return Path(os.getenv("SHELLBRAIN_BACKUP_DIR", str(get_machine_backups_dir()))).expanduser().resolve()
+
+
+def get_backup_mirror_dir() -> Path | None:
+    """Resolve the optional mirrored backup directory."""
+
+    configured = os.getenv("SHELLBRAIN_BACKUP_MIRROR_DIR")
+    if not configured:
+        return None
+    return Path(configured).expanduser().resolve()
+
+
+def should_fail_on_unsafe_app_role() -> bool:
+    """Return whether app commands should fail instead of warning on unsafe DB roles."""
+
+    configured = os.getenv("SHELLBRAIN_FAIL_ON_UNSAFE_DB_ROLE")
+    if configured is None or not configured.strip():
+        return True
+    return configured.strip().lower() not in {"0", "false", "no", "off"}
+
+
+def get_instance_mode_default() -> str:
+    """Resolve the default instance mode used when stamping metadata for the current DB."""
+
+    return os.getenv("SHELLBRAIN_INSTANCE_MODE", "live").strip().lower() or "live"

shellbrain-0.1.0/app/boot/config.py

@@ -0,0 +1,14 @@
+"""This module defines boot-time helpers that load YAML-backed configuration providers."""
+
+from functools import lru_cache
+from pathlib import Path
+
+from app.config.loader import YamlConfigProvider
+
+
+@lru_cache(maxsize=1)
+def get_config_provider() -> YamlConfigProvider:
+    """This function returns the shared YAML configuration provider instance."""
+
+    defaults_dir = Path(__file__).resolve().parents[1] / "config" / "defaults"
+    return YamlConfigProvider(defaults_dir)

shellbrain-0.1.0/app/boot/create_policy.py

@@ -0,0 +1,52 @@
+"""Boot-time helpers for normalized create-policy settings."""
+
+from typing import Any
+
+from app.boot.config import get_config_provider
+from app.core.contracts.errors import ErrorCode, ErrorDetail
+
+
+_SUPPORTED_GATES = ("schema", "semantic", "integrity")
+_SUPPORTED_SCOPES = ("repo", "global")
+
+
+def get_create_policy_settings() -> dict[str, Any]:
+    """Return normalized create-policy settings from YAML config."""
+
+    policy = get_config_provider().get_create_policy()
+    configured_gates = policy.get("gates")
+    if not isinstance(configured_gates, list) or not configured_gates:
+        raise ValueError("create_policy.gates must be a non-empty list")
+    gates = [str(gate) for gate in configured_gates if str(gate) in _SUPPORTED_GATES]
+    if len(gates) != len(configured_gates):
+        raise ValueError("create_policy.gates contains unsupported values")
+    if "schema" not in gates:
+        raise ValueError("create_policy.gates must include schema")
+    configured_defaults = policy.get("defaults")
+    if not isinstance(configured_defaults, dict):
+        raise ValueError("create_policy.defaults must be a mapping")
+    scope = configured_defaults.get("scope")
+    if not isinstance(scope, str) or scope not in _SUPPORTED_SCOPES:
+        raise ValueError("create_policy.defaults.scope must be repo or global")
+    return {
+        "gates": gates,
+        "defaults": {
+            "scope": scope,
+        },
+    }
+
+
+def get_create_hydration_defaults() -> dict[str, Any]:
+    """Return normalized create defaults used by CLI hydration."""
+
+    return dict(get_create_policy_settings()["defaults"])
+
+
+def validate_create_policy_settings() -> list[ErrorDetail]:
+    """Return structured config errors for unsupported create-policy settings."""
+
+    try:
+        get_create_policy_settings()
+    except ValueError as exc:
+        return [ErrorDetail(code=ErrorCode.INTERNAL_ERROR, message=str(exc), field="create_policy.gates")]
+    return []

shellbrain-0.1.0/app/boot/db.py

@@ -0,0 +1,70 @@
+"""This module defines boot-time factory helpers for database engine and sessions."""
+
+import os
+from pathlib import Path
+
+from app.boot.config import get_config_provider
+from app.periphery.admin.machine_state import try_load_machine_config
+from app.periphery.db.engine import get_engine
+from app.periphery.db.session import get_session_factory
+
+
+def get_db_dsn() -> str:
+    """This function resolves the database DSN from environment configuration."""
+
+    machine_config, machine_error = try_load_machine_config()
+    if machine_error:
+        raise RuntimeError(
+            "Shellbrain machine config is unreadable. Rerun `shellbrain init` to repair it."
+        )
+    if machine_config is not None:
+        return machine_config.database.app_dsn
+
+    runtime = get_config_provider().get_runtime()
+    database = runtime.get("database")
+    if not isinstance(database, dict):
+        raise RuntimeError("runtime.database must be configured")
+    dsn_env = database.get("dsn_env")
+    if not isinstance(dsn_env, str) or not dsn_env:
+        raise RuntimeError("runtime.database.dsn_env must be configured")
+    dsn = os.getenv(dsn_env)
+    if not dsn:
+        raise RuntimeError(f"{dsn_env} is not set")
+    return dsn
+
+
+def get_optional_db_dsn() -> str | None:
+    """Resolve the application DSN when present, otherwise return None."""
+
+    machine_config, machine_error = try_load_machine_config()
+    if machine_error:
+        return None
+    if machine_config is not None:
+        return machine_config.database.app_dsn
+
+    runtime = get_config_provider().get_runtime()
+    database = runtime.get("database")
+    if not isinstance(database, dict):
+        return None
+    dsn_env = database.get("dsn_env")
+    if not isinstance(dsn_env, str) or not dsn_env:
+        return None
+    return os.getenv(dsn_env)
+
+
+def get_engine_instance():
+    """This function builds a shared SQLAlchemy engine for the application."""
+
+    return get_engine(get_db_dsn())
+
+
+def get_session_factory_instance():
+    """This function builds a reusable SQLAlchemy session factory for the app."""
+
+    return get_session_factory(get_engine_instance())
+
+
+def get_defaults_dir() -> Path:
+    """This function returns the path to bundled YAML default configuration files."""
+
+    return Path(__file__).resolve().parents[1] / "config" / "defaults"

shellbrain-0.1.0/app/boot/embeddings.py

@@ -0,0 +1,55 @@
+"""This module defines boot-time wiring for embedding provider construction."""
+
+from app.boot.home import get_machine_models_dir
+from app.boot.config import get_config_provider
+from app.core.interfaces.embeddings import IEmbeddingProvider
+from app.periphery.admin.machine_state import load_machine_config
+from app.periphery.embeddings.local_provider import SentenceTransformersEmbeddingProvider
+
+
+def _get_embedding_config() -> dict:
+    """This function returns runtime embedding configuration values."""
+
+    runtime = get_config_provider().get_runtime()
+    values = runtime.get("embeddings")
+    if not isinstance(values, dict):
+        raise ValueError("runtime.embeddings must be configured")
+    return values
+
+
+def get_embedding_model_name() -> str:
+    """This function resolves the model name persisted alongside embedding vectors."""
+
+    config = _get_embedding_config()
+    provider = config.get("provider")
+    model = config.get("model")
+    if not isinstance(provider, str) or not provider:
+        raise ValueError("runtime.embeddings.provider must be configured")
+    if not isinstance(model, str) or not model:
+        raise ValueError("runtime.embeddings.model must be configured")
+    if provider == "sentence_transformers":
+        return model
+    raise ValueError(f"Unsupported embedding provider: {provider}")
+
+
+def get_embedding_provider() -> IEmbeddingProvider:
+    """This function constructs the configured local embedding provider."""
+
+    config = _get_embedding_config()
+    provider = config.get("provider")
+    model = config.get("model")
+    if not isinstance(provider, str) or not provider:
+        raise ValueError("runtime.embeddings.provider must be configured")
+    if not isinstance(model, str) or not model:
+        raise ValueError("runtime.embeddings.model must be configured")
+    if provider == "sentence_transformers":
+        machine_config = load_machine_config()
+        cache_folder = str(get_machine_models_dir())
+        if machine_config is not None:
+            cache_folder = machine_config.embeddings.cache_path
+            if machine_config.embeddings.readiness_state != "ready":
+                raise RuntimeError(
+                    "Shellbrain embeddings are not ready. Rerun `shellbrain init` to finish model setup."
+                )
+        return SentenceTransformersEmbeddingProvider(model=model, cache_folder=cache_folder)
+    raise ValueError(f"Unsupported embedding provider: {provider}")

shellbrain-0.1.0/app/boot/home.py

@@ -0,0 +1,45 @@
+"""Helpers for locating Shellbrain machine-owned runtime directories."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+
+def get_shellbrain_home() -> Path:
+    """Return the machine-owned Shellbrain home root."""
+
+    configured = os.getenv("SHELLBRAIN_HOME")
+    if configured:
+        return Path(configured).expanduser().resolve()
+    return Path("~/.shellbrain").expanduser().resolve()
+
+
+def get_machine_config_path() -> Path:
+    """Return the machine configuration file path."""
+
+    return get_shellbrain_home() / "config.toml"
+
+
+def get_machine_lock_path() -> Path:
+    """Return the machine-scoped init lock path."""
+
+    return get_shellbrain_home() / "init.lock"
+
+
+def get_machine_models_dir() -> Path:
+    """Return the machine-owned embedding model cache path."""
+
+    return get_shellbrain_home() / "models"
+
+
+def get_machine_backups_dir() -> Path:
+    """Return the machine-owned default backup directory."""
+
+    return get_shellbrain_home() / "backups"
+
+
+def get_machine_postgres_data_dir() -> Path:
+    """Return the managed Postgres bind-mounted data directory."""
+
+    return get_shellbrain_home() / "postgres-data"

shellbrain-0.1.0/app/boot/migrations.py

@@ -0,0 +1,61 @@
+"""Packaged Alembic bootstrap helpers for installed-shellbrain database migrations."""
+
+from __future__ import annotations
+
+from importlib.resources import as_file, files
+
+from alembic import command
+from alembic.config import Config
+
+from app.boot.admin_db import get_admin_db_dsn, get_backup_dir, get_backup_mirror_dir, get_instance_mode_default
+from app.boot.db import get_optional_db_dsn
+from app.periphery.admin.destructive_guard import backup_and_verify_before_destructive_action
+from app.periphery.admin.instance_guard import ensure_instance_metadata, fetch_instance_metadata
+from app.periphery.admin.privileges import reconcile_app_role_privileges
+
+
+def upgrade_database(revision: str = "head") -> None:
+    """Apply packaged Alembic migrations to the configured database."""
+
+    config = Config()
+    admin_dsn = get_admin_db_dsn()
+    if _database_has_shellbrain_objects(admin_dsn):
+        backup_and_verify_before_destructive_action(
+            admin_dsn=admin_dsn,
+            backup_root=get_backup_dir(),
+            mirror_root=get_backup_mirror_dir(),
+        )
+    config.set_main_option("sqlalchemy.url", admin_dsn)
+    with as_file(files("app").joinpath("migrations")) as migrations_path:
+        config.set_main_option("script_location", str(migrations_path))
+        command.upgrade(config, revision)
+    if fetch_instance_metadata(admin_dsn) is None:
+        ensure_instance_metadata(
+            admin_dsn,
+            instance_mode=get_instance_mode_default(),
+            created_by="app.admin.migrate",
+            notes="Stamped by packaged migration runner.",
+        )
+    app_dsn = get_optional_db_dsn()
+    if app_dsn:
+        reconcile_app_role_privileges(admin_dsn=admin_dsn, app_dsn=app_dsn)
+
+
+def _database_has_shellbrain_objects(admin_dsn: str) -> bool:
+    """Return whether the target database already contains Shellbrain-managed tables."""
+
+    import psycopg
+
+    with psycopg.connect(admin_dsn.replace("+psycopg", "")) as conn:
+        with conn.cursor() as cur:
+            cur.execute(
+                """
+                SELECT EXISTS (
+                  SELECT 1
+                  FROM information_schema.tables
+                  WHERE table_schema = 'public'
+                    AND table_name IN ('memories', 'episodes', 'episode_events', 'operation_invocations')
+                )
+                """
+            )
+            return bool(cur.fetchone()[0])