Installation

Prerequisites

Before installing CEMS, you need:

CEMS Server

A CEMS server URL and API key from your admin.Don’t have one? See Server Deployment.

Python 3.11+

CEMS requires Python 3.11 or later.The installer will set up uv automatically.

Installation Methods

Choose the installation method that fits your workflow:

Interactive Install (Recommended)
Non-Interactive Install
Install from Source
Skills Only (Any Agent)

The interactive installer walks you through setup step-by-step:

curl -fsSL https://getcems.com/install.sh | bash

What happens:

Installs uv if missing
Installs CEMS CLI tools via uv tool install
Prompts for API URL and key
Asks which IDEs to configure (Claude Code, Cursor, Codex, Goose, or all)
Deploys hooks, skills, and MCP configs
Saves credentials to ~/.cems/credentials (chmod 600)
Saves IDE choices to ~/.cems/install.conf

The installer is idempotent — safe to run multiple times.

For automation, scripts, or CI/CD:

CEMS_API_KEY=your-key-here \
CEMS_API_URL=https://cems.example.com \
CEMS_TOOL=claude \
  curl -fsSL https://getcems.com/install.sh | bash

Environment Variables:

Variable	Required	Default	Description
`CEMS_API_KEY`	Yes	—	Your CEMS API key
`CEMS_API_URL`	No	`https://cems.chocksy.com`	CEMS server URL
`CEMS_TOOL`	No	`claude`	IDE to configure: `claude`, `cursor`, `codex`, `goose`, or `all`

Non-interactive install skips IDE selection prompts — specify CEMS_TOOL to choose.

For development or custom modifications:

git clone https://github.com/chocksy/cems.git
cd cems
./install.sh

This runs a development install:

Checks for uv (required)
Runs uv tool install -e . --force (editable mode)
Delegates to cems setup for configuration

Editable mode means your local changes take effect immediately.

If your agent supports skills.sh, you can add CEMS skills without the full install:

npx skills add Chocksy/cems

What you get:

cems-recall skill
cems-remember skill
cems-foundation skill

What you still need:

CEMS server URL and API key
Manual configuration (add credentials to ~/.cems/credentials)

Skills-only install doesn’t include hooks, observer daemon, or automatic memory injection.

IDE Configuration

CEMS can configure multiple IDEs. Here’s what gets installed for each:

Claude Code

Full Integration: 6 hooks, 6 skills, 2 commands

Hooks (~/.claude/hooks/):

cems_session_start.py — Profile + context injection at session start
cems_user_prompts_submit.py — Memory search + observations on every prompt
cems_post_tool_use.py — Extract tool learning after tool execution
cems_pre_tool_use.py — Gate rules enforcement before tool execution
cems_stop.py — Session analysis + observer daemon start on session end
cems_pre_compact.py — Context preservation before compaction

Skills (~/.claude/skills/cems/):

recall.md — /recall <query> to search memories
remember.md — /remember <content> to add personal memory
share.md — /share <content> to add team memory
forget.md — /forget <id> to delete memory
context.md — /context to show memory system status
memory-guide.md — Proactive memory usage guide

Commands (~/.claude/commands/):

recall.md — /recall command variant
remember.md — /remember command variant

Settings (~/.claude/settings.json):

Hook configuration merged (not overwritten)

Cursor

MCP + Hooks: 3 hooks, 5 skills

Hooks (~/.cursor/hooks/):

cems_session_start.py — Profile injection
cems_agent_response.py — Agent response hook
cems_stop.py — Session end hook

Skills (~/.cursor/skills/):

cems-recall/SKILL.md — Search memories
cems-remember/SKILL.md — Add personal memory
cems-forget/SKILL.md — Delete memory
cems-share/SKILL.md — Add team memory
cems-context/SKILL.md — Memory status

MCP Config (~/.cursor/mcp.json):

CEMS MCP server config merged

Codex

MCP + Commands: 3 commands, 2 skills

Commands (~/.codex/commands/):

recall.md — Search memories
remember.md — Add memory
foundation.md — Foundation guidelines

Skills (~/.codex/skills/):

recall/SKILL.md — Search memories
remember/SKILL.md — Add memory

MCP Config (~/.codex/config.toml):

CEMS MCP server config merged

Goose

MCP Extension

MCP Config (~/.config/goose/config.yaml):

CEMS MCP extension block merged

MCP Tools Available:

memory_add — Store a memory
memory_search — Search with full retrieval pipeline
memory_get — Retrieve full document by ID
memory_forget — Delete or archive a memory
memory_update — Update memory content
memory_maintenance — Trigger maintenance jobs

Credentials

CEMS credentials are stored in ~/.cems/credentials with chmod 600. Credential Resolution Order:

CLI flags: --api-url, --api-key
Environment variables: CEMS_API_URL, CEMS_API_KEY
Credentials file: ~/.cems/credentials

Credentials File Format:

CEMS_API_URL=https://cems.example.com
CEMS_API_KEY=cems_usr_abc123...
CEMS_AUTO_UPDATE=1

Manual Credential Setup:

mkdir -p ~/.cems
cat > ~/.cems/credentials <<EOF
CEMS_API_URL=https://cems.example.com
CEMS_API_KEY=cems_usr_abc123...
EOF
chmod 600 ~/.cems/credentials

Verification

After installation, verify everything works:

Check CLI installation

cems --version

Expected output:

cems version 0.7.1

Test server connection

cems health

Expected output:

✓ Connected to CEMS server
✓ API key valid
✓ User: yourname

Verify hooks (Claude Code)

ls ~/.claude/hooks/cems_*.py

Should list 6 hook files.

