{"id":37231308,"url":"https://github.com/prometh-sh/prometh-cortex","last_synced_at":"2026-04-21T09:00:40.076Z","repository":{"id":319976095,"uuid":"1047913820","full_name":"prometh-sh/prometh-cortex","owner":"prometh-sh","description":"Prometh Cortex is a personal knowledge orchestration system that transforms notes, tasks, and documents into structured, AI-ready data for insight extraction, traceability, and Retrieval-Augmented Generation (RAG) workflows.","archived":false,"fork":false,"pushed_at":"2026-04-20T20:39:35.000Z","size":322,"stargazers_count":7,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-20T22:33:52.159Z","etag":null,"topics":["genai","prometh","vibe-coding","vibecoding"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/prometh-sh.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":"NOTICE","maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-08-31T14:14:43.000Z","updated_at":"2026-04-20T20:36:45.000Z","dependencies_parsed_at":"2025-10-21T09:26:44.267Z","dependency_job_id":"8c809cfa-196e-49e7-8951-4e0103e7501f","html_url":"https://github.com/prometh-sh/prometh-cortex","commit_stats":null,"previous_names":["ivannagy/prometh-cortex"],"tags_count":10,"template":false,"template_full_name":null,"purl":"pkg:github/prometh-sh/prometh-cortex","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/prometh-sh%2Fprometh-cortex","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/prometh-sh%2Fprometh-cortex/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/prometh-sh%2Fprometh-cortex/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/prometh-sh%2Fprometh-cortex/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/prometh-sh","download_url":"https://codeload.github.com/prometh-sh/prometh-cortex/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/prometh-sh%2Fprometh-cortex/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32084721,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-21T06:27:27.065Z","status":"ssl_error","status_checked_at":"2026-04-21T06:27:21.250Z","response_time":128,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["genai","prometh","vibe-coding","vibecoding"],"created_at":"2026-01-15T03:42:51.948Z","updated_at":"2026-04-21T09:00:40.069Z","avatar_url":"https://github.com/prometh-sh.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Prometh Cortex\n\n[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)\n[![PyPI version](https://img.shields.io/pypi/v/prometh-cortex.svg)](https://pypi.org/project/prometh-cortex/)\n[![Python Support](https://img.shields.io/pypi/pyversions/prometh-cortex.svg)](https://pypi.org/project/prometh-cortex/)\n[![Tests](https://github.com/prometh-sh/prometh-cortex/actions/workflows/test.yml/badge.svg)](https://github.com/prometh-sh/prometh-cortex/actions/workflows/test.yml)\n[![Claude Code](https://img.shields.io/badge/Claude%20Code-Compatible-green.svg)](https://docs.anthropic.com/en/docs/claude-code)\n\nMulti-Datalake RAG Indexer with Local MCP Integration\n\n## Table of Contents\n\n- [Overview](#overview)\n- [Features](#features)\n- [Installation](#installation)\n- [Quick Start](#quick-start)\n- [Configuration](#configuration)\n- [Vector Store Configuration](#vector-store-configuration)\n- [CLI Commands](#cli-commands)\n- [Integration](#integration)\n  - [Claude Desktop](#claude-desktop-integration)\n  - [OpenCode](#opencode-integration)\n  - [Perplexity](#perplexity-integration)\n  - [VSCode](#vscode-with-github-copilot-integration)\n  - [SSE Daemon Mode](#sse-daemon-mode)\n- [Development](#development)\n- [Contributing](#contributing)\n- [License](#license)\n- [Support](#support)\n\n## Overview\n\nPrometh Cortex is a local-first, extensible system for indexing multiple datalake repositories containing Markdown files and exposing their content for retrieval-augmented generation (RAG) workflows through a local MCP (Modular Command Processor) server.\n\n## Features\n\n- **Multi-Datalake Support**: Index multiple repositories of Markdown documents\n- **YAML Frontmatter Parsing**: Rich metadata extraction with structured schema support\n- **Dual Vector Store Support**: Choose between local FAISS or cloud-native Qdrant\n- **Incremental Indexing**: Smart change detection for efficient updates\n- **MCP Server**: Local server with stdio, SSE, and streamable HTTP transports for Claude, OpenCode, VSCode, and other tools\n- **CLI Interface**: Easy-to-use command line tools for indexing and querying\n- **Performance Optimized**: Target \u003c100ms query response time on M1/M2 Mac\n\n## Installation\n\n### From PyPI (Recommended)\n\n```bash\npip install prometh-cortex\n```\n\n### From Source (Development)\n\n```bash\ngit clone https://github.com/prometh-sh/prometh-cortex.git\ncd prometh-cortex\npip install -e \".[dev]\"\n```\n\n## Quick Start\n\n1. **Install via pip**:\n```bash\npip install prometh-cortex\n```\n\n2. **Initialize configuration** (creates `~/.config/prometh-cortex/config.toml`):\n```bash\npcortex config --init\n```\n\n3. **Edit your config file**:\n```bash\n# macOS/Linux\nnano ~/.config/prometh-cortex/config.toml\n\n# Or use your preferred editor\n# Update the [datalake] repos with your document paths\n```\n\n4. **Build index**:\n```bash\npcortex build\n```\n\n5. **Query locally**:\n```bash\npcortex query \"search for something\"\n```\n\n6. **Start servers**:\n```bash\n# For Claude Desktop (MCP protocol)\npcortex mcp\n\n# For Perplexity/VSCode/HTTP integrations\npcortex serve\n```\n\n### Configuration File Locations\n\nPrometh-cortex follows the XDG Base Directory Specification. Config files are searched in this order:\n\n1. `./config.toml` - Current directory (highest priority)\n2. `~/.config/prometh-cortex/config.toml` - XDG config directory (recommended)\n3. `~/.prometh-cortex/config.toml` - Fallback location\n\n**Useful commands**:\n```bash\n# Initialize config in XDG directory (recommended for system-wide use)\npcortex config --init\n\n# Create sample config in current directory (for project-specific config)\npcortex config --sample\n\n# Show all config search paths\npcortex config --show-paths\n```\n\n## Configuration\n\nCreate a `config.toml` file with your settings:\n\n```bash\ncp config.toml.sample config.toml\n# Edit config.toml with your specific paths and settings\n```\n\n### Configuration Format (TOML) - v0.5.0\n\nPrometh Cortex v0.5.0 builds on the unified collection architecture with **memory preservation during force rebuilds**. A single FAISS/Qdrant index contains all documents plus an auto-injected virtual `prmth_memory` source for session summaries and decisions.\n\n```toml\n[datalake]\n# Add your document directories here\nrepos = [\n    \"/path/to/your/notes\",\n    \"/path/to/your/documents\",\n    \"/path/to/your/projects\"\n]\n\n[storage]\nrag_index_dir = \"/path/to/index/storage\"\n\n[server]\nport = 8080\nhost = \"localhost\"\nauth_token = \"your-secure-token\"\ntransport = \"stdio\"  # \"stdio\", \"sse\", or \"streamable-http\" (v0.4.0+)\n\n[embedding]\nmodel = \"sentence-transformers/all-MiniLM-L6-v2\"\nmax_query_results = 10\n\n# Single unified collection\n[[collections]]\nname = \"prometh_cortex\"\n\n# Multiple sources with per-source chunking parameters\n[[sources]]\nname = \"knowledge_base\"\nchunk_size = 768\nchunk_overlap = 76\nsource_patterns = [\"docs/specs\", \"docs/prds\"]\n\n[[sources]]\nname = \"meetings\"\nchunk_size = 512\nchunk_overlap = 51\nsource_patterns = [\"meetings\"]\n\n[[sources]]\nname = \"todos\"\nchunk_size = 256\nchunk_overlap = 26\nsource_patterns = [\"todos\", \"reminders\"]\n\n[[sources]]\nname = \"default\"\nchunk_size = 512\nchunk_overlap = 50\nsource_patterns = [\"*\"]  # Catch-all for unmatched documents\n\n# Virtual memory source (v0.5.0+)\n# Auto-injected; no file-based routing\n# Stores session summaries, decisions, patterns\n# Preserved during force rebuilds\n[[sources]]\nname = \"prmth_memory\"\nchunk_size = 512\nchunk_overlap = 50\nsource_patterns = [\".prmth_memory\"]  # Virtual pattern (won't match real files)\n\n[vector_store]\ntype = \"faiss\"  # or \"qdrant\"\n\n# Qdrant configuration (when type = \"qdrant\")\n[vector_store.qdrant]\nhost = \"localhost\"\nport = 6333\ncollection_name = \"prometh_cortex\"\n```\n\n**Key Features in v0.5.0**:\n- ✅ Memory preservation during `pcortex build --force` and `pcortex rebuild`\n- ✅ Virtual `prmth_memory` source auto-injected into all configs\n- ✅ Session memories queryable immediately (no rebuild needed)\n- ✅ Deduped memories by content hash (idempotent)\n- ✅ Works with both FAISS (sidecar JSON) and Qdrant (filter-based deletion)\n\n**Key Changes from v0.4.0**:\n- ✅ Memory tool now preserves session data across force rebuilds\n- ✅ Better incremental indexing for memory-heavy workflows\n- ✅ Improved metadata tracking for memory documents\n\n**Key Changes from v0.3.0**:\n- ✅ SSE/HTTP Transport for daemon mode\n- ✅ OpenCode first-class support\n- ✅ Auto config generation for all clients\n- ✅ Memory tool for session persistence\n\n## Vector Store Configuration\n\nPrometh Cortex supports two vector store backends:\n\n### Option 1: FAISS (Default - Local Storage)\n\n**Best for**: Local development, private deployments, no external dependencies\n\n```toml\n[vector_store]\ntype = \"faiss\"\n\n[storage]\nrag_index_dir = \".rag_index\"\n```\n\n**Advantages**:\n- ✅ No external dependencies\n- ✅ Fast local queries\n- ✅ Works offline\n- ✅ Simple setup\n\n**Disadvantages**:\n- ❌ Limited to single machine\n- ❌ No concurrent write access\n- ❌ Manual backup required\n\n### Option 2: Qdrant (Cloud-native Vector Database)\n\n**Best for**: Production deployments, team collaboration, scalable solutions\n\n#### Local Qdrant with Docker\n\n```bash\n# Start Qdrant container with persistent storage\ndocker run -d \\\n  --name qdrant \\\n  -p 6333:6333 \\\n  -v $(pwd)/qdrant_storage:/qdrant/storage \\\n  qdrant/qdrant\n\n[vector_store]\ntype = \"qdrant\"\n\n[vector_store.qdrant]\nhost = \"localhost\"\nport = 6333\ncollection_name = \"prometh_cortex\"\n```\n\n#### Cloud Qdrant\n\n```bash\n[vector_store]\ntype = \"qdrant\"\n\n[vector_store.qdrant]\nhost = \"your-cluster.qdrant.io\"\nport = 6333\ncollection_name = \"prometh_cortex\"\napi_key = \"your-api-key-here\"\nuse_https = true\n```\n\n**Advantages**:\n- ✅ Concurrent access support\n- ✅ Built-in clustering and replication\n- ✅ Advanced filtering capabilities\n- ✅ REST API access\n- ✅ Automatic backups (cloud)\n- ✅ Horizontal scaling\n\n**Disadvantages**:\n- ❌ Requires external service\n- ❌ Network dependency\n- ❌ Additional complexity\n\n#### Qdrant Setup Steps\n\n1. **Local Docker Setup**:\n   ```bash\n   # Create persistent storage directory\n   mkdir -p qdrant_storage\n   \n   # Start Qdrant container\n   docker run -d \\\n     --name qdrant \\\n     --restart unless-stopped \\\n     -p 6333:6333 \\\n     -p 6334:6334 \\\n     -v $(pwd)/qdrant_storage:/qdrant/storage \\\n     qdrant/qdrant\n   \n   # Verify Qdrant is running\n   curl http://localhost:6333/health\n   ```\n\n2. **Configure Environment**:\n   ```bash\n# Add to your config.toml:\n[vector_store]\ntype = \"qdrant\"\n\n[vector_store.qdrant]\nhost = \"localhost\"\nport = 6333\ncollection_name = \"prometh_cortex\"\n# api_key = \"\"  # Optional for local Docker  \n# use_https = false  # Default for local\n   ```\n\n3. **Build Index**:\n   ```bash\n   # Initial build or incremental update\n   pcortex build\n   \n   # Force complete rebuild\n   pcortex rebuild --confirm\n   ```\n\n4. **Verify Setup**:\n   ```bash\n   # Check health and statistics\n   pcortex query \"test\" --max-results 1\n   \n   # Or directly check Qdrant\n   curl http://localhost:6333/collections/prometh_cortex\n   ```\n\n#### Qdrant Cloud Setup\n\n1. **Create Qdrant Cloud Account**:\n   - Visit [Qdrant Cloud](https://qdrant.io/cloud/)\n   - Create a cluster and get your credentials\n\n2. **Configure Environment**:\n   ```bash\n# Add to your config.toml:\n[vector_store]\ntype = \"qdrant\"\n\n[vector_store.qdrant]\nhost = \"your-cluster-id.qdrant.io\"\nport = 6333\ncollection_name = \"prometh_cortex\"\napi_key = \"your-api-key\"\nuse_https = true\n   ```\n\n#### Migration Between Vector Stores\n\n```bash\n# Backup current index (if using FAISS)\npcortex build --backup /tmp/backup_$(date +%Y%m%d_%H%M%S)\n\n# Change vector store type in config.toml\nsed -i 's/type = \"faiss\"/type = \"qdrant\"/' config.toml\n\n# Rebuild index with new vector store\npcortex rebuild --confirm\n\n# Verify migration successful\npcortex query \"test migration\" --max-results 1\n```\n\n## CLI Commands\n\n### Build Index\n```bash\n# Initial build (automatic incremental updates)\npcortex build\n\n# Force complete rebuild (ignores incremental changes)\npcortex build --force\n\n# Disable incremental indexing\npcortex build --no-incremental\n\n# Rebuild entire index (with confirmation)\npcortex rebuild\npcortex rebuild --confirm  # Skip confirmation prompt\n```\n\n### Query Index (Unified Collection with Optional Source Filtering)\n```bash\n# Query across all sources in unified collection\npcortex query \"search term\"\n\n# Query with source filtering (optional)\npcortex query \"meeting notes\" --source meetings\npcortex query \"action items\" -s todos\n\n# Query with options\npcortex query \"search term\" --max-results 5 --show-content\n```\n\n### List Sources (v0.3.0+)\n```bash\n# List all configured sources with statistics\npcortex sources\n\n# Verbose output with chunk configuration details\npcortex sources -v\n```\n\n### Start Servers\n\n#### MCP Server (for Claude Desktop, OpenCode, Claude Code)\n```bash\n# Start MCP server with stdio protocol (default)\npcortex mcp start\n\n# Start as persistent SSE daemon (v0.4.0+)\npcortex mcp start --transport sse --port 3100\n\n# SSE on all interfaces (for Tailscale/remote access)\npcortex mcp start -t sse --host 0.0.0.0 -p 3100\n\n# Streamable HTTP transport (newer MCP spec)\npcortex mcp start -t streamable-http --port 3100\n```\n\n#### Generate Client Configs (v0.4.0+)\n```bash\n# Generate config for various clients\npcortex mcp init claude                        # Claude Desktop (stdio)\npcortex mcp init opencode                      # OpenCode (stdio)\npcortex mcp init opencode --write              # Write directly to config file\n\n# Generate SSE client configs (for daemon mode)\npcortex mcp init claude -t sse                 # Claude Desktop (SSE)\npcortex mcp init opencode -t sse               # OpenCode (SSE)\npcortex mcp init opencode -t sse --url http://mac-mini.tail:3100  # Remote SSE\n```\n\n#### HTTP Server (for web integrations)\n```bash\n# Start HTTP server (default: localhost:8080)\npcortex serve\n\n# Custom host/port\npcortex serve --host 0.0.0.0 --port 9000\n\n# Development mode with auto-reload\npcortex serve --reload\n```\n\n## Server Types (v0.3.0+, Transports v0.4.0+, Memory v0.5.0+)\n\n### MCP Protocol Server (`pcortex mcp start`)\n**For Claude Desktop, OpenCode, Claude Code, and other MCP clients**\n\nProvides MCP tools with configurable transport (v0.4.0+):\n- **stdio** (default): Subprocess per client session, suitable for Claude Desktop\n- **sse**: Persistent daemon with Server-Sent Events, shared across multiple clients\n- **streamable-http**: Newer MCP spec HTTP transport (v0.5.0+)\n\nMCP Tools:\n- **prometh_cortex_query**: Search unified index with optional `source_type` filtering\n- **prometh_cortex_list_sources**: List all sources with statistics (v0.3.0+)\n- **prometh_cortex_health**: Get system health status and unified collection metrics\n- **prometh_cortex_memory**: Store session summaries, decisions, patterns directly to index (v0.5.0+)\n\n#### Memory Tool (v0.5.0+)\n\nStore and query session insights without rebuilding the entire index.\n\n**Purpose**: Capture high-value knowledge from agent sessions (OpenCode, Claude Desktop) and make it immediately searchable across your knowledge base.\n\n**Key Features**:\n- ✅ **Immediate Availability**: Documents queryable right after creation (no rebuild needed)\n- ✅ **Automatic Deduplication**: Same title + content = same document ID (idempotent)\n- ✅ **Memory Preservation**: Memories survive `pcortex build --force` and `pcortex rebuild`\n- ✅ **Metadata Rich**: Store tags, session IDs, project references, custom metadata\n- ✅ **Virtual Source**: Auto-injected `prmth_memory` source (no file-based routing)\n\n**Parameters**:\n```json\n{\n  \"title\": \"string (required) — Document title for search\",\n  \"content\": \"string (required) — Markdown body (Content, Decisions, Patterns, etc.)\",\n  \"tags\": [\"array of strings (optional) — e.g., 'kubernetes', 'incident', 'session'\"],\n  \"metadata\": {\n    \"source_project\": \"string (optional) — Project or context\",\n    \"author\": \"string (optional) — Author/agent name\",\n    \"session_id\": \"string (optional) — Session identifier\",\n    \"custom_field\": \"any (optional) — Custom metadata\"\n  }\n}\n```\n\n**Usage Example** (Claude Desktop / OpenCode):\n```\nUser: \"Save this session summary to memory\"\n\nAgent Response:\nprometh_cortex_memory(\n  title=\"Session: Microservices Architecture Review - 2026-04-20\",\n  content=\"\"\"## Summary\nReviewed and documented the microservices architecture decisions for the platform migration project.\n\n## Decisions Made\n- Use event-driven architecture for service communication\n- Implement circuit breaker pattern for resilience\n- Store session state in distributed cache (Redis/Memcached)\n\n## Lessons Learned\n- Service mesh complexity grows with cluster size\n- Proper monitoring critical before production deployment\n- Version compatibility matrix must be maintained\n\n## Next Steps\n- Document API contracts for all services\n- Set up distributed tracing infrastructure\n- Schedule follow-up architecture review in 2 weeks\n\"\"\",\n  tags=[\"session\", \"architecture\", \"microservices\"],\n  metadata={\n    \"session_id\": \"sess_arch_review_2026_04_20\",\n    \"project\": \"platform-migration\",\n    \"version\": \"v0.5.0\"\n  }\n)\n```\n\n**Query Memory Documents**:\n```bash\n# Query across memory documents only\npcortex query \"circuit breaker pattern\" --source prmth_memory\n\n# Query everywhere (memories + other sources)\npcortex query \"architecture decisions\"\n\n# Via HTTP API\ncurl -X POST http://localhost:8001/prometh_cortex_query \\\n  -H \"Authorization: Bearer your-token\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"query\": \"session decisions and lessons learned\",\n    \"source_type\": \"prmth_memory\",\n    \"max_results\": 5\n  }'\n```\n\n**Force Rebuild with Memory Preservation**:\n```bash\n# Both commands now preserve memories (v0.5.0+)\npcortex build --force\npcortex rebuild --confirm\n\n# Verify memories still accessible after rebuild\npcortex query \"architecture decisions\" --source prmth_memory\n```\n\n**Memory Workflow** (Typical Session):\n1. **During Session**: Capture decisions/patterns via `prometh_cortex_memory()` tool\n2. **Immediately Queryable**: Ask \"What did we decide about X?\" → searches memory\n3. **Force Rebuild**: Run `pcortex build --force` when source docs change\n4. **Memories Preserved**: Session insights survive the rebuild\n5. **Long-term KB**: Export memories to permanent documents when needed\n\n### HTTP REST Server (`pcortex serve`)\n**For Perplexity, VSCode, web integrations**\n\n#### Query Endpoint\n**POST** `/prometh_cortex_query`\n\n```json\n{\n  \"query\": \"search term or question\",\n  \"max_results\": 10,\n  \"source_type\": \"meetings\",  // Optional: filter by source (v0.3.0+)\n  \"filters\": {\n    \"datalake\": \"notes\",\n    \"tags\": [\"work\", \"project\"]\n  }\n}\n```\n\n#### List Sources Endpoint (v0.3.0+)\n**GET** `/prometh_cortex_sources`\n\nReturns all configured sources with:\n- Source names and chunking parameters\n- Source patterns for document routing\n- Document count per source\n- Total documents in unified index\n\n```json\n{\n  \"collection_name\": \"prometh_cortex\",\n  \"sources\": [\n    {\n      \"name\": \"knowledge_base\",\n      \"chunk_size\": 768,\n      \"chunk_overlap\": 76,\n      \"source_patterns\": [\"docs/specs\", \"docs/prds\"],\n      \"document_count\": 145\n    },\n    {\n      \"name\": \"meetings\",\n      \"chunk_size\": 512,\n      \"chunk_overlap\": 51,\n      \"source_patterns\": [\"meetings\"],\n      \"document_count\": 89\n    }\n  ],\n  \"total_sources\": 2,\n  \"total_documents\": 412\n}\n```\n\n#### Health Endpoint\n**GET** `/prometh_cortex_health`\n\nReturns server status, unified collection metrics, and performance metrics.\n\n## Supported YAML Frontmatter Schema\n\n```yaml\n---\ntitle: Document Title\ncreated: YYYY-MM-DDTHH:MM:SS\nauthor: Author Name\ncategory: #Category\ntags:\n  - #tag1\n  - tag2\nfocus: Work\nuuid: document-uuid\nproject:\n  - name: Project Name\n    uuid: project-uuid            # UUID preserved for document linking\nreminder:\n  - subject: Reminder Text\n    uuid: reminder-uuid           # UUID preserved for document linking\n    list: List Name\nevent:\n  subject: Event Subject\n  uuid: event-uuid                # UUID preserved for document linking\n  shortUUID: MF042576B            # Short UUID also preserved\n  organizer: Organizer Name\n  attendees:\n    - Attendee 1\n    - Attendee 2\n  location: Event Location\n  start: YYYY-MM-DDTHH:MM:SS      # Event start time\n  end: YYYY-MM-DDTHH:MM:SS        # Event end time\nrelated:\n  - Related Item 1\n  - Related Item 2\n---\n```\n\n**Note on UUIDs for Document Linking:**\n- Project, reminder, and event UUIDs are **preserved** in vector store metadata\n- These UUIDs enable cross-document linking and relationship queries\n- Use these UUIDs to find related documents across your datalake\n- Query by UUID: `event_uuid:B897515C-1BE9-41B6-8423-3988BE0C9E3E`\n\n### YAML Frontmatter Best Practices\n\n**⚠️ Important**: When using special characters in YAML values, always quote them properly to ensure correct parsing:\n\n#### ✅ Correct Usage:\n```yaml\n---\ntitle: \"[PRJ-0119] Add New Feature\"    # Quoted because of brackets\nauthor: \"John O'Connor\"                # Quoted because of apostrophe\ntags:\n  - \"C#\"                               # Quoted because of hash symbol\n  - \"project-2024\"                     # Safe without quotes\ncategory: \"Work \u0026 Personal\"            # Quoted because of ampersand\n---\n```\n\n#### ❌ Problematic Usage:\n```yaml\n---\ntitle: [PRJ-0119] Add New Feature      # Brackets will cause parsing errors\nauthor: John O'Connor                  # Apostrophe may cause issues\ntags:\n  - C#                                 # Hash symbol conflicts with YAML\ncategory: Work \u0026 Personal              # Ampersand may cause issues  \n---\n```\n\n#### Common Characters That Need Quoting:\n- **Square brackets** `[]`: `title: \"[PROJECT-123] Task Name\"`\n- **Curly braces** `{}`: `status: \"{COMPLETED}\"`\n- **Hash/Pound** `#`: `tag: \"C#\"`\n- **Colon** `:`: `note: \"Time: 3:30 PM\"`\n- **Ampersand** `\u0026`: `title: \"Sales \u0026 Marketing\"`\n- **Asterisk** `*`: `priority: \"*HIGH*\"`\n- **Pipe** `|`: `command: \"grep | sort\"`\n- **Greater/Less than** `\u003c\u003e`: `comparison: \"\u003c100ms\"`\n- **At symbol** `@`: `email: \"@company.com\"`\n- **Apostrophes** `'`: `name: \"O'Connor\"`\n\n#### Why This Matters:\n- **Metadata Parsing**: Improper YAML syntax prevents frontmatter from being extracted\n- **Index Quality**: Missing metadata means poor search results and filtering\n- **Qdrant Storage**: Malformed YAML leads to incomplete document payloads\n- **Search Performance**: Documents without proper metadata are harder to find\n\n#### Validation:\nTest your YAML frontmatter before indexing:\n```bash\n# Quick validation of a document\npython -c \"\nimport yaml\nimport frontmatter\n\nwith open('your-document.md', 'r') as f:\n    post = frontmatter.load(f)\n    print('✅ YAML parsed successfully')\n    print(f'Title: {post.metadata.get(\\\"title\\\", \\\"N/A\\\")}')\n    print(f'Fields: {list(post.metadata.keys())}')\n\"\n```\n\n## Integration\n\n### Claude Desktop Integration\n\nConfigure Claude Desktop by editing `~/Library/Application Support/Claude/claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"prometh-cortex\": {\n      \"command\": \"/path/to/your/project/.venv/bin/python\",\n      \"args\": [\n        \"-m\", \"prometh_cortex.cli.main\", \"mcp\"\n      ],\n      \"env\": {\n        \"DATALAKE_REPOS\": \"/path/to/your/notes,/path/to/your/documents,/path/to/your/projects\",\n        \"RAG_INDEX_DIR\": \"/path/to/index/storage\",\n        \"MCP_PORT\": \"8080\",\n        \"MCP_HOST\": \"localhost\",\n        \"MCP_AUTH_TOKEN\": \"your-secure-token\",\n        \"EMBEDDING_MODEL\": \"sentence-transformers/all-MiniLM-L6-v2\",\n        \"MAX_QUERY_RESULTS\": \"10\",\n        \"CHUNK_SIZE\": \"512\",\n        \"CHUNK_OVERLAP\": \"50\",\n        \"VECTOR_STORE_TYPE\": \"faiss\"\n      }\n    }\n  }\n}\n```\n\n**Setup Steps**:\n\n1. **Install in Virtual Environment**:\n   ```bash\n   cd /path/to/prometh-cortex\n   python -m venv .venv\n   source .venv/bin/activate  # On macOS/Linux\n   pip install -e .\n   ```\n\n2. **Configure Settings**: Create and customize your configuration:\n   ```bash\n   # Create configuration file\n   cp config.toml.sample config.toml\n   \n   # Edit config.toml with your specific paths and settings\n   # Update the [datalake] repos array with your document directories\n   # Set your preferred [storage] rag_index_dir location\n   # Customize [server] auth_token for security\n   ```\n\n3. **Build your index**:\n   ```bash\n   source .venv/bin/activate\n   pcortex build --force\n   ```\n\n4. **Get Absolute Paths**: Update the MCP configuration with your actual paths:\n   ```bash\n   # Get your virtual environment Python path\n   which python  # While .venv is activated\n   \n   # Get your project directory\n   pwd\n   ```\n\n5. **Update Claude Desktop Config**: Use absolute paths in your `claude_desktop_config.json`:\n   ```json\n   {\n     \"mcpServers\": {\n       \"prometh-cortex\": {\n         \"command\": \"/path/to/your/project/.venv/bin/python\",\n         \"args\": [\n           \"-m\", \"prometh_cortex.cli.main\", \"mcp\"\n         ],\n         \"env\": {\n           \"DATALAKE_REPOS\": \"/path/to/your/notes,/path/to/your/documents,/path/to/your/projects\",\n           \"RAG_INDEX_DIR\": \"/path/to/index/storage\",\n           \"MCP_PORT\": \"8080\",\n           \"MCP_HOST\": \"localhost\",\n           \"MCP_AUTH_TOKEN\": \"your-secure-token\",\n           \"EMBEDDING_MODEL\": \"sentence-transformers/all-MiniLM-L6-v2\",\n           \"MAX_QUERY_RESULTS\": \"10\",\n           \"CHUNK_SIZE\": \"512\",\n           \"CHUNK_OVERLAP\": \"50\"\n         }\n       }\n     }\n   }\n   ```\n\n6. **Verify Configuration**:\n   ```bash\n   # Test MCP server manually\n   source .venv/bin/activate\n   pcortex mcp  # Should start without errors\n   ```\n\n7. **Restart Claude Desktop**: Completely quit and restart Claude Desktop application.\n\n**Troubleshooting**:\n- ✅ **Check Logs**: Look at Claude Desktop console logs for MCP connection errors\n- ✅ **Verify Paths**: Ensure all paths in the config are absolute and correct\n- ✅ **Test Index**: Run `pcortex query \"test\"` to verify your index works\n- ✅ **Environment**: Make sure environment variables are accessible from the MCP context\n\n**Usage**: After restarting Claude Desktop, you'll have access to these MCP tools:\n- **prometh_cortex_query**: Search your indexed documents\n  - Ask: \"Search my notes for yesterday's meetings\"\n  - Ask: \"Find documents about project planning\" \n  - Ask: \"What meetings did I have last week?\"\n- **prometh_cortex_health**: Check system status\n  - Ask: \"How many documents are indexed in prometh-cortex?\"\n  - Ask: \"What's the health status of my knowledge base?\"\n\n### OpenCode Integration\n\nGenerate and install configuration automatically:\n\n```bash\n# Generate OpenCode config (prints to console)\npcortex mcp init opencode\n\n# Write directly to ~/.config/opencode/opencode.json\npcortex mcp init opencode --write\n\n# SSE mode (requires running daemon, see SSE Daemon Mode below)\npcortex mcp init opencode --transport sse\n```\n\n**Manual Configuration**: Add the `\"mcp\"` section to `~/.config/opencode/opencode.json`:\n\n```json\n{\n  \"mcp\": {\n    \"prometh-cortex\": {\n      \"type\": \"local\",\n      \"command\": [\"/path/to/pcortex\", \"mcp\", \"start\"],\n      \"environment\": {\n        \"RAG_INDEX_DIR\": \"/path/to/index/storage\",\n        \"VECTOR_STORE_TYPE\": \"qdrant\",\n        \"QDRANT_HOST\": \"your-cluster.qdrant.io\",\n        \"QDRANT_PORT\": \"6333\",\n        \"QDRANT_COLLECTION_NAME\": \"prometh_cortex\",\n        \"QDRANT_API_KEY\": \"your-api-key\",\n        \"QDRANT_USE_HTTPS\": \"true\",\n        \"MCP_AUTH_TOKEN\": \"your-secure-token\",\n        \"EMBEDDING_MODEL\": \"sentence-transformers/all-MiniLM-L6-v2\",\n        \"MAX_QUERY_RESULTS\": \"10\"\n      },\n      \"enabled\": true,\n      \"timeout\": 60000\n    }\n  }\n}\n```\n\n**Remote Mode** (for persistent SSE daemon):\n```json\n{\n  \"mcp\": {\n    \"prometh-cortex\": {\n      \"type\": \"remote\",\n      \"url\": \"http://127.0.0.1:3100/sse\",\n      \"headers\": {\n        \"Authorization\": \"Bearer your-secure-token\"\n      },\n      \"enabled\": true,\n      \"timeout\": 60000\n    }\n  }\n}\n```\n\n### SSE Daemon Mode\n\nRun Cortex as a persistent daemon instead of spawning per client session (v0.4.0+). This gives you single startup cost, shared Qdrant connections, and no duplicate vector index loads.\n\n**1. Start the daemon:**\n```bash\npcortex mcp start --transport sse --port 3100\n\n# Or bind to all interfaces for Tailscale/remote access\npcortex mcp start -t sse --host 0.0.0.0 -p 3100\n```\n\n**2. Configure clients to connect via SSE:**\n```bash\n# Claude Code\nclaude mcp add --transport sse prometh-cortex http://127.0.0.1:3100/sse\n\n# OpenCode\npcortex mcp init opencode -t sse --write\n\n# Claude Desktop\npcortex mcp init claude -t sse --write\n\n# Remote access (e.g., via Tailscale)\npcortex mcp init opencode -t sse --url http://mac-mini.tail:3100\n```\n\n**3. (Optional) Run as macOS launchd service:**\n\nCreate `~/Library/LaunchAgents/sh.prometh.cortex-mcp.plist` for auto-start on boot with keepalive.\n\n### Claude.ai Web Integration\n\nConfigure Claude.ai to use your MCP server by adding it as a custom integration:\n\n1. Start your MCP server: `pcortex serve`\n2. Use the webhook URL: `http://localhost:8080/prometh_cortex_query`\n3. Set authentication header: `Authorization: Bearer your-secret-token`\n4. Send queries in JSON format:\n   ```json\n   {\n     \"query\": \"search term\",\n     \"max_results\": 10\n   }\n   ```\n\n### Perplexity Integration\n\nConfigure Perplexity to use your local MCP server for document search:\n\n**Prerequisites**:\n1. **Start HTTP Server** (not MCP protocol):\n   ```bash\n   source .venv/bin/activate\n   pcortex serve --port 8001  # Use different port than MCP\n   ```\n\n2. **Configure for Performance** (important for Perplexity timeouts):\n   ```bash\n# Edit your config.toml for faster responses\n# In the [embedding] section, set:\n# max_query_results = 3  # Reduce from default 10 to 3\n   ```\n\n3. **Verify Health**:\n   ```bash\n   curl -H \"Authorization: Bearer your-secret-token\" \\\n        http://localhost:8001/prometh_cortex_health\n   ```\n\n**Integration Setup**:\n1. **Server Configuration**:\n   - Protocol: `HTTP`\n   - URL: `http://localhost:8001/prometh_cortex_query`\n   - Method: `POST`\n   - Headers: `Authorization: Bearer your-secret-token`\n   - Content-Type: `application/json`\n\n2. **Query Format**:\n   ```json\n   {\n     \"query\": \"your search query\",\n     \"max_results\": 3\n   }\n   ```\n\n3. **Example Request**:\n   ```bash\n   curl -X POST http://localhost:8001/prometh_cortex_query \\\n     -H \"Authorization: Bearer your-secret-token\" \\\n     -H \"Content-Type: application/json\" \\\n     -d '{\"query\": \"meeting notes\", \"max_results\": 3}'\n   ```\n\n**Performance Optimization**:\n- ✅ **Reduced Results**: Use `max_results: 3` instead of 10 to avoid timeouts\n- ✅ **Dedicated Port**: Use separate port (8001) for Perplexity vs other integrations\n- ✅ **Quick Queries**: Response time optimized to \u003c400ms for timeout compatibility\n\n**Usage in Perplexity**: \n- Ask: \"Search my local documents for project updates\"\n- Ask: \"Find my notes about last week's meetings\"\n- Ask: \"What information do I have about [specific topic]?\"\n\n### VSCode with GitHub Copilot Integration\n\nConfigure VSCode to use your MCP server with GitHub Copilot:\n\n#### Option 1: VSCode MCP Extension (Recommended)\n\n1. **Install MCP for VSCode**:\n   ```bash\n   # Install the VSCode MCP extension\n   code --install-extension ms-vscode.mcp\n   ```\n\n2. **Configure MCP Settings**: Add to your VSCode `settings.json` or create `.vscode/mcp.json`:\n   ```json\n   {\n     \"mcpServers\": {\n       \"prometh-cortex\": {\n         \"command\": \"/path/to/your/project/.venv/bin/python\",\n         \"args\": [\n           \"-m\", \"prometh_cortex.cli.main\", \"mcp\"\n         ],\n         \"env\": {\n           \"DATALAKE_REPOS\": \"/path/to/your/notes,/path/to/your/documents,/path/to/your/projects\",\n           \"RAG_INDEX_DIR\": \"/path/to/index/storage\",\n           \"MCP_PORT\": \"8080\",\n           \"MCP_HOST\": \"localhost\",\n           \"MCP_AUTH_TOKEN\": \"your-secure-token\",\n           \"EMBEDDING_MODEL\": \"sentence-transformers/all-MiniLM-L6-v2\",\n           \"MAX_QUERY_RESULTS\": \"10\",\n           \"CHUNK_SIZE\": \"512\",\n           \"CHUNK_OVERLAP\": \"50\"\n         }\n       }\n     }\n   }\n   ```\n\n3. **Update User Settings**: Add to your VSCode `settings.json`:\n   ```json\n   {\n     \"mcp.servers\": {\n       \"prometh-cortex\": {\n         \"enabled\": true\n       }\n     }\n   }\n   ```\n\n4. **Verify Integration**:\n   - Open Command Palette (`Cmd+Shift+P`)\n   - Run \"MCP: List Servers\" \n   - You should see \"prometh-cortex\" listed and active\n\n#### Option 2: Direct HTTP Integration\n\nAdd to your VSCode `settings.json`:\n```json\n{\n  \"github.copilot.advanced\": {\n    \"debug.useElectronPrompts\": true,\n    \"debug.useNodeUserForPrompts\": true\n  },\n  \"prometh-cortex.server.url\": \"http://localhost:8001\",\n  \"prometh-cortex.server.token\": \"your-secret-token\"\n}\n```\n\nStart the HTTP server:\n```bash\nsource .venv/bin/activate\npcortex serve --port 8001\n```\n\n#### Option 3: Custom Task Integration\n\nCreate `.vscode/tasks.json` for quick queries:\n```json\n{\n  \"version\": \"2.0.0\",\n  \"tasks\": [\n    {\n      \"label\": \"Query Prometh-Cortex\",\n      \"type\": \"shell\",\n      \"command\": \"curl\",\n      \"args\": [\n        \"-H\", \"Authorization: Bearer your-secret-token\",\n        \"-H\", \"Content-Type: application/json\",\n        \"-d\", \"{\\\"query\\\": \\\"${input:searchQuery}\\\", \\\"max_results\\\": 5}\",\n        \"http://localhost:8001/prometh_cortex_query\"\n      ],\n      \"group\": \"build\",\n      \"presentation\": {\n        \"echo\": true,\n        \"reveal\": \"always\",\n        \"panel\": \"new\"\n      }\n    }\n  ],\n  \"inputs\": [\n    {\n      \"id\": \"searchQuery\",\n      \"description\": \"Enter your search query\",\n      \"default\": \"meeting notes\",\n      \"type\": \"promptString\"\n    }\n  ]\n}\n```\n\n**Setup Steps**:\n1. **Build Index**: Ensure your RAG index is built and up-to-date\n   ```bash\n   source .venv/bin/activate\n   pcortex build --force\n   ```\n\n2. **Start MCP Server** (for Option 1):\n   ```bash\n   # MCP server runs automatically when VSCode starts\n   # Check VSCode Output panel for MCP logs\n   ```\n\n3. **Start HTTP Server** (for Options 2-3):\n   ```bash\n   source .venv/bin/activate\n   pcortex serve --port 8001\n   ```\n\n**Usage**:\n- **Option 1**: Use MCP commands directly in GitHub Copilot chat\n  - Ask: \"Search my documents for project planning notes\"\n  - Ask: \"Find my meeting notes from last week\"\n- **Option 2**: GitHub Copilot will automatically query your local documents\n- **Option 3**: Press `Ctrl+Shift+P` → \"Tasks: Run Task\" → \"Query Prometh-Cortex\"\n\n**Troubleshooting**:\n- ✅ **Check MCP Output**: View \"Output\" panel in VSCode, select \"MCP\" from dropdown\n- ✅ **Verify Paths**: Ensure all paths are absolute and accessible\n- ✅ **Test Manually**: Run `pcortex mcp` or `pcortex serve` to verify functionality\n- ✅ **Restart VSCode**: After configuration changes, restart VSCode completely\n\n**Usage**: Press `Ctrl+Shift+P` → \"Tasks: Run Task\" → \"Query Prometh-Cortex\"\n\n### General MCP Configuration Guide\n\n**Two Server Types Available**:\n\n1. **MCP Protocol Server** (`pcortex mcp start`):\n   - **Purpose**: AI assistant integration (Claude Desktop, OpenCode, Claude Code, VSCode)\n   - **Transports** (v0.4.0+):\n     - `stdio` (default): Subprocess per client, no network port\n     - `sse`: Persistent daemon on configurable host:port, shared across clients\n     - `streamable-http`: Newer MCP spec transport\n   - **Usage**: Direct integration with MCP-compatible clients\n\n2. **HTTP REST Server** (`pcortex serve`):\n   - **Purpose**: Web applications, HTTP clients (Perplexity, custom integrations)\n   - **Protocol**: HTTP REST API\n   - **Port**: Configurable (default: 8080)\n   - **Usage**: Traditional HTTP API access\n\n#### MCP Transport Selection Guide\n\n| Transport | Best For | Port | Startup | Shared State | Setup |\n|-----------|----------|------|---------|--------------|-------|\n| **stdio** | Single client (Claude Desktop) | None | ~2s | No | Simple: `pcortex mcp` |\n| **sse** | Multiple clients (OpenCode + Claude Desktop) | Yes | ~2s | Yes | Daemon: `pcortex mcp start -t sse` |\n| **streamable-http** | HTTP clients + MCP | Yes | ~2s | Yes | Daemon: `pcortex mcp start -t streamable-http` |\n\n**Decision Tree**:\n- **Just using Claude Desktop?** → Use `stdio` (default)\n- **Using OpenCode + Claude Desktop?** → Use `sse` daemon (shared startup cost)\n- **Remote access needed?** → Use `sse` with `--host 0.0.0.0` (Tailscale/SSH tunnel)\n- **Need HTTP API + MCP?** → Use `streamable-http` daemon\n\n**Configuration Prerequisites**: \n\n1. **Environment Setup**:\n    ```bash\n    # Create and activate virtual environment\n    python -m venv .venv\n    source .venv/bin/activate  # macOS/Linux\n   \n   # Install in development mode\n   pip install -e .\n   ```\n\n2. **Create Configuration**:\n   ```bash\n   # Create configuration from sample\n   cp config.toml.sample config.toml\n   # Edit config.toml with your specific settings\n   ```\n\n3. **Build Index**:\n   ```bash\n   pcortex build --force\n   ```\n\n4. **Test Configuration**:\n   ```bash\n   # Test MCP server\n   pcortex mcp  # Should start without errors, Ctrl+C to stop\n   \n   # Test HTTP server\n   pcortex serve  # Should show server info, Ctrl+C to stop\n   \n   # Test query functionality\n   pcortex query \"test search\"\n   ```\n\n**Common Integration Pattern**:\n\nFor **HTTP integrations** (Perplexity, web apps):\n```bash\n# Start HTTP server\npcortex serve --port 8001\n\n# Query endpoint\nPOST http://localhost:8001/prometh_cortex_query\nAuthorization: Bearer your-secret-token\nContent-Type: application/json\n\n{\n  \"query\": \"your search query\",\n  \"max_results\": 10,\n  \"filters\": {\n    \"datalake\": \"notes\",\n    \"tags\": [\"work\"]\n  }\n}\n\n# Health check\nGET http://localhost:8001/prometh_cortex_health\nAuthorization: Bearer your-secret-token\n```\n\nFor **MCP integrations** (Claude Desktop, VSCode):\n```json\n{\n  \"mcpServers\": {\n    \"prometh-cortex\": {\n      \"command\": \"/path/to/your/project/.venv/bin/python\",\n      \"args\": [\n        \"-m\", \"prometh_cortex.cli.main\", \"mcp\"\n      ],\n      \"env\": {\n        \"DATALAKE_REPOS\": \"/path/to/your/notes,/path/to/your/documents,/path/to/your/projects\",\n        \"RAG_INDEX_DIR\": \"/path/to/index/storage\",\n        \"MCP_PORT\": \"8080\",\n        \"MCP_HOST\": \"localhost\",\n        \"MCP_AUTH_TOKEN\": \"your-secure-token\",\n        \"EMBEDDING_MODEL\": \"sentence-transformers/all-MiniLM-L6-v2\",\n        \"MAX_QUERY_RESULTS\": \"10\",\n        \"CHUNK_SIZE\": \"512\",\n        \"CHUNK_OVERLAP\": \"50\",\n        \"VECTOR_STORE_TYPE\": \"faiss\"\n      }\n    }\n  }\n}\n```\n\n**Performance Tuning**:\n- **For Perplexity**: Set `max_query_results = 3` in config.toml to avoid timeouts\n- **For Development**: Use `--reload` flag with `pcortex serve`\n- **For Production**: Use production WSGI server instead of development server\n\n**Auto-start Script**:\nCreate `start_servers.sh` for easy management:\n```bash\n#!/bin/bash\n# Kill existing servers\npkill -f \"pcortex serve\" 2\u003e/dev/null || true\npkill -f \"pcortex mcp\" 2\u003e/dev/null || true\n\n# Activate virtual environment\nsource .venv/bin/activate\n\n# Start HTTP server in background\nnohup pcortex serve --port 8001 \u003e /tmp/prometh-cortex-http.log 2\u003e\u00261 \u0026\n\necho \"Prometh-Cortex servers started\"\necho \"HTTP Server: http://localhost:8001\"\necho \"MCP Server: Available for stdio connections\"\necho \"Logs: /tmp/prometh-cortex-http.log\"\n```\n\n**Troubleshooting Checklist**:\n- ✅ **Virtual Environment**: Always use absolute paths to `.venv/bin/python`\n- ✅ **Configuration**: Set `datalake.repos` and `storage.rag_index_dir` in config.toml \n- ✅ **Index Built**: Run `pcortex build` before using servers\n- ✅ **Ports Available**: Check port conflicts with `lsof -i :8080`\n- ✅ **Logs Check**: Monitor server logs for configuration errors\n- ✅ **Path Permissions**: Ensure read access to datalake and write access to index directory\n\n## Development\n\n### Setup Development Environment\n```bash\n# Clone repository\ngit clone https://github.com/prometh-sh/prometh-cortex.git\ncd prometh-cortex\n\n# Install with development dependencies\npip install -e \".[dev]\"\n\n# Install pre-commit hooks\npre-commit install\n```\n\n### Run Tests\n```bash\n# Run all tests\npytest\n\n# Run with coverage\npytest --cov=src/prometh_cortex\n\n# Run specific test types\npytest tests/unit/\npytest tests/integration/\n```\n\n### Code Quality\n```bash\n# Format code\nblack src/ tests/\nisort src/ tests/\n\n# Lint code\nflake8 src/ tests/\n\n# Type checking\nmypy src/\n```\n\n## Performance\n\n- **Query Speed**: Target \u003c100ms on M1/M2 Mac\n- **Index Size**: Scales to thousands of documents\n- **Memory Usage**: Optimized chunking and streaming processing\n- **Storage**: Efficient FAISS local storage or scalable Qdrant\n- **Incremental Updates**: Only processes changed documents\n\n## Architecture\n\n```\n┌─────────────────────┐\n│    config.toml      │\n└──────────┬──────────┘\n           │\n┌──────────▼──────────────────┐\n│ Datalake Ingest \u0026 Parser    │\n│ - Markdown files            │\n│ - YAML frontmatter          │\n└──────────┬──────────────────┘\n           │\n┌──────────▼──────────────────┐\n│ Vector Store / Indexing     │\n│ - FAISS (local) or Qdrant   │\n│ - Local embedding model     │\n│ - Incremental indexing      │\n└──────────┬──────────────────┘\n           │\n┌──────────▼──────────────────┐\n│     MCP Server              │\n│ - stdio / SSE / HTTP        │\n│ - prometh_cortex_query      │\n│ - prometh_cortex_health     │\n│ - prometh_cortex_sources    │\n└──────────┬──────────────────┘\n           │\n    ┌──────┼──────┐\n    │      │      │\n  stdio   SSE   HTTP\n    │      │      │\n Claude  Multi   REST\nDesktop client  API\n         daemon\n```\n\n## License\n\nApache 2.0 License - see [LICENSE](LICENSE) for details.\n\n## Contributing\n\nWe welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.\n\n### Quick Contribution Guide\n\n1. Fork the repository\n2. Create a feature branch: `git checkout -b feature/your-feature-name`\n3. Make your changes with clear, descriptive commits\n4. Add tests for new functionality\n5. Ensure all tests pass: `pytest`\n6. Format code: `black src/ tests/` and `isort src/ tests/`\n7. Submit a pull request with a clear description\n\n### Code of Conduct\n\nThis project follows our [Code of Conduct](CODE_OF_CONDUCT.md). By participating, you agree to uphold this code.\n\n### Security\n\nFound a security vulnerability? Please see [SECURITY.md](SECURITY.md) for responsible disclosure guidelines.\n\n## Documentation\n\n**Architecture \u0026 Design**:\n- **[Memory Preservation Spec (v0.5.0)](docs/specs/feature-memory-preservation-force-rebuild-spec.md)** - Technical specification for preserving memories across force rebuilds\n- **[Unified Collection Spec (v0.3.0+)](docs/specs/feature-unified-collection-per-source-chunking-spec.md)** - Complete technical specification for unified collection with per-source chunking architecture\n- **[Multi-Collection Spec (v0.2.0 - Deprecated)](docs/specs/feature-rag-multi-collection-indexing-spec.md)** - Legacy multi-collection architecture (archived for reference)\n\n**Migration Guides**:\n- **[v0.4.0 → v0.5.0 Migration Guide](docs/migration-v0.4-to-v0.5.md)** - Memory preservation and improved indexing\n- **[v0.2.0 → v0.3.0 Migration Guide](docs/migration-v0.2-to-v0.3.md)** - Step-by-step guide for migrating from multi-collection to unified collection\n- **[v0.1.x → v0.2.0 Migration Guide](docs/migration-v0.1-to-v0.2.md)** - Historical migration guide (archived)\n\n**Key Improvements in v0.5.0**:\n- **Memory Preservation**: Session memories survive `pcortex build --force` and `pcortex rebuild`\n- **Memory Tool (MCP)**: `prometh_cortex_memory()` for capturing decisions, patterns, and session summaries\n- **Dual Backend Support**: FAISS (sidecar JSON) and Qdrant (filter-based) memory preservation\n- **Smart Metadata Retrieval**: Handle both parent document IDs and chunk IDs seamlessly\n\n**Key Improvements in v0.4.0**:\n- **SSE/HTTP Transport**: Run MCP as a persistent daemon shared across clients\n- **OpenCode Support**: First-class config generation for OpenCode\n- **Auto Config**: `pcortex mcp init \u003ctarget\u003e` generates configs for Claude, OpenCode, VSCode, Codex, Perplexity\n- **Remote Access**: SSE daemon with `--host 0.0.0.0` for Tailscale/multi-machine setups\n\n**Key Improvements in v0.3.0**:\n- **Unified Collection**: Single FAISS/Qdrant index instead of multiple\n- **Per-Source Chunking**: Different chunk sizes per document source in unified index\n- **Topic-Based Queries**: Query across document types naturally\n- **Better Performance**: ~300ms queries (vs ~500ms multi-collection)\n- **Lower Memory**: Single index (vs 3-5x for multi-collection)\n\n## Support\n\n### Getting Help\n\n- **Documentation**: See the [/docs](docs/) directory for detailed guides\n- **Issues**: Report bugs or request features via [GitHub Issues](https://github.com/prometh-sh/prometh-cortex/issues)\n- **Discussions**: Ask questions or share ideas in [GitHub Discussions](https://github.com/prometh-sh/prometh-cortex/discussions)\n- **Security**: For security issues, see [SECURITY.md](SECURITY.md)\n\n### Resources\n\n- **PyPI Package**: https://pypi.org/project/prometh-cortex/\n- **Source Code**: https://github.com/prometh-sh/prometh-cortex\n- **Changelog**: See [CHANGELOG.md](CHANGELOG.md) for version history\n\n### Community\n\nWe encourage community participation! Whether you're fixing bugs, adding features, improving documentation, or helping others, all contributions are valued.\n\n---\n\n**Made with ❤️ for the knowledge management community**\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprometh-sh%2Fprometh-cortex","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fprometh-sh%2Fprometh-cortex","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprometh-sh%2Fprometh-cortex/lists"}