ekkOS Documentation

Installation

Install the ekkOS CLI or MCP server for your development environment.

Prerequisites

Node.js 18+ — Required for the CLI and MCP server
npm — Included with Node.js
Claude Code, Cursor, or Windsurf — At least one AI coding tool

Installation Methods

RECOMMENDED

ekkOS CLI

The CLI provides everything you need: automated setup, API proxy, hooks, session tracking, context management, and usage analytics. This is the recommended way to use ekkOS with Claude Code.

npm install -g @ekkos/cli

After installing, run:

ekkos init    # authenticate & configure your IDEs
ekkos run     # launch Claude Code with memory

What the CLI deploys

MCP server config Hook scripts Skills & agents CLAUDE.md instructions API proxy routing Context eviction

MCP Server Only (NPX)

Zero install

If you only want the MCP memory tools (no proxy, no hooks, no context management), you can configure the MCP server directly in your IDE. No global install needed — npx runs it on demand.

npx @ekkos/mcp-server

See the manual setup guide for IDE-specific config files.

MCP Server (Global Install)

Faster startup

Install the MCP server globally for faster startup (avoids npx download each time):

npm install -g @ekkos/mcp-server

TypeScript SDK

Custom integration

For building custom integrations or using ekkOS memory in your own applications:

npm install @ekkos/sdk

The SDK provides typed access to all ekkOS APIs for Node.js/TypeScript applications.

Feature Comparison

Feature	CLI	MCP Only
Memory tools (Search, Forge, Directive...)
Automatic IDE detection & config		—
API proxy (cost tracking, cache optimization)		—
Intelligent context eviction at ~80%		—
Session naming & tracking		—
Hooks (auto-capture on every turn)		—
Skills & agents deployment		—
Usage analytics (daily/weekly/monthly)		—
Multi-session / swarm support		—
Works with Cursor & Windsurf

Platform Notes

ekkOS works on macOS, Windows, and Linux. The CLI handles platform differences automatically, but here are some things to know.

🍎

macOS

Full support

Full session tracking from startup
Hooks deploy as .sh scripts
Config paths: ~/.claude/, ~/.ekkos/
Install Node.js via brew install node or nodejs.org

🪟

Windows

Supported

Hooks deploy as .cmd batch scripts (handled automatically)
Native Windows shell integration
If you see ENOENT errors, ensure claude is in your PATH or install Claude Code globally
Session binding may use fallback mode — all features still work, session naming is slightly delayed
Config paths: %USERPROFILE%\.claude\, %USERPROFILE%\.ekkos\

🐧

Linux

Full support

Full session tracking from startup
Hooks deploy as .sh scripts
Config paths: ~/.claude/, ~/.ekkos/
Headless/SSH environments: use ekkos init --key YOUR_KEY to skip browser auth
Remote setup: use ekkos setup-remote for headless server deployments

Environment Variables

Variable	Required	Description
`EKKOS_API_KEY`	Yes*	Your ekkOS API key. *CLI handles this automatically via `ekkos init`
`EKKOS_API_URL`	No	API endpoint (default: https://mcp.ekkos.dev)
`EKKOS_PROXY_MODE`	No	Proxy mode: `passthrough` (default) or `active`
`EKKOS_DISABLE_EVICTION`	No	Set to `1` to disable automatic context eviction
`EKKOS_SMART_EVICTION`	No	Set to `1` to enable AI-powered intelligent context compression
`EKKOS_DEBUG`	No	Enable debug logging (set to `true`)

Verify Installation

If you installed the CLI:

ekkos doctor

This runs diagnostic checks on Node.js, Claude Code, session support, hooks, and MCP configuration.

If you installed the MCP server only:

EKKOS_API_KEY=your_key npx @ekkos/mcp-server

You should see output indicating the server is ready to accept MCP connections.

The MCP server is designed to be started by your AI tool, not run standalone. The test above just verifies the package works.