@simbimbo/memory-ocmemog 0.1.11 → 0.1.12

package/brain/runtime/memory/vector_index.py

@@ -1,325 +1,3 @@
 from __future__ import annotations
 
-import hashlib
-import json
-import math
-import re
-import threading
-from typing import Any, Dict, List, Iterable
-
-from brain.runtime import state_store
-from brain.runtime.instrumentation import emit_event
-from brain.runtime.memory import embedding_engine, store, memory_links
-from brain.runtime.security import redaction
-
-LOGFILE = state_store.reports_dir() / "brain_memory.log.jsonl"
-
-EMBEDDING_TABLES: tuple[str, ...] = tuple(store.MEMORY_TABLES)
-_REBUILD_LOCK = threading.Lock()
-_WRITE_CHUNK_SIZE = 64
-_EMBEDDING_TEXT_LIMIT = 8000
-_HTML_TAG_RE = re.compile(r"<[^>]+>")
-_WHITESPACE_RE = re.compile(r"\s+")
-
-
-def _ensure_vector_table(conn) -> None:
-    conn.execute(
-        """
-        CREATE TABLE IF NOT EXISTS vector_embeddings (
-            id TEXT PRIMARY KEY,
-            source_type TEXT NOT NULL,
-            source_id TEXT NOT NULL,
-            embedding TEXT NOT NULL,
-            created_at TEXT NOT NULL DEFAULT (datetime('now'))
-        )
-        """
-    )
-    conn.execute(
-        "CREATE INDEX IF NOT EXISTS idx_vector_embeddings_source ON vector_embeddings (source_type, source_id)"
-    )
-
-
-def _cosine_similarity(a: List[float], b: List[float]) -> float:
-    if not a or not b:
-        return 0.0
-    size = min(len(a), len(b))
-    if size == 0:
-        return 0.0
-    a2 = a[:size]
-    b2 = b[:size]
-    dot = sum(x * y for x, y in zip(a2, b2))
-    mag_a = math.sqrt(sum(x * x for x in a2))
-    mag_b = math.sqrt(sum(x * x for x in b2))
-    if mag_a == 0.0 or mag_b == 0.0:
-        return 0.0
-    return dot / (mag_a * mag_b)
-
-
-def insert_memory(memory_id: int, content: str, confidence: float, *, source_type: str = "knowledge") -> None:
-    source_type = source_type if source_type in EMBEDDING_TABLES else "knowledge"
-    redacted_content, changed = redaction.redact_text(content)
-    embedding = embedding_engine.generate_embedding(redacted_content)
-    metadata_json = json.dumps({"redacted": changed, "source_type": source_type})
-
-    def _write() -> None:
-        conn = store.connect()
-        try:
-            _ensure_vector_table(conn)
-            conn.execute(
-                "INSERT INTO memory_index (source, confidence, metadata_json, content, schema_version) VALUES (?, ?, ?, ?, ?)",
-                (
-                    f"{source_type}:{memory_id}",
-                    confidence,
-                    metadata_json,
-                    redacted_content,
-                    store.SCHEMA_VERSION,
-                ),
-            )
-            if embedding:
-                emit_event(LOGFILE, "brain_memory_embedding_generated", status="ok", source_id=str(memory_id))
-                conn.execute(
-                    """
-                    INSERT INTO vector_embeddings (id, source_type, source_id, embedding)
-                    VALUES (?, ?, ?, ?)
-                    ON CONFLICT(id) DO UPDATE SET embedding=excluded.embedding
-                    """,
-                    (f"{source_type}:{memory_id}", source_type, str(memory_id), json.dumps(embedding)),
-                )
-            conn.commit()
-        finally:
-            conn.close()
-
-    store.submit_write(_write, timeout=30.0)
-
-
-def _load_table_rows(table: str, *, limit: int | None = None, descending: bool = False, missing_only: bool = False) -> List[Dict[str, Any]]:
-    conn = store.connect()
-    try:
-        order = "DESC" if descending else "ASC"
-        where = ""
-        params: list[Any] = []
-        if missing_only:
-            where = " WHERE CAST(id AS TEXT) NOT IN (SELECT source_id FROM vector_embeddings WHERE source_type = ?)"
-            params.append(table)
-        if limit is None:
-            rows = conn.execute(
-                f"SELECT id, content, confidence, metadata_json FROM {table}{where} ORDER BY id {order}",
-                tuple(params),
-            ).fetchall()
-        else:
-            rows = conn.execute(
-                f"SELECT id, content, confidence, metadata_json FROM {table}{where} ORDER BY id {order} LIMIT ?",
-                tuple(params + [limit]),
-            ).fetchall()
-    finally:
-        conn.close()
-    return [dict(row) for row in rows]
-
-
-def _embedding_input(text: str, *, table: str = "knowledge") -> str:
-    cleaned = _HTML_TAG_RE.sub(" ", text)
-    cleaned = _WHITESPACE_RE.sub(" ", cleaned).strip()
-    lowered = cleaned.lower()
-    artifactish = (
-        "| chunk " in lowered
-        or ".sql" in lowered
-        or "topology/" in lowered
-        or cleaned.count("),(") >= 8
-    )
-    if table == "knowledge" and artifactish:
-        return cleaned[:500]
-    if table == "knowledge" and len(cleaned) > 9000:
-        return cleaned[:1000]
-    if table == "reflections" and len(cleaned) > 8000:
-        return cleaned[:1200]
-    if len(cleaned) > 20000:
-        return cleaned[:2000]
-    if len(cleaned) > 12000:
-        return cleaned[:4000]
-    return cleaned[:_EMBEDDING_TEXT_LIMIT]
-
-
-def _prepare_embedding_rows(rows: Iterable[Dict[str, Any]], *, table: str) -> List[Dict[str, Any]]:
-    prepared: List[Dict[str, Any]] = []
-    embedding_cache: Dict[str, List[float] | None] = {}
-    for row in rows:
-        content = str(row.get("content") or "")
-        redacted_content, changed = redaction.redact_text(content)
-        embedding_input = _embedding_input(redacted_content, table=table)
-        cache_key = hashlib.sha256(embedding_input.encode("utf-8", errors="ignore")).hexdigest()
-        if cache_key in embedding_cache:
-            embedding = embedding_cache[cache_key]
-        else:
-            embedding = embedding_engine.generate_embedding(embedding_input)
-            embedding_cache[cache_key] = embedding
-        if not embedding:
-            continue
-        try:
-            metadata = json.loads(row.get("metadata_json") or "{}")
-        except Exception:
-            metadata = {}
-        metadata["redacted"] = changed
-        prepared.append(
-            {
-                "id": int(row["id"]),
-                "content": redacted_content,
-                "confidence": float(row.get("confidence") or 0.0),
-                "metadata_json": json.dumps(metadata),
-                "embedding": json.dumps(embedding),
-                "source_type": table,
-            }
-        )
-    return prepared
-
-
-def _write_embedding_chunk(table: str, rows: List[Dict[str, Any]]) -> int:
-    if not rows:
-        return 0
-
-    def _write() -> int:
-        conn = store.connect()
-        try:
-            _ensure_vector_table(conn)
-            for row in rows:
-                conn.execute(
-                    f"UPDATE {table} SET content=?, metadata_json=? WHERE id=?",
-                    (row["content"], row["metadata_json"], row["id"]),
-                )
-                conn.execute(
-                    """
-                    INSERT INTO vector_embeddings (id, source_type, source_id, embedding)
-                    VALUES (?, ?, ?, ?)
-                    ON CONFLICT(id) DO UPDATE SET embedding=excluded.embedding
-                    """,
-                    (f"{table}:{row['id']}", table, str(row["id"]), row["embedding"]),
-                )
-            conn.commit()
-            return len(rows)
-        finally:
-            conn.close()
-
-    return int(store.submit_write(_write, timeout=60.0))
-
-
-def index_memory(limit: int = 100, *, tables: Iterable[str] | None = None) -> int:
-    emit_event(LOGFILE, "brain_memory_vector_index_start", status="ok")
-    count = 0
-    for table in (tables or EMBEDDING_TABLES):
-        if table not in EMBEDDING_TABLES:
-            continue
-        prepared = _prepare_embedding_rows(_load_table_rows(table, limit=limit, descending=True), table=table)
-        for offset in range(0, len(prepared), _WRITE_CHUNK_SIZE):
-            count += _write_embedding_chunk(table, prepared[offset: offset + _WRITE_CHUNK_SIZE])
-    emit_event(LOGFILE, "brain_memory_vector_index_complete", status="ok", indexed=count)
-    return count
-
-
-def rebuild_vector_index(*, tables: Iterable[str] | None = None) -> int:
-    emit_event(LOGFILE, "brain_memory_vector_rebuild_start", status="ok")
-    if not _REBUILD_LOCK.acquire(blocking=False):
-        emit_event(LOGFILE, "brain_memory_vector_rebuild_complete", status="skipped", reason="already_running")
-        return 0
-    count = 0
-    try:
-        requested_tables = [table for table in (tables or EMBEDDING_TABLES) if table in EMBEDDING_TABLES]
-
-        def _clear() -> None:
-            conn = store.connect()
-            try:
-                _ensure_vector_table(conn)
-                if requested_tables:
-                    conn.executemany(
-                        "DELETE FROM vector_embeddings WHERE source_type = ?",
-                        [(table,) for table in requested_tables],
-                    )
-                conn.commit()
-            finally:
-                conn.close()
-
-        store.submit_write(_clear, timeout=60.0)
-        for table in requested_tables:
-            prepared = _prepare_embedding_rows(_load_table_rows(table), table=table)
-            for offset in range(0, len(prepared), _WRITE_CHUNK_SIZE):
-                count += _write_embedding_chunk(table, prepared[offset: offset + _WRITE_CHUNK_SIZE])
-    finally:
-        _REBUILD_LOCK.release()
-    emit_event(LOGFILE, "brain_memory_vector_rebuild_complete", status="ok", indexed=count)
-    return count
-
-
-def backfill_missing_vectors(*, tables: Iterable[str] | None = None, limit_per_table: int | None = None) -> int:
-    emit_event(LOGFILE, "brain_memory_vector_backfill_start", status="ok")
-    if not _REBUILD_LOCK.acquire(blocking=False):
-        emit_event(LOGFILE, "brain_memory_vector_backfill_complete", status="skipped", reason="already_running")
-        return 0
-    count = 0
-    try:
-        requested_tables = [table for table in (tables or EMBEDDING_TABLES) if table in EMBEDDING_TABLES]
-        for table in requested_tables:
-            prepared = _prepare_embedding_rows(
-                _load_table_rows(table, limit=limit_per_table, missing_only=True),
-                table=table,
-            )
-            for offset in range(0, len(prepared), _WRITE_CHUNK_SIZE):
-                count += _write_embedding_chunk(table, prepared[offset: offset + _WRITE_CHUNK_SIZE])
-    finally:
-        _REBUILD_LOCK.release()
-    emit_event(LOGFILE, "brain_memory_vector_backfill_complete", status="ok", indexed=count)
-    return count
-
-
-def search_memory(query: str, limit: int = 5) -> List[Dict[str, Any]]:
-    emit_event(LOGFILE, "brain_memory_vector_search_start", status="ok")
-    conn = store.connect()
-    _ensure_vector_table(conn)
-
-    query_embedding = embedding_engine.generate_embedding(query)
-    results: List[Dict[str, Any]] = []
-
-    if query_embedding:
-        rows = conn.execute("SELECT id, source_type, source_id, embedding FROM vector_embeddings").fetchall()
-        scored: List[Dict[str, Any]] = []
-        for row in rows:
-            try:
-                emb = json.loads(row["embedding"])
-                emb_list = [float(x) for x in emb]
-            except Exception:
-                continue
-            score = _cosine_similarity(query_embedding, emb_list)
-            scored.append(
-                {
-                    "entry_id": row["id"],
-                    "source_type": row["source_type"],
-                    "source_id": row["source_id"],
-                    "score": round(score, 6),
-                }
-            )
-        scored.sort(key=lambda item: item["score"], reverse=True)
-        results = scored[:limit]
-
-    if not results:
-        rows = conn.execute(
-            "SELECT id, source, content, confidence, metadata_json FROM memory_index WHERE content LIKE ? ORDER BY id DESC LIMIT ?",
-            (f"%{query}%", limit),
-        ).fetchall()
-        fallback_results: List[Dict[str, Any]] = []
-        for row in rows:
-            source_ref = str(row["source"] or "")
-            source_type, _, source_id = source_ref.partition(":")
-            canonical_type = source_type if source_type in EMBEDDING_TABLES else "knowledge"
-            canonical_ref = f"{canonical_type}:{source_id}" if source_id else source_ref
-            fallback_results.append(
-                {
-                    "entry_id": canonical_ref,
-                    "source_type": canonical_type,
-                    "source_id": source_id or str(row["id"]),
-                    "score": float(row["confidence"] or 0.0),
-                    "content": str(row["content"] or "")[:240],
-                    "links": memory_links.get_memory_links(canonical_ref),
-                }
-            )
-        results = fallback_results
-
-    conn.close()
-    emit_event(LOGFILE, "brain_memory_vector_search_complete", status="ok", result_count=len(results))
-    return results
+from ocmemog.runtime.memory.vector_index import *  # noqa: F401,F403

