omni-cortex 1.4.0__tar.gz → 1.5.0__tar.gz

{omni_cortex-1.4.0 → omni_cortex-1.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: omni-cortex
-Version: 1.4.0
+Version: 1.5.0
 Summary: Give Claude Code a perfect memory - auto-logs everything, searches smartly, and gets smarter over time
 Project-URL: Homepage, https://github.com/AllCytes/Omni-Cortex
 Project-URL: Repository, https://github.com/AllCytes/Omni-Cortex

omni_cortex-1.5.0/dashboard/backend/backfill_summaries.py

@@ -0,0 +1,280 @@
+"""Backfill utility for generating activity summaries.
+
+This module provides functions to retroactively generate natural language
+summaries for existing activity records that don't have them.
+"""
+
+import json
+import sqlite3
+import sys
+from pathlib import Path
+from typing import Optional
+
+# Add parent paths for imports
+sys.path.insert(0, str(Path(__file__).parent.parent.parent / "src"))
+
+from database import get_write_connection, ensure_migrations
+
+
+def generate_activity_summary(
+    tool_name: Optional[str],
+    tool_input: Optional[str],
+    success: bool,
+    file_path: Optional[str],
+    event_type: str,
+) -> tuple[str, str]:
+    """Generate natural language summary for an activity.
+
+    Returns:
+        tuple of (short_summary, detailed_summary)
+    """
+    short = ""
+    detail = ""
+
+    # Parse tool input if available
+    input_data = {}
+    if tool_input:
+        try:
+            input_data = json.loads(tool_input)
+        except (json.JSONDecodeError, TypeError):
+            pass
+
+    # Generate summaries based on tool type
+    if tool_name == "Read":
+        path = input_data.get("file_path", file_path or "unknown file")
+        filename = Path(path).name if path else "file"
+        short = f"Read file: {filename}"
+        detail = f"Reading contents of {path}"
+
+    elif tool_name == "Write":
+        path = input_data.get("file_path", file_path or "unknown file")
+        filename = Path(path).name if path else "file"
+        short = f"Write file: {filename}"
+        detail = f"Writing/creating file at {path}"
+
+    elif tool_name == "Edit":
+        path = input_data.get("file_path", file_path or "unknown file")
+        filename = Path(path).name if path else "file"
+        short = f"Edit file: {filename}"
+        detail = f"Editing {path} - replacing text content"
+
+    elif tool_name == "Bash":
+        cmd = input_data.get("command", "")[:50]
+        short = f"Run command: {cmd}..."
+        detail = f"Executing bash command: {input_data.get('command', 'unknown')}"
+
+    elif tool_name == "Grep":
+        pattern = input_data.get("pattern", "")
+        short = f"Search for: {pattern[:30]}"
+        detail = f"Searching codebase for pattern: {pattern}"
+
+    elif tool_name == "Glob":
+        pattern = input_data.get("pattern", "")
+        short = f"Find files: {pattern[:30]}"
+        detail = f"Finding files matching pattern: {pattern}"
+
+    elif tool_name == "Skill":
+        skill = input_data.get("skill", "unknown")
+        short = f"Run skill: /{skill}"
+        detail = f"Executing slash command /{skill}"
+
+    elif tool_name == "Task":
+        desc = input_data.get("description", "task")
+        short = f"Spawn agent: {desc[:30]}"
+        detail = f"Launching sub-agent for: {input_data.get('prompt', desc)[:100]}"
+
+    elif tool_name == "WebSearch":
+        query = input_data.get("query", "")
+        short = f"Web search: {query[:30]}"
+        detail = f"Searching the web for: {query}"
+
+    elif tool_name == "WebFetch":
+        url = input_data.get("url", "")
+        short = f"Fetch URL: {url[:40]}"
+        detail = f"Fetching content from: {url}"
+
+    elif tool_name == "TodoWrite":
+        todos = input_data.get("todos", [])
+        count = len(todos) if isinstance(todos, list) else 0
+        short = f"Update todo list: {count} items"
+        detail = f"Managing task list with {count} items"
+
+    elif tool_name == "AskUserQuestion":
+        questions = input_data.get("questions", [])
+        count = len(questions) if isinstance(questions, list) else 1
+        short = f"Ask user: {count} question(s)"
+        detail = f"Prompting user for input with {count} question(s)"
+
+    elif tool_name and tool_name.startswith("mcp__"):
+        parts = tool_name.split("__")
+        server = parts[1] if len(parts) > 1 else "unknown"
+        tool = parts[2] if len(parts) > 2 else tool_name
+        short = f"MCP call: {server}/{tool}"
+        detail = f"Calling {tool} tool from MCP server {server}"
+
+    elif tool_name == "cortex_remember" or (tool_name and "remember" in tool_name.lower()):
+        params = input_data.get("params", {})
+        content = params.get("content", "") if isinstance(params, dict) else ""
+        short = f"Store memory: {content[:30]}..." if content else "Store memory"
+        detail = f"Saving to memory system: {content[:100]}" if content else "Saving to memory system"
+
+    elif tool_name == "cortex_recall" or (tool_name and "recall" in tool_name.lower()):
+        params = input_data.get("params", {})
+        query = params.get("query", "") if isinstance(params, dict) else ""
+        short = f"Recall: {query[:30]}" if query else "Recall memories"
+        detail = f"Searching memories for: {query}" if query else "Retrieving memories"
+
+    elif tool_name == "NotebookEdit":
+        path = input_data.get("notebook_path", "")
+        filename = Path(path).name if path else "notebook"
+        short = f"Edit notebook: {filename}"
+        detail = f"Editing Jupyter notebook {path}"
+
+    else:
+        short = f"{event_type}: {tool_name or 'unknown'}"
+        detail = f"Activity type {event_type} with tool {tool_name}"
+
+    # Add status suffix for failures
+    if not success:
+        short = f"[FAILED] {short}"
+        detail = f"[FAILED] {detail}"
+
+    return short, detail
+
+
+def backfill_activity_summaries(db_path: str) -> int:
+    """Generate summaries for activities that don't have them.
+
+    Args:
+        db_path: Path to the SQLite database
+
+    Returns:
+        Number of activities updated
+    """
+    # First ensure migrations are applied
+    ensure_migrations(db_path)
+
+    conn = get_write_connection(db_path)
+
+    # Check if summary column exists
+    columns = conn.execute("PRAGMA table_info(activities)").fetchall()
+    column_names = {col[1] for col in columns}
+
+    if "summary" not in column_names:
+        print(f"[Backfill] Summary column not found in {db_path}, skipping")
+        conn.close()
+        return 0
+
+    cursor = conn.execute("""
+        SELECT id, tool_name, tool_input, success, file_path, event_type
+        FROM activities
+        WHERE summary IS NULL OR summary = ''
+    """)
+
+    count = 0
+    for row in cursor.fetchall():
+        short, detail = generate_activity_summary(
+            row["tool_name"],
+            row["tool_input"],
+            bool(row["success"]),
+            row["file_path"],
+            row["event_type"],
+        )
+
+        conn.execute(
+            """
+            UPDATE activities
+            SET summary = ?, summary_detail = ?
+            WHERE id = ?
+            """,
+            (short, detail, row["id"]),
+        )
+        count += 1
+
+        if count % 100 == 0:
+            conn.commit()
+            print(f"[Backfill] Processed {count} activities...")
+
+    conn.commit()
+    conn.close()
+    return count
+
+
+def backfill_mcp_servers(db_path: str) -> int:
+    """Extract and populate mcp_server for existing activities.
+
+    Args:
+        db_path: Path to the SQLite database
+
+    Returns:
+        Number of activities updated
+    """
+    # First ensure migrations are applied
+    ensure_migrations(db_path)
+
+    conn = get_write_connection(db_path)
+
+    # Check if mcp_server column exists
+    columns = conn.execute("PRAGMA table_info(activities)").fetchall()
+    column_names = {col[1] for col in columns}
+
+    if "mcp_server" not in column_names:
+        print(f"[Backfill] mcp_server column not found in {db_path}, skipping")
+        conn.close()
+        return 0
+
+    cursor = conn.execute("""
+        SELECT id, tool_name FROM activities
+        WHERE tool_name LIKE 'mcp__%'
+          AND (mcp_server IS NULL OR mcp_server = '')
+    """)
+
+    count = 0
+    for row in cursor.fetchall():
+        parts = row["tool_name"].split("__")
+        if len(parts) >= 2:
+            server = parts[1]
+            conn.execute(
+                "UPDATE activities SET mcp_server = ? WHERE id = ?",
+                (server, row["id"]),
+            )
+            count += 1
+
+    conn.commit()
+    conn.close()
+    return count
+
+
+def backfill_all(db_path: str) -> dict:
+    """Run all backfill operations on a database.
+
+    Args:
+        db_path: Path to the SQLite database
+
+    Returns:
+        Dictionary with counts of updated records
+    """
+    print(f"[Backfill] Starting backfill for {db_path}")
+
+    results = {
+        "summaries": backfill_activity_summaries(db_path),
+        "mcp_servers": backfill_mcp_servers(db_path),
+    }
+
+    print(f"[Backfill] Complete: {results['summaries']} summaries, {results['mcp_servers']} MCP servers")
+    return results
+
+
+if __name__ == "__main__":
+    # Allow running from command line with database path as argument
+    if len(sys.argv) < 2:
+        print("Usage: python backfill_summaries.py <path-to-database>")
+        sys.exit(1)
+
+    db_path = sys.argv[1]
+    if not Path(db_path).exists():
+        print(f"Error: Database not found at {db_path}")
+        sys.exit(1)
+
+    results = backfill_all(db_path)
+    print(f"Backfill complete: {results}")

{omni_cortex-1.4.0 → omni_cortex-1.5.0}/dashboard/backend/database.py

@@ -24,6 +24,58 @@ def get_write_connection(db_path: str) -> sqlite3.Connection:
     return conn
 
 
+def ensure_migrations(db_path: str) -> None:
+    """Ensure database has latest migrations applied.
+
+    This function checks for and applies any missing schema updates,
+    including command analytics columns and natural language summary columns.
+    """
+    conn = get_write_connection(db_path)
+
+    # Check if activities table exists
+    table_check = conn.execute(
+        "SELECT name FROM sqlite_master WHERE type='table' AND name='activities'"
+    ).fetchone()
+
+    if not table_check:
+        conn.close()
+        return
+
+    # Check available columns
+    columns = conn.execute("PRAGMA table_info(activities)").fetchall()
+    column_names = {col[1] for col in columns}
+
+    migrations_applied = []
+
+    # Migration v1.1: Command analytics columns
+    if "command_name" not in column_names:
+        conn.executescript("""
+            ALTER TABLE activities ADD COLUMN command_name TEXT;
+            ALTER TABLE activities ADD COLUMN command_scope TEXT;
+            ALTER TABLE activities ADD COLUMN mcp_server TEXT;
+            ALTER TABLE activities ADD COLUMN skill_name TEXT;
+
+            CREATE INDEX IF NOT EXISTS idx_activities_command ON activities(command_name);
+            CREATE INDEX IF NOT EXISTS idx_activities_mcp ON activities(mcp_server);
+            CREATE INDEX IF NOT EXISTS idx_activities_skill ON activities(skill_name);
+        """)
+        migrations_applied.append("v1.1: command analytics columns")
+
+    # Migration v1.2: Natural language summary columns
+    if "summary" not in column_names:
+        conn.executescript("""
+            ALTER TABLE activities ADD COLUMN summary TEXT;
+            ALTER TABLE activities ADD COLUMN summary_detail TEXT;
+        """)
+        migrations_applied.append("v1.2: summary columns")
+
+    if migrations_applied:
+        conn.commit()
+        print(f"[Database] Applied migrations: {', '.join(migrations_applied)}")
+
+    conn.close()
+
+
 def parse_tags(tags_str: Optional[str]) -> list[str]:
     """Parse tags from JSON string."""
     if not tags_str:
@@ -183,9 +235,13 @@ def get_activities(
     limit: int = 100,
     offset: int = 0,
 ) -> list[Activity]:
-    """Get activity log entries."""
+    """Get activity log entries with all available fields."""
     conn = get_connection(db_path)
 
+    # Check available columns for backward compatibility
+    columns = conn.execute("PRAGMA table_info(activities)").fetchall()
+    column_names = {col[1] for col in columns}
+
     query = "SELECT * FROM activities WHERE 1=1"
     params: list = []
 
@@ -212,21 +268,37 @@ def get_activities(
             # Fallback for edge cases
             ts = datetime.now()
 
-        activities.append(
-            Activity(
-                id=row["id"],
-                session_id=row["session_id"],
-                event_type=row["event_type"],
-                tool_name=row["tool_name"],
-                tool_input=row["tool_input"],
-                tool_output=row["tool_output"],
-                success=bool(row["success"]),
-                error_message=row["error_message"],
-                duration_ms=row["duration_ms"],
-                file_path=row["file_path"],
-                timestamp=ts,
-            )
-        )
+        activity_data = {
+            "id": row["id"],
+            "session_id": row["session_id"],
+            "event_type": row["event_type"],
+            "tool_name": row["tool_name"],
+            "tool_input": row["tool_input"],
+            "tool_output": row["tool_output"],
+            "success": bool(row["success"]),
+            "error_message": row["error_message"],
+            "duration_ms": row["duration_ms"],
+            "file_path": row["file_path"],
+            "timestamp": ts,
+        }
+
+        # Add command analytics fields if available
+        if "command_name" in column_names:
+            activity_data["command_name"] = row["command_name"]
+        if "command_scope" in column_names:
+            activity_data["command_scope"] = row["command_scope"]
+        if "mcp_server" in column_names:
+            activity_data["mcp_server"] = row["mcp_server"]
+        if "skill_name" in column_names:
+            activity_data["skill_name"] = row["skill_name"]
+
+        # Add summary fields if available
+        if "summary" in column_names:
+            activity_data["summary"] = row["summary"]
+        if "summary_detail" in column_names:
+            activity_data["summary_detail"] = row["summary_detail"]
+
+        activities.append(Activity(**activity_data))
 
     conn.close()
     return activities
@@ -933,6 +1005,12 @@ def get_activity_detail(db_path: str, activity_id: str) -> Optional[dict]:
     if "skill_name" in column_names:
         result["skill_name"] = row["skill_name"]
 
+    # Add summary fields if they exist
+    if "summary" in column_names:
+        result["summary"] = row["summary"]
+    if "summary_detail" in column_names:
+        result["summary_detail"] = row["summary_detail"]
+
     conn.close()
     return result
 

{omni_cortex-1.4.0 → omni_cortex-1.5.0}/dashboard/backend/main.py

@@ -32,6 +32,7 @@ except ImportError:
 from database import (
     bulk_update_memory_status,
     delete_memory,
+    ensure_migrations,
     get_activities,
     get_activity_detail,
     get_activity_heatmap,
@@ -487,6 +488,9 @@ async def list_activities(
     if not Path(project).exists():
         raise HTTPException(status_code=404, detail="Database not found")
 
+    # Ensure migrations are applied (adds summary columns if missing)
+    ensure_migrations(project)
+
     return get_activities(project, event_type, tool_name, limit, offset)
 
 
@@ -627,6 +631,9 @@ async def get_activity_detail_endpoint(
     if not Path(project).exists():
         raise HTTPException(status_code=404, detail="Database not found")
 
+    # Ensure migrations are applied
+    ensure_migrations(project)
+
     activity = get_activity_detail(project, activity_id)
     if not activity:
         raise HTTPException(status_code=404, detail="Activity not found")
@@ -634,6 +641,26 @@ async def get_activity_detail_endpoint(
     return activity
 
 
+@app.post("/api/activities/backfill-summaries")
+async def backfill_activity_summaries_endpoint(
+    project: str = Query(..., description="Path to the database file"),
+):
+    """Generate summaries for existing activities that don't have them."""
+    if not Path(project).exists():
+        raise HTTPException(status_code=404, detail="Database not found")
+
+    try:
+        from backfill_summaries import backfill_all
+        results = backfill_all(project)
+        return {
+            "success": True,
+            "summaries_updated": results["summaries"],
+            "mcp_servers_updated": results["mcp_servers"],
+        }
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=f"Backfill failed: {str(e)}")
+
+
 # --- Session Context Endpoints ---
 
 

{omni_cortex-1.4.0 → omni_cortex-1.5.0}/dashboard/backend/models.py

@@ -84,6 +84,14 @@ class Activity(BaseModel):
     duration_ms: Optional[int] = None
     file_path: Optional[str] = None
     timestamp: datetime
+    # Command analytics fields
+    command_name: Optional[str] = None
+    command_scope: Optional[str] = None
+    mcp_server: Optional[str] = None
+    skill_name: Optional[str] = None
+    # Natural language summary fields
+    summary: Optional[str] = None
+    summary_detail: Optional[str] = None
 
 
 class Session(BaseModel):

{omni_cortex-1.4.0 → omni_cortex-1.5.0}/omni_cortex/__init__.py

@@ -1,3 +1,3 @@
 """Omni Cortex MCP - Universal Memory System for Claude Code."""
 
-__version__ = "1.4.0"
+__version__ = "1.5.0"

{omni_cortex-1.4.0 → omni_cortex-1.5.0}/omni_cortex/database/migrations.py

@@ -24,6 +24,12 @@ MIGRATIONS: dict[str, str] = {
         CREATE INDEX IF NOT EXISTS idx_activities_mcp ON activities(mcp_server);
         CREATE INDEX IF NOT EXISTS idx_activities_skill ON activities(skill_name);
     """,
+    # Natural language summary columns for activity display
+    "1.2": """
+        -- Add natural language summary columns to activities table
+        ALTER TABLE activities ADD COLUMN summary TEXT;
+        ALTER TABLE activities ADD COLUMN summary_detail TEXT;
+    """,
 }
 
 

{omni_cortex-1.4.0 → omni_cortex-1.5.0}/omni_cortex/database/schema.py

@@ -46,6 +46,14 @@ CREATE TABLE IF NOT EXISTS activities (
     project_path TEXT,
     file_path TEXT,
     metadata TEXT,
+    -- Command analytics columns (v1.1)
+    command_name TEXT,
+    command_scope TEXT,
+    mcp_server TEXT,
+    skill_name TEXT,
+    -- Natural language summaries (v1.2)
+    summary TEXT,
+    summary_detail TEXT,
     FOREIGN KEY (session_id) REFERENCES sessions(id),
     FOREIGN KEY (agent_id) REFERENCES agents(id)
 );

{omni_cortex-1.4.0 → omni_cortex-1.5.0}/omni_cortex/tools/activities.py

@@ -13,6 +13,7 @@ from ..models.activity import Activity, ActivityCreate, create_activity, get_act
 from ..models.memory import list_memories
 from ..utils.formatting import format_activity_markdown, format_timeline_markdown
 from ..utils.timestamps import now_iso, parse_iso
+from pathlib import Path
 
 
 # === Input Models ===
@@ -319,3 +320,134 @@ def _extract_mcp_server(tool_name: str) -> Optional[str]:
         return parts[1]  # Server name is the second part
 
     return None
+
+
+# === Natural Language Summary Generation ===
+
+
+def generate_activity_summary(
+    tool_name: Optional[str],
+    tool_input: Optional[str],
+    success: bool,
+    file_path: Optional[str],
+    event_type: str,
+) -> tuple[str, str]:
+    """Generate natural language summary for an activity.
+
+    Returns:
+        tuple of (short_summary, detailed_summary)
+        - short_summary: 12-20 words, shown in collapsed view
+        - detailed_summary: Expanded description with more context
+    """
+    short = ""
+    detail = ""
+
+    # Parse tool input if available
+    input_data = {}
+    if tool_input:
+        try:
+            input_data = json.loads(tool_input)
+        except (json.JSONDecodeError, TypeError):
+            pass
+
+    # Generate summaries based on tool type
+    if tool_name == "Read":
+        path = input_data.get("file_path", file_path or "unknown file")
+        filename = Path(path).name if path else "file"
+        short = f"Read file: {filename}"
+        detail = f"Reading contents of {path}"
+
+    elif tool_name == "Write":
+        path = input_data.get("file_path", file_path or "unknown file")
+        filename = Path(path).name if path else "file"
+        short = f"Write file: {filename}"
+        detail = f"Writing/creating file at {path}"
+
+    elif tool_name == "Edit":
+        path = input_data.get("file_path", file_path or "unknown file")
+        filename = Path(path).name if path else "file"
+        short = f"Edit file: {filename}"
+        detail = f"Editing {path} - replacing text content"
+
+    elif tool_name == "Bash":
+        cmd = input_data.get("command", "")[:50]
+        short = f"Run command: {cmd}..."
+        detail = f"Executing bash command: {input_data.get('command', 'unknown')}"
+
+    elif tool_name == "Grep":
+        pattern = input_data.get("pattern", "")
+        short = f"Search for: {pattern[:30]}"
+        detail = f"Searching codebase for pattern: {pattern}"
+
+    elif tool_name == "Glob":
+        pattern = input_data.get("pattern", "")
+        short = f"Find files: {pattern[:30]}"
+        detail = f"Finding files matching pattern: {pattern}"
+
+    elif tool_name == "Skill":
+        skill = input_data.get("skill", "unknown")
+        short = f"Run skill: /{skill}"
+        detail = f"Executing slash command /{skill}"
+
+    elif tool_name == "Task":
+        desc = input_data.get("description", "task")
+        short = f"Spawn agent: {desc[:30]}"
+        detail = f"Launching sub-agent for: {input_data.get('prompt', desc)[:100]}"
+
+    elif tool_name == "WebSearch":
+        query = input_data.get("query", "")
+        short = f"Web search: {query[:30]}"
+        detail = f"Searching the web for: {query}"
+
+    elif tool_name == "WebFetch":
+        url = input_data.get("url", "")
+        short = f"Fetch URL: {url[:40]}"
+        detail = f"Fetching content from: {url}"
+
+    elif tool_name == "TodoWrite":
+        todos = input_data.get("todos", [])
+        count = len(todos) if isinstance(todos, list) else 0
+        short = f"Update todo list: {count} items"
+        detail = f"Managing task list with {count} items"
+
+    elif tool_name == "AskUserQuestion":
+        questions = input_data.get("questions", [])
+        count = len(questions) if isinstance(questions, list) else 1
+        short = f"Ask user: {count} question(s)"
+        detail = f"Prompting user for input with {count} question(s)"
+
+    elif tool_name and tool_name.startswith("mcp__"):
+        parts = tool_name.split("__")
+        server = parts[1] if len(parts) > 1 else "unknown"
+        tool = parts[2] if len(parts) > 2 else tool_name
+        short = f"MCP call: {server}/{tool}"
+        detail = f"Calling {tool} tool from MCP server {server}"
+
+    elif tool_name == "cortex_remember" or (tool_name and "remember" in tool_name.lower()):
+        params = input_data.get("params", {})
+        content = params.get("content", "") if isinstance(params, dict) else ""
+        short = f"Store memory: {content[:30]}..." if content else "Store memory"
+        detail = f"Saving to memory system: {content[:100]}" if content else "Saving to memory system"
+
+    elif tool_name == "cortex_recall" or (tool_name and "recall" in tool_name.lower()):
+        params = input_data.get("params", {})
+        query = params.get("query", "") if isinstance(params, dict) else ""
+        short = f"Recall: {query[:30]}" if query else "Recall memories"
+        detail = f"Searching memories for: {query}" if query else "Retrieving memories"
+
+    elif tool_name == "NotebookEdit":
+        path = input_data.get("notebook_path", "")
+        filename = Path(path).name if path else "notebook"
+        short = f"Edit notebook: {filename}"
+        detail = f"Editing Jupyter notebook {path}"
+
+    else:
+        short = f"{event_type}: {tool_name or 'unknown'}"
+        detail = f"Activity type {event_type} with tool {tool_name}"
+
+    # Add status suffix for failures
+    if not success:
+        short = f"[FAILED] {short}"
+        detail = f"[FAILED] {detail}"
+
+    return short, detail

{omni_cortex-1.4.0 → omni_cortex-1.5.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "omni-cortex"
-version = "1.4.0"
+version = "1.5.0"
 description = "Give Claude Code a perfect memory - auto-logs everything, searches smartly, and gets smarter over time"
 readme = "README.md"
 license = "MIT"

omni_cortex-1.5.0/scripts/check-venv.py

@@ -0,0 +1,106 @@
+#!/usr/bin/env python3
+"""
+Venv Health Check
+=================
+
+Diagnoses common venv issues like corrupted metadata, missing packages,
+and version mismatches.
+
+Usage:
+    python scripts/check-venv.py
+    python scripts/check-venv.py --fix  # Attempt auto-fix
+"""
+
+import importlib
+import importlib.metadata
+import sys
+from pathlib import Path
+
+
+def check_package(name: str, import_name: str = None) -> tuple[bool, str]:
+    """Check if a package is properly installed and importable."""
+    import_name = import_name or name.replace("-", "_")
+
+    try:
+        # Check if metadata is accessible
+        version = importlib.metadata.version(name)
+    except importlib.metadata.PackageNotFoundError:
+        return False, f"Not installed (metadata missing)"
+    except Exception as e:
+        return False, f"Metadata error: {e}"
+
+    try:
+        # Check if package is importable
+        module = importlib.import_module(import_name)
+        module_version = getattr(module, "__version__", "unknown")
+        if module_version != "unknown" and module_version != version:
+            return False, f"Version mismatch: metadata={version}, module={module_version}"
+        return True, f"OK (v{version})"
+    except ImportError as e:
+        return False, f"Import failed: {e}"
+    except Exception as e:
+        return False, f"Error: {e}"
+
+
+def main():
+    print("Venv Health Check")
+    print("=" * 50)
+    print(f"Python: {sys.executable}")
+    print(f"Version: {sys.version.split()[0]}")
+    print()
+
+    # Core packages to check
+    packages = [
+        ("pydantic", "pydantic"),
+        ("pydantic-core", "pydantic_core"),
+        ("fastapi", "fastapi"),
+        ("uvicorn", "uvicorn"),
+        ("pyyaml", "yaml"),
+        ("httpx", "httpx"),
+        ("aiosqlite", "aiosqlite"),
+    ]
+
+    # Check if we're in the right project
+    project_root = Path(__file__).parent.parent
+    pyproject = project_root / "pyproject.toml"
+
+    if pyproject.exists():
+        print(f"Project: {project_root}")
+        # Try to check omni-cortex
+        packages.insert(0, ("omni-cortex", "omni_cortex"))
+    print()
+
+    all_ok = True
+    issues = []
+
+    print("Package Status:")
+    print("-" * 50)
+    for pkg_name, import_name in packages:
+        ok, status = check_package(pkg_name, import_name)
+        symbol = "✓" if ok else "✗"
+        print(f"  {symbol} {pkg_name}: {status}")
+        if not ok:
+            all_ok = False
+            issues.append((pkg_name, status))
+
+    print()
+
+    if all_ok:
+        print("✓ All packages healthy!")
+    else:
+        print("✗ Issues detected:")
+        print()
+        for pkg, issue in issues:
+            print(f"  - {pkg}: {issue}")
+        print()
+        print("Suggested fixes:")
+        print("  1. Try force-reinstall: uv pip install --force-reinstall <package>")
+        print("  2. Rebuild venv: rm -rf .venv && uv venv && uv pip install -e .")
+        print("  3. Use system pip: pip install -e . --force-reinstall")
+        return 1
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())