From 9ade9a6a48700ae90455617f60434700cc9f6115 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=F0=9F=8D=95?= Date: Fri, 5 Jun 2026 12:39:51 +0800 Subject: [PATCH] docs: update installation instructions and clarify MCP server setup --- README.md | 4 +- docs/api/cli.md | 5 +- docs/for-agents/installation.md | 82 +++++++++++++----------------- docs/getting-started/overview.md | 7 +-- docs/getting-started/quickstart.md | 17 +++++-- docs/reference/troubleshooting.md | 12 +++-- 6 files changed, 64 insertions(+), 63 deletions(-) diff --git a/README.md b/README.md index 0d171cdc..400d1009 100644 --- a/README.md +++ b/README.md @@ -6,11 +6,11 @@ It builds a project-local context graph through autonomous **knowledge curation**, ensuring you **never re-explain your project** to an AI agent. -Memory artifacts are stored directly inside your repository, exposing compact, task-specific recall through an MCP server without requiring global installation or cloud dependencies. +Memory artifacts are stored directly inside your repository, exposing compact, task-specific recall through an MCP server without cloud dependencies. ## 🚀 Key Features -* **Zero-Install**: Run anywhere via `npx` or `bunx` without global installation. +* **One-Off Setup**: Try or initialize Konteks with `npx` or `bunx`; use an installed CLI for MCP startup. * **Language-Aware**: Understands code structure across [various file types](src/assets/grammar-registry.ts). * **Local-First**: Your project memory stays in your repo—no cloud, no accounts. * **Token-Efficient**: High-fidelity context synthesis designed for LLM economy. diff --git a/docs/api/cli.md b/docs/api/cli.md index 5f23c4e6..a5907c53 100644 --- a/docs/api/cli.md +++ b/docs/api/cli.md @@ -1,6 +1,6 @@ # CLI API -The Konteks CLI manages local project memory. It is designed to run through `npx`, `bunx`, `pnpm dlx`, or `yarn dlx`. +The Konteks CLI manages local project memory. It can run through `npx`, `bunx`, `pnpm dlx`, or `yarn dlx` for one-off commands, but MCP server registration should use an installed `konteks-cli` executable for fast startup. For terms, see the [Glossary](../reference/glossary.md). @@ -21,6 +21,9 @@ For terms, see the [Glossary](../reference/glossary.md). | `konteks mcp` | Serve | Start the MCP server for an agent client. | | `konteks install-skills` | Compatibility | Install Konteks skills for agents without MCP prompt support. | +> [!IMPORTANT] +> Configure MCP clients with an installed command such as `"command": "konteks-cli", "args": ["mcp"]`. Avoid one-off runners for MCP server startup because package resolution or downloads can exceed the client startup timeout. + ## Memory Portability Durable memory export/import is the portable path. It includes saved observations and diary entries, then rebuilds local retrieval indexes on import: diff --git a/docs/for-agents/installation.md b/docs/for-agents/installation.md index ea7becea..682479ae 100644 --- a/docs/for-agents/installation.md +++ b/docs/for-agents/installation.md @@ -21,11 +21,12 @@ Do not create a new application. Konteks is added to the project the user alread 2. Check whether Konteks is already initialized by looking for `.konteks/config.json`. 3. If it is already initialized, skip initialization and continue to MCP setup and workflow verification. 4. Verify that either Node.js 22.13 or newer, or Bun 1.3 or newer, is available. -5. Run `konteks-cli init` through the available package runner. -6. Configure the user's MCP-compatible agent to run `konteks-cli mcp`. -7. Install compatibility skills only when the agent supports MCP tools but does not show MCP prompts. -8. Run a quick verification command. -9. Explain the exact next prompt the user should run at the start of future sessions. +5. Install `konteks-cli` globally with the available package manager. +6. Run `konteks-cli init`. +7. Configure the user's MCP-compatible agent to run `konteks-cli mcp`. +8. Install compatibility skills only when the agent supports MCP tools but does not show MCP prompts. +9. Run a quick verification command. +10. Explain the exact next prompt the user should run at the start of future sessions. ## Prerequisite Checks @@ -35,31 +36,42 @@ Run quick checks from the project root: pwd test -f .konteks/config.json && echo "Konteks is already initialized" node -v +npm -v bun --version ``` Use whichever runtime is available: -* Prefer `npx -y konteks-cli` when Node.js 22.13 or newer is available. -* Use `bunx konteks-cli` when Bun 1.3 or newer is available. -* If both are available, prefer the package manager the user requested. If they did not express a preference, use `npx`. +* Prefer Bun when Bun 1.3 or newer is available. +* Use npm when Node.js 22.13 or newer and npm are available but Bun is not available. +* If both are available, prefer the package manager the user requested. If they did not express a preference, use Bun. If neither supported runtime is available, stop and ask the user to install Node.js 22.13+ or Bun 1.3+ before continuing. Do not install system runtimes unless the user explicitly asks you to do that. -## Initialize Konteks +## Install Konteks Globally -Run one initialization command from the project root: +Install Konteks globally before running setup or configuring MCP. MCP clients expect the server process to start quickly; one-off package runners such as `npx`, `bunx`, `pnpm dlx`, and `yarn dlx` may spend time resolving or downloading packages before the server starts. + +With Bun: ```bash -npx -y konteks-cli init +bun add -g konteks-cli ``` -Equivalent package-runner options: +With npm: ```bash -bunx konteks-cli init -pnpm dlx konteks-cli init -yarn dlx konteks-cli init +npm install -g konteks-cli +``` + +If global package installation requires network access, package downloads, or elevated approval, ask the user for approval with the exact command before continuing. + +## Initialize Konteks + +Run one initialization command from the project root: + +```bash +konteks-cli init ``` Initialization should: @@ -81,21 +93,8 @@ Use this MCP server definition: { "mcpServers": { "konteks": { - "command": "npx", - "args": ["-y", "konteks-cli", "mcp"] - } - } -} -``` - -If the user chose Bun, use: - -```json -{ - "mcpServers": { - "konteks": { - "command": "bunx", - "args": ["konteks-cli", "mcp"] + "command": "konteks-cli", + "args": ["mcp"] } } } @@ -116,31 +115,17 @@ Konteks exposes its lifecycle workflows as MCP prompts: If the current agent does not show MCP prompts in its prompt or command UI, install the same lifecycle workflows as native skills: ```bash -npx -y konteks-cli install-skills --global -``` - -Use the same package runner chosen earlier: - -```bash -bunx konteks-cli install-skills --global -pnpm dlx konteks-cli install-skills --global -yarn dlx konteks-cli install-skills --global +konteks-cli install-skills --global ``` -Use `--global` by default for agent compatibility skills, because these prompts are useful across projects. If the user wants project-local skills only, omit `--global`. +Use `--global` for agent compatibility skills, because these prompts are useful across projects and this playbook keeps Konteks installed globally. ## Verify Setup Run: ```bash -npx -y konteks-cli status -``` - -Or with the selected runner: - -```bash -bunx konteks-cli status +konteks-cli status ``` Successful setup means the status command can find the project root, memory directory, and indexed project memory. If status says memory is not initialized, return to the project root and run `konteks-cli init` again. @@ -179,6 +164,7 @@ The save prompt should persist compact durable memories first, then one session * Do not commit `.konteks/`; initialization should add it to `.gitignore`. * Do not add Konteks as an application dependency unless the user explicitly asks for that. * Do not invent custom memory directories; Konteks uses `.konteks/` in the project root. +* Do not configure MCP to launch Konteks through `npx`, `bunx`, `pnpm dlx`, or `yarn dlx`; use the globally installed `konteks-cli` command. * Keep installation output brief. Report what was initialized, how MCP was configured, whether compatibility skills were installed, and the first prompt to run. * If network access, package downloads, or global config writes require approval, ask for approval with the exact command you need to run. @@ -187,7 +173,7 @@ The save prompt should persist compact durable memories first, then one session When everything is ready, leave the user with a short message like: ```text -Konteks is initialized for this project. I configured the MCP server with npx, installed global compatibility skills because this agent does not expose MCP prompts, and verified setup with `konteks-cli status`. +Konteks is initialized for this project. I configured the MCP server with the globally installed `konteks-cli` command, installed global compatibility skills because this agent does not expose MCP prompts, and verified setup with `konteks-cli status`. For future fresh sessions, start with `/konteks-warm-up`. Use `/konteks-recall ` when you need focused project memory, and run `/konteks-save` before ending a meaningful session. ``` diff --git a/docs/getting-started/overview.md b/docs/getting-started/overview.md index a8445cf8..d40c8cf5 100644 --- a/docs/getting-started/overview.md +++ b/docs/getting-started/overview.md @@ -26,11 +26,12 @@ Konteks stores memory artifacts inside your repository, typically in a `.konteks * No cloud services, no external accounts, and no telemetry. * Memory is as portable as your repo. -### 2. Zero-Friction (The Zero-Install Mandate) +### 2. Zero-Friction Setup -We believe that setup should not be a barrier. Konteks is designed to be used through the JavaScript package ecosystem without global installation. +We believe that setup should not be a barrier. Konteks can be tried and initialized through the JavaScript package ecosystem without a global install. -* Use it via `npx` or `bunx`. +* Use one-off runners such as `npx` or `bunx` for setup and trial commands. +* Use an installed `konteks-cli` command for MCP server startup so agents do not wait on package resolution. * No separate database service or external account required. * Works anywhere Node.js or Bun is available. diff --git a/docs/getting-started/quickstart.md b/docs/getting-started/quickstart.md index 4011f569..1ff34013 100644 --- a/docs/getting-started/quickstart.md +++ b/docs/getting-started/quickstart.md @@ -9,7 +9,7 @@ Set up Konteks once, then use the same [session](../reference/glossary.md#sessio Run setup commands from your project root. Konteks requires **Node.js 22.13+** or **Bun 1.3+**. -Use `npx -y konteks-cli` by default unless you prefer another package runner. +Use `npx -y konteks-cli` by default for one-off setup unless you prefer another package runner. ### 1. Initialize Memory @@ -35,6 +35,15 @@ Do not commit `.konteks/`; initialization adds it to `.gitignore` so project mem ### 2. Set Up MCP +Install Konteks before configuring MCP. MCP clients expect the server process to start quickly, while one-off runners such as `npx`, `bunx`, `pnpm dlx`, and `yarn dlx` may spend time resolving or downloading packages before the server starts. + +```bash +npm install -g konteks-cli + +# or, with Bun: +bun add -g konteks-cli +``` + Add Konteks to your MCP-compatible coding agent configuration before opening the agent. > [!TIP] @@ -44,8 +53,8 @@ Add Konteks to your MCP-compatible coding agent configuration before opening the { "mcpServers": { "konteks": { - "command": "npx", - "args": ["-y", "konteks-cli", "mcp"] + "command": "konteks-cli", + "args": ["mcp"] } } } @@ -54,7 +63,7 @@ Add Konteks to your MCP-compatible coding agent configuration before opening the MCP configuration locations are agent-specific. Prefer a global registration when your agent supports it, and restart or reload the agent after changing its MCP configuration. > [!IMPORTANT] -> Konteks exposes its lifecycle workflows as [MCP Prompts](https://modelcontextprotocol.io/docs/concepts/prompts). If your agent does not show MCP Prompts in its autocomplete UI, run `npx -y konteks-cli install-skills --global` once after initialization to use the lifecycle prompts as native skills. Use the same package runner you chose for setup. See [Compatibility](../api/cli.md#compatibility-skills). +> Konteks exposes its lifecycle workflows as [MCP Prompts](https://modelcontextprotocol.io/docs/concepts/prompts). If your agent does not show MCP Prompts in its autocomplete UI, run `konteks-cli install-skills --global` once after installation to use the lifecycle prompts as native skills. See [Compatibility](../api/cli.md#compatibility-skills). ## From This Point On diff --git a/docs/reference/troubleshooting.md b/docs/reference/troubleshooting.md index fbe5ae3a..720dc8bf 100644 --- a/docs/reference/troubleshooting.md +++ b/docs/reference/troubleshooting.md @@ -33,13 +33,15 @@ This guide helps you resolve common issues encountered while setting up or using ### 4. "MCP Tool timeout or connection error" **Symptoms**: Your AI agent reports that it cannot connect to the Konteks server or the tool timed out. -**Cause**: The MCP server process may have crashed or is taking too long to process a large project. +**Cause**: The MCP server process may have crashed, is taking too long to process a large project, or is being launched through a one-off package runner that must resolve or download packages before the server starts. **Solution**: -1. Run `konteks status` to check project memory freshness. -2. Ensure you are using a supported runtime (Bun 1.3+ or Node 22.13+). -3. Check `.konteks/errors.log` for recent internal Konteks errors. -4. Check the logs of your AI agent/host for connection-level errors. +1. Install Konteks globally with `npm install -g konteks-cli` or `bun add -g konteks-cli`. +2. Configure your MCP client with `"command": "konteks-cli"` and `"args": ["mcp"]`, not `npx`, `bunx`, `pnpm dlx`, or `yarn dlx`. +3. Run `konteks-cli status` to check project memory freshness. +4. Ensure you are using a supported runtime (Bun 1.3+ or Node 22.13+). +5. Check `.konteks/errors.log` for recent internal Konteks errors. +6. Check the logs of your AI agent/host for connection-level errors. ### 5. "Secrets or sensitive data in recall"