package/brain/runtime/model_roles.py

@@ -1,11 +1,3 @@
 from __future__ import annotations
 
-from brain.runtime import config
-
-
-def get_model_for_role(role: str) -> str:
-    if role == "memory":
-        return config.OCMEMOG_MEMORY_MODEL
-    if role == "embedding":
-        return config.OCMEMOG_OPENAI_EMBED_MODEL
-    return config.OCMEMOG_MEMORY_MODEL
+from ocmemog.runtime.model_roles import *  # noqa: F401,F403

package/brain/runtime/model_router.py

@@ -1,24 +1,3 @@
 from __future__ import annotations
 
-from dataclasses import dataclass
-
-from brain.runtime import config
-
-
-@dataclass(frozen=True)
-class ModelSelection:
-    provider_id: str = ""
-    model: str = ""
-
-
-def get_provider_for_role(role: str) -> ModelSelection:
-    if role != "embedding":
-        return ModelSelection()
-    provider = (config.BRAIN_EMBED_MODEL_PROVIDER or "").strip().lower()
-    if provider in {"openai", "openai_compatible", "openai-compatible"}:
-        return ModelSelection(provider_id="openai", model=config.OCMEMOG_OPENAI_EMBED_MODEL)
-    if provider in {"local-openai", "local_openai", "llamacpp", "llama.cpp"}:
-        return ModelSelection(provider_id="local-openai", model=config.OCMEMOG_LOCAL_EMBED_MODEL)
-    if provider in {"ollama", "local-ollama"}:
-        return ModelSelection(provider_id="ollama", model=config.OCMEMOG_OLLAMA_EMBED_MODEL)
-    return ModelSelection()
+from ocmemog.runtime.model_router import *  # noqa: F401,F403

