Metadata-Version: 2.4
Name: omni-cortex
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
Project-URL: Issues, https://github.com/AllCytes/Omni-Cortex/issues
Project-URL: Documentation, https://github.com/AllCytes/Omni-Cortex#readme
Author: Tony
License-Expression: MIT
License-File: LICENSE
Keywords: ai,anthropic,claude,claude-code,llm,mcp,memory,semantic-search
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
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: httpx>=0.25.0
Requires-Dist: mcp>=1.0.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: pyyaml>=6.0.0
Provides-Extra: dev
Requires-Dist: black>=23.0.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Provides-Extra: semantic
Requires-Dist: numpy>=1.24.0; extra == 'semantic'
Requires-Dist: sentence-transformers>=2.2.0; extra == 'semantic'
Description-Content-Type: text/markdown

# Omni Cortex MCP

A universal memory system for Claude Code that combines activity logging with intelligent knowledge storage.

## What Is This?

**For AI/ML experts:** A dual-layer context system with activity provenance, hybrid semantic search (FTS5 + embeddings), and temporal importance decay. Think of it as **Git + Elasticsearch + a knowledge graph for AI context**.

**For developers:** It gives Claude Code a persistent, searchable memory that auto-logs everything and gets smarter over time. Like a **senior developer's institutional knowledge**—searchable, organized, and always available.

**For everyone:** It makes your AI assistant actually remember things. No more re-explaining your project every session.

### Why Not Just Use CLAUDE.md or Basic Memory?

| Feature | Claude Code | CLAUDE.md | Basic MCP | Omni-Cortex |
|---------|:-----------:|:---------:|:---------:|:-----------:|
| Persists between sessions | ❌ | ✅ | ✅ | ✅ |
| Auto-logs all activity | ❌ | ❌ | ❌ | ✅ |
| Hybrid search (keyword + semantic) | ❌ | ❌ | ❌ | ✅ |
| Auto-categorizes memories | ❌ | ❌ | ❌ | ✅ |
| Importance decay + access boosting | ❌ | ❌ | ❌ | ✅ |
| Session history & context | ❌ | ❌ | ❌ | ✅ |
| Memory relationships | ❌ | ❌ | ❌ | ✅ |
| Cross-project search | ❌ | ❌ | ❌ | ✅ |
| Visual dashboard | ❌ | ❌ | ❌ | ✅ |

**The difference:** Basic solutions are like sticky notes. Omni-Cortex is like having a trusted long-term employee who remembers everything, files it automatically, and hands you exactly what you need.

## Features

- **Zero Configuration**: Works out of the box - just install and run setup
- **Dual-Layer Storage**: Activity logging (audit trail) + Knowledge store (memories)
- **18 MCP Tools**: Full-featured API for memory management, activity tracking, session continuity, and cross-project search
- **Semantic Search**: AI-powered search using sentence-transformers (optional)
- **Hybrid Search**: Combines keyword (FTS5) + semantic search for best results
- **Full-Text Search**: SQLite FTS5-powered keyword search with smart ranking
- **Auto-Categorization**: Automatic memory type detection and tag suggestions
- **Session Continuity**: "Last time you were working on..." context
- **Importance Decay**: Frequently accessed memories naturally surface
- **Auto Activity Logging**: Automatically logs all tool calls via hooks

## Installation

### Quick Install (Recommended)

```bash
# Install the package
pip install omni-cortex

# Run automatic setup (configures MCP server + hooks)
omni-cortex-setup
```

That's it! Omni Cortex will now:
- Automatically log all Claude Code tool calls
- Provide memory tools (cortex_remember, cortex_recall, etc.)
- Create a per-project database at `.omni-cortex/cortex.db`

### With Semantic Search

For AI-powered semantic search capabilities:

```bash
pip install omni-cortex[semantic]
omni-cortex-setup
```

### From Source

```bash
git clone https://github.com/AllCytes/Omni-Cortex.git
cd omni-cortex
pip install -e ".[semantic]"
python -m omni_cortex.setup
```

### Manual Configuration

If you prefer manual setup, add to `~/.claude.json`:

```json
{
  "mcpServers": {
    "omni-cortex": {
      "command": "python",
      "args": ["-m", "omni_cortex.server"]
    }
  }
}
```

And optionally configure hooks in `~/.claude/settings.json` for activity logging:

```json
{
  "hooks": {
    "PreToolUse": [{
      "type": "command",
      "command": "python -m omni_cortex.hooks.pre_tool_use"
    }],
    "PostToolUse": [{
      "type": "command",
      "command": "python -m omni_cortex.hooks.post_tool_use"
    }]
  }
}
```

