Metadata-Version: 2.4
Name: cortex-vec
Version: 0.7.0
Summary: Vector store CLI for the cortex vault — hybrid BM25 + embedding retrieval over a markdown knowledge vault
Author: XBlueSky
License-Expression: Apache-2.0
Project-URL: Homepage, https://cortexes.pages.dev
Project-URL: Repository, https://github.com/XBlueSky/cortexes
Project-URL: Changelog, https://github.com/XBlueSky/cortexes/blob/plugin/CHANGELOG.md
Keywords: knowledge-base,semantic-search,bm25,chromadb,claude-code
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Text Processing :: Indexing
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: chromadb
Requires-Dist: openai
Requires-Dist: python-frontmatter
Requires-Dist: pysqlite3-binary; sys_platform == "linux"
Requires-Dist: rank-bm25
Requires-Dist: jieba
Requires-Dist: snowballstemmer
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Dynamic: license-file

# cortex-vec

Vector store CLI for the [cortex](https://github.com/XBlueSky/cortexes)
knowledge vault — hybrid retrieval over a plain-markdown vault, fusing a
persistent BM25 index with OpenAI-embedding vector search (ChromaDB) via
Reciprocal Rank Fusion. Handles mixed Chinese/English content.

The vault is the source of truth (markdown + git); everything this tool
builds is a rebuildable derived index.

## Install

```bash
# Recommended: isolated tool install via uv
uv tool install cortex-vec

# Or with pip
pip install cortex-vec
```

## Usage

```bash
cortex-vec rebuild                # full rebuild (embeddings, needs OPENAI_API_KEY)
cortex-vec rebuild --bm25-only    # rebuild just the BM25 index — free, no API key
cortex-vec search "nginx certificate" --n 5
cortex-vec status                 # index health: vector + BM25 entry counts
```

Configuration lives in `~/.cortex/config.json` (created by the cortex
plugin's `/cortex:genesis` command). `OPENAI_API_KEY` is required for
embeddings; without it, `search` automatically degrades to BM25-only.

This package is the retrieval backend of the
[Cortex Claude Code plugin](https://github.com/XBlueSky/cortexes) — session
recording, memory distillation, and indexed retrieval for Claude Code. See
the repository for the full documentation.