package/brain/runtime/providers.py

@@ -1,68 +1,3 @@
 from __future__ import annotations
 
-import json
-import os
-import urllib.request
-
-from brain.runtime import config, state_store
-from brain.runtime.instrumentation import emit_event
-
-LOGFILE = state_store.reports_dir() / "brain_memory.log.jsonl"
-
-
-class ProviderExecute:
-    def execute_embedding_call(self, selection, text: str) -> dict[str, object]:
-        provider_id = getattr(selection, "provider_id", "") or ""
-        model = getattr(selection, "model", "") or config.OCMEMOG_OPENAI_EMBED_MODEL
-        if provider_id in {"openai", "local-openai"}:
-            api_key = None
-            url_base = config.OCMEMOG_OPENAI_API_BASE
-            provider_label = "openai"
-            if provider_id == "openai":
-                api_key = os.environ.get("OCMEMOG_OPENAI_API_KEY") or os.environ.get("OPENAI_API_KEY")
-                if not api_key:
-                    return {}
-            else:
-                url_base = config.OCMEMOG_LOCAL_EMBED_BASE_URL
-                api_key = os.environ.get("OCMEMOG_LOCAL_EMBED_API_KEY") or os.environ.get("LOCAL_EMBED_API_KEY")
-                provider_label = "local-openai"
-            url = f"{url_base.rstrip('/')}/embeddings"
-            payload = json.dumps({"model": model, "input": text}).encode("utf-8")
-            req = urllib.request.Request(url, data=payload, method="POST")
-            if api_key:
-                req.add_header("Authorization", f"Bearer {api_key}")
-            req.add_header("Content-Type", "application/json")
-            try:
-                with urllib.request.urlopen(req, timeout=20) as resp:
-                    data = json.loads(resp.read().decode("utf-8"))
-            except Exception as exc:
-                emit_event(LOGFILE, "brain_embedding_provider_error", status="error", provider=provider_label, error=str(exc))
-                return {}
-            try:
-                embedding = data["data"][0]["embedding"]
-            except Exception as exc:
-                emit_event(LOGFILE, "brain_embedding_provider_error", status="error", provider=provider_label, error=str(exc))
-                return {}
-            return {"embedding": embedding}
-
-        if provider_id == "ollama":
-            url = f"{config.OCMEMOG_OLLAMA_HOST.rstrip('/')}/api/embeddings"
-            payload = json.dumps({"model": model, "prompt": text}).encode("utf-8")
-            req = urllib.request.Request(url, data=payload, method="POST")
-            req.add_header("Content-Type", "application/json")
-            try:
-                with urllib.request.urlopen(req, timeout=20) as resp:
-                    data = json.loads(resp.read().decode("utf-8"))
-            except Exception as exc:
-                emit_event(LOGFILE, "brain_embedding_provider_error", status="error", provider="ollama", error=str(exc))
-                return {}
-            embedding = data.get("embedding")
-            if not isinstance(embedding, list):
-                emit_event(LOGFILE, "brain_embedding_provider_error", status="error", provider="ollama", error="invalid_embedding")
-                return {}
-            return {"embedding": embedding}
-
-        return {}
-
-
-provider_execute = ProviderExecute()
+from ocmemog.runtime.providers import *  # noqa: F401,F403

