|
| 1 | +# Cortex documentation |
| 2 | + |
| 3 | +This page sorts the existing documentation by the task you came to do. It holds |
| 4 | +no facts of its own: every entry points at the one document that owns the |
| 5 | +subject, so a correction is made once, where it belongs. The links and their |
| 6 | +section anchors are checked by `tests_py/scripts/test_docs_index_links.py`. |
| 7 | + |
| 8 | +## 1. First local memory round trip |
| 9 | + |
| 10 | +1. Install the plugin: [README § Install](../README.md#install). |
| 11 | +2. Check the environment before the first session: |
| 12 | + `python -m mcp_server.doctor` (one line per check, with the fix for each). |
| 13 | +3. Store and retrieve one memory with the `remember` and `recall` tools: |
| 14 | + their schemas ([`remember`](api-reference.md#remember), |
| 15 | + [`recall`](api-reference.md#recall)), and what each |
| 16 | + call does inside ([write path](data-flow.md#memory-write-path-remember), |
| 17 | + [read path](data-flow.md#memory-read-path-recall)). |
| 18 | +4. See where the memory now lives and how to delete it: |
| 19 | + [PRIVACY § Where your data is stored](../PRIVACY.md#where-your-data-is-stored) and |
| 20 | + [§ Your controls](../PRIVACY.md#your-controls). |
| 21 | + |
| 22 | +Known problems on this path are tracked in the open: the host ignores the plugin's |
| 23 | +`postInstall` step ([#703](https://github.com/cdeust/Cortex/issues/703)), a profile |
| 24 | +with no configuration can reach for a local PostgreSQL |
| 25 | +([#704](https://github.com/cdeust/Cortex/issues/704)), and the first SessionStart |
| 26 | +downloads both model files inside the hook |
| 27 | +([#705](https://github.com/cdeust/Cortex/issues/705)). Read |
| 28 | +[Limits worth knowing before you install](../README.md#limits-worth-knowing-before-you-install) |
| 29 | +first. |
| 30 | + |
| 31 | +## 2. Concepts |
| 32 | + |
| 33 | +- What Cortex keeps, checks and lets fade: [README § Keep context useful](../README.md#keep-context-useful). |
| 34 | +- Storage backends, SQLite by default and PostgreSQL as an opt-in: |
| 35 | + [README § Storage](../README.md#storage). |
| 36 | +- Layers and module boundaries: [architecture.md](architecture.md), |
| 37 | + [module-inventory.md](module-inventory.md). |
| 38 | +- Every pipeline, step by step: [data-flow.md](data-flow.md). |
| 39 | +- What the retrieval numbers do and do not establish: |
| 40 | + [README § Does the retrieval work](../README.md#does-the-retrieval-work), |
| 41 | + [README § Verification](../README.md#verification), |
| 42 | + [benchmarks-detail.md](benchmarks-detail.md). |
| 43 | + |
| 44 | +## 3. Set up a host |
| 45 | + |
| 46 | +- Claude Code and Codex: [README § Cortex in Codex and Claude Code](../README.md#cortex-in-codex-and-claude-code), |
| 47 | + [codex-plugin.md](codex-plugin.md). |
| 48 | +- Claude and Codex on the same memory: [shared-host-memory.md](shared-host-memory.md). |
| 49 | +- Claude Desktop, Cowork and other MCP hosts: [README § Every other MCP host](../README.md#every-other-mcp-host). |
| 50 | +- The upstream MCP servers that `ingest_codebase` and `ingest_prd` consume: |
| 51 | + [mcp-connections.example.json](mcp-connections.example.json). |
| 52 | +- Windows, WSL, dev containers, remote PostgreSQL, corporate proxies and headless CI: |
| 53 | + [deployment-scenarios.md](deployment-scenarios.md). |
| 54 | +- Scheduled background grooming: [groomer-scheduling.md](groomer-scheduling.md). |
| 55 | + |
| 56 | +## 4. API contracts |
| 57 | + |
| 58 | +- Tool catalogue, by tier, with purpose and target latency: [mcp-tools.md](mcp-tools.md). |
| 59 | +- Input schemas, responses and errors: [api-reference.md](api-reference.md), |
| 60 | + [error codes](api-reference.md#error-codes). |
| 61 | +- Design decisions behind the contracts: [adr/](adr/). |
| 62 | + |
| 63 | +## 5. Troubleshooting |
| 64 | + |
| 65 | +- A codebase ingest that looks hung: [troubleshooting.md](troubleshooting.md), starting at |
| 66 | + [Is it hung or just slow?](troubleshooting.md#1-is-it-hung-or-just-slow). |
| 67 | +- Setup errors: [troubleshooting.md § Common setup errors](troubleshooting.md#5-common-setup-errors). |
| 68 | +- A model download that stalls behind a proxy: |
| 69 | + [troubleshooting.md § Stalled model download](troubleshooting.md#4-stalled-model-download), |
| 70 | + [deployment-scenarios.md § Corporate proxy](deployment-scenarios.md#corporate-proxy--custom-ca-model-downloads). |
| 71 | +- Local log files and their rotation: [runbooks/local-log-rotation.md](runbooks/local-log-rotation.md). |
| 72 | + |
| 73 | +## 6. Privacy, security and costs |
| 74 | + |
| 75 | +- What is processed, where it is stored and what leaves the machine: [PRIVACY.md](../PRIVACY.md), |
| 76 | + in particular [What leaves your machine](../PRIVACY.md#what-leaves-your-machine). |
| 77 | +- What Cortex can reach and how to report a vulnerability: [SECURITY.md](../SECURITY.md), |
| 78 | + and the argument with its evidence: [ASSURANCE-CASE.md](ASSURANCE-CASE.md). |
| 79 | +- Energy and carbon: no figure is published, and the page says why: |
| 80 | + [README § Green software engineering](../README.md#green-software-engineering). |
| 81 | + |
| 82 | +## 7. Contributing |
| 83 | + |
| 84 | +- The gates a change has to clear: [CONTRIBUTING.md](../CONTRIBUTING.md), |
| 85 | + [testing-guide.md](testing-guide.md). |
| 86 | +- Who decides and where the project is going: [GOVERNANCE.md](../GOVERNANCE.md), |
| 87 | + [ROADMAP.md](ROADMAP.md). |
0 commit comments