ekkOS_ Connect

This repository contains the official VS Code/Cursor extension for ekkOS_ — the persistent memory layer for AI coding assistants.

Note: Forks or mirrors of this repository may be outdated. For the most current version, install from the VS Code Marketplace.

Endless Context CLI — ekkos run

The killer feature: A Claude Code wrapper that gives you endless context with near-zero loss.

# Install and run
npx @ekkos/cli run

What happens:

1. Launches Claude Code in a smart PTY wrapper
2. Monitors context usage in real-time
3. When context fills up → auto-clears and auto-continues
4. Your conversation continues seamlessly — you barely notice

No more "sorry, I lost context." The CLI handles everything automatically.

Human-Readable Session IDs

Every session gets a memorable 3-word name like groovy-koala-saves or velvet-monk-skips:

• Deterministic — Same session always gets the same name
• Trackable — Appears in Claude's footer: · Turn 47 · groovy-koala-saves ·
• Resumable — /continue groovy-koala-saves picks up where you left off

Time Machine — View Full Sessions

Every turn is stored and viewable on the ekkOS_ Platform:

platform.ekkos.dev/time-machine

• Browse all your sessions by name or date
• View full conversation history turn-by-turn
• See patterns applied, files touched, decisions made
• Export sessions for reference or debugging
• Live Mode — Watch sessions update in real-time

Your AI conversations are now auditable, searchable, and permanent.

Early Access - Free Beta

You're early! This extension and ekkos.dev are in free beta.

Found an issue? Report it

What This Extension Does

One-click setup for ekkOS_ memory across all AI IDEs:

• One-click OAuth — Connect to your ekkOS_ account instantly
• Auto MCP Deploy — Automatically configures all supported IDEs:
  • Cursor (~/.cursor/mcp.json)
  • Claude Code CLI (~/.claude/settings.json)
  • Claude Desktop App
  • Windsurf (~/.codeium/windsurf/mcp_config.json)
  • VS Code (Continue extension)
  • OpenAI Codex CLI
• Cross-Platform — macOS, Linux, and Windows
• Health Check — Test MCP connectivity with one click
• AI Instructions — Deploy .claude.md and .cursorrules to your project
• Status Bar — Always know your connection status
• Setup Wizard — Windows-optimized one-button setup with auto-fix
• System Check — 3-gate preflight diagnostics (Claude, PTY, MCP)

New in v2.12.18

Windows Preflight System

The extension now includes a comprehensive Windows setup wizard that ensures all prerequisites are met before enabling auto-continue features:

CLI Doctor Command

The companion CLI includes diagnostic tools:

# Run 3-gate diagnostics
npx @ekkos/cli doctor

# Machine-readable output (for automation)
npx @ekkos/cli doctor --json

# Attempt auto-fixes for safe issues
npx @ekkos/cli doctor --fix

Auto-Continue Improvements

• Session State Fix: Uses observedSessionThisRun pattern to prevent stale session restoration
• Cache Fallback: Falls back to most recent session from local cache when no session observed
• Hard Fail on Windows: Clear error messages with remediation steps when PTY unavailable

What This Extension Does NOT Document

This extension intentionally does not describe:

• Internal system architecture
• How memory is processed server-side
• Infrastructure or backend topology

Getting Started

1. Click the ekkOS_ icon in the activity bar
2. Click "Connect Account"
3. Sign in with your ekkOS_ account
4. MCP config is automatically deployed to all detected IDEs

Commands

Configuration

Requirements

• VS Code 1.80.0+ (or Cursor/Windsurf)
• Node.js 18+ (for MCP server)
• Claude Code CLI (for ekkos run auto-continue features)

Windows Setup

Windows users should run the Setup Wizard for best results:

1. Open Command Palette (Ctrl+Shift+P)
2. Run ekkOS_: Setup Wizard (Recommended)
3. The wizard will:
   • Check Claude Code installation
   • Verify PTY support (required for auto-continue)
   • Configure MCP server
   • Auto-fix issues or show one-click terminal commands

CLI Diagnostics:

# Check system prerequisites
npx @ekkos/cli doctor