package/brain/runtime/security/redaction.py

@@ -1,14 +1,3 @@
 from __future__ import annotations
 
-import re
-
-EMAIL_RE = re.compile(r"\b[\w.+-]+@[\w.-]+\.[A-Za-z]{2,}\b")
-PHONE_RE = re.compile(r"\b(?:\+?1[-.\s]?)?(?:\(?\d{3}\)?[-.\s]?){2}\d{4}\b")
-
-
-def redact_text(text: str) -> tuple[str, bool]:
-    if not isinstance(text, str):
-        return "", False
-    redacted = EMAIL_RE.sub("[redacted-email]", text)
-    redacted = PHONE_RE.sub("[redacted-phone]", redacted)
-    return redacted, redacted != text
+from ocmemog.runtime.security.redaction import *  # noqa: F401,F403

package/brain/runtime/state_store.py

@@ -1,25 +1,3 @@
 from __future__ import annotations
 
-from pathlib import Path
-
-from . import storage_paths
-
-
-def root_dir() -> Path:
-    return storage_paths.root_dir()
-
-
-def data_dir() -> Path:
-    return storage_paths.data_dir()
-
-
-def memory_dir() -> Path:
-    return storage_paths.memory_dir()
-
-
-def reports_dir() -> Path:
-    return storage_paths.reports_dir()
-
-
-def memory_db_path() -> Path:
-    return storage_paths.memory_db_path()
+from ocmemog.runtime.state_store import *  # noqa: F401,F403

