{
  "markdown": "# Cortex - RAG MCP for a knowledge base\n\n<!-- mcp-name: io.github.VBlackJack/cortex -->\n\n**English** | [Français](README.fr.md)\n\nCortex is an MCP (Model Context Protocol) server that exposes semantic search\nover a local knowledge base. It lets Claude, Codex and Gemini find the right\npassage in your documents without wasting their context window. Search is\nsemantic (by meaning, not keyword), in French and in English. Cortex processes\nand indexes the knowledge base locally without sending its content; the MCP\nclient may still pass requested chunks to its model under its own policy.\nThe optional Confluence writer only downloads explicitly allowlisted spaces;\nthe generated Markdown, vector index, and lexical index remain local.\n\nStarting with 2026.0906.01, Companion offers a guided home screen, operation history and Confluence setup from one page or space link. Connection and measured scope confirmation stay in the flow; successful collection is followed by indexing. Use the combined installer to keep Cortex and Companion compatible.\n\n## Measured scope without enumerating the space (2026.0907.00)\n\nAdding a Confluence source measures its page, subtree and whole-space scopes\nwith one indexed count each instead of reading the space page by page. On a\n5916-page space that measurement took 3 min 19 s, past the timeout of every\ngraphical caller, so Companion showed nothing at all. It now answers in about a\nsecond, and the emitted contract is unchanged.\n\nTwo whole-space numbers shift by one as a result: the resolved page is no longer\nfolded into the space total, and a space with no visible page reports zero rather\nthan one. A deployment whose search endpoint returns no total cannot measure a\nscope and reports that as a permanent failure instead of a retryable one. See\n[the contracts](docs/en/confluence-writer.md).\n\nPaired Companion 2026.0907.00 restores the contrast of the scope window, whose\noptions were drawn in the system text colour, and stops reporting a timeout as a\nconnection failure or advising a delay increase that silently reverts.\n\n## Source management in Companion (2026.0906.02)\n\nThe workflow includes search, remote page trees, impact review, evidence-based\nreadiness, save-and-update, last-removal undo and recovery actions. See\n[the contracts](docs/en/confluence-writer.md).\n\n\nPaired version 2026.0906.02 provides visible **My sources** cards, a prefilled\nselection editor, confirmed page/space removal and browser links to originals.\nRemoval only changes Cortex tracking; search reflects it after successful\ncollection and indexing.\n\nRemoving the final source explicitly writes `spaces = []` in a schema v2 or v3\nconfiguration. This intentional empty allowlist permits an empty publication\nwith tombstones for prior documents. An absent `spaces` key remains incomplete\nconfiguration and collection is refused. Connection and credential validation\nand publication safeguards still apply. Both updated components are required;\nthis capability is absent from the installed 2026.0906.01 release.\n\n\n## Installation\n\n### Windows, no Python (recommended)\n\nThe simplest path: one installer for Cortex, Cortex Companion, the windowless\nConfluence converter, and the offline models. No separate Python or .NET\nruntime is required.\n\n1. Download `Cortex-Setup.exe` and `SHA256SUMS` from the\n   [latest release](https://github.com/VBlackJack/Cortex/releases/latest).\n2. Before running the unsigned installer, calculate its digest with\n   `Get-FileHash .\\Cortex-Setup.exe -Algorithm SHA256` in PowerShell and verify\n   that it exactly matches the `Cortex-Setup.exe` line in `SHA256SUMS`.\n3. Double-click only after that check. If SmartScreen still warns, select\n   `More info`, then `Run anyway`.\n4. Choose the folder that holds your documents, keep `Index everything in this\n   folder`, and finish. Cortex Companion opens when installation completes.\n5. In Companion, open `Settings` and verify the knowledge-base folder. The\n   Cortex executable installed with Companion is detected automatically.\n6. Drop your documents in that folder, open `Local database`, then select\n   `Synchronize local documents`.\n7. Restart your AI application: Cortex shows up there as an MCP server.\n\nCompanion then lets you synchronize, schedule, diagnose, and configure Cortex\nwithout a terminal. Details, silent mode and reinstall:\n[Windows install](docs/en/windows-install.md).\n\n### Standalone archives (Windows x64, macOS Apple Silicon, Linux x64)\n\nEvery release also ships one ZIP archive per platform. It contains the single\n`cortex` or `cortex.exe` binary (MCP server + CLI, no Python) and the licenses\nfor every embedded dependency. See\n[Standalone distribution](docs/en/distribution.md).\n\n### From PyPI (Python, advanced)\n\n```powershell\npy -m pip install --upgrade cortex-local-rag\ncortex setup\n```\n\nThis path installs the CLI and MCP server, but not Cortex Companion. The model\nis downloaded on first use if its cache is empty.\n\n### From source (Python, advanced)\n\n```bat\n:: From the folder where you cloned Cortex\ninstall.bat\n```\n\n`install.bat` initializes the configuration, installs the dependencies, offers\nto register Cortex in the detected MCP clients, and validates the installation.\nDetails: [Setup](docs/en/setup.md).\n\n## How it works\n\n```\nDocuments folder (.md, .pdf)       Optional Confluence writer (REST)\n      |                                      |\n      |                              current Markdown generation\n      +------------------+-------------------+\n                         |\n                         v\n  cortex sync           <- Split, hash, vectorize, update FTS5\n                         |\n                         v\n  %LOCALAPPDATA%\\Cortex\\  <- ChromaDB + lexical.db\n      |\n      v\n  cortex serve          <- MCP server (FastMCP)\n      |\n      v\n  MCP clients           <- Claude / Codex / Gemini / Antigravity / LM Studio / Cursor / Windsurf / VS Code\n```\n\nThe embedding model is the multilingual ONNX\n`paraphrase-multilingual-MiniLM-L12-v2`. The Windows installer bundles it; a\nsource installation or standalone binary downloads it when the local cache is\nempty.\n\n## Two indexing modes\n\n- **Whole folder** (default): anything you place in the chosen folder, at the\n  root or in any subfolder, becomes searchable. Nothing to configure.\n- **Sections** (advanced): limits indexing to named subfolders you can search\n  separately (defaults `knowledge`, `projects`, `notes`).\n\nThese modes govern the user-selected document folder. Generated ingestion\ndocuments are indexed separately from the current published generation with\n`source_kind=doc` and section `sources`.\n\nDetails: [Configuration](docs/en/configuration.md).\n\n## The `cortex` command\n\nThe installed package exposes a single command:\n\n| Subcommand | Purpose |\n|---|---|\n| `cortex setup` | Config + index + client registration in one go (`--kb-path`, `--yes`, `--no-index`, `--reset`). |\n| `cortex serve` | Runs the MCP server (used by clients). |\n| `cortex sync` | Incremental index synchronization. |\n| `cortex search` | Searches the index from the console (debugging aid). |\n| `cortex ingestion` | Shows source health and whether catch-up is due. |\n| `cortex confluence` | Stores the PAT interactively or runs the allowlisted writer. |\n| `cortex config` | Reads or changes configuration through an atomic JSON contract, notably for Companion. |\n| `cortex bundle` | Describes or verifies an encrypted portable archive. |\n| `cortex doctor` | Installation diagnostics (read-only). |\n| `cortex register` / `cortex unregister` | Adds or removes Cortex from MCP clients. |\n| `cortex init` | Creates the single per-user configuration. |\n| `cortex check` | Verifies the installation. |\n\n`cortex --help` describes every subcommand and `cortex <command> --help` describes\nits options. A prompt-free installation scripts as:\n\n```powershell\ncortex setup --yes --kb-path \"D:\\Documents\\Knowledge\"\n```\n\n## Exposed MCP tools\n\n| Tool | Description |\n|---|---|\n| `cortex_search` | Hybrid search. Parameters: `query`, `section`, `top_k` (1-10), source/author filters, and occurred/updated date ranges. |\n| `cortex_sync` | Triggers an incremental sync of the selected folder and, on a full sync, the current published document generation. |\n| `cortex_list_sections` | Lists included sections and \"out of policy\" folders. |\n| `cortex_freshness` | Read-only vault and ingestion freshness summary. Parameters: `section` (optional), `include_entries` (`false` by default). |\n\n## Documentation\n\n- [Table of contents](docs/en/index.md)\n- [Windows install](docs/en/windows-install.md): unified Cortex + Companion +\n  Confluence converter + models installer, corpus choice, silent mode,\n  reinstall.\n- [Standalone distribution](docs/en/distribution.md): per-platform archives and reproducible builds.\n- [Install from source](docs/en/setup.md): prerequisites, MCP clients.\n- [User guide](docs/en/user-guide.md): sync, search, tools, doctor, logs.\n- [FAQ](docs/en/faq.md): installation, local data, sync, and diagnostics.\n- [Release notes](docs/en/release-notes.md): user-visible changes by version and\n  the published-history notice.\n- [Technical changelog](CHANGELOG.md): complete changes by version.\n- [Configuration](docs/en/configuration.md): `config.toml`, indexing modes,\n  sections, data home, migration.\n- [Ingestion scheduling](docs/en/ingestion-scheduling.md): source health,\n  catch-up, retries, and Task Scheduler.\n- [Metadata v2 migration](docs/en/metadata-v2-migration.md): structured search\n  metadata, backup, migration, and restore.\n- [Confluence writer](docs/en/confluence-writer.md): allowlisted REST ingestion,\n  Windows Credential Manager, conversion, and atomic generations.\n- [Reproducible install](docs/en/reproducible-install.md): `requirements.lock`,\n  `--require-hashes`, regenerating the lock.\n- [Public specification](docs/en/spec.md): MCP surface, index contracts, data,\n  distribution, and limits.\n- [Architecture](docs/en/architecture.md): end-to-end and technical choices.\n- [Security](docs/en/security.md): local runtime, telemetry off,\n  single-writer.\n\n## Prerequisites\n\n| Path | Requirements |\n|---|---|\n| Windows installer | No separate Python or .NET runtime. At least ~500 MB of space (applications, model + index). |\n| Standalone archive | No Python. ~500 MB of space (model + index). |\n| From source | Python 3.10+. ~500 MB of space. |\n| Client | Claude Desktop/Code, Codex, Gemini, Antigravity, LM Studio, Cursor, Windsurf or VS Code (MCP support). |\n\n## License\n\nApache 2.0. See [LICENSE](LICENSE).\n\n## Retrieval validation\n\nSee [the validation guide](docs/en/retrieval-validation.md) for the desktop JSON search contract, the isolated FR/EN relevance corpus, performance measurements and exact paired-commit checks.\n",
  "bytes": 10744,
  "sha": "682fac9d180b7411c35273b121dbace289b5ac5b65c42251ad986dbd9ee32705",
  "repo_slug": "vblackjack/cortex",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_vblackjack_cortex_b5714f10/readme"
}