69 lines
2.6 KiB
Markdown
69 lines
2.6 KiB
Markdown
# 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.
|
|
|
|
```env
|
|
# 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.
|