package/brain/runtime/storage_paths.py

@@ -1,41 +1,3 @@
 from __future__ import annotations
 
-import os
-from pathlib import Path
-
-
-def root_dir() -> Path:
-    configured = os.environ.get("OCMEMOG_STATE_DIR") or os.environ.get("BRAIN_STATE_DIR")
-    if configured:
-        base = Path(configured).expanduser()
-    else:
-        base = Path(__file__).resolve().parents[2] / ".ocmemog-state"
-    base.mkdir(parents=True, exist_ok=True)
-    return base
-
-
-def data_dir() -> Path:
-    path = root_dir() / "data"
-    path.mkdir(parents=True, exist_ok=True)
-    return path
-
-
-def memory_dir() -> Path:
-    path = root_dir() / "memory"
-    path.mkdir(parents=True, exist_ok=True)
-    return path
-
-
-def reports_dir() -> Path:
-    path = root_dir() / "reports"
-    path.mkdir(parents=True, exist_ok=True)
-    return path
-
-
-def memory_db_path() -> Path:
-    override = os.environ.get("OCMEMOG_DB_PATH")
-    if override:
-        path = Path(override).expanduser()
-        path.parent.mkdir(parents=True, exist_ok=True)
-        return path
-    return memory_dir() / "brain_memory.sqlite3"
+from ocmemog.runtime.storage_paths import *  # noqa: F401,F403

