ekkOS Documentation — Complete Guide to AI Memory

Installation

Install the ekkOS CLI — it includes the Memory MCP server (ekkos mcp / npx @ekkos/cli@latest mcp).

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

Quick Install

One command that handles everything — installs Node.js if needed, then installs the ekkOS CLI.

macOS / Linux

curl -fsSL https://ekkos.dev/install.sh | bash

Windows (PowerShell)

irm https://ekkos.dev/install.ps1 | iex

After installing, run ekkos init then ekkos pulse

Manual Installation

RECOMMENDED

ekkOS CLI

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

npm install -g @ekkos/cli@latest

After installing, run each command separately:

ekkos init

ekkos pulse

Windows: If npm is not recognized, install Node.js first: winget install OpenJS.NodeJS.LTS — then reopen your terminal.
macOS: If npm is not found, run brew install node or download from nodejs.org.

What the CLI deploys

MCP server config 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 -y @ekkos/cli@latest mcp

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

MCP Server (Global Install)

Faster startup

Install the CLI globally for faster startup (avoids npx download each time). Use ekkos mcp in your IDE config, or npx -y @ekkos/cli@latest mcp with npx.

npm install -g @ekkos/cli

Legacy package: @ekkos/mcp-server is deprecated — use @ekkos/cli only. See Connect Your AI and DEPLOYMENT.md for npm publish notes.

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		—
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, and MCP configuration.

If you installed the MCP server only:

EKKOS_API_KEY=your_key npx -y @ekkos/cli@latest mcp

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.