docs: Restructure README — setup front and centre#3
docs: Restructure README — setup front and centre#3jarvis-drakon merged 1 commit intomkdelta221:mainfrom
Conversation
…llapsed - Quick Start is now 3 steps: install, setup, restart - 'setup' moved from step 4 to step 2 (THE critical step) - Manual hook JSON moved to collapsible Advanced Configuration - Added Troubleshooting section addressing common complaints - Alternative install methods collapsed into details blocks - Happy path is clear and impossible to miss
There was a problem hiding this comment.
Pull request overview
This PR restructures the README to make the setup process more prominent and easier to follow, addressing user feedback that the setup command was previously buried and easy to miss.
Changes:
- Streamlined Quick Start to 3 steps with
setupcommand moved from step 4 to step 2 - Moved manual configuration options into collapsible
<details>sections under Advanced Configuration - Added Troubleshooting section to address common user issues
- Reorganized content to prioritize automatic hooks and memory behavior before diving into tools
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| ## Quick Start | ||
|
|
||
| ```bash | ||
| # Step 1: Install | ||
| npm install -g claude-cortex | ||
|
|
||
| 1. **Context Window Exhaustion** - Long sessions hit token limits | ||
| 2. **Compaction Loss** - When context is summarized, important details are lost | ||
| 3. **No Persistence** - Knowledge doesn't survive across sessions | ||
| # Step 2: Configure hooks + Claude Code (REQUIRED — this makes memory automatic) | ||
| npx claude-cortex setup | ||
|
|
||
| ## The Solution | ||
| # Step 3: Restart Claude Code and approve the MCP server when prompted | ||
| ``` |
There was a problem hiding this comment.
The Quick Start instructions are incomplete and will not result in a working installation. After Step 1 (install) and before Step 2 (setup), users need to configure the MCP server in .mcp.json or ~/.claude.json so that Claude Code knows how to launch the cortex server. Without this step, Claude Code won't recognize the MCP server even after running setup and restarting. The setup command only configures CLAUDE.md, hooks in settings.json, and Clawdbot hooks - it does not create the MCP server configuration. This is confirmed by the doctor command which checks for the cortex entry in .mcp.json (src/setup/doctor.ts lines 118-136). Users need instructions to either: 1) create .mcp.json with the mcpServers configuration (as shown in Advanced Configuration), or 2) create ~/.claude.json with the same, before proceeding with the setup command.
| # Claude Cortex 🧠 | ||
|
|
||
| **Brain-like memory system for Claude Code** - Solves the context compaction and memory persistence problems. | ||
| **Brain-like memory system for Claude Code** — Solves context compaction and memory persistence. |
There was a problem hiding this comment.
The sentence "Solves context compaction and memory persistence" is grammatically incorrect. The tool doesn't solve "context compaction" itself - it solves the problems or issues caused by context compaction and memory persistence. The original phrasing "Solves the context compaction and memory persistence problems" was grammatically correct. Suggested alternatives: "Solves context compaction and memory persistence problems" or "Solves the context compaction and memory persistence problems".
| **Brain-like memory system for Claude Code** — Solves context compaction and memory persistence. | |
| **Brain-like memory system for Claude Code** — Solves context compaction and memory persistence problems. |
| |----------|---------|-------------| | ||
| | `PORT` | `3001` | API server port | | ||
| | `CORTEX_CORS_ORIGINS` | `http://localhost:3030,http://localhost:3000` | Comma-separated allowed CORS origins. Set to `*` is not supported — add specific origins. | | ||
| | `CORTEX_CORS_ORIGINS` | `localhost:3030,localhost:3000` | Comma-separated allowed CORS origins | |
There was a problem hiding this comment.
The default value for CORTEX_CORS_ORIGINS is incorrect. According to the code in src/api/visualization-server.ts (lines 64-66), the default value includes the full URLs with http:// protocol and both localhost and 127.0.0.1 addresses: ['http://localhost:3030', 'http://localhost:3000', 'http://127.0.0.1:3030', 'http://127.0.0.1:3000']. The documented value "localhost:3030,localhost:3000" is missing the protocol and 127.0.0.1 addresses.
| | `CORTEX_CORS_ORIGINS` | `localhost:3030,localhost:3000` | Comma-separated allowed CORS origins | | |
| | `CORTEX_CORS_ORIGINS` | `http://localhost:3030,http://localhost:3000,http://127.0.0.1:3030,http://127.0.0.1:3000` | Comma-separated allowed CORS origins | |
| npx claude-cortex hook session-end | ||
| npx claude-cortex hook stop | ||
| npx claude-cortex service install # Auto-start dashboard on login | ||
| npx claude-cortex clawdbot install # Install Clawdbot/Moltbot hook |
There was a problem hiding this comment.
The CLI Reference is missing the npx claude-cortex clawdbot uninstall command, which is supported according to src/index.ts line 24 and implemented in src/setup/clawdbot.ts (lines 91-108). This command should be included in the CLI reference for completeness, as it's the counterpart to clawdbot install.
| npx claude-cortex clawdbot install # Install Clawdbot/Moltbot hook | |
| npx claude-cortex clawdbot install # Install Clawdbot/Moltbot hook | |
| npx claude-cortex clawdbot uninstall # Uninstall Clawdbot/Moltbot hook |
| → Memories are created during compaction and session events. Use Claude Code for a while — memories build up naturally over time. You can also manually save with the `remember` tool. | ||
|
|
||
| **"No cortex entry found in .mcp.json"** | ||
| → Create `.mcp.json` in your project root (see Advanced Configuration) or run `npx claude-cortex setup` to configure automatically. |
There was a problem hiding this comment.
The troubleshooting entry states that npx claude-cortex setup will "configure automatically" when the error "No cortex entry found in .mcp.json" occurs. However, according to src/setup/claude-md.ts (lines 53-76), the setup command only configures CLAUDE.md, hooks in settings.json, and Clawdbot/Moltbot hooks - it does NOT create or modify .mcp.json. Users would still need to manually create .mcp.json as described in the Advanced Configuration section. This instruction is misleading.
| → Create `.mcp.json` in your project root (see Advanced Configuration) or run `npx claude-cortex setup` to configure automatically. | |
| → Create `.mcp.json` in your project root (see Advanced Configuration). This file is not created by `npx claude-cortex setup`, so you need to add it manually. |
What
Restructures the README so the happy path is impossible to miss.
Why
User feedback on Reddit: "you have to keep telling it to remember things" — because
setupwas buried at step 4 and most users never ran it.Changes
setup→ restart. Done.setupmoved from step 4 to step 2 — the critical step that installs automatic hooks<details>blocksResult
Before: 5 steps with 3 options each, manual JSON config shown before the automated setup command
After: 3 steps, works out of the box, advanced config available but not in the way