package/docs/architecture/memory.md

@@ -2,28 +2,24 @@
 
 ## What this repo actually ships
 
-ocmemog vendors a subset of brAIn's memory package and wraps it with a small FastAPI sidecar. The authoritative local implementation lives in:
+ocmemog ships a repo-local memory implementation with a FastAPI sidecar, while still carrying some compatibility residue from earlier brAIn-derived runtime surfaces. The authoritative local implementation lives in:
 
-- `brain/runtime/memory/store.py` for the main SQLite schema
-- `brain/runtime/memory/retrieval.py` for keyword-first retrieval
-- `brain/runtime/memory/vector_index.py` for embeddings and fallback semantic lookup
+- `ocmemog/runtime/memory/store.py` for the main SQLite schema
+- `ocmemog/runtime/memory/retrieval.py` for keyword-first retrieval
+- `ocmemog/runtime/memory/vector_index.py` for embeddings and fallback semantic lookup
 - `ocmemog/sidecar/app.py` for the plugin-facing HTTP API
 
-Unlike brAIn, this repo does not ship the full cognition/runtime stack. Several modules under `brain/runtime/*` are compatibility shims so the copied memory package can import cleanly.
+Unlike brAIn, this repo does not ship the full cognition/runtime stack. Several modules under `brain/runtime/*` are compatibility shims so `ocmemog/runtime/*` can import cleanly.
 
 ## Storage layout
 
-By default, ocmemog stores state under `.ocmemog-state/` at the repo root unless `OCMEMOG_STATE_DIR` or `BRAIN_STATE_DIR` overrides it.
+By default, ocmemog stores state under `.ocmemog-state/` at the repo root unless `OCMEMOG_STATE_DIR` overrides it. `BRAIN_STATE_DIR` remains as a legacy compatibility alias and should not be used for new deployments.
 
 Primary files:
 
