2.6 KiB

Raw Blame History

Handoff: `.env.example` Update Required Before Merge

The Claude harness cannot write .env.example (the path is protected by the pre_tool_env_guard.sh hook). Apply the following change manually before merging this branch.

What to change

.env.example currently presents the local-Ollama embedder block as a commented-out option. After this change it must present the same block uncommented (as the active default), with OpenAI and Gemini examples preserved beneath as commented fallback blocks.

This must line up with backend/app/config.py's new defaults (mxbai-embed-large, http://localhost:11434/v1, ollama) so that operators copying .env.example to .env see the same values the backend falls back to when those keys are unset.

Required block

Replace whatever currently lives in .env.example's "Embedding" section with the block below. Keep the surrounding sections (LLM, Neo4j, optional LLM_BOOST, ZEP_API_KEY) untouched.

# Embeddings — default: local Ollama, free, no API key, OpenAI-compatible
# endpoint. Pre-requisite: `ollama pull mxbai-embed-large` (1024-dim, matches
# Graphiti). In Docker, the container reaches the host daemon via
# host.docker.internal:11434 (see docker-compose.yml); in host mode
# (`npm run dev`), keep http://localhost:11434/v1 as below.
EMBEDDING_BASE_URL=http://localhost:11434/v1
EMBEDDING_API_KEY=ollama
EMBEDDING_MODEL=mxbai-embed-large

# Embeddings — remote fallback (uncomment ONE block if you prefer not to run
# Ollama locally). Note: any override must produce 1024-dim vectors to match
# Graphiti's vector index — 768-dim models (e.g. nomic-embed-text) are NOT
# supported.
#
# OpenAI:
# EMBEDDING_BASE_URL=https://api.openai.com/v1
# EMBEDDING_API_KEY=your_openai_api_key
# EMBEDDING_MODEL=text-embedding-3-small
#
# Gemini (also set GRAPHITI_LLM_PROVIDER=gemini):
# EMBEDDING_MODEL=gemini-embedding-001

Consistency check

After applying, confirm:

EMBEDDING_MODEL=mxbai-embed-large matches Config.EMBEDDING_MODEL default in backend/app/config.py.
EMBEDDING_BASE_URL=http://localhost:11434/v1 matches Config.EMBEDDING_BASE_URL default.
EMBEDDING_API_KEY=ollama matches Config.EMBEDDING_API_KEY default.
The README's env block (the one inside README.md) shows the same uncommented default values and the same commented OpenAI/Gemini fallbacks.

Why this is not auto-applied

.env.example lives in the project root and matches the pre_tool_env_guard.sh blocklist for env / secrets paths. The guard is deliberately broad (any .env* filename) to prevent accidental writes to real secret files. The fix is one-line manual application; do not weaken the guard.

2.6 KiB Raw Blame History

Handoff: .env.example Update Required Before Merge