Graphiti's default cross-encoder hard-codes the OpenAI gpt-4.1-nano model
and depends on OpenAI-specific logprobs/logit_bias, so the adapter has
been injecting a no-op _PassthroughReranker just to keep search code
paths working. Search results consumed by SearchResult, InsightForge,
Panorama, and Interview were therefore returned in Graphiti's RRF order
with no real reranking signal.
Add an Ollama-backed CrossEncoderClient that scores passages through a
local chat model via the OpenAI-compatible /v1 surface and wire it into
_get_graphiti() behind a RERANKER_PROVIDER switch (default: ollama).
Construction is side-effect-free and the rank() method never raises:
per-passage parse failures degrade to a deterministic low score, and a
whole-call failure falls back to passthrough order with a single WARNING
log so Flask keeps serving when Ollama is unreachable. Setting
RERANKER_PROVIDER=none preserves the legacy passthrough for CI and slim
containers that cannot pull the model.
Closes#39
Two coupled changes that together restore non-empty post-migration graph
builds and remove the silent "succeeded but empty" outcome.
Root cause: Config defaulted EMBEDDING_MODEL to OpenAI text-embedding-3-small
(1536 dim), but Graphiti's Neo4j vector index is 1024 dim. With the
documented Dashscope LLM default, EMBEDDING_API_KEY/EMBEDDING_BASE_URL
fell back to LLM_*, producing either a 4xx (since #29 propagates as
Task.FAILED) or a write that landed metadata but no entities.
Changes:
- Flip Config defaults to local Ollama (mxbai-embed-large, 1024 dim,
http://localhost:11434/v1). Override semantics unchanged: explicit
EMBEDDING_* env vars continue to win, so existing OpenAI/Gemini setups
are not affected.
- Gate _build_graph_worker on a non-zero entity-node count before
complete_task. Mirrors the existing _recover_stuck_projects rule;
surfaces any residual silent failure as Task.FAILED with the new
progress.emptyGraphFailure locale key, instead of marking the project
GRAPH_COMPLETED on an empty graph.
- Update README, CLAUDE.md, and docker-compose.yml comments to reflect
Ollama as the active default and OpenAI/Gemini as commented fallbacks.
- The matching .env.example diff is recorded in
.kiro/specs/graph-build-empty-fix/HANDOFF.md for manual operator apply
(file is hook-protected from the assistant).
Spec: .kiro/specs/graph-build-empty-fix/
Closes#37
Replace the silent placeholder-UUID fallback in
_GraphNamespace.add_batch with logger.exception(...) + raise so
embedder misconfiguration (404 unknown model, connection refused, etc.)
fails the surrounding graph-build Task with a visible error instead of
producing a Task that looks completed while the graph stays empty.
Document the existing-but-undocumented Ollama embedder configuration
in .env.example, CLAUDE.md, README.md, and docker-compose.yml.
mxbai-embed-large is the recommended local model because its 1024-dim
output matches Graphiti's default EMBEDDING_DIM. Adds a curl smoke
test to verify embedder reachability before the first graph build.
No new env var or provider literal: Ollama is reached through the
existing openai-provider branch by setting EMBEDDING_BASE_URL,
EMBEDDING_API_KEY, and EMBEDDING_MODEL.
Closes#18
Bring repo docs in line with the Graphiti+Neo4j migration and prepare
the codebase for Spec-Driven Development.
CLAUDE.md:
- Promote Neo4j + Graphiti to primary memory/graph layer; mark Zep
Cloud as deprecated / compat-only.
- Document the full env-var surface: NEO4J_*, EMBEDDING_MODEL, optional
LLM_BOOST_* block.
- Codify must-respect implementation rules (Task model for long ops,
reasoning-output stripping, simulation IPC, subprocess cleanup,
startup recovery, per-project group_id isolation, chat prefix
injection).
- Note i18n (vue-i18n + /locales/) and Docker prerequisite for dev.
README.md / README-EN.md / README-ZH.md:
- Resolve unresolved merge-conflict markers in README.md left over from
the feat/graphiti-neo4j-migration merge (file was broken Markdown).
- Lead with Docker as the recommended deployment path; keep source
install as a documented alternative.
- Replace Zep env vars with NEO4J_URI / NEO4J_USER / NEO4J_PASSWORD /
EMBEDDING_MODEL across all three READMEs.
- Add optional LLM_BOOST_* block with omit-if-unused note.
- Fix language-switcher links between the three READMEs.
.claude/onboarding/step1_codebase/:
- Document repo analysis, CLAUDE.md conventions decisions, and README
resolution choices.
Replaces the paid, rate-limited Zep Cloud service with Graphiti (graphiti-core
0.11.6) backed by a local Neo4j instance — free, unlimited, and self-hosted.
Key changes:
- Add GraphitiAdapter: drop-in Zep-compatible wrapper around Graphiti with a
persistent event-loop thread to avoid asyncio/Neo4j driver conflicts
- Switch LLM client to native GeminiClient + GeminiEmbedder (text-embedding-004
fails on Gemini compat endpoint; use google-genai SDK directly)
- Add _GeminiReranker passthrough replacing OpenAIRerankerClient (which
hardcodes gpt-4.1-nano and uses logprobs unsupported by Gemini)
- Fix Cypher queries: use s.uuid/t.uuid for edge source/target instead of
r.source_node_uuid (null property in Graphiti's schema)
- Add ontology-based entity type classifier (_classify_entity_type) so nodes
get colored by type in the D3 graph visualization instead of all being Entity
- Apply classifier in ZepEntityReader so filter_defined_entities finds entities
(previously 0 personas loaded because all labels were ['Entity'])
- Add startup recovery: auto-mark graph_building projects as graph_completed
on backend restart if Neo4j already has their data
- Add resume capability to graph build: skip already-processed episodes after
a restart (断点续传)
- Add non-blocking graph data cache with background refresh in graph.py
- Add EMBEDDING_MODEL config (default: gemini-embedding-001 for Gemini users)
- Add CLAUDE.md with project architecture and dev commands
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Dominik Seemann
Dominik Seemann
Abhishek Yadav