-- `.ocmemog-state/memory/brain_memory.sqlite3`
-- `.ocmemog-state/reports/brain_memory.log.jsonl`
-- `.ocmemog-state/data/person_memory.db`
-- `.ocmemog-state/data/interaction_memory.db`
-- `.ocmemog-state/data/sentiment_memory.db`
+- `.ocmemog-state/memory/ocmemog_memory.sqlite3`
+- `.ocmemog-state/reports/ocmemog_memory.log.jsonl`
 - `.ocmemog-state/data/unresolved_state.db`
-- `.ocmemog-state/data/memory_graph.db`
 
 The main SQLite database owns these tables:
 
@@ -48,7 +44,7 @@ The current sidecar behavior is simpler than brAIn's full memory architecture:
 Operational limits:
 
 - Semantic fallback now rehydrates any embedded bucket (`knowledge`, `runbooks`, `lessons`) when there are no keyword hits.
-- Default embeddings are local hash vectors (`BRAIN_EMBED_MODEL_LOCAL=simple`), which are deterministic but weak.
+- Default embeddings are local hash vectors (`OCMEMOG_EMBED_MODEL_LOCAL=simple`; legacy alias: `BRAIN_EMBED_MODEL_LOCAL`), which are deterministic but weak.
 - `runbooks`, `lessons`, `directives`, `reflections`, and `tasks` are now included in the default searchable categories and embedding index.
 
 ## Write paths
@@ -60,14 +56,14 @@ The main repo-local write paths are:
 - `promote.promote_candidate()` writes to `promotions` plus one of `knowledge`, `runbooks`, or `lessons`
 - `vector_index.insert_memory()` writes to `memory_index` and `vector_embeddings`
 - `memory_links.add_memory_link()` writes link metadata inside the main memory DB
-- `person_memory`, `interaction_memory`, `sentiment_memory`, `unresolved_state`, and `memory_graph` each write to separate SQLite files under `.ocmemog-state/data`
+- `unresolved_state` writes to a separate SQLite file under `.ocmemog-state/data`; core memory relationships and provenance now live in the main memory DB.
 
 ## Distillation and promotion
 
 The brAIn docs describe a richer distill/promote pipeline. In ocmemog today:
 
-- Distillation exists in `brain/runtime/memory/distill.py`
-- Model-backed distillation is not available because `brain/runtime/inference.py` is still a shim
+- Distillation exists in `ocmemog/runtime/memory/distill.py`
+- Model-backed distillation depends on the configured runtime inference provider and may fall back to heuristics when no usable provider is available
 - The practical fallback is a first-line heuristic summary plus generated verification prompts
 - Promotion is available locally and writes promoted summaries into `knowledge`, `runbooks`, or `lessons`
 - Successful promotion also logs a reinforcement event and attempts vector indexing
@@ -80,11 +76,11 @@ Available support paths:
 
 - `integrity.run_integrity_check()` checks for missing tables, orphan candidates, duplicate promotions, missing memory references, and index mismatches
 - `health.get_memory_health()` reports counts and a coarse integrity summary
-- `brain_memory.log.jsonl` captures retrieval, embedding, integrity, and promotion events
+- `ocmemog_memory.log.jsonl` captures retrieval, embedding, integrity, and promotion events
 
 Known caveat:
 
-- health/integrity currently treat `memory_index` as the "vector" coverage source, even though actual embeddings live in `vector_embeddings`
+- health/integrity now use source coverage against `vector_embeddings`, but operator interpretation still depends on the active embedding backend and any compatibility-shim surfaces reported by runtime probe
 
 ## Sidecar contract
 
@@ -100,19 +96,19 @@ The sidecar also reports runtime readiness through `mode`, `missingDeps`, `todo`
 
 ## Runtime adapters
 
-ocmemog ships lightweight runtime adapters for inference + embeddings. They require environment configuration:
+ocmemog now uses repo-local runtime adapters for inference + embeddings, with some compatibility residue still present behind the runtime boundary. The primary active surfaces are under `ocmemog/runtime/*` and require environment configuration:
 
