io.github.VBlackJack/cortex
Local multi-client RAG server over the Model Context Protocol.
Open source Open in the app JSON README (API)
About
Local multi-client RAG server over the Model Context Protocol.
Details
- Kind
- MCP servers
- Topic
- AI, RAG & memory
- Publisher
- vblackjack
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 2026.907.3
- Last push
- 2026-09-04T09:41:24Z
- Repository state
- ativo
- Language
- Python
- License
- Apache-2.0
- Added
- 2026-08-29 03:02:18
- Updated
- 2026-09-07 20:03:49
- Origin id
io.github.VBlackJack/cortex
README
# Cortex - RAG MCP pour base de connaissance
**Francais** | [English](README.en.md)
Cortex est un serveur MCP (Model Context Protocol) qui expose une recherche
semantique sur une base de connaissance locale. Il permet a Claude, Codex et
Gemini de retrouver le bon passage dans vos documents sans consommer inutilement
leur fenetre de contexte. La recherche est semantique (par sens, pas par
mot-cle), en francais comme en anglais. Cortex traite et indexe la base en local
sans envoyer son contenu ; le client MCP peut toutefois transmettre au modele
les passages qu'il a demandes, selon sa propre politique.
Le writer Confluence optionnel ne telecharge que les espaces explicitement
autorises ; le Markdown genere, l'index vectoriel et l'index lexical restent
locaux.
## Installation
### Windows, sans Python (recommande)
La voie la plus simple : un seul installeur pour Cortex, Cortex Companion, le
convertisseur Confluence console et les modeles hors ligne. Aucun Python ni
runtime .NET n'est a installer separement.
1. Telecharger `Cortex-Setup.exe` et `SHA256SUMS` depuis la
[derniere release](https://github.com/VBlackJack/Cortex/releases/latest).
2. Avant de lancer l'installeur non signe, calculer son empreinte avec
`Get-FileHash .\Cortex-Setup.exe -Algorithm SHA256` dans PowerShell et
verifier qu'elle correspond exactement a la ligne `Cortex-Setup.exe` de
`SHA256SUMS`.
3. Double-cliquer seulement apres cette verification. Si SmartScreen affiche
encore un avertissement, choisir `Informations complementaires`, puis
`Executer quand meme`.
4. Choisir le dossier de vos documents, laisser `Tout indexer dans ce dossier`
et terminer. Cortex Companion s'ouvre a la fin de l'installation.
5. Dans Companion, ouvrir `Réglages` pour verifier le dossier de la base de
connaissances. L'executable Cortex installe avec Companion est detecte
automatiquement.
6. Deposer vos documents dans ce dossier, ouvrir `Base locale`, puis choisir
`Synchroniser les documents locaux`.
7. Redemarrer votre application IA : Cortex y apparait comme serveur MCP.
Companion permet ensuite de synchroniser, planifier, diagnostiquer et configurer
Cortex sans terminal. Details, mode silencieux et reinstallation :
[Installation Windows](docs/fr/installation-windows.md).
### Archives autonomes (Windows x64, macOS Apple Silicon, Linux x64)
Chaque release fournit aussi une archive ZIP par plateforme. Elle contient le
binaire unique `cortex` ou `cortex.exe` (serveur MCP + CLI, sans Python) et les
licences de toutes les dependances embarquees. Voir
[Distribution autonome](docs/fr/distribution.md).
### Depuis PyPI (Python, avance)
```powershell
py -m pip install --upgrade cortex-local-rag
cortex setup
```
Cette voie installe la CLI et le serveur MCP, mais pas Cortex Companion. Le
modele est telecharge lors de sa premiere utilisation si son cache est vide.
### Depuis les sources (Python, avance)
```bat
:: Depuis le dossier ou vous avez clone Cortex
install.bat
```
`install.bat` initialise la configuration, installe les dependances, propose
d'enregistrer Cortex dans les clients MCP detectes et valide l'installation.
Details : [Installation](docs/fr/setup.md).
## Fonctionnement en bref
```
Dossier de documents (.md, .pdf) Writer Confluence optionnel (REST)
| |
| generation Markdown courante
+------------------+-------------------+
|
v
cortex sync <- Decoupe, hash, vectorise, met a jour FTS5
|
v
%LOCALAPPDATA%\Cortex\ <- ChromaDB + lexical.db
|
v
cortex serve <- Serveur MCP (FastMCP)
|
v
Clients MCP <- Claude / Codex / Gemini / Antigravity / LM Studio / Cursor / Windsurf / VS Code
```
Le modele d'embedding est le multilingue ONNX
`paraphrase-multilingual-MiniLM-L12-v2`. L'installeur Windows l'embarque ; une
installation depuis les sources ou un binaire autonome le telecharge si son
cache local est vide.
## Deux modes d'indexation
- **Tout le dossier** (defaut) : tout ce que vous placez dans le dossier
choisi, a la racine ou dans n'importe quel sous-dossier, devient cherchable.
Rien a configurer.
- **Sections** (avance) : limite l'indexation a des sous-dossiers nommes que
vous pouvez chercher separement (defauts `knowledge`, `projects`, `notes`).
Ces modes gouvernent le dossier de documents choisi par l'utilisateur. Les
documents d'ingestion generes sont indexes separement depuis la generation
publiee courante avec `source_kind=doc` et la section `sources`.
Details : [Configuration](docs/fr/configuration.md).
## Commande `cortex`
Le paquet installe expose une commande unique :
| Sous-commande | Role |
|---|---|
| `cortex setup` | Config + index + enregistrement des clients en une fois (`--kb-path`, `--yes`, `--no-index`, `--reset`). |
| `cortex serve` | Lance le serveur MCP (utilise par les clients). |
| `cortex sync` | Synchronisation incrementale de l'index. |
| `cortex search` | Recherche dans l'index depuis la console (aide au debogage). |
| `cortex ingestion` | Affiche la sante d'une source et indique si un rattrapage est du. |
| `cortex confluence` | Stocke le PAT interactivement ou lance le writer sur liste blanche. |
| `cortex config` | Lit ou modifie la configuration via un contrat JSON atomique, notamment pour Companion. |
| `cortex bundle` | Decrit ou verifie une archive portable chiffree. |
| `cortex doctor` | Diagnostic de l'installation (lecture seule). |
| `cortex register` / `cortex unregister` | Ajoute ou retire Cortex des clients MCP. |
| `cortex init` | Cree la seule configuration par utilisateur. |
| `cortex check` | Verifie l'installation. |
`cortex --help` decrit chaque sous-commande et `cortex <commande> --help` decrit
ses options. Une installation sans invite se scripte ainsi :
```powershell
cortex setup --yes --kb-path "D:\Documents\Connaissances"
```
## Outils MCP exposes
| Outil | Description |
|---|---|
| `cortex_search` | Recherche hybride. Parametres : `query`, `section`, `top_k` (1-10), filtres source/auteur et plages de dates de creation/mise a jour. |
| `cortex_sync` | Declenche un sync incremental du dossier choisi et, sur un sync complet, de la generation documentaire courante. |
| `cortex_list_sections` | Liste les sections incluses et les dossiers "out of policy". |
| `cortex_freshness` | Resume en lecture seule de la fraicheur du vault et de l'ingestion. Parametres : `section` (optionnel), `include_entries` (`false` par defaut). |
## Documentation
- [Sommaire](docs/fr/index.md)
- [Installation Windows](docs/fr/installation-windows.md) : installateur unique
Cortex + Companion + convertisseur Confluence + modeles, choix du corpus,
mode silencieux, reinstallation.
- [Distribution autonome](docs/fr/distribution.md) : archives par plateforme et builds reproductibles.
- [Installation depuis les sources](docs/fr/setup.md) : prerequis, clients MCP.
- [Guide d'utilisation](docs/fr/user-guide.md) : sync, recherche, outils,
doctor, logs.
- [FAQ](docs/fr/faq.md) : installation, donnees locales, sync et diagnostic.
- [Notes de version](docs/fr/notes-de-version.md) : changements visibles par
version et avis sur l'historique publie.
- [Journal technique](CHANGELOG.md) : detail complet des changements par version.
- [Configuration](docs/fr/configuration.md) : `config.toml`, modes d'indexation,
sections, data home, migration.
- [Planification de l'ingestion](docs/fr/ingestion-scheduling.md) : sante des
sources, rattrapage, reprises et Planificateur de taches.
- [Migration metadata v2](docs/fr/metadata-v2-migration.md) : metadonnees de
recherche structurees, sauvegarde, migration et restauration.
- [Writer Confluence](docs/fr/writer-confluence.md) : ingestion REST sur liste
blanche, Windows Credential Manager, conversion et generations atomiques.
- [Installation reproductible](docs/fr/install-reproductible.md) :
`requirements.lock`, `--require-hashes`, regeneration du verrou.
- [Specification publique](docs/fr/spec.md) : surface MCP, contrats de l'index,
donnees, distribution et limites.
- [Architecture](docs/fr/architecture.md) : bout en bout et choix techniques.
- [Securite](docs/fr/security.md) : runtime local, telemetrie off,
single-writer.
## Prerequis
| Voie | Prerequis |
|---|---|
| Installeur Windows | Aucun Python ni runtime .NET separe. ~500 Mo d'espace minimum (applications, modele + index). |
| Archive autonome | Aucun Python. ~500 Mo d'espace (modele + index). |
| Depuis les sources | Python 3.10+. ~500 Mo d'espace. |
| Client | Claude Desktop/Code, Codex, Gemini, Antigravity, LM Studio, Cursor, Windsurf ou VS Code (support MCP). |
## Licence
Apache 2.0. Voir [LICENSE](LICENSE).