omni-cortex 1.6.0__tar.gz → 1.7.1__tar.gz

{omni_cortex-1.6.0 → omni_cortex-1.7.1}/.gitignore

@@ -155,3 +155,8 @@ PROMPT.md
 memories.json
 .claude/
 .mcp.json
+
+# Personal/local files
+adws/
+specs/omni-cortex-adw-system.md
+nul

{omni_cortex-1.6.0 → omni_cortex-1.7.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: omni-cortex
-Version: 1.6.0
+Version: 1.7.1
 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
@@ -24,6 +24,7 @@ Requires-Python: >=3.10
 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 +77,179 @@ 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
+cd dashboard/backend
+pip install -e .
+uvicorn main:app --host 0.0.0.0 --port 8765 --reload
+
+# Terminal 2: Frontend
+cd dashboard/frontend
+npm install
+npm run dev
+```
+
+Open http://localhost:5173 in your browser.
+
+### 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 +467,47 @@ 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
+/dev-setup
+```
+
+This will guide you through setting up the development environment.
+
+### Manual Setup
+
 ```bash
-# Install dev dependencies
-pip install -e ".[dev]"
+# Clone and install in editable mode
+git clone https://github.com/AllCytes/Omni-Cortex.git
+cd Omni-Cortex
+pip install -e .
+
+# Install dashboard dependencies
+cd dashboard/backend && pip install -r requirements.txt
+cd ../frontend && npm install
+cd ../..
 
-# Run tests
+# Verify installation
+omni-cortex --help
+omni-cortex-dashboard --help
+```
+
+**Important**: Always use `pip install -e .` (editable mode) so changes are immediately reflected without reinstalling.
+
+### 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.6.0 → omni_cortex-1.7.1}/README.md

@@ -39,7 +39,179 @@ 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
+cd dashboard/backend
+pip install -e .
+uvicorn main:app --host 0.0.0.0 --port 8765 --reload
+
+# Terminal 2: Frontend
+cd dashboard/frontend
+npm install
+npm run dev
+```
+
+Open http://localhost:5173 in your browser.
+
+### 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)
 
@@ -257,18 +429,47 @@ 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
+/dev-setup
+```
+
+This will guide you through setting up the development environment.
+
+### Manual Setup
+
 ```bash
-# Install dev dependencies
-pip install -e ".[dev]"
+# Clone and install in editable mode
+git clone https://github.com/AllCytes/Omni-Cortex.git
+cd Omni-Cortex
+pip install -e .
+
+# Install dashboard dependencies
+cd dashboard/backend && pip install -r requirements.txt
+cd ../frontend && npm install
+cd ../..
 
-# Run tests
+# Verify installation
+omni-cortex --help
+omni-cortex-dashboard --help
+```
+
+**Important**: Always use `pip install -e .` (editable mode) so changes are immediately reflected without reinstalling.
+
+### 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.7.1/dashboard/backend/.env.example

@@ -0,0 +1,12 @@
+# Dashboard Backend Environment Configuration
+#
+# NOTE: This file is for reference only.
+# The dashboard now loads from the PROJECT ROOT .env file.
+#
+# Copy the root .env.example to .env and configure there:
+#   cp ../../.env.example ../../.env
+#
+# Required settings in root .env:
+#   GEMINI_API_KEY=your-api-key-here
+#
+# See ../../.env.example for all available options.

{omni_cortex-1.6.0 → omni_cortex-1.7.1}/dashboard/backend/chat_service.py

@@ -1,6 +1,7 @@
 """Chat service for natural language queries about memories using Gemini Flash."""
 
 import os
+from pathlib import Path
 from typing import Optional, AsyncGenerator, Any
 
 from dotenv import load_dotenv
@@ -9,8 +10,9 @@ from database import search_memories, get_memories, create_memory
 from models import FilterParams
 from prompt_security import build_safe_prompt, xml_escape
 
-# Load environment variables
-load_dotenv()
+# Load environment variables from project root
+_project_root = Path(__file__).parent.parent.parent
+load_dotenv(_project_root / ".env")
 
 # Configure Gemini
 _api_key = os.getenv("GEMINI_API_KEY") or os.getenv("GOOGLE_API_KEY")

{omni_cortex-1.6.0 → omni_cortex-1.7.1}/dashboard/backend/image_service.py

@@ -5,6 +5,7 @@ import os
 import uuid
 from dataclasses import dataclass, field
 from enum import Enum
+from pathlib import Path
 from typing import Optional
 
 from dotenv import load_dotenv
@@ -12,7 +13,9 @@ from dotenv import load_dotenv
 from database import get_memory_by_id
 from prompt_security import xml_escape
 
-load_dotenv()
+# Load environment variables from project root
+_project_root = Path(__file__).parent.parent.parent
+load_dotenv(_project_root / ".env")
 
 
 class ImagePreset(str, Enum):