-- `brain/runtime/inference.py` → OpenAI chat completions (requires `OCMEMOG_OPENAI_API_KEY`)
-- `brain/runtime/providers.py` → OpenAI embeddings (requires `BRAIN_EMBED_MODEL_PROVIDER=openai` + API key)
-- `brain/runtime/model_roles.py` + `model_router.py` → role-to-model and provider routing
+- `ocmemog/runtime/inference.py` → chat/inference routing (OpenAI or local-openai depending on configured provider)
+- `ocmemog/runtime/providers.py` → embedding provider routing
+- `ocmemog/runtime/model_roles.py` + `model_router.py` → role-to-model and provider routing
 
 Effect on behavior:
 
 - Distillation uses OpenAI when API key is set, otherwise falls back to heuristics
 - Embeddings use OpenAI when configured, otherwise fall back to local hash or sentence-transformers
-- Role-aware context selection is still partially stubbed because `brain.runtime.roles` is not present
+- Role-aware context selection is now supported via `ocmemog.runtime.roles`, with native ownership tracked in runtime compatibility reporting.
 
 ## TODO: Missing runtime dependencies
 
-- TODO: add a repo-local `brain.runtime.roles` implementation or remove role-priority logic from `context_builder`
+- DONE: add a repo-local `brain.runtime.roles` implementation.
 - TODO: decide whether to add additional provider backends beyond OpenAI

package/docs/release-checklist.md

@@ -2,20 +2,33 @@
 
 Use this checklist before publishing an ocmemog release.
 
+The release gate is now codified by:
+
+```bash
+./scripts/ocmemog-release-check.sh
+```
+
 ## Versioning
 - [ ] Update `package.json` version
 - [ ] Ensure release tag matches package version
 - [ ] Update `CHANGELOG.md`
-- [ ] Confirm README examples reference the current version where applicable
+- [ ] Confirm README/release docs reflect current versioned package identity and release workflow
 
 ## Validation
-- [ ] `bash -n scripts/install-ocmemog.sh`
-- [ ] `bash -n scripts/ocmemog-install.sh`
-- [ ] `./scripts/install-ocmemog.sh --help`
-- [ ] `./scripts/install-ocmemog.sh --dry-run`
-- [ ] `./.venv/bin/python -m pytest -q tests/test_regressions.py tests/test_governance_queue.py tests/test_promotion_governance_integration.py tests/test_hybrid_retrieval.py`
+- [ ] Install test deps for sidecar route tests: `python3 -m pip install -r requirements-test.txt`
+- [ ] `./scripts/ocmemog-release-check.sh`
+- [ ] Verify `tests/test_doctor.py` still passes for doctor health surfaces if you changed check coverage
+- [ ] Verify `reports/release-gate-proof.json` exists after a passing gate and documents:
+  - live ingest/search/get/hydrate verification
+  - capped response selection (`memory/search` and `conversation/hydrate`)
+  - reference recall for distinctive injected memory
+- [ ] If testing against a protected sidecar, confirm auth-bearing requests succeed (`x-ocmemog-token` or `Authorization: Bearer ...`)
 - [ ] `npm pack --dry-run`
 
+The `ocmemog-release-check` command enforces strict doctor mode for repo-locally safe checks, runs a focused pytest subset, validates explicit sidecar route behavior, runs live `/healthz`, `/memory/ingest`, `/memory/search`, `/memory/get`, and `/conversation/hydrate` smoke checks, and executes a full integrated proof in fresh state.
+Legacy-state verification is optional and can be enabled with `OCMEMOG_RELEASE_LEGACY_ENDPOINT`.
+GitHub CI runs the same release check command so local and CI validation remain aligned.
+
 ## Install flow
 - [ ] Verify default installer path still works: `./scripts/install-ocmemog.sh`
 - [ ] Verify optional prereq install path is documented correctly