Skip to content

quickstart.md

Latest commit

 

History

History
122 lines (83 loc) · 3.54 KB

quickstart.md

File metadata and controls

122 lines (83 loc) · 3.54 KB
Raw

Quickstart

Set up Konteks once, then use the same session flow whenever you open your coding agent.

Tip

Using an AI coding agent? See AI-Assisted Installation for a copy-ready prompt that asks the agent to install Konteks, configure MCP, and verify setup for you.

Prerequisite: Project Setup

Run setup commands from your project root. Konteks requires Node.js 22.13+ or Bun 1.3+.

Use npx -y konteks-cli by default for one-off setup unless you prefer another package runner.

1. Initialize Memory

Run one command from your project root:

npx -y konteks-cli init

# or your preferred package manager:
bunx konteks-cli init
pnpm dlx konteks-cli init
yarn dlx konteks-cli init

What happens?

  • Creates a .konteks/ directory for local memory storage.
  • Initializes the memory.sqlite substrate.
  • Creates .konteks/.gitignore so memory artifacts stay untracked.
  • Extracts and indexes the current project state.

Do not commit .konteks/; initialization keeps project memory untracked with a local .konteks/.gitignore.

2. Set Up MCP

Install Konteks before configuring MCP. Use the global install command that matches your runtime.

bun add -g konteks-cli
npm install -g konteks-cli
pnpm add -g konteks-cli
yarn global add konteks-cli

Add one MCP server definition before opening the agent.

Tip

Global Registration: Register Konteks globally in your agent's config so you don't have to repeat this setup for every project.

For Bun users:

{
  "mcpServers": {
    "konteks": {
      "command": "bunx",
      "args": ["--bun", "konteks-cli", "mcp"]
    }
  }
}

For Node (npm/yarn/pnpm) users:

{
  "mcpServers": {
    "konteks": {
      "command": "konteks-cli",
      "args": ["mcp"]
    }
  }
}

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. If your agent does not show MCP Prompts in its autocomplete UI, run bunx --bun konteks-cli install-skills --global for Bun installs or konteks-cli install-skills --global for npm installs. See Compatibility.

From This Point On

Use this flow whenever you open a fresh coding-agent session in the project. For the full model behind this loop, read the Warm Up -> Build -> Save lifecycle.

3. Open Your Agent

Open your coding agent from the root of your project after the MCP server is configured.

4. Warm Up

Run the Warm Up prompt at the start of a fresh agent session. The focus is optional: leave it blank for general project context, or add a free-form focus to shape the memories loaded during Warm Up.

/konteks-warm-up

For focused context:

/konteks-warm-up security, authentication, and authorization

5. Build

Give your agent the task directly. RECALL IS OPTIONAL; use it when the work benefits from remembered modules, constraints, prior decisions, or historical context:

/konteks-recall last attack, vulnerability, prevention and mitigation

6. Save

When the session is complete or worth preserving:

/konteks-save

The prompt tells your agent to save future-useful durable memories first, then one compact session diary. You do not need to manually summarize or split the work yourself.