Verify skills

ls ~/.claude/skills/cems/

Test memory operations

cems add "Test memory"
cems search "test"
cems list

Updating

Automatic Updates

CEMS auto-updates when you start a new Claude Code session (if >24 hours old). The SessionStart hook checks for updates and runs cems update in the background. Disable auto-update:

export CEMS_AUTO_UPDATE=0
# Or add to ~/.cems/credentials:
echo "CEMS_AUTO_UPDATE=0" >> ~/.cems/credentials

Manual Updates

# Pull latest package + re-deploy hooks/skills
cems update

What cems update does:

Runs uv tool upgrade cems to pull latest version
Re-deploys hooks, skills, and MCP configs to configured IDEs
Uses IDE choices from ~/.cems/install.conf

Reconfiguration

To change settings or add/remove IDE integrations:

cems setup

This re-runs the full setup wizard:

Prompts for new credentials (or keeps existing)
Asks which IDEs to configure
Re-deploys hooks, skills, and configs
Updates ~/.cems/install.conf

Uninstallation

Remove Hooks/Skills (Keep Credentials)
Complete Removal

cems uninstall

This removes:

All hooks from ~/.claude/, ~/.cursor/, etc.
All skills
MCP config entries

This keeps:

~/.cems/credentials
~/.cems/install.conf
CEMS CLI tools

cems uninstall --all

This removes everything:

All hooks, skills, and configs
~/.cems/ directory
CEMS CLI tools

To manually remove CLI tools:

uv tool uninstall cems

Advanced Configuration

Observer Daemon

The observer daemon (cems-observer) runs in the background and watches session transcripts. Check if running:

ps aux | grep cems-observer

Manual start:

cems-observer &

Configuration: The observer daemon reads from ~/.cems/credentials and watches:

~/.claude/projects/*/ for JSONL transcript files
Polls every 30 seconds
Sends 50KB chunks to server when accumulated

Custom Hook Configuration

If you need to customize hook behavior, edit the hook files directly:

# Add custom logic before profile injection
import sys
import json

# Your custom code here

# Then run the standard CEMS logic
# ...

Custom hook modifications will be overwritten by cems update. Make backups.

Environment Variables

CEMS respects these environment variables:

Variable	Default	Description
`CEMS_API_URL`	`https://cems.chocksy.com`	CEMS server URL
`CEMS_API_KEY`	—	Your API key
`CEMS_AUTO_UPDATE`	`1`	Enable auto-updates (0=disable)
`CEMS_LOG_LEVEL`	`INFO`	Logging level
`CEMS_OBSERVER_POLL_INTERVAL`	`30`	Observer poll interval (seconds)

Troubleshooting

uv not found after install

The installer installs uv to ~/.local/bin/. Add to PATH:

export PATH="$HOME/.local/bin:$PATH"

Add to your shell profile:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

cems command not found

uv tool installs to ~/.local/bin/. Ensure it’s on PATH:

export PATH="$HOME/.local/bin:$PATH"

Verify:

which cems
ls -la ~/.local/bin/cems

Hooks not executing

Verify hooks exist:
```
ls -la ~/.claude/hooks/cems_*.py
```

Test hook manually:

echo '{"prompt": "test"}' | uv run ~/.claude/hooks/cems_user_prompts_submit.py

Check settings.json:
```
cat ~/.claude/settings.json
```
Re-run setup:
```
cems setup
```

Skills not appearing in IDE

Verify skill files exist:
```
ls -la ~/.claude/skills/cems/
```
Restart IDE completely
Check IDE skill directory (may vary):
- Claude Code: ~/.claude/skills/
- Cursor: ~/.cursor/skills/
- Codex: ~/.codex/skills/
Re-run setup:
```
cems setup
```

Permission denied errors

The credentials file requires chmod 600:

chmod 600 ~/.cems/credentials

If hooks can’t execute:

chmod +x ~/.claude/hooks/cems_*.py

Next Steps

Quick Start

Learn how to use CEMS in your daily workflow

Server Deployment

Set up CEMS server for your team

API Reference

Explore the full API and CLI

Architecture

Understand how CEMS works under the hood

Get Started

Core Concepts

IDE Integration

Using CEMS

Server Deployment

Advanced

Installation

Prerequisites

CEMS Server

Python 3.11+

Installation Methods

IDE Configuration

Claude Code

Cursor

Codex

Goose

Credentials

Verification

Updating

Automatic Updates

Manual Updates

Reconfiguration

Uninstallation

Advanced Configuration

Observer Daemon

Custom Hook Configuration

Environment Variables

Troubleshooting

Next Steps

Quick Start

Server Deployment

API Reference

Architecture

Build docs developers (and LLMs) love

Get Started

Core Concepts

IDE Integration

Using CEMS

Server Deployment

Advanced

​Prerequisites

CEMS Server

Python 3.11+

​Installation Methods

​IDE Configuration

​Claude Code

​Cursor

​Codex

​Goose

​Credentials

​Verification

​Updating

​Automatic Updates

​Manual Updates

​Reconfiguration

​Uninstallation

​Advanced Configuration

​Observer Daemon

​Custom Hook Configuration

​Environment Variables

​Troubleshooting

​Next Steps

Quick Start

Server Deployment

API Reference

Architecture

Build docs developers (and LLMs) love

Prerequisites

Installation Methods

IDE Configuration

Claude Code

Cursor

Codex

Goose

Credentials

Verification

Updating

Automatic Updates

Manual Updates

Reconfiguration

Uninstallation

Advanced Configuration

Observer Daemon

Custom Hook Configuration

Environment Variables

Troubleshooting

Next Steps