Troubleshooting

Common issues and solutions for CEMS deployment, hooks, skills, and search.

Quick Diagnostics

Start with these commands to identify the issue:

# Check CEMS CLI version
cems --version

# Test server connection
cems health

# Verify credentials
cat ~/.cems/credentials

# Check which IDEs are configured
cat ~/.cems/install.conf

# Test memory operations
cems add "test memory"
cems search "test"

Installation Issues

CEMS CLI not found

Symptoms: cems: command not found Causes:

uv not installed
CEMS not installed via uv tool install
Shell PATH not updated

Fix:

Install uv if missing

curl -LsSf https://astral.sh/uv/install.sh | sh

Install CEMS CLI

uv tool install cems

Update shell PATH

Add to ~/.bashrc or ~/.zshrc:

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

Then reload:

source ~/.bashrc  # or ~/.zshrc

Verify installation

cems --version

Installation script fails

Symptoms: install.sh exits with error Common errors:

Permission denied

Error: chmod: cannot access '~/.cems/credentials': Permission deniedFix:

sudo chown -R $USER:$USER ~/.cems
chmod 700 ~/.cems
chmod 600 ~/.cems/credentials

Missing API URL or key

Error: CEMS_API_URL or CEMS_API_KEY not setFix: Set environment variables before install:

export CEMS_API_URL=https://cems.example.com
export CEMS_API_KEY=cems_usr_...
./install.sh

IDE not found

Error: Claude Code directory not found: ~/.claudeFix: Only install for IDEs you have:

# Skip Claude Code, only install Cursor
./install.sh --cursor

# Or use interactive mode
./install.sh
# Choose only installed IDEs when prompted

Connection Issues

Memory not being recalled

Symptoms: /recall returns empty or hook doesn’t inject memories Debug steps:

Check credentials

cat ~/.cems/credentials
# Should contain:
# CEMS_API_URL=https://...
# CEMS_API_KEY=cems_usr_...

Test connection

cems health
# Should return: {"status": "healthy", ...}

If fails:

Check API URL is reachable: curl $CEMS_API_URL/health
Check API key is valid
Check firewall/network

Test search directly

cems search "test"

If returns results, issue is in hook integration (see Skills Not Appearing).

Check hook output (Claude Code)

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

Should return JSON with memories. If error:

Check Python environment: uv python --version
Check hook file exists: ls ~/.claude/hooks/cems_*.py
Check hook logs in Claude Code output panel

401 Unauthorized

Symptoms: API returns {"detail": "Invalid API key"} Causes:

Expired or invalid API key
Wrong API URL
Credentials file not loaded

Fix:

# Verify credentials file
cat ~/.cems/credentials

# Test with explicit credentials
cems health \
  --api-url https://cems.example.com \
  --api-key cems_usr_YOUR_KEY

# If works, credentials file is wrong - regenerate:
rm ~/.cems/credentials
cems setup  # Re-run setup

# Or get new API key from admin:
# (Admin runs:)
curl -X POST http://localhost:8765/admin/users/USER_ID/reset-key \
  -H "Authorization: Bearer $CEMS_ADMIN_KEY"

Connection timeout

Symptoms: Connection timed out or Connection refused Causes:

Server not running
Firewall blocking port
Wrong API URL

Fix:

Local Server
Remote Server

# Check server is running
docker compose ps
# Should show cems-server on port 8765

# If not running:
docker compose up -d

# Check logs
docker compose logs cems-server

# Test direct connection
curl http://localhost:8765/health

# Check firewall
sudo ufw status
# Port 8765 should be open

# Test from local machine
curl https://cems.example.com/health

# If fails, check reverse proxy (nginx/caddy)
# Check SSL certificate
# Check DNS resolution

Hook Issues

Skills not appearing

Symptoms: /recall and /remember skills don’t show in IDE Fix for each IDE:

Claude Code
Cursor
Codex

Verify files exist:

ls ~/.claude/skills/cems/
# Should show: recall.md, remember.md, share.md, etc.

Check settings.json:

cat ~/.claude/settings.json | grep cems
# Should show hooks and skills config

Re-install skills:
```
cems setup --claude
```
Restart Claude Code: Close and reopen Claude Code application
Test manually: Type / in chat - should see /recall, /remember, etc.

Verify files exist:

ls ~/.cursor/skills/
# Should show: cems-recall/, cems-remember/, etc.

Check MCP config:

cat ~/.cursor/mcp.json
# Should show CEMS MCP server config

Re-install:
```
cems setup --cursor
```
Restart Cursor

Verify files exist:

ls ~/.codex/commands/
# Should show: recall.md, remember.md
ls ~/.codex/skills/
# Should show: recall/, remember/

Check MCP config:
```
cat ~/.codex/config.toml | grep cems
```
Re-install:
```
cems setup --codex
```

Hook execution fails

Symptoms: Hook runs but returns error Debug:

# Test hook directly (Claude Code)
echo '{"prompt": "what is my Python version?"}' | \
  uv run ~/.claude/hooks/cems_user_prompts_submit.py

