shellbrain 0.1.20__tar.gz → 0.1.22__tar.gz

{shellbrain-0.1.20 → shellbrain-0.1.22}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: shellbrain
-Version: 0.1.20
+Version: 0.1.22
 Summary: Repo-scoped Shellbrain CLI with explicit evidence-backed writes.
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown

shellbrain-0.1.22/app/boot/_dsn_resolution.py

@@ -0,0 +1,45 @@
+"""Shared helpers for resolving configured application and admin DSNs."""
+
+from __future__ import annotations
+
+import os
+from typing import Any, Callable
+
+
+def resolve_database_dsn(
+    *,
+    load_machine_config: Callable[[], tuple[object | None, str | None]],
+    runtime_provider: Callable[[], dict[str, Any]],
+    machine_field: str,
+    runtime_env_key: str,
+    required: bool,
+) -> str | None:
+    """Resolve one configured DSN from machine config first, then runtime env config."""
+
+    machine_config, machine_error = load_machine_config()
+    if machine_error:
+        if required:
+            raise RuntimeError(
+                "Shellbrain machine config is unreadable. Rerun `shellbrain init` to repair it."
+            )
+        return None
+    if machine_config is not None:
+        return getattr(machine_config.database, machine_field)
+
+    runtime = runtime_provider()
+    database = runtime.get("database")
+    if not isinstance(database, dict):
+        if required:
+            raise RuntimeError("runtime.database must be configured")
+        return None
+
+    env_name = database.get(runtime_env_key)
+    if not isinstance(env_name, str) or not env_name:
+        if required:
+            raise RuntimeError(f"runtime.database.{runtime_env_key} must be configured")
+        return None
+
+    dsn = os.getenv(env_name)
+    if not dsn and required:
+        raise RuntimeError(f"{env_name} is not set")
+    return dsn or None

{shellbrain-0.1.20 → shellbrain-0.1.22}/app/boot/admin_db.py

@@ -5,6 +5,7 @@ from __future__ import annotations
 import os
 from pathlib import Path
 
+from app.boot._dsn_resolution import resolve_database_dsn
 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
@@ -13,44 +14,15 @@ 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")
+    dsn = _resolve_admin_db_dsn(required=True)
+    assert dsn is not None
     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)
+    return _resolve_admin_db_dsn(required=False)
 
 
 def get_backup_dir() -> Path:
@@ -86,3 +58,15 @@ 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"
+
+
+def _resolve_admin_db_dsn(*, required: bool) -> str | None:
+    """Resolve the admin DSN from machine config or runtime env config."""
+
+    return resolve_database_dsn(
+        load_machine_config=try_load_machine_config,
+        runtime_provider=lambda: get_config_provider().get_runtime(),
+        machine_field="admin_dsn",
+        runtime_env_key="admin_dsn_env",
+        required=required,
+    )

shellbrain-0.1.22/app/boot/db.py