### Uninstall

```bash
omni-cortex-setup --uninstall
pip uninstall omni-cortex
```

## Tools

### Memory Tools (6)

| Tool | Description |
|------|-------------|
| `cortex_remember` | Store information with auto-categorization |
| `cortex_recall` | Search memories (modes: keyword, semantic, hybrid) |
| `cortex_list_memories` | List memories with filters and pagination |
| `cortex_update_memory` | Update memory content, tags, or status |
| `cortex_forget` | Delete a memory |
| `cortex_link_memories` | Create relationships between memories |

### Activity Tools (3)

| Tool | Description |
|------|-------------|
| `cortex_log_activity` | Manually log an activity |
| `cortex_get_activities` | Query the activity log |
| `cortex_get_timeline` | Get a chronological timeline |

### Session Tools (3)

| Tool | Description |
|------|-------------|
| `cortex_start_session` | Start a new session with context |
| `cortex_end_session` | End session and generate summary |
| `cortex_get_session_context` | Get context from previous sessions |

### Utility Tools (3)

| Tool | Description |
|------|-------------|
| `cortex_list_tags` | List all tags with usage counts |
| `cortex_review_memories` | Review and update memory freshness |
| `cortex_export` | Export data to markdown or JSON |

### Global Tools (3)

| Tool | Description |
|------|-------------|
| `cortex_global_search` | Search memories across all projects |
| `cortex_global_stats` | Get global index statistics |
| `cortex_sync_to_global` | Manually sync to global index |

## Memory Types

Memories are automatically categorized into:

- `general` - General notes and information
- `warning` - Cautions, things to avoid
- `tip` - Tips, tricks, best practices
- `config` - Configuration and settings
- `troubleshooting` - Debugging and problem-solving
- `code` - Code snippets and algorithms
- `error` - Error messages and failures
- `solution` - Solutions to problems
- `command` - CLI commands
- `concept` - Definitions and explanations
- `decision` - Architectural decisions

## Storage

- **Per-project**: `.omni-cortex/cortex.db` in your project directory
- **Global**: `~/.omni-cortex/global.db` for cross-project search

## Configuration

Create `.omni-cortex/config.yaml` in your project:

```yaml
schema_version: "1.0"
embedding_enabled: true
decay_rate_per_day: 0.5
freshness_review_days: 30
auto_provide_context: true
context_depth: 3
```

## Web Dashboard

A visual interface for browsing, searching, and managing your memories.

![Dashboard Preview](docs/images/dashboard-preview.png)

### Features
- **Memory Browser**: View, search, filter, and edit memories
- **Ask AI**: Chat with your memories using Gemini
- **Real-time Updates**: WebSocket-based live sync
- **Statistics**: Memory counts, types, tags distribution
- **Project Switcher**: Switch between project databases

### Quick Start

```bash
# Backend (requires Python 3.10+)
cd dashboard/backend
pip install -e .
uvicorn main:app --host 0.0.0.0 --port 8765 --reload

# Frontend (requires Node.js 18+)
cd dashboard/frontend
npm install
npm run dev
```

Open http://localhost:5173 in your browser.

### Ask AI Setup (Optional)

To enable the "Ask AI" chat feature, set your Gemini API key:

```bash
export GEMINI_API_KEY=your_api_key_here
```

See [dashboard/README.md](dashboard/README.md) for full documentation.

## Documentation

- [Tool Reference](docs/TOOLS.md) - Complete documentation for all 18 tools with examples
- [Configuration Guide](docs/CONFIGURATION.md) - Configuration options and troubleshooting
- **Teaching Materials** (PDF):
  - `docs/OmniCortex_QuickStart.pdf` - 3-page quick start guide
  - `docs/OmniCortex_FeatureComparison.pdf` - Comparison with basic memory MCPs
  - `docs/OmniCortex_Philosophy.pdf` - Design principles and inspiration
  - `docs/OmniCortex_CommandReference.pdf` - All tools with parameters

### Regenerating PDFs

To regenerate the teaching material PDFs:

```bash
# Requires reportlab
pip install reportlab

# Generate all 4 PDFs
python docs/create_pdfs.py
```

The PDFs use a light theme with blue/purple/green accents. Edit `docs/create_pdfs.py` to customize colors or content.

## Development

```bash
# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Format code
black src tests
ruff check src tests
```

## Security

Omni Cortex v1.0.3 has been security reviewed:
- All SQL queries use parameterized statements
- Input validation via Pydantic models
- Model name validation prevents code injection
- YAML loading uses `safe_load()`

## License

MIT