# Check Python environment
uv python --version

# Check dependencies
uv pip list | grep cems

# Re-install CEMS package
uv tool install --force cems

# Check hook logs
# Claude Code: Output panel → CEMS
# Cursor: Developer Tools → Console

Common errors:

ModuleNotFoundError: No module named 'cems'

Cause: CEMS package not installed in Python environmentFix:

uv tool install --force cems

JSONDecodeError: Expecting value

Cause: Hook returned invalid JSONFix: Check hook output:

~/.claude/hooks/cems_user_prompts_submit.py <<< '{"prompt":"test"}' 2>&1

Look for print statements or errors before JSON output.

ConnectionError: Failed to connect to API

Cause: CEMS server unreachable from hookFix:

Check credentials file exists: cat ~/.cems/credentials
Test connection: cems health
Check network/firewall

Search Issues

Poor search results

Symptoms: Relevant memories not returned or irrelevant results returned Diagnosis:

Check if memories exist

cems list | grep "keyword"

If missing, memories weren’t stored. Check:

/remember skill works: cems add "test memory"
Observer daemon running (for automatic extraction)

Test with raw mode

cems search "your query" --raw

Raw mode bypasses relevance filtering. If results appear:

Memories exist but filtered out (score too low)
Adjust threshold or use hybrid mode

Try hybrid mode

cems search "your query" --mode hybrid

Hybrid mode uses:

Query synthesis (2-5 expanded queries)
HyDE (hypothetical document embeddings)
RRF fusion (combines vector + full-text)
Better for complex/semantic queries

Check scoring adjustments

Recent memories score higher (time decay). Check last access:

cems list --sort last_accessed

Pin important memories:

cems pin <memory_id>

Search returns empty

Symptoms: cems search returns [] even though memories exist Causes:

No embeddings generated

Symptom: cems list shows memories but search returns emptyCause: Embeddings not generated (API key issue or embedder failure)Fix:

Check OpenRouter API key:

docker compose logs cems-server | grep OPENROUTER

Re-index memories:
```
cems maintenance --job reindex
```

Check embedding backend config:

docker compose logs cems-server | grep embedding

Scope mismatch

Symptom: Memories stored in personal but searching sharedFix:

# Search both scopes
cems search "query" --scope both

# Or check which scope memories are in:
cems list | grep scope

Project filter too strict

Symptom: Searching with --project returns emptyCause: Memories not tagged with projectFix:

Search without project filter:
```
cems search "query"  # no --project
```
Check memory source_ref:
```
cems list | grep source_ref
```

Disable project penalty:

export CEMS_ENABLE_PROJECT_PENALTY=false
cems search "query"

Query synthesis fails

Symptoms: Hybrid mode falls back to vector mode Cause: LLM API error or timeout Debug:

# Check server logs
docker compose logs cems-server | grep "query synthesis"

# Common errors:
# - OpenRouter API key invalid
# - Rate limit exceeded
# - Model unavailable

# Fix: Check OpenRouter dashboard
# https://openrouter.ai/activity

# Test LLM manually:
curl https://openrouter.ai/api/v1/chat/completions \
  -H "Authorization: Bearer $OPENROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4o-mini",
    "messages": [{"role": "user", "content": "test"}]
  }'

Server Issues

Docker container won’t start

Symptoms: docker compose up -d fails or containers crash Debug:

# Check container status
docker compose ps

# Check logs for errors
docker compose logs cems-server
docker compose logs postgres
docker compose logs cems-mcp

# Common issues:

Port already in use

Error: Error starting userland proxy: listen tcp4 0.0.0.0:8765: bind: address already in useFix:

# Find process using port
sudo lsof -i :8765

# Kill process or change port in docker-compose.yml:
ports:
  - "8766:8765"  # Map host 8766 to container 8765

Missing environment variables

Error: OPENROUTER_API_KEY is requiredFix:

# Check .env file exists
cat .env

# If missing:
cp .env.example .env
nano .env  # Add OPENROUTER_API_KEY

# Restart
docker compose down
docker compose up -d

Database connection failed

Error: could not connect to server: Connection refusedFix:

# Check postgres is running
docker compose ps postgres

# If not running:
docker compose up -d postgres

# Check logs
docker compose logs postgres

# Wait for postgres to be ready (can take 10-30 seconds)
docker compose logs -f postgres | grep "ready to accept connections"

# Then restart cems-server
docker compose restart cems-server

Database migration issues

Symptoms: Server starts but API returns errors about missing tables Fix:

# Check if migrations ran
docker compose logs cems-server | grep migration

# Run migrations manually
docker compose exec cems-server python -m cems.db.migrate

# If fails, check database connection:
docker compose exec postgres psql -U cems -d cems -c '\dt'
# Should show tables: users, teams, memory_documents, memory_chunks, etc.

Maintenance Issues

Consolidation merging too aggressively

Symptoms: Distinct memories being merged into one Cause: Deduplication threshold too low Fix:

# Increase thresholds (more conservative)
export CEMS_DEDUP_AUTOMERGE_THRESHOLD=0.99  # Default 0.98
export CEMS_DEDUP_LLM_THRESHOLD=0.85        # Default 0.80