@@ -0,0 +1,45 @@
+"""This module defines boot-time factory helpers for database engine and sessions."""
+
+from app.boot._dsn_resolution import resolve_database_dsn
+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."""
+
+    dsn = _resolve_app_db_dsn(required=True)
+    assert dsn is not None
+    return dsn
+
+
+def get_optional_db_dsn() -> str | None:
+    """Resolve the application DSN when present, otherwise return None."""
+
+    return _resolve_app_db_dsn(required=False)
+
+
+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 _resolve_app_db_dsn(*, required: bool) -> str | None:
+    """Resolve the application DSN from machine config or runtime env config."""
+
+    return resolve_database_dsn(
+        load_machine_config=try_load_machine_config,
+        runtime_provider=lambda: get_config_provider().get_runtime(),
+        machine_field="app_dsn",
+        runtime_env_key="dsn_env",
+        required=required,
+    )

{shellbrain-0.1.20 → shellbrain-0.1.22}/app/boot/read_policy.py

@@ -4,6 +4,7 @@ from copy import deepcopy
 from typing import Any
 
 from app.boot.config import get_config_provider
+from app.core.entities.memory import MATURE_MEMORY_KIND_VALUES
 
 
 _SUPPORTED_MODES = ("targeted", "ambient")
@@ -164,6 +165,8 @@ def resolve_read_payload_defaults(payload: dict[str, Any]) -> dict[str, Any]:
         resolved["include_global"] = settings["include_global"]
     if resolved.get("limit") is None:
         resolved["limit"] = settings["limits_by_mode"][resolved["mode"]]
+    if resolved.get("kinds") is None:
+        resolved["kinds"] = list(MATURE_MEMORY_KIND_VALUES)
 
     incoming_expand = resolved.get("expand")
     merged_expand = deepcopy(settings["expand"])

{shellbrain-0.1.20 → shellbrain-0.1.22}/app/core/contracts/requests.py

@@ -5,6 +5,10 @@ from typing import Annotated, Literal
 from pydantic import BaseModel, ConfigDict, Field, field_validator
 
 
+MemoryKindValue = Literal["problem", "solution", "failed_tactic", "fact", "preference", "change", "frontier"]
+AssociationRelationValue = Literal["depends_on", "associated_with", "matures_into"]
+
+
 class StrictBaseModel(BaseModel):
     """This base model enforces strict schemas by rejecting unknown fields."""
 
@@ -30,9 +34,7 @@ class MemoryReadRequest(StrictBaseModel):
     mode: Literal["ambient", "targeted"]
     query: str = Field(min_length=1)
     include_global: bool | None = None
-    kinds: (
-        list[Literal["problem", "solution", "failed_tactic", "fact", "preference", "change"]] | None
-    ) = None
+    kinds: list[MemoryKindValue] | None = Field(default=None, min_length=1)
     limit: int | None = Field(default=None, ge=1, le=100)
     expand: ReadExpandRequest | None = None
 
@@ -40,8 +42,8 @@ class MemoryReadRequest(StrictBaseModel):
     @classmethod
     def _validate_kinds_unique(
         cls,
-        value: list[Literal["problem", "solution", "failed_tactic", "fact", "preference", "change"]] | None,
-    ) -> list[Literal["problem", "solution", "failed_tactic", "fact", "preference", "change"]] | None:
+        value: list[MemoryKindValue] | None,
+    ) -> list[MemoryKindValue] | None:
         """This validator enforces unique kinds filters for read requests."""
 
         if value is None:
@@ -63,7 +65,7 @@ class MemoryCreateAssociationLink(StrictBaseModel):
     """This model defines a typed explicit association link payload on create."""
 
     to_memory_id: str
-    relation_type: Literal["depends_on", "associated_with"]
+    relation_type: AssociationRelationValue
     confidence: float | None = Field(default=None, ge=0.0, le=1.0)
     salience: float | None = Field(default=None, ge=0.0, le=1.0)
     rationale: str | None = None
@@ -91,7 +93,7 @@ class MemoryCreateBody(StrictBaseModel):
 
     text: str
     scope: Literal["repo", "global"]
-    kind: Literal["problem", "solution", "failed_tactic", "fact", "preference", "change"]
+    kind: MemoryKindValue
     rationale: str | None = None
     links: MemoryCreateLinks = Field(default_factory=MemoryCreateLinks)
     evidence_refs: list[str] = Field(min_length=1)
@@ -165,7 +167,7 @@ class AssociationLinkUpdate(StrictBaseModel):
 
     type: Literal["association_link"]
     to_memory_id: str
-    relation_type: Literal["depends_on", "associated_with"]
+    relation_type: AssociationRelationValue
     confidence: float | None = Field(default=None, ge=0.0, le=1.0)
     salience: float | None = Field(default=None, ge=0.0, le=1.0)
     rationale: str | None = None

{shellbrain-0.1.20 → shellbrain-0.1.22}/app/core/entities/associations.py

@@ -9,6 +9,7 @@ class AssociationRelationType(str, Enum):
 
     DEPENDS_ON = "depends_on"
     ASSOCIATED_WITH = "associated_with"
+    MATURES_INTO = "matures_into"
 
 
 class AssociationSourceMode(str, Enum):

{shellbrain-0.1.20 → shellbrain-0.1.22}/app/core/entities/memory.py

@@ -2,6 +2,7 @@
 
 from dataclasses import dataclass
 from enum import Enum
+from typing import Final
 
 
 class MemoryKind(str, Enum):
@@ -13,6 +14,25 @@ class MemoryKind(str, Enum):
     FACT = "fact"
     PREFERENCE = "preference"
     CHANGE = "change"
+    FRONTIER = "frontier"
+
+
+MATURE_MEMORY_KINDS: Final[tuple[MemoryKind, ...]] = (
+    MemoryKind.PROBLEM,
+    MemoryKind.SOLUTION,
+    MemoryKind.FAILED_TACTIC,
+    MemoryKind.FACT,
+    MemoryKind.PREFERENCE,
+    MemoryKind.CHANGE,
+)
+MATURE_MEMORY_KIND_VALUES: Final[tuple[str, ...]] = tuple(kind.value for kind in MATURE_MEMORY_KINDS)
+
+
+def is_mature_memory_kind(kind: MemoryKind | str) -> bool:
+    """Return whether one kind belongs to the mature durable-memory set."""
+
+    normalized_kind = kind if isinstance(kind, MemoryKind) else MemoryKind(kind)
+    return normalized_kind in MATURE_MEMORY_KINDS
 
 
 class MemoryScope(str, Enum):

{shellbrain-0.1.20 → shellbrain-0.1.22}/app/core/policies/read_policy/pipeline.py

@@ -8,10 +8,8 @@ from app.core.interfaces.retrieval import IVectorSearch
 from app.core.policies.read_policy.context_pack_builder import assemble_context_pack
 from app.core.policies.read_policy.expansion import expand_candidates
 from app.core.policies.read_policy.fusion_rrf import fuse_with_rrf
-from app.core.policies.read_policy.scenario_lift import derive_scenarios
 from app.core.policies.read_policy.scoring import score_candidates
 from app.core.policies.read_policy.seed_retrieval import retrieve_seeds
-from app.core.policies.read_policy.utility_prior import apply_utility_prior
 
 
 def build_context_pack(
@@ -45,13 +43,8 @@ def build_context_pack(
         "implicit": expanded_candidates["implicit"],
     }
     scored_candidates = score_candidates(bucketed_candidates, payload)
-    adjusted_candidates = {
-        bucket_name: apply_utility_prior(candidates, payload)
-        for bucket_name, candidates in scored_candidates.items()
-    }
-    pack = assemble_context_pack(adjusted_candidates, payload)
-    hydrated_pack = _hydrate_pack_items(pack, memories)
-    return derive_scenarios(hydrated_pack, payload)["pack"]
+    pack = assemble_context_pack(scored_candidates, payload)
+    return _hydrate_pack_items(pack, memories)
 
 
 def _resolve_read_defaults(payload: dict[str, Any]) -> dict[str, Any]:

shellbrain-0.1.22/app/migrations/versions/20260410_0009_frontier_memory_family.py

@@ -0,0 +1,96 @@
+"""Add frontier memory kind and matures_into association relation constraints."""
+
+from alembic import op
+
+
+revision = "20260410_0009"
+down_revision = "20260320_0008"
+branch_labels = None
+depends_on = None
+
+
+def _drop_check_constraint(table_name: str, required_snippets: list[str]) -> None:
+    """Drop one unnamed CHECK constraint by matching its rendered definition."""
+
+    like_clauses = " AND ".join(
+        f"pg_get_constraintdef(con.oid) LIKE '%{snippet}%'" for snippet in required_snippets
+    )
+    op.execute(
+        f"""
+        DO $$
+        DECLARE constraint_name TEXT;
+        BEGIN
+          SELECT con.conname
+          INTO constraint_name
+          FROM pg_constraint con
+          JOIN pg_class rel ON rel.oid = con.conrelid
+          JOIN pg_namespace nsp ON nsp.oid = rel.relnamespace
+          WHERE nsp.nspname = current_schema()
+            AND rel.relname = '{table_name}'
+            AND con.contype = 'c'
+            AND {like_clauses}
+          LIMIT 1;
+
+          IF constraint_name IS NOT NULL THEN
+            EXECUTE format('ALTER TABLE {table_name} DROP CONSTRAINT %I', constraint_name);
+          END IF;
+        END $$;
+        """
+    )
+
+
+def upgrade() -> None:
+    """Widen durable-memory and association relation constraints for frontier support."""
+
+    _drop_check_constraint("memories", ["kind", "problem", "change"])
+    _drop_check_constraint("association_edges", ["relation_type", "depends_on", "associated_with"])
+    _drop_check_constraint("association_observations", ["relation_type", "depends_on", "associated_with"])
+
+    op.execute(
+        """
+        ALTER TABLE memories
+        ADD CONSTRAINT ck_memories_kind_ratified
+        CHECK (kind IN ('problem', 'solution', 'failed_tactic', 'fact', 'preference', 'change', 'frontier'));
+
+        ALTER TABLE association_edges
+        ADD CONSTRAINT ck_association_edges_relation_type
+        CHECK (relation_type IN ('depends_on', 'associated_with', 'matures_into'));
+
+        ALTER TABLE association_observations
+        ADD CONSTRAINT ck_association_observations_relation_type
+        CHECK (relation_type IN ('depends_on', 'associated_with', 'matures_into'));
+        """
+    )
+
+
+def downgrade() -> None:
+    """Restore the prior durable-memory and association relation constraint set."""
+
+    op.execute(
+        """
+        ALTER TABLE association_observations
+        DROP CONSTRAINT IF EXISTS ck_association_observations_relation_type;
+
+        ALTER TABLE association_edges
+        DROP CONSTRAINT IF EXISTS ck_association_edges_relation_type;
+
+        ALTER TABLE memories
+        DROP CONSTRAINT IF EXISTS ck_memories_kind_ratified;
+        """
+    )
+
+    op.execute(
+        """
+        ALTER TABLE memories
+        ADD CONSTRAINT ck_memories_kind_ratified
+        CHECK (kind IN ('problem', 'solution', 'failed_tactic', 'fact', 'preference', 'change'));
+
+        ALTER TABLE association_edges
+        ADD CONSTRAINT ck_association_edges_relation_type
+        CHECK (relation_type IN ('depends_on', 'associated_with'));
+
+        ALTER TABLE association_observations
+        ADD CONSTRAINT ck_association_observations_relation_type
+        CHECK (relation_type IN ('depends_on', 'associated_with'));
+        """
+    )

{shellbrain-0.1.20 → shellbrain-0.1.22}/app/onboarding_assets/claude/skills/shellbrain-session-start/SKILL.md

@@ -26,10 +26,10 @@ Treat current repo state as ground truth. Treat Shellbrain as advisory long-term
 2. Otherwise, do not rerun `init` just because a new agent session started. Start with focused `read` queries right away.
 3. If readiness is unclear, inspect with `shellbrain admin doctor` instead of rerunning `init` by reflex.
 4. If `doctor` reports `repair_needed`, rerun `shellbrain init` instead of trying to repair Shellbrain manually.
-5. In Claude Code, if direct `shellbrain` calls fail in the current session, retry through a login shell that sources the user's login profile:
-   - `zsh -lc 'source ~/.zprofile >/dev/null 2>&1; shellbrain --help'`
-   - `bash -lc 'source ~/.bash_profile >/dev/null 2>&1; shellbrain --help'`
-6. If the wrapped login-shell check still cannot find `shellbrain`, inspect Python's user script directory:
+5. In Claude Code, if direct `shellbrain` calls fail in the current session, do a one-time login-shell retry that sources the user's login profile and resolves the CLI path:
+   - `zsh -lc 'source ~/.zprofile >/dev/null 2>&1; command -v shellbrain'`
+   - `bash -lc 'source ~/.bash_profile >/dev/null 2>&1; command -v shellbrain'`
+6. Do not keep sourcing the login profile on every Shellbrain command. Once `shellbrain` is visible, use plain `shellbrain ...`. If the host tool keeps starting fresh shells without your login PATH, reuse the absolute path returned by `command -v shellbrain` instead of re-sourcing the profile on every call. If the one-time login-shell retry still cannot find `shellbrain`, inspect Python's user script directory:
    - `python3 -c "import sysconfig; print(sysconfig.get_path('scripts', 'posix_user'))"`
    If `shellbrain` exists there, call it directly or add that directory to the login profile PATH and retry. If it does not, reinstall the Shellbrain CLI.
 7. Resolve the target repo:

{shellbrain-0.1.20 → shellbrain-0.1.22}/app/onboarding_assets/codex/shellbrain-session-start/SKILL.md

@@ -31,10 +31,10 @@ Treat current repo state as ground truth. Treat Shellbrain as advisory long-term
 2. Otherwise, do not rerun `init` just because a new agent session started. Start with focused `read` queries right away.
 3. If readiness is unclear, inspect with `shellbrain admin doctor` instead of rerunning `init` by reflex.
 4. If `doctor` reports `repair_needed`, rerun `shellbrain init` instead of trying to repair Shellbrain manually.
-5. In Codex or similar tool shells, if direct `shellbrain` calls fail in the current session, retry through a login shell that sources the user's login profile:
-   - `zsh -lc 'source ~/.zprofile >/dev/null 2>&1; shellbrain --help'`
-   - `bash -lc 'source ~/.bash_profile >/dev/null 2>&1; shellbrain --help'`
-6. If the wrapped login-shell check still cannot find `shellbrain`, inspect Python's user script directory:
+5. In Codex or similar tool shells, if direct `shellbrain` calls fail in the current session, do a one-time login-shell retry that sources the user's login profile and resolves the CLI path:
+   - `zsh -lc 'source ~/.zprofile >/dev/null 2>&1; command -v shellbrain'`
+   - `bash -lc 'source ~/.bash_profile >/dev/null 2>&1; command -v shellbrain'`
+6. Do not keep sourcing the login profile on every Shellbrain command. Once `shellbrain` is visible, use plain `shellbrain ...`. If the host tool keeps starting fresh shells without your login PATH, reuse the absolute path returned by `command -v shellbrain` instead of re-sourcing the profile on every call. If the one-time login-shell retry still cannot find `shellbrain`, inspect Python's user script directory:
    - `python3 -c "import sysconfig; print(sysconfig.get_path('scripts', 'posix_user'))"`
    If `shellbrain` exists there, call it directly or add that directory to the login profile PATH and retry. If it does not, reinstall the Shellbrain CLI.
 7. Resolve the target repo:

{shellbrain-0.1.20 → shellbrain-0.1.22}/app/onboarding_assets/codex/shellbrain-session-start/references/session-workflow.md

@@ -43,13 +43,13 @@ Use Shellbrain normally after `doctor` shows the machine bootstrap is `ready` an
 
 If `doctor` reports `repair_needed`, rerun `shellbrain init` instead of trying to patch Shellbrain manually.
 
-In Codex desktop and similar tool shells, if direct `shellbrain` calls fail in the current session, retry through a login shell that sources `~/.zprofile`:
+In Codex desktop and similar tool shells, if direct `shellbrain` calls fail in the current session, do a one-time login-shell retry that sources `~/.zprofile` and resolves the CLI path:
 
 ```bash
-zsh -lc 'source ~/.zprofile >/dev/null 2>&1; shellbrain --help'
+zsh -lc 'source ~/.zprofile >/dev/null 2>&1; command -v shellbrain'
 ```
 
-Assume Shellbrain comes from a one-time machine install. Do not rerun `init` just because a new agent starts. If direct calls fail in the current Codex session, keep using the `zsh -lc 'source ~/.zprofile ...'` wrapper for Shellbrain invocations before declaring Shellbrain blocked. Only if the wrapped check fails should you ask the operator to restore the machine-level install.
+Assume Shellbrain comes from a one-time machine install. Do not rerun `init` just because a new agent starts. Do not keep sourcing the login profile on every Shellbrain command. The login-shell step is only a one-time availability and PATH check when direct calls fail. Once `shellbrain` is visible, use plain `shellbrain ...`. If the host tool keeps starting fresh shells without your login PATH, resolve the absolute path once with `command -v shellbrain` and reuse that path for later invocations. Only if the one-time login-shell retry fails should you ask the operator to restore the machine-level install.
 
 Drop into the advanced/operator path only when `doctor` says the managed runtime is blocked.
 
@@ -228,7 +228,7 @@ Important modeling pattern for changed truth:
   Do not rerun `init`. Start with `read`. Use `doctor` only if readiness is unclear.
 
 - `shellbrain: command not found`
-  Retry through `zsh -lc 'source ~/.zprofile >/dev/null 2>&1; shellbrain --help'` first. Only if that still fails should you ask the operator to restore the one-time machine install.
+  Retry through `zsh -lc 'source ~/.zprofile >/dev/null 2>&1; command -v shellbrain'` first. Do not keep prefixing every Shellbrain command with profile sourcing. Only if that still fails should you ask the operator to restore the one-time machine install.
 
 - `shellbrain init` fails or `doctor` shows `repair_needed`
   Rerun `shellbrain init`. That is the normal repair path.

{shellbrain-0.1.20 → shellbrain-0.1.22}/app/onboarding_assets/cursor/skills/shellbrain-session-start/SKILL.md

@@ -27,10 +27,10 @@ Shellbrain has two layers:
 2. Otherwise, do not rerun `init` just because a new agent session started. Start with focused `read` queries right away.
 3. If readiness is unclear, inspect with `shellbrain admin doctor` instead of rerunning `init` by reflex.
 4. If `doctor` reports `repair_needed`, rerun `shellbrain init`.
-5. If direct `shellbrain` calls fail in the current Cursor shell, retry through a login shell that sources the user's login profile:
-   - `zsh -lc 'source ~/.zprofile >/dev/null 2>&1; shellbrain --help'`
-   - `bash -lc 'source ~/.bash_profile >/dev/null 2>&1; shellbrain --help'`
-6. If the wrapped login-shell check still cannot find `shellbrain`, inspect Python's user script directory:
+5. If direct `shellbrain` calls fail in the current Cursor shell, do a one-time login-shell retry that sources the user's login profile and resolves the CLI path:
+   - `zsh -lc 'source ~/.zprofile >/dev/null 2>&1; command -v shellbrain'`
+   - `bash -lc 'source ~/.bash_profile >/dev/null 2>&1; command -v shellbrain'`
+6. Do not keep sourcing the login profile on every Shellbrain command. Once `shellbrain` is visible, use plain `shellbrain ...`. If the host tool keeps starting fresh shells without your login PATH, reuse the absolute path returned by `command -v shellbrain` instead of re-sourcing the profile on every call. If the one-time login-shell retry still cannot find `shellbrain`, inspect Python's user script directory:
    - `python3 -c "import sysconfig; print(sysconfig.get_path('scripts', 'posix_user'))"`
 7. Resolve the target repo:
    - use the current working directory when already inside the repo

{shellbrain-0.1.20 → shellbrain-0.1.22}/app/periphery/admin/repo_state.py

@@ -124,35 +124,6 @@ def save_repo_registration(registration: RepoRegistration, repo_root: Path) -> P
     return path
 
 
-def register_repo(
-    *,
-    repo_root: Path,
-    machine_instance_id: str,
-    explicit_repo_id: str | None = None,
-    claude_status: str = "not_checked",
-    claude_settings_path: str | None = None,
-    claude_note: str | None = None,
-) -> RepoRegistration:
-    """Resolve and persist one repo registration."""
-
-    identity = resolve_repo_identity(repo_root=repo_root, explicit_repo_id=explicit_repo_id)
-    registration_root = Path(identity.git_root).resolve() if identity.git_root is not None else Path(repo_root).resolve()
-    registration = RepoRegistration(
-        repo_state_version=REPO_STATE_VERSION,
-        repo_id=identity.repo_id,
-        identity_strength=identity.identity_strength,
-        git_root=identity.git_root,
-        source_remote=identity.source_remote,
-        registered_at=datetime.now(timezone.utc).isoformat(),
-        machine_instance_id=machine_instance_id,
-        claude_status=claude_status,
-        claude_settings_path=claude_settings_path,
-        claude_note=claude_note,
-    )
-    save_repo_registration(registration, registration_root)
-    return registration
-
-
 def register_repo_for_target(
     *,
     repo_root: Path,

{shellbrain-0.1.20 → shellbrain-0.1.22}/app/periphery/cli/schema_validation.py

@@ -8,6 +8,7 @@ from app.core.contracts.errors import ErrorCode, ErrorDetail
 from app.core.contracts.requests import (
     BatchUtilityVoteItem,
     EpisodeEventsRequest,
+    MemoryKindValue,
     MemoryBatchUpdateRequest,
     MemoryCreateLinks,
     MemoryCreateRequest,
@@ -27,17 +28,15 @@ class AgentReadRequest(StrictBaseModel):
     mode: Literal["ambient", "targeted"] | None = None
     query: str = Field(min_length=1)
     include_global: bool | None = None
-    kinds: (
-        list[Literal["problem", "solution", "failed_tactic", "fact", "preference", "change"]] | None
-    ) = None
+    kinds: list[MemoryKindValue] | None = Field(default=None, min_length=1)
     limit: int | None = Field(default=None, ge=1, le=100)
 
     @field_validator("kinds")
     @classmethod
     def _validate_kinds_unique(
         cls,
-        value: list[Literal["problem", "solution", "failed_tactic", "fact", "preference", "change"]] | None,
-    ) -> list[Literal["problem", "solution", "failed_tactic", "fact", "preference", "change"]] | None:
+        value: list[MemoryKindValue] | None,
+    ) -> list[MemoryKindValue] | None:
         """This validator enforces unique kinds filters for agent read requests."""
 
         if value is None:
@@ -52,7 +51,7 @@ class AgentCreateBody(StrictBaseModel):
 
     text: str
     scope: Literal["repo", "global"] | None = None
-    kind: Literal["problem", "solution", "failed_tactic", "fact", "preference", "change"]
+    kind: MemoryKindValue
     rationale: str | None = None
     links: MemoryCreateLinks = Field(default_factory=MemoryCreateLinks)
     evidence_refs: list[str] = Field(min_length=1)

{shellbrain-0.1.20 → shellbrain-0.1.22}/app/periphery/db/repos/relational/read_policy_repo.py

@@ -150,7 +150,24 @@ class ReadPolicyRepo(IReadPolicyRepo):
                 *self._visibility_filters(repo_id=repo_id, include_global=include_global, kinds=kinds),
             )
         )
-        union_stmt = union_all(from_stmt, reverse_associated_stmt).subquery()
+        reverse_matures_into_stmt = (
+            select(
+                association_edges.c.from_memory_id.label("memory_id"),
+                association_edges.c.relation_type,
+                association_edges.c.strength,
+                literal("association").label("expansion_type"),
+            )
+            .select_from(association_edges.join(memories, memories.c.id == association_edges.c.from_memory_id))
+            .where(
+                association_edges.c.repo_id == repo_id,
+                association_edges.c.to_memory_id == anchor_memory_id,
+                association_edges.c.relation_type == "matures_into",
+                association_edges.c.state != "deprecated",
+                association_edges.c.strength >= min_strength,
+                *self._visibility_filters(repo_id=repo_id, include_global=include_global, kinds=kinds),
+            )
+        )
+        union_stmt = union_all(from_stmt, reverse_associated_stmt, reverse_matures_into_stmt).subquery()
         stmt = (
             select(
                 union_stmt.c.memory_id,

{shellbrain-0.1.20 → shellbrain-0.1.22}/app/periphery/identity/claude_runtime.py

@@ -46,17 +46,6 @@ def detect_claude_runtime_without_hook() -> bool:
     )
 
 
-def detect_claude_runtime_signal() -> bool:
-    """Return whether one real Claude runtime signal is present in the current environment."""
-
-    if os.getenv("SHELLBRAIN_HOST_APP") == "claude_code":
-        return True
-    return any(
-        os.getenv(name)
-        for name in ("CLAUDE_SESSION_ID", "CLAUDE_CODE_REMOTE_SESSION_ID", "CLAUDE_CODE_AGENT_NAME")
-    )
-
-
 def resolve_trusted_claude_transcript_path() -> Path | None:
     """Return the trusted Claude transcript path injected by the Shellbrain hook when present."""
 

{shellbrain-0.1.20 → shellbrain-0.1.22}/app/periphery/identity/compatibility.py

@@ -31,8 +31,3 @@ def host_identity_drifted_error(*, caller_id: str) -> ErrorDetail:
         message=f"Trusted caller identity drifted and could not be resolved for `{caller_id}`. Verify the host thread/session still exists and rerun `events`.",
     )
 
-
-def transcript_source_not_found_error(*, message: str) -> ErrorDetail:
-    """Return the canonical error for transcript-source resolution failures."""
-
-    return ErrorDetail(code=ErrorCode.TRANSCRIPT_SOURCE_NOT_FOUND, message=message)