# Auto-fix safe issues
npx @ekkos/cli doctor --fix

# Run Claude with auto-continue
npx @ekkos/cli run

Endless Context & Session Management

How "Endless Context" Works

ekkOS_ creates the illusion of endless context through:

1. Lossless Verbatim Storage — Every turn is captured to L2 (episodic memory) with full fidelity
2. Smart Background Compression — When context approaches limits, ekkOS_ preserves and restores seamlessly
3. Local Cache — Session data cached at ~/.ekkos/cache/sessions/ for instant restoration

Note: This is not true infinite context — it's an illusion created by ekkOS_'s memory architecture. Claude's 200k token window is still the hard limit per request, but ekkOS_ makes context loss invisible.

Session Names

Sessions are identified by memorable 3-word slugs (e.g., groovy-koala-saves, velvet-monk-skips). These are:

• Deterministic — Same session UUID always produces same name
• Human-readable — Easy to reference and remember
• Tracked automatically — Appear in Claude's footer: · Turn N · groovy-koala-saves ·

The /continue Command

When context is cleared (manually or automatically), use /continue to restore:

# In Claude Code:
/continue                    # Restore most recent session
/continue groovy-koala-saves # Restore specific session

What gets restored:

• Recent conversation turns (up to ~60KB / ~15k tokens)
• Active patterns and directives
• File context and goals
• Session metadata

Auto-Continue with ekkos run

The CLI wrapper provides automatic context restoration:

# Launch Claude with auto-continue enabled
npx @ekkos/cli run

# With specific session
npx @ekkos/cli run --session velvet-monk-skips

# With verbose logging
npx @ekkos/cli run --verbose

What ekkos run does:

1. Launches Claude Code in a PTY (pseudo-terminal)
2. Monitors output for context limit warnings
3. Automatically runs /clear when context is high
4. Immediately runs /continue to restore session
5. User experiences seamless "endless" conversation

Session State & Local Cache

Sessions are cached locally in three tiers:

Local cache structure:

~/.ekkos/cache/sessions/
├── index.json                           # Session index
├── c71a7c88-...-.jsonl                  # Turn data (JSONL)
└── c71a7c88-...-.meta.json              # Session metadata

Session Selection Priority

When restoring a session, ekkOS_ uses this priority:

1. observedSessionThisRun — Session seen in current process (most reliable)
2. lastSeenSessionName — Session from TUI output (if recent, <15s)
3. Most Recent from Cache — From local cache index (fallback)
4. Persisted State — From ~/.ekkos/state.json (last resort)

This prevents the "wrong session" bug where stale state was restored on Windows.

Context Preservation Hooks

ekkOS_ hooks automatically capture context:

Hook location: ~/.claude/hooks/

Recommended: Disable Auto-Compact

For best results with ekkOS_, disable Claude Code's auto-compact to get true "endless context":

Option 1: Via Claude Code

# In Claude Code, run:
/config
# Then toggle "Auto-compact enabled" to OFF

Option 2: Via Config File

# Edit ~/.claude.json and add:
{
  "autoCompactEnabled": false
}

Why Disable Auto-Compact?

ekkOS_ remembers what auto-compact forgets. With auto-compact disabled:

• Use full 200k token window
• ekkOS_ captures every turn to L2 (episodic memory)
• Recall any turn: ekkOS_Recall({session_id: "...", from_turn: 30, to_turn: 47})
• Never lose context again

Troubleshooting

MCP not loading?

1. Check Node.js version: node --version (must be 18+)
2. Verify config file exists at the correct path
3. Test manually: EKKOS_API_KEY=xxx npx @ekkos/mcp-server
4. Restart your IDE completely

Config file locations:

Links

• Documentation: docs.ekkos.dev
• Issues: GitHub Issues
• Discord: discord.gg/vePAuEYp

License & Trademarks

ekkOS_ and the ekkOS_ logo are trademarks of ekkOS Technologies Inc.

This extension is provided under the MIT license. Unauthorized reproduction or distribution of ekkOS_ trademarks or branding assets is prohibited.

For licensing inquiries: ekkos.dev