← Elara Core START TOOLS ARCH STORY PLAY PERSONAS FAQ 🔍

// FAQ & TROUBLESHOOTING

Common issues, fixes, and answers. Check here before filing an issue.

[ SETUP ]
Installation and initial configuration issues.
ChromaDB won't install

ChromaDB requires C++ build tools for its native extensions. On most systems, the error looks like Failed building wheel for chroma-hnswlib.

Fix: Install the build dependencies for your OS, then retry with no cache:

# Ubuntu/Debian
sudo apt install build-essential

# macOS
xcode-select --install

# Then install with no cache
pip install chromadb --no-cache-dir
WSL users: Make sure you're installing inside WSL, not in Windows PowerShell. Run which python to confirm.
Python version mismatch

Elara Core requires Python 3.10 or higher. Older versions will fail during install or at runtime with syntax errors.

# Check your version
python --version

# If it shows 3.9 or lower, upgrade:
sudo apt install python3.10 python3.10-venv

# Or use pyenv:
pyenv install 3.10
pyenv global 3.10
Tip: On some systems, python3 points to 3.10+ while python points to 2.x or 3.8. Try python3 --version first.
Permission denied on data directory

By default, Elara stores data in ~/.elara/. If you see permission errors, the directory may have been created by a different user or with restricted permissions.

# Fix permissions on the default directory
chmod -R u+rw ~/.elara/

# Or use a custom location instead
export ELARA_DATA_DIR="/path/to/your/data"
elara init

To make the custom path permanent, add the export line to your ~/.bashrc or ~/.zshrc.

MCP client can't find the server

This usually means the elara command isn't in your shell's PATH, or the config file points to the wrong location.

# Verify elara is installed and findable
which elara

# If nothing shows, find where pip installed it
pip show elara-core | grep Location

# Test the server directly
elara serve

If which elara returns nothing, the install directory isn't in PATH. Common fix:

# Add pip's bin directory to PATH
export PATH="$HOME/.local/bin:$PATH"
Cursor/Windsurf: These editors may use a different shell environment. Use the full absolute path to elara in your MCP config if the short name doesn't work.
[ RUNTIME ]
Things that go wrong while Elara is running.
Tools not showing up in my editor

If the server starts but your MCP client shows zero tools, try these steps in order:

1. Restart your MCP client completely (not just reload).

2. Check server logs for errors:

# Run the server manually and watch output
elara serve 2>&1 | head -50

3. Verify the config file path matches where Elara is actually installed.

4. Some clients cache tool lists. Delete the MCP cache and restart.

Claude Code: Run claude mcp list to verify the server is registered. If it shows "elara" but no tools, the server is crashing on startup — check the logs.
Memory search returns nothing

Semantic search relies on ChromaDB vector indexes. If they're empty or corrupted, searches return no results.

# Rebuild all indexes from source data
elara_rebuild_indexes()

# Or rebuild a specific collection
elara_rebuild_indexes(collection="memories")

You can also check index health by calling elara_status() — it reports memory counts per collection. If counts are zero but you know you've saved memories, a rebuild will fix it.

After migration: If you moved your data directory or upgraded Elara, always run a rebuild. The ChromaDB files may not be portable across different machines or Python versions.
Mood stuck at default values

If elara_mood() always returns the same baseline values, check two things:

1. Verify the persona file exists in your data directory:

ls ~/.elara/persona*

# If missing, reinitialize
elara init

2. Confirm the mood module loaded. Call elara_status() and look for "mood" in the output. If it's missing, the module failed to import — check server logs for errors.

Mood adjusts via elara_mood_adjust(). If you've never called it or set a mode, values will remain at defaults. Try elara_mode(mode="dev") to set a preset.

Gmail tools failing

Gmail integration requires OAuth2 authentication. If you see "credentials not found" or "token expired" errors:

# Run the OAuth flow (opens browser)
elara_gmail(action="auth")

# After auth, test with:
elara_gmail(action="inbox", n=3)

You need a Google Cloud project with the Gmail API enabled and OAuth credentials configured. The token is stored in your Elara data directory and refreshes automatically — but if it expires after 7 days (test mode), re-run the auth flow.

Google Cloud console: If you're using a "Testing" publishing status, tokens expire in 7 days. Set your app to "Production" (internal use is fine) for persistent tokens.
Dreams not running automatically

Dreams (weekly/monthly pattern analysis) don't run on a timer by default. They need to be triggered.

Option 1: Manual trigger

# Run weekly dream analysis
elara_dream(dream_type="weekly")

# Check if any dreams are overdue
elara_dream_info(action="status")

Option 2: Cron job (for automatic scheduling)

# Run weekly dreams every Sunday at 3 AM
0 3 * * 0 elara dream --type weekly

# Run monthly dreams on the 1st at 4 AM
0 4 1 * * elara dream --type monthly

Use elara_dream_info(action="read", dream_type="weekly") to read the latest report.

[ DATA ]
Managing, backing up, and resetting your data.
Where is my data stored?

By default, everything lives in ~/.elara/. This includes:

~/.elara/
├― memories.jsonl # semantic memories
├― corrections.json # learned corrections
├― episodes/ # episodic session data
├― reasoning/ # reasoning trails
├― chroma/ # vector index database
├― dreams/ # dream reports
├― handoff.json # session continuity
└― persona.json # mood & temperament

Override the location by setting ELARA_DATA_DIR:

export ELARA_DATA_DIR="/custom/path"
How do I back up my data?

Copy the entire data directory. ChromaDB stores everything as local files, so a simple copy works.

# Full backup
cp -r ~/.elara/ ~/.elara-backup-$(date +%Y%m%d)

# Or tar it up
tar czf elara-backup-$(date +%Y%m%d).tar.gz ~/.elara/
Tip: The JSON/JSONL source files are the ground truth. ChromaDB indexes can always be rebuilt from them using elara_rebuild_indexes(). If space is tight, you can skip backing up the chroma/ directory.
How do I reset everything?

Delete the data directory and reinitialize. This is a clean slate — all memories, episodes, corrections, and mood history will be gone.

# Nuclear option — back up first if unsure
rm -rf ~/.elara/
elara init
This is irreversible. Consider backing up first. There is no undo.
Can I use multiple personas?

Yes. Point different sessions at different persona files using the ELARA_PERSONA_FILE environment variable.

# Work persona
export ELARA_PERSONA_FILE="~/.elara/persona-work.json"

# Personal persona
export ELARA_PERSONA_FILE="~/.elara/persona-personal.json"

Each persona file tracks its own mood, temperament, and imprints independently. Memory and episodes are shared unless you also change ELARA_DATA_DIR.

For fully isolated instances, set both variables to different paths.

[ COMPATIBILITY ]
Client-specific notes and known issues.
MCP client compatibility matrix
Client Notes
Claude Code Best supported. Use claude mcp add elara -- elara serve. All 34 tools auto-discovered. Supports streaming and parallel tool calls.
Cursor Works via .cursor/mcp.json. Some users report needing to restart twice on first setup. Check the MCP panel for connection status.
Windsurf Config goes in ~/.codeium/windsurf/mcp_config.json. Tools appear in the Cascade panel. May need the full path to the elara binary.
Cline VS Code extension. Add via Cline Settings → MCP Servers. Auto-detects all tools. Requires the Cline extension v2.0+.
General rule: If your client supports MCP servers via stdio transport, Elara will work. The config is always the same: command elara, args ["serve"].
- - - - - - - - [ STILL STUCK? ] - - - - - - - -

Can't find your answer?

Open an issue on GitHub with your OS, Python version, and the full error message.

Open an Issue →