omni-cortex 1.2.0__py3-none-any.whl → 1.11.3__py3-none-any.whl

{omni_cortex-1.2.0.dist-info → omni_cortex-1.11.3.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: omni-cortex
-Version: 1.2.0
+Version: 1.11.3
 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
@@ -21,9 +21,11 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: >=3.10
+Requires-Dist: claude-agent-sdk>=0.1.0
 Requires-Dist: httpx>=0.25.0
 Requires-Dist: mcp>=1.0.0
 Requires-Dist: pydantic>=2.0.0
+Requires-Dist: python-dotenv>=1.0.0
 Requires-Dist: pyyaml>=6.0.0
 Provides-Extra: dev
 Requires-Dist: black>=23.0.0; extra == 'dev'
@@ -76,7 +78,180 @@ A universal memory system for Claude Code that combines activity logging with in
 - **Importance Decay**: Frequently accessed memories naturally surface
 - **Auto Activity Logging**: Automatically logs all tool calls via hooks
 
-## Installation
+## Getting Started (5 Minutes)
+
+A step-by-step guide to get Omni Cortex running on your machine.
+
+### Prerequisites
+
+- **Python 3.10+** - Check with `python --version`
+- **Claude Code CLI** - The Anthropic CLI tool
+- **pip** - Python package manager (comes with Python)
+
+### Step 1: Install the Package
+
+**Option A: From PyPI (Recommended for most users)**
+```bash
+pip install omni-cortex
+```
+
+**Option B: From Source (For development/contributions)**
+```bash
+git clone https://github.com/AllCytes/Omni-Cortex.git
+cd Omni-Cortex
+pip install -e ".[semantic]"
+```
+
+**Expected output:**
+```
+Successfully installed omni-cortex-1.7.1
+```
+
+### Step 2: Run the Setup
+
+```bash
+omni-cortex-setup
+```
+
+This automatically:
+- Adds Omni Cortex as an MCP server in `~/.claude.json`
+- Configures hooks in `~/.claude/settings.json` for activity logging
+
+**Expected output:**
+```
+✓ MCP server configured
+✓ Hooks configured
+Setup complete! Restart Claude Code to activate.
+```
+
+### Step 3: Restart Claude Code
+
+Close and reopen your Claude Code terminal. This loads the new MCP configuration.
+
+### Step 4: Verify It's Working
+
+In Claude Code, try storing a memory:
+
+```
+Ask Claude: "Remember that the database uses SQLite for storage"
+```
+
+Claude should use the `cortex_remember` tool. Then verify:
+
+```
+Ask Claude: "What do you remember about the database?"
+```
+
+Claude should use `cortex_recall` and find your memory.
+
+### Step 5: Start the Dashboard (Optional)
+
+The web dashboard lets you browse and search memories visually.
+
+```bash
+# Start the dashboard (opens http://localhost:5173)
+omni-cortex-dashboard
+```
+
+Or manually:
+```bash
+# Terminal 1: Backend (uses dashboard's own venv)
+cd dashboard/backend
+.venv/Scripts/python -m uvicorn main:app --host 127.0.0.1 --port 8765 --reload
+
+# Terminal 2: Frontend
+cd dashboard/frontend
+npm install
+npm run dev
+```
+
+Open http://localhost:5173 in your browser.
+
+**Note:** The dashboard has its own virtual environment at `dashboard/backend/.venv` with FastAPI and other web dependencies. This is separate from the project root `.venv` which contains the MCP server package.
+
+### Troubleshooting
+
+<details>
+<summary><b>❌ "omni-cortex-setup" command not found</b></summary>
+
+**Cause:** pip installed to a location not in your PATH.
+
+**Solution:**
+```bash
+# Find where pip installed it
+python -m omni_cortex.setup
+
+# Or add Python scripts to PATH (Windows)
+# Add %APPDATA%\Python\Python3x\Scripts to your PATH
+
+# On macOS/Linux, ensure ~/.local/bin is in PATH
+export PATH="$HOME/.local/bin:$PATH"
+```
+</details>
+
+<details>
+<summary><b>❌ Claude doesn't see cortex_* tools</b></summary>
+
+**Cause:** MCP server not configured or Claude Code not restarted.
+
+**Solution:**
+1. Check `~/.claude.json` contains the `omni-cortex` MCP server entry
+2. Fully close and reopen Claude Code (not just the terminal)
+3. Run `omni-cortex-setup` again if needed
+</details>
+
+<details>
+<summary><b>❌ "ModuleNotFoundError: No module named 'omni_cortex'"</b></summary>
+
+**Cause:** Python environment mismatch.
+
+**Solution:**
+```bash
+# Ensure you're using the same Python that pip used
+which python  # or `where python` on Windows
+pip show omni-cortex  # Check if installed
+
+# Reinstall if needed
+pip install --force-reinstall omni-cortex
+```
+</details>
+
+<details>
+<summary><b>❌ Dashboard won't start</b></summary>
+
+**Cause:** Missing dependencies or port conflict.
+
+**Solution:**
+```bash
+# Install backend dependencies
+cd dashboard/backend
+pip install -e .
+
+# Check if port 8765 is in use
+# Windows: netstat -ano | findstr :8765
+# macOS/Linux: lsof -i :8765
+
+# Use a different port if needed
+uvicorn main:app --port 8766
+```
+</details>
+
+<details>
+<summary><b>❌ Semantic search not working</b></summary>
+
+**Cause:** Semantic extras not installed.
+
+**Solution:**
+```bash
+pip install omni-cortex[semantic]
+```
+
+First search will download the embedding model (~100MB).
+</details>
+
+---
+
+## Installation (Detailed)
 
 ### Quick Install (Recommended)
 
@@ -294,18 +469,72 @@ The PDFs use a light theme with blue/purple/green accents. Edit `docs/create_pdf
 
 ## Development
 
+### Quick Setup (with Claude Code)
+
+If you're using Claude Code, just run:
+
 ```bash
-# Install dev dependencies
-pip install -e ".[dev]"
+/dev-setup
+```
+
+This will guide you through setting up the development environment.
+
+### Manual Setup
 
-# Run tests
+```bash
+# Clone and install in editable mode
+git clone https://github.com/AllCytes/Omni-Cortex.git
+cd Omni-Cortex
+pip install -e .
+
+# Dashboard backend has its own venv (already included in repo)
+# If missing, set it up:
+cd dashboard/backend
+python -m venv .venv
+.venv/Scripts/pip install -r requirements.txt  # Windows
+# .venv/bin/pip install -r requirements.txt    # macOS/Linux
+cd ../frontend && npm install
+cd ../..
+
+# Verify installation
+omni-cortex --help
+omni-cortex-dashboard --help
+```
+
+**Important**: Always use `pip install -e .` (editable mode) so changes are immediately reflected without reinstalling.
+
+### Project Structure
+
+```
+omni-cortex/
+├── .venv/                       # Project root venv (omni-cortex MCP package)
+├── src/omni_cortex/             # MCP server source code
+├── dashboard/
+│   ├── backend/
+│   │   ├── .venv/               # Dashboard backend venv (FastAPI, uvicorn)
+│   │   ├── main.py              # FastAPI application
+│   │   └── database.py          # Database queries
+│   └── frontend/                # Vue 3 + Vite frontend
+├── adws/                        # Agentic Development Workflows
+├── specs/                       # Implementation plans
+│   ├── todo/                    # Plans waiting to be built
+│   └── done/                    # Completed plans
+└── tests/                       # Unit tests
+```
+
+**Why two venvs?** The dashboard is a standalone web application that can be packaged/deployed separately from the MCP server. They have different dependencies (MCP server needs `mcp`, dashboard needs `fastapi`).
+
+### Running Tests
+
+```bash
 pytest
 
-# Format code
-black src tests
-ruff check src tests
+# With coverage
+pytest --cov=src/omni_cortex
 ```
 
+See [CONTRIBUTING.md](CONTRIBUTING.md) for full development guidelines.
+
 ## Security
 
 Omni Cortex v1.0.3 has been security reviewed:

omni_cortex-1.11.3.dist-info/RECORD

@@ -0,0 +1,25 @@
+omni_cortex-1.11.3.data/data/share/omni-cortex/hooks/post_tool_use.py,sha256=kHBRCP6VctSk3evApsgDaL3UElGSEBGwRfV4hBZPqgE,14539
+omni_cortex-1.11.3.data/data/share/omni-cortex/hooks/pre_tool_use.py,sha256=mkZ7eeBnjWkIgNnrqfYSXIhhLNYYk4hQx_6F0pNrGoc,6395
+omni_cortex-1.11.3.data/data/share/omni-cortex/hooks/session_utils.py,sha256=3SKPCytqWuRPOupWdzmwBoKBDJqtLcT1Nle_pueDQUY,5746
+omni_cortex-1.11.3.data/data/share/omni-cortex/hooks/stop.py,sha256=T1bwcmbTLj0gzjrVvFBT1zB6wff4J2YkYBAY-ZxZI5g,5336
+omni_cortex-1.11.3.data/data/share/omni-cortex/hooks/subagent_stop.py,sha256=V9HQSFGNOfkg8ZCstPEy4h5V8BP4AbrVr8teFzN1kNk,3314
+omni_cortex-1.11.3.data/data/share/omni-cortex/dashboard/backend/.env.example,sha256=9xS7-UiWlMddRwzlyyyKNHAMlNTsgH-2sPV266guJpQ,372
+omni_cortex-1.11.3.data/data/share/omni-cortex/dashboard/backend/backfill_summaries.py,sha256=ElchfcBv4pmVr2PsePCgFlCyuvf4_jDJj_C3AmMhu7U,8973
+omni_cortex-1.11.3.data/data/share/omni-cortex/dashboard/backend/chat_service.py,sha256=5UCvLayZGeSdGsYAzOeupumclAhoFLusGYLdyl33ANc,9304
+omni_cortex-1.11.3.data/data/share/omni-cortex/dashboard/backend/database.py,sha256=LAN7GSM2tvMcJaL0RrGJurH9-tw3cs2QtPduqCbLvj0,34974
+omni_cortex-1.11.3.data/data/share/omni-cortex/dashboard/backend/image_service.py,sha256=NP6ojFpHb6iNTYRkXqYu1CL6WvooZpZ54mjLiWSWG_g,19205
+omni_cortex-1.11.3.data/data/share/omni-cortex/dashboard/backend/logging_config.py,sha256=WnunFGET9zlsn9WBpVsio2zI7BiUQanE0xzAQQxIhII,3944
+omni_cortex-1.11.3.data/data/share/omni-cortex/dashboard/backend/main.py,sha256=rJrmYJvkGhRsXOdYKOTRPMVnwA00W5QoGJ_Aa3v-TRE,46219
+omni_cortex-1.11.3.data/data/share/omni-cortex/dashboard/backend/models.py,sha256=LkmcYq1imsyDlMYnX3Z_FOTmPsu37MQEfJSI-w5EjvM,7330
+omni_cortex-1.11.3.data/data/share/omni-cortex/dashboard/backend/project_config.py,sha256=ZxGoeRpHvN5qQyf2hRxrAZiHrPSwdQp59f0di6O1LKM,4352
+omni_cortex-1.11.3.data/data/share/omni-cortex/dashboard/backend/project_scanner.py,sha256=lwFXS8iJbOoxf7FAyo2TjH25neaMHiJ8B3jS57XxtDI,5713
+omni_cortex-1.11.3.data/data/share/omni-cortex/dashboard/backend/prompt_security.py,sha256=LcdZhYy1CfpSq_4BPO6lMJ15phc2ZXLUSBAnAvODVCI,3423
+omni_cortex-1.11.3.data/data/share/omni-cortex/dashboard/backend/pyproject.toml,sha256=9pbbGQXLe1Xd06nZAtDySCHIlfMWvPaB-C6tGZR6umc,502
+omni_cortex-1.11.3.data/data/share/omni-cortex/dashboard/backend/security.py,sha256=nQsoPE0n5dtY9ive00d33W1gL48GgK7C5Ae0BK2oW2k,3479
+omni_cortex-1.11.3.data/data/share/omni-cortex/dashboard/backend/uv.lock,sha256=miB9zGGSirBkjDE-OZTPCnv43Yc98xuAz_Ne8vTNFHg,186004
+omni_cortex-1.11.3.data/data/share/omni-cortex/dashboard/backend/websocket_manager.py,sha256=gNQLd94AcC-InumGQmUolREhiogCzilYWpLN8SRZjHI,3645
+omni_cortex-1.11.3.dist-info/METADATA,sha256=oM6RvKOj_J7rCFrqbgZOiYHxFLxy-eLnIlq5QHIEf_o,15712
+omni_cortex-1.11.3.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+omni_cortex-1.11.3.dist-info/entry_points.txt,sha256=rohx4mFH2ffZmMb9QXPZmFf-ZGjA3jpKVDVeET-ttiM,150
+omni_cortex-1.11.3.dist-info/licenses/LICENSE,sha256=oG_397owMmi-Umxp5sYocJ6RPohp9_bDNnnEu9OUphg,1072
+omni_cortex-1.11.3.dist-info/RECORD,,

omni_cortex-1.2.0.data/data/share/omni-cortex/hooks/post_tool_use.py

@@ -1,160 +0,0 @@
-#!/usr/bin/env python3
-"""PostToolUse hook - logs tool result after execution.
-
-This hook is called by Claude Code after each tool completes.
-It logs the tool output, duration, and success/error status.
-
-Hook configuration for settings.json:
-{
-    "hooks": {
-        "PostToolUse": [
-            {
-                "type": "command",
-                "command": "python hooks/post_tool_use.py"
-            }
-        ]
-    }
-}
-"""
-
-import json
-import sys
-import os
-import sqlite3
-from datetime import datetime, timezone
-from pathlib import Path
-
-
-def get_db_path() -> Path:
-    """Get the database path for the current project."""
-    project_path = os.environ.get("CLAUDE_PROJECT_DIR", os.getcwd())
-    return Path(project_path) / ".omni-cortex" / "cortex.db"
-
-
-def ensure_database(db_path: Path) -> sqlite3.Connection:
-    """Ensure database exists and is initialized.
-
-    Auto-creates the database and schema if it doesn't exist.
-    This enables 'out of the box' functionality.
-    """
-    db_path.parent.mkdir(parents=True, exist_ok=True)
-    conn = sqlite3.connect(str(db_path))
-
-    # Check if schema exists
-    cursor = conn.cursor()
-    cursor.execute("SELECT name FROM sqlite_master WHERE type='table' AND name='activities'")
-    if cursor.fetchone() is None:
-        # Apply minimal schema for activities (full schema applied by MCP)
-        conn.executescript("""
-            CREATE TABLE IF NOT EXISTS activities (
-                id TEXT PRIMARY KEY,
-                session_id TEXT,
-                agent_id TEXT,
-                timestamp TEXT NOT NULL,
-                event_type TEXT NOT NULL,
-                tool_name TEXT,
-                tool_input TEXT,
-                tool_output TEXT,
-                duration_ms INTEGER,
-                success INTEGER DEFAULT 1,
-                error_message TEXT,
-                project_path TEXT,
-                file_path TEXT,
-                metadata TEXT
-            );
-            CREATE INDEX IF NOT EXISTS idx_activities_timestamp ON activities(timestamp DESC);
-            CREATE INDEX IF NOT EXISTS idx_activities_tool ON activities(tool_name);
-        """)
-        conn.commit()
-
-    return conn
-
-
-def generate_id() -> str:
-    """Generate a unique activity ID."""
-    timestamp_ms = int(datetime.now().timestamp() * 1000)
-    random_hex = os.urandom(4).hex()
-    return f"act_{timestamp_ms}_{random_hex}"
-
-
-def truncate(text: str, max_length: int = 10000) -> str:
-    """Truncate text to max length."""
-    if len(text) <= max_length:
-        return text
-    return text[:max_length - 20] + "\n... [truncated]"
-
-
-def main():
-    """Process PostToolUse hook."""
-    try:
-        # Read all input at once (more reliable than json.load on stdin)
-        raw_input = sys.stdin.read()
-        if not raw_input or not raw_input.strip():
-            print(json.dumps({}))
-            return
-
-        input_data = json.loads(raw_input)
-
-        # Extract data from hook input
-        tool_name = input_data.get("tool_name")
-        tool_input = input_data.get("tool_input", {})
-        tool_output = input_data.get("tool_output", {})
-        agent_id = input_data.get("agent_id")
-
-        # Determine success/error
-        is_error = input_data.get("is_error", False)
-        error_message = None
-        if is_error and isinstance(tool_output, dict):
-            error_message = tool_output.get("error") or tool_output.get("message")
-
-        # Skip logging our own tools to prevent recursion
-        # MCP tools are named like "mcp__omni-cortex__cortex_remember"
-        if tool_name and ("cortex_" in tool_name or "omni-cortex" in tool_name):
-            print(json.dumps({}))
-            return
-
-        session_id = os.environ.get("CLAUDE_SESSION_ID")
-        project_path = os.environ.get("CLAUDE_PROJECT_DIR", os.getcwd())
-
-        # Auto-initialize database (creates if not exists)
-        db_path = get_db_path()
-        conn = ensure_database(db_path)
-
-        # Insert activity record
-        cursor = conn.cursor()
-        cursor.execute(
-            """
-            INSERT INTO activities (
-                id, session_id, agent_id, timestamp, event_type,
-                tool_name, tool_input, tool_output, success, error_message, project_path
-            ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
-            """,
-            (
-                generate_id(),
-                session_id,
-                agent_id,
-                datetime.now(timezone.utc).isoformat(),
-                "post_tool_use",
-                tool_name,
-                truncate(json.dumps(tool_input, default=str)),
-                truncate(json.dumps(tool_output, default=str)),
-                0 if is_error else 1,
-                error_message,
-                project_path,
-            ),
-        )
-        conn.commit()
-        conn.close()
-
-        # Return empty response (no modification)
-        print(json.dumps({}))
-
-    except Exception as e:
-        # Hooks should never block - log error but continue
-        print(json.dumps({"systemMessage": f"Cortex post_tool_use: {e}"}))
-
-    sys.exit(0)
-
-
-if __name__ == "__main__":
-    main()

omni_cortex-1.2.0.dist-info/RECORD

@@ -1,20 +0,0 @@
-omni_cortex-1.2.0.data/data/share/omni-cortex/hooks/post_tool_use.py,sha256=zXy30KNDW6UoWP0nwq5n320r1wFa-tE6V4QuSdDzx8w,5106
-omni_cortex-1.2.0.data/data/share/omni-cortex/hooks/pre_tool_use.py,sha256=SlvvEKsIkolDG5Y_35VezY2e7kRpbj1GiDlBW-naj2g,4900
-omni_cortex-1.2.0.data/data/share/omni-cortex/hooks/stop.py,sha256=T1bwcmbTLj0gzjrVvFBT1zB6wff4J2YkYBAY-ZxZI5g,5336
-omni_cortex-1.2.0.data/data/share/omni-cortex/hooks/subagent_stop.py,sha256=V9HQSFGNOfkg8ZCstPEy4h5V8BP4AbrVr8teFzN1kNk,3314
-omni_cortex-1.2.0.data/data/share/omni-cortex/dashboard/backend/chat_service.py,sha256=hmTvlwK5w29nOLUGCwaaIslEuLgA1-JezXbLwxWDSdM,8265
-omni_cortex-1.2.0.data/data/share/omni-cortex/dashboard/backend/database.py,sha256=HNwfyfebHq0Gdooc4bZdyNp_FD7WFx9z6KJkWLWtHp8,25400
-omni_cortex-1.2.0.data/data/share/omni-cortex/dashboard/backend/image_service.py,sha256=fHP4AA9rM9r05PMglO1eY9Fd93v0JaNuaUX2HiRA-PI,18013
-omni_cortex-1.2.0.data/data/share/omni-cortex/dashboard/backend/logging_config.py,sha256=dFcNqfw2jTfUjFERV_Pr5r5PjY9wSQGXEYPf0AyR5Yk,2869
-omni_cortex-1.2.0.data/data/share/omni-cortex/dashboard/backend/main.py,sha256=RCKdsvOp1oJC64dZjh08b2NqCozSJdvla2wCmRexrk4,30478
-omni_cortex-1.2.0.data/data/share/omni-cortex/dashboard/backend/models.py,sha256=lWb4Rvy6E-x21CGAeahSdVRzxGCVrEgYdc5vKbfo6_A,5671
-omni_cortex-1.2.0.data/data/share/omni-cortex/dashboard/backend/project_config.py,sha256=ZxGoeRpHvN5qQyf2hRxrAZiHrPSwdQp59f0di6O1LKM,4352
-omni_cortex-1.2.0.data/data/share/omni-cortex/dashboard/backend/project_scanner.py,sha256=lwFXS8iJbOoxf7FAyo2TjH25neaMHiJ8B3jS57XxtDI,5713
-omni_cortex-1.2.0.data/data/share/omni-cortex/dashboard/backend/pyproject.toml,sha256=9pbbGQXLe1Xd06nZAtDySCHIlfMWvPaB-C6tGZR6umc,502
-omni_cortex-1.2.0.data/data/share/omni-cortex/dashboard/backend/uv.lock,sha256=e7IMinX0BR2EcnpPwHYCdDJQDzuDzQ3D-FmPOiPKfGA,131248
-omni_cortex-1.2.0.data/data/share/omni-cortex/dashboard/backend/websocket_manager.py,sha256=fv16XkRkgN4SDNwTiP_p9qFnWta9lIpAXgKbFETZ7uM,2770
-omni_cortex-1.2.0.dist-info/METADATA,sha256=FYI3wuEZJ6oV0Mvla_GvwumdOzhvl938i-g2ZV4SM18,9855
-omni_cortex-1.2.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-omni_cortex-1.2.0.dist-info/entry_points.txt,sha256=rohx4mFH2ffZmMb9QXPZmFf-ZGjA3jpKVDVeET-ttiM,150
-omni_cortex-1.2.0.dist-info/licenses/LICENSE,sha256=oG_397owMmi-Umxp5sYocJ6RPohp9_bDNnnEu9OUphg,1072
-omni_cortex-1.2.0.dist-info/RECORD,,