# Restart server
docker compose restart cems-server

# Test with manual consolidation
cems maintenance --job consolidation --limit 100

# Check logs for merge decisions
docker compose logs cems-server | grep "Auto-merging\|LLM merge"

Re-indexing takes too long

Symptoms: Monthly re-indexing job runs for hours Cause: Too many memories or slow embedding API Fix:

# Run in batches
cems maintenance --job reindex --limit 1000 --offset 0
cems maintenance --job reindex --limit 1000 --offset 1000
# etc.

# Or increase timeout
export CEMS_LLAMACPP_TIMEOUT_SECONDS=120  # Default 60

# Or switch to faster embedding backend
export CEMS_EMBEDDING_BACKEND=llamacpp_server  # Local, faster
# Requires llama.cpp server running - see deployment docs

Observation reflection producing bad summaries

Symptoms: Reflected observations lose important details Cause: LLM over-compressing or hallucinating Fix:

# Increase MIN_OBSERVATIONS_THRESHOLD (less frequent reflection)
# Edit src/cems/maintenance/observation_reflector.py:
MIN_OBSERVATIONS_THRESHOLD = 20  # Default 10

# Or change LLM model to more capable one
export CEMS_LLM_MODEL=anthropic/claude-3.5-sonnet  # Default gpt-4o-mini

# Rebuild and restart
docker compose build cems-server
docker compose up -d cems-server

Performance Issues

Slow search queries

Symptoms: Search takes >5 seconds Causes:

Too many LLM calls (hybrid mode)
Large memory corpus
Slow embedding API

Fix:

Use Vector Mode
Reduce Token Budget
Optimize Database

# Disable query synthesis and HyDE
cems search "query" --mode vector

# Or via API:
curl -X POST http://localhost:8765/api/memory/search \
  -d '{"query": "...", "enable_query_synthesis": false}'

# Lower max_tokens to reduce assembly time
cems search "query" --max-tokens 1000  # Default 2000

# Run VACUUM ANALYZE on postgres
docker compose exec postgres psql -U cems -d cems -c 'VACUUM ANALYZE;'

# Rebuild HNSW index
docker compose exec postgres psql -U cems -d cems -c '
  REINDEX INDEX memory_chunks_embedding_idx;
'

High memory usage

Symptoms: Server OOM killed or using >4GB RAM Cause: Large batch operations or memory leaks Fix:

# Reduce batch sizes
export CEMS_EMBEDDING_BATCH_SIZE=50  # Default 100

# Limit consolidation scope
cems maintenance --job consolidation --limit 1000

# Restart server periodically
docker compose restart cems-server

# Check for memory leaks
docker stats cems-server

Getting Help

GitHub Issues

Report bugs or request features

Logs

Always include logs when reporting issues:

docker compose logs cems-server > cems-server.log
docker compose logs cems-mcp > cems-mcp.log
docker compose logs postgres > postgres.log

Debug Mode

Enable debug logging:

# In .env
CEMS_DEBUG_MODE=true

# Restart
docker compose restart cems-server

# Watch logs
docker compose logs -f cems-server

Collect Diagnostic Info

# System info
cems --version
cems status

# Server health
curl http://localhost:8765/health
curl http://localhost:8766/health

# Database status
docker compose exec postgres psql -U cems -d cems -c '
  SELECT COUNT(*) FROM memory_documents;
  SELECT COUNT(*) FROM memory_chunks;
  SELECT COUNT(*) FROM users;
'

# Recent logs
docker compose logs --tail 100 cems-server

Get Started

Core Concepts

IDE Integration

Using CEMS

Server Deployment

Advanced

​Quick Diagnostics

​Installation Issues

​CEMS CLI not found

​Installation script fails

​Connection Issues

​Memory not being recalled

​401 Unauthorized

​Connection timeout

​Hook Issues

​Skills not appearing

​Hook execution fails

​Search Issues

​Poor search results

​Search returns empty

​Query synthesis fails

​Server Issues

​Docker container won’t start

​Database migration issues

​Maintenance Issues

​Consolidation merging too aggressively

​Re-indexing takes too long

​Observation reflection producing bad summaries

​Performance Issues

​Slow search queries

​High memory usage

​Getting Help

GitHub Issues

Logs

​Debug Mode

​Collect Diagnostic Info

​Next Steps

Maintenance

Retrieval Tuning

Build docs developers (and LLMs) love

Quick Diagnostics

Installation Issues

CEMS CLI not found

Installation script fails

Connection Issues

Memory not being recalled

401 Unauthorized

Connection timeout

Hook Issues

Skills not appearing

Hook execution fails

Search Issues

Poor search results

Search returns empty

Query synthesis fails

Server Issues

Docker container won’t start

Database migration issues

Maintenance Issues

Consolidation merging too aggressively

Re-indexing takes too long

Observation reflection producing bad summaries

Performance Issues

Slow search queries

High memory usage

Getting Help

Debug Mode

Collect Diagnostic Info

Next Steps