omni-cortex 1.7.0__tar.gz → 1.8.0__tar.gz

{omni_cortex-1.7.0 → omni_cortex-1.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: omni-cortex
-Version: 1.7.0
+Version: 1.8.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
@@ -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)
 
@@ -312,8 +487,12 @@ 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
+# 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 ../..
 
@@ -324,6 +503,27 @@ 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

{omni_cortex-1.7.0 → omni_cortex-1.8.0}/README.md

@@ -39,7 +39,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)
 
@@ -275,8 +448,12 @@ 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
+# 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 ../..
 
@@ -287,6 +464,27 @@ 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

omni_cortex-1.8.0/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.7.0 → omni_cortex-1.8.0}/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.7.0 → omni_cortex-1.8.0}/dashboard/backend/database.py

@@ -1049,8 +1049,8 @@ def create_memory(
     # Insert memory
     conn.execute(
         """
-        INSERT INTO memories (id, content, context, type, status, importance_score, access_count, created_at, last_accessed, tags)
-        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+        INSERT INTO memories (id, content, context, type, status, importance_score, access_count, created_at, last_accessed, updated_at, tags)
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
         """,
         (
             memory_id,
@@ -1062,6 +1062,7 @@ def create_memory(
             0,
             now,
             now,
+            now,
             json.dumps(tags) if tags else None,
         ),
     )

{omni_cortex-1.7.0 → omni_cortex-1.8.0}/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):

{omni_cortex-1.7.0 → omni_cortex-1.8.0}/dashboard/backend/main.py

@@ -31,6 +31,7 @@ except ImportError:
 
 from database import (
     bulk_update_memory_status,
+    create_memory,
     delete_memory,
     ensure_migrations,
     get_activities,
@@ -62,6 +63,7 @@ from models import (
     ConversationSaveRequest,
     ConversationSaveResponse,
     FilterParams,
+    MemoryCreateRequest,
     MemoryUpdate,
     ProjectInfo,
     ProjectRegistration,
@@ -230,6 +232,20 @@ if RATE_LIMITING_AVAILABLE:
 else:
     limiter = None
 
+
+def rate_limit(limit_string: str):
+    """Decorator for conditional rate limiting.
+
+    Returns the actual limiter decorator if available, otherwise a no-op.
+    Usage: @rate_limit("10/minute")
+    """
+    if limiter is not None:
+        return limiter.limit(limit_string)
+    # No-op decorator when rate limiting is not available
+    def noop_decorator(func):
+        return func
+    return noop_decorator
+
 # CORS configuration (environment-aware)
 cors_config = get_cors_config()
 app.add_middleware(
@@ -333,6 +349,7 @@ async def refresh_projects():
 
 
 @app.get("/api/memories")
+@rate_limit("100/minute")
 async def list_memories(
     project: str = Query(..., description="Path to the database file"),
     memory_type: Optional[str] = Query(None, alias="type"),
@@ -373,6 +390,46 @@ async def list_memories(
         raise
 
 
+@app.post("/api/memories")
+@rate_limit("30/minute")
+async def create_memory_endpoint(
+    request: MemoryCreateRequest,
+    project: str = Query(..., description="Path to the database file"),
+):
+    """Create a new memory."""
+    try:
+        if not Path(project).exists():
+            log_error("/api/memories POST", FileNotFoundError("Database not found"), project=project)
+            raise HTTPException(status_code=404, detail="Database not found")
+
+        # Create the memory
+        memory_id = create_memory(
+            db_path=project,
+            content=request.content,
+            memory_type=request.memory_type,
+            context=request.context,
+            tags=request.tags if request.tags else None,
+            importance_score=request.importance_score,
+        )
+
+        # Fetch the created memory to return it
+        created_memory = get_memory_by_id(project, memory_id)
+
+        # Broadcast to WebSocket clients
+        await manager.broadcast("memory_created", created_memory.model_dump(by_alias=True))
+
+        log_success("/api/memories POST", memory_id=memory_id, type=request.memory_type)
+        return created_memory
+    except HTTPException:
+        raise
+    except Exception as e:
+        import traceback
+        print(f"[DEBUG] create_memory_endpoint error: {type(e).__name__}: {e}")
+        traceback.print_exc()
+        log_error("/api/memories POST", e, project=project)
+        raise
+
+
 # NOTE: These routes MUST be defined before /api/memories/{memory_id} to avoid path conflicts
 @app.get("/api/memories/needs-review")
 async def get_memories_needing_review_endpoint(
@@ -744,6 +801,7 @@ async def chat_status():
 
 
 @app.post("/api/chat", response_model=ChatResponse)
+@rate_limit("10/minute")
 async def chat_with_memories(
     request: ChatRequest,
     project: str = Query(..., description="Path to the database file"),
@@ -770,6 +828,7 @@ async def chat_with_memories(
 
 
 @app.get("/api/chat/stream")
+@rate_limit("10/minute")
 async def stream_chat(
     project: str = Query(..., description="Path to the database file"),
     question: str = Query(..., description="The question to ask"),
@@ -846,6 +905,7 @@ async def get_image_presets():
 
 
 @app.post("/api/image/generate-batch", response_model=BatchImageGenerationResponse)
+@rate_limit("5/minute")
 async def generate_images_batch(
     request: BatchImageGenerationRequest,
     db_path: str = Query(..., alias="project", description="Path to the database file"),
@@ -903,6 +963,7 @@ async def generate_images_batch(
 
 
 @app.post("/api/image/refine", response_model=SingleImageResponseModel)
+@rate_limit("5/minute")
 async def refine_image(request: ImageRefineRequest):
     """Refine an existing generated image with a new prompt."""
     result = await image_service.refine_image(

{omni_cortex-1.7.0 → omni_cortex-1.8.0}/dashboard/backend/models.py

@@ -128,6 +128,16 @@ class FilterParams(BaseModel):
     offset: int = 0
 
 
+class MemoryCreateRequest(BaseModel):
+    """Create request for a new memory."""
+
+    content: str = Field(..., min_length=1, max_length=50000)
+    memory_type: str = Field(default="general")
+    context: Optional[str] = None
+    importance_score: int = Field(default=50, ge=1, le=100)
+    tags: list[str] = Field(default_factory=list)
+
+
 class MemoryUpdate(BaseModel):
     """Update request for a memory."""
 

{omni_cortex-1.7.0 → omni_cortex-1.8.0}/omni_cortex/__init__.py

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

{omni_cortex-1.7.0 → omni_cortex-1.8.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "omni-cortex"
-version = "1.7.0"
+version = "1.8.0"
 description = "Give Claude Code a perfect memory - auto-logs everything, searches smartly, and gets smarter over time"
 readme = "README.md"
 license = "MIT"
@@ -31,6 +31,8 @@ dependencies = [
     "pydantic>=2.0.0",
     "httpx>=0.25.0",
     "pyyaml>=6.0.0",
+    "python-dotenv>=1.0.0",
+    "claude-agent-sdk>=0.1.0",
 ]
 
 [project.urls]

omni_cortex-1.7.0/dashboard/backend/.env.example

@@ -1,22 +0,0 @@
-# Omni-Cortex Dashboard Environment Configuration
-# Copy this file to .env and fill in your values
-
-# Gemini API Key for AI chat and image generation
-# Get your key from: https://aistudio.google.com/apikey
-GEMINI_API_KEY=your-api-key-here
-
-# Alternative (also works)
-# GOOGLE_API_KEY=your-api-key-here
-
-# API Key for dashboard access (auto-generated if not set)
-# DASHBOARD_API_KEY=your-secret-key-here
-
-# Environment: development or production
-# ENVIRONMENT=development
-
-# CORS Origins (comma-separated, for production)
-# CORS_ORIGINS=https://your-domain.com
-
-# SSL Configuration (optional, for HTTPS)
-# SSL_KEYFILE=/path/to/key.pem
-# SSL_CERTFILE=/path/to/cert.pem