Convert all issue numbers to GitHub links

- Converted bare issue numbers to proper markdown links - Format: [#123](https://github.com/getzep/graphiti/issues/123) - Applied to all three triage documents - Makes issues clickable in GitHub web interface
Add comprehensive issue triage documentation
2025-10-07 09:23:55 -07:00 · 2025-10-07 09:19:26 -07:00
3 changed files with 800 additions and 0 deletions
--- a/DUPLICATES.md
+++ b/DUPLICATES.md
@ -0,0 +1,156 @@
+# Duplicate GitHub Issues
+
+**Date**: 2025-10-07
+
+## Confirmed Duplicates (Already Marked)
+
+### [#963](https://github.com/getzep/graphiti/issues/963) - Duplicate Entities in Neo4j
+- **Status**: Marked as duplicate
+- **Original Issue**: [#875](https://github.com/getzep/graphiti/issues/875) - Duplicate Entities in Neo4j with custom db name
+- **Labels**: bug, duplicate
+- **Action**: Can be closed with reference to [#875](https://github.com/getzep/graphiti/issues/875)
+- **Notes**: Same core issue - deduplication not working properly
+
+---
+
+### [#941](https://github.com/getzep/graphiti/issues/941) - TaskGroup Errors
+- **Title**: ERROR：unhandled errors in a TaskGroup (1 sub-exception)
+- **Status**: Marked as duplicate
+- **Labels**: duplicate
+- **Notes**: Reporter mentioned issue was previously reported in [#353](https://github.com/getzep/graphiti/issues/353)
+- **Action**: Close with reference to original issue
+
+---
+
+### [#920](https://github.com/getzep/graphiti/issues/920) - Timezone-Naive/Aware Datetime Comparison
+- **Title**: [BUG] edge_operations.py is unable to compare a timezone-naive datetime with a timezone-aware one
+- **Status**: Marked as duplicate
+- **Labels**: bug, duplicate
+- **Original Issue**: Likely resolved by commit 73015e9 "Fix datetime comparison errors by normalizing to UTC"
+- **Action**: Close with reference to recent fix. Ask reporter to verify on latest version.
+
+---
+
+### [#867](https://github.com/getzep/graphiti/issues/867) - MCP with GPT-oss Models
+- **Title**: MPC does not work with GPT-oss:20 or 120B
+- **Status**: Marked as duplicate
+- **Duplicate Of**: [#831](https://github.com/getzep/graphiti/issues/831) - [BUG] GPT-oss:20 and 120
+- **Labels**: bug, duplicate
+- **Action**: Close with reference to [#831](https://github.com/getzep/graphiti/issues/831)
+
+---
+
+### [#801](https://github.com/getzep/graphiti/issues/801) - Empty Fulltext Search Results
+- **Title**: [BUG] empty-result bug in episode_fulltext_search
+- **Status**: Marked as duplicate
+- **Labels**: bug, duplicate
+- **Original Issue**: Likely [#810](https://github.com/getzep/graphiti/issues/810) - Empty group_id handling issues
+- **Action**: Close with reference to [#810](https://github.com/getzep/graphiti/issues/810) or related search issue
+
+---
+
+### [#787](https://github.com/getzep/graphiti/issues/787) - Rate Limit with SEMAPHORE_LIMIT
+- **Title**: [BUG] Got rate limit even SEMAPHORE_LIMIT=1 in mcp server
+- **Status**: Marked as duplicate
+- **Labels**: bug, duplicate
+- **Action**: Close with reference to original rate limiting issue
+
+---
+
+## Potential Duplicates (Require Investigation)
+
+### Database Configuration Issues (Likely Related)
+
+[#851](https://github.com/getzep/graphiti/issues/851), [#798](https://github.com/getzep/graphiti/issues/798), [#715](https://github.com/getzep/graphiti/issues/715) - All relate to database name handling
+- [#851](https://github.com/getzep/graphiti/issues/851) - Search only connects to 'neo4j' db
+- [#798](https://github.com/getzep/graphiti/issues/798) - Database name not passed through Graphiti object
+- [#715](https://github.com/getzep/graphiti/issues/715) - Feature request to configure Neo4j database name
+
+**Analysis**: These may be describing the same underlying issue. [#715](https://github.com/getzep/graphiti/issues/715) appears to be the feature request, while [#851](https://github.com/getzep/graphiti/issues/851) and [#798](https://github.com/getzep/graphiti/issues/798) are bugs from the missing feature.
+
+**Recommendation**: Fix the root cause and consolidate. Keep [#715](https://github.com/getzep/graphiti/issues/715) as the tracking issue if implementing multi-DB support properly.
+
+---
+
+### Bulk Upload Failures
+
+[#882](https://github.com/getzep/graphiti/issues/882), [#879](https://github.com/getzep/graphiti/issues/879), [#871](https://github.com/getzep/graphiti/issues/871), [#658](https://github.com/getzep/graphiti/issues/658) - Bulk upload failures
+- [#882](https://github.com/getzep/graphiti/issues/882) - IndexError during node resolution
+- [#879](https://github.com/getzep/graphiti/issues/879) - ValidationError 'duplicates' field missing
+- [#871](https://github.com/getzep/graphiti/issues/871) - Invalid JSON and index errors
+- [#658](https://github.com/getzep/graphiti/issues/658) - "Bulk ingestion not possible"
+
+**Analysis**: All appear to be bulk upload failures, potentially from same root cause in validation/schema handling.
+
+**Recommendation**: Investigate if these are manifestations of same bug. If so, consolidate into single issue.
+
+---
+
+### FalkorDB Query Errors
+
+[#815](https://github.com/getzep/graphiti/issues/815), [#757](https://github.com/getzep/graphiti/issues/757), [#731](https://github.com/getzep/graphiti/issues/731) - FalkorDB query errors
+- [#815](https://github.com/getzep/graphiti/issues/815) - falkordb query error
+- [#757](https://github.com/getzep/graphiti/issues/757) - quickstart_falkordb example query error
+- [#731](https://github.com/getzep/graphiti/issues/731) - Malformed Cypher query on episode insertion
+
+**Analysis**: May be same underlying issue with FalkorDB Cypher query generation.
+
+**Recommendation**: Investigate if root cause is same. Could consolidate.
+
+---
+
+### MCP Server + Custom LLM Providers
+
+[#565](https://github.com/getzep/graphiti/issues/565), [#945](https://github.com/getzep/graphiti/issues/945) - OPENAI_BASE_URL issues
+- [#565](https://github.com/getzep/graphiti/issues/565) - Cross-encoder ignores OPENAI_BASE_URL
+- [#945](https://github.com/getzep/graphiti/issues/945) - Custom OPENAI_BASE_URL causes NaN embeddings
+
+**Analysis**: Both relate to custom OpenAI-compatible endpoints not being respected in MCP server.
+
+**Recommendation**: Likely same root issue - configuration not properly passed through MCP components.
+
+---
+
+### Ollama Compatibility
+
+[#868](https://github.com/getzep/graphiti/issues/868), [#831](https://github.com/getzep/graphiti/issues/831) - Ollama issues
+- [#868](https://github.com/getzep/graphiti/issues/868) - Cannot get minimal example to work with Ollama
+- [#831](https://github.com/getzep/graphiti/issues/831) - GPT-oss:20 and 120 (Ollama models)
+
+**Analysis**: Both relate to Ollama model compatibility issues.
+
+---
+
+### Search Result Issues
+
+[#534](https://github.com/getzep/graphiti/issues/534), [#801](https://github.com/getzep/graphiti/issues/801), [#810](https://github.com/getzep/graphiti/issues/810) - Search returning empty/no results
+- [#534](https://github.com/getzep/graphiti/issues/534) - retrieve_episodes always returns no results
+- [#801](https://github.com/getzep/graphiti/issues/801) - episode_fulltext_search empty results (marked duplicate)
+- [#810](https://github.com/getzep/graphiti/issues/810) - Empty group_id handled inconsistently
+
+**Analysis**: Likely all related to search filtering/group_id handling issues.
+
+---
+
+### Documentation/Setup Questions (Can Be Consolidated)
+
+[#517](https://github.com/getzep/graphiti/issues/517), [#530](https://github.com/getzep/graphiti/issues/530) - OpenRouter setup questions
+- [#517](https://github.com/getzep/graphiti/issues/517) - How to setup with OpenRouter and Voyage
+- [#530](https://github.com/getzep/graphiti/issues/530) - Does this work with Cursor AI + OpenRouter ChatGPT
+
+**Analysis**: Same topic - using OpenRouter as provider. Could close with documentation reference.
+
+---
+
+## Summary
+
+- **Confirmed Duplicates (Already Marked)**: 6 issues ready to close
+- **Potential Duplicate Clusters**: 7 clusters (20+ issues) requiring investigation
+- **Estimated Consolidation**: Could reduce issue count by 15-25 through deduplication
+
+## Recommended Actions
+
+1. **Immediate**: Close the 6 confirmed duplicates with appropriate references
+2. **Investigation**: Review potential duplicate clusters to confirm root causes
+3. **Consolidation**: Create tracking issues for clusters where multiple issues stem from same bug
+4. **Documentation**: Several "questions" can be closed once docs are updated
--- a/ISSUE_TRIAGE.md
+++ b/ISSUE_TRIAGE.md
@ -0,0 +1,361 @@
+# GitHub Issues Triage & Categorization
+
+**Date**: 2025-10-07
+**Total Open Issues**: 100+
+**Analysis Scope**: Issues [#451](https://github.com/getzep/graphiti/issues/451) - [#972](https://github.com/getzep/graphiti/issues/972)
+
+## Issue Clusters
+
+### 1. Database Driver Support
+
+#### FalkorDB Issues (6 issues)
+- [#972](https://github.com/getzep/graphiti/issues/972) - [BUG] Vector type mismatch in cosine distance operations
+  - *Component*: `component:database`
+  - *Status*: Open
+
+- [#815](https://github.com/getzep/graphiti/issues/815) - [BUG] falkordb query
+  - *Component*: `component:database`
+  - *Status*: Open
+
+- [#757](https://github.com/getzep/graphiti/issues/757) - [BUG] run quickstart_falkordb example, get query error
+  - *Component*: `component:database`
+  - *Status*: Open
+
+- [#749](https://github.com/getzep/graphiti/issues/749) - [BUG] Official Docker Image doesn't support FalkorDB
+  - *Component*: `component:database`, `component:mcp`
+  - *Status*: Open
+
+- [#731](https://github.com/getzep/graphiti/issues/731) - Episode insertion fails due to malformed Cypher query
+  - *Component*: `component:database`
+  - *Status*: Open
+
+- [#719](https://github.com/getzep/graphiti/issues/719) - FalkorDB support in MCP-Server
+  - *Component*: `component:mcp`, `component:database`
+  - *Status*: Open
+
+#### New Database Support Requests (6 issues)
+- [#947](https://github.com/getzep/graphiti/issues/947) - Apache AGE Graph DB support
+- [#933](https://github.com/getzep/graphiti/issues/933) - Support RDF
+- [#781](https://github.com/getzep/graphiti/issues/781) - More graph database support (NebulaGraph mentioned)
+- [#779](https://github.com/getzep/graphiti/issues/779) - Postgres with pgvector support
+- [#644](https://github.com/getzep/graphiti/issues/644) - AWS Neptune driver
+- [#643](https://github.com/getzep/graphiti/issues/643) - Kuzu driver support (may already be implemented?)
+- [#642](https://github.com/getzep/graphiti/issues/642) - MemGraph driver
+
+**Analysis**: FalkorDB has multiple critical bugs affecting basic operations. Consider deprecating or fixing comprehensively. High demand for alternative backends suggests need for driver abstraction layer.
+
+---
+
+### 2. MCP Server Issues (9 issues)
+
+- [#923](https://github.com/getzep/graphiti/issues/923) - [BUG] Switch from SSE (deprecated) to Streamable HTTP
+  - *Priority*: HIGH - using deprecated protocol
+  - *Component*: `component:mcp`
+
+- [#945](https://github.com/getzep/graphiti/issues/945) - [BUG] Custom OPENAI_BASE_URL causes NaN embeddings
+  - *Component*: `component:mcp`, `component:llm`
+
+- [#848](https://github.com/getzep/graphiti/issues/848) - [BUG] clear_graph tool fails silently (async session bug)
+  - *Component*: `component:mcp`
+
+- [#840](https://github.com/getzep/graphiti/issues/840) - [BUG] Failed to validate request (initialization timing)
+  - *Component*: `component:mcp`
+
+- [#723](https://github.com/getzep/graphiti/issues/723) - DEFAULT_MAX_TOKENS 8192 too restrictive
+  - *Component*: `component:mcp`
+
+- [#578](https://github.com/getzep/graphiti/issues/578) - MCP server with Gemini model
+  - *Component*: `component:mcp`, `component:llm`
+
+- [#565](https://github.com/getzep/graphiti/issues/565) - Cross-encoder ignores OPENAI_BASE_URL
+  - *Component*: `component:mcp`, `component:llm`
+
+- [#509](https://github.com/getzep/graphiti/issues/509) - MCP server add_nodes tool call doesn't work
+  - *Component*: `component:mcp`
+
+**Duplicates in this cluster**:
+- [#867](https://github.com/getzep/graphiti/issues/867) + [#831](https://github.com/getzep/graphiti/issues/831) - GPT-oss:20 and 120B models (duplicate)
+- [#787](https://github.com/getzep/graphiti/issues/787) - Rate limit even with SEMAPHORE_LIMIT=1 (marked duplicate)
+
+**Analysis**: MCP server has protocol deprecation issue ([#923](https://github.com/getzep/graphiti/issues/923)) and multiple configuration/provider issues. Should be high priority for users relying on MCP integration.
+
+---
+
+### 3. LLM Provider Compatibility (8 issues)
+
+- [#902](https://github.com/getzep/graphiti/issues/902) - [BUG] OpenAI internal call broken (reasoning.effort param)
+  - *Component*: `component:llm`
+
+- [#878](https://github.com/getzep/graphiti/issues/878) - [BUG] GPT-5 temperature parameter unsupported
+  - *Component*: `component:llm`
+
+- [#912](https://github.com/getzep/graphiti/issues/912) - [BUG] Pydantic validation error with deepseek-r1:7b
+  - *Component*: `component:llm`
+
+- [#791](https://github.com/getzep/graphiti/issues/791) - [BUG] Small model setting defaults to gpt-4.1-nano
+  - *Component*: `component:llm`
+
+- [#790](https://github.com/getzep/graphiti/issues/790) - [BUG] Failed to parse structured response with Gemini
+  - *Component*: `component:llm`
+
+- [#868](https://github.com/getzep/graphiti/issues/868) - [BUG] Cannot work with Ollama
+  - *Component*: `component:llm`
+
+- [#763](https://github.com/getzep/graphiti/issues/763) - [BUG] LLMConfig.max_tokens not respected
+  - *Component*: `component:llm`
+
+- [#760](https://github.com/getzep/graphiti/issues/760) - [BUG] Hallucinations with default models
+  - *Component*: `component:llm`
+
+**Additional LLM Provider Requests**:
+- [#907](https://github.com/getzep/graphiti/issues/907) - VSC Copilot models
+- [#751](https://github.com/getzep/graphiti/issues/751) - Alibaba Cloud AI model
+- [#724](https://github.com/getzep/graphiti/issues/724) - Gemini with Google Cloud Credentials
+- [#459](https://github.com/getzep/graphiti/issues/459) - Amazon Bedrock support
+
+**Analysis**: Structured output compatibility is a recurring theme. Many issues stem from providers not supporting OpenAI's structured output format. Documentation should clearly state which providers are fully compatible.
+
+---
+
+### 4. Duplicate Entities (3 issues)
+
+- [#963](https://github.com/getzep/graphiti/issues/963) - [BUG] Duplicate entities in Neo4j (marked duplicate)
+  - *Component*: `component:core`
+  - *Status*: Duplicate (see [#875](https://github.com/getzep/graphiti/issues/875))
+
+- [#875](https://github.com/getzep/graphiti/issues/875) - [BUG] Duplicate entities with custom db name
+  - *Component*: `component:core`, `component:database`
+  - *Priority*: HIGH - core deduplication functionality broken
+
+- [#774](https://github.com/getzep/graphiti/issues/774) - Same Chinese text extracted as different facts
+  - *Component*: `component:core`
+
+**Analysis**: Core deduplication functionality appears broken, especially with custom database names. Critical for production use.
+
+---
+
+### 5. Bulk Upload Issues (3 issues)
+
+- [#882](https://github.com/getzep/graphiti/issues/882) - [BUG] IndexError during node resolution
+  - *Component*: `component:bulk`
+
+- [#879](https://github.com/getzep/graphiti/issues/879) - ValidationError 'duplicates' field missing
+  - *Component*: `component:bulk`
+
+- [#871](https://github.com/getzep/graphiti/issues/871) - Invalid JSON and index errors
+  - *Component*: `component:bulk`
+
+**Related**:
+- [#747](https://github.com/getzep/graphiti/issues/747) - Add progress reporting to bulk upload
+- [#658](https://github.com/getzep/graphiti/issues/658) - Bulk ingestion not possible (may be duplicate)
+
+**Analysis**: Bulk operations are fundamentally broken. Appears to be schema/validation issues in the bulk processing pipeline.
+
+---
+
+### 6. Search Issues (6 issues)
+
+- [#810](https://github.com/getzep/graphiti/issues/810) - [BUG] Empty group_id handled inconsistently in search
+  - *Component*: `component:search`
+
+- [#801](https://github.com/getzep/graphiti/issues/801) - [BUG] episode_fulltext_search empty results (marked duplicate)
+  - *Component*: `component:search`
+
+- [#838](https://github.com/getzep/graphiti/issues/838) - Allow searching across all groups when group_ids is None
+  - *Component*: `component:search`
+
+- [#772](https://github.com/getzep/graphiti/issues/772) - [BUG] BFS max_depth parameter ignored
+  - *Component*: `component:search`
+
+- [#789](https://github.com/getzep/graphiti/issues/789) - [BUG] BFS returns duplicate edges with swapped source/target
+  - *Component*: `component:search`
+
+- [#777](https://github.com/getzep/graphiti/issues/777) - [BUG] MMR reranker RuntimeWarning, no results
+  - *Component*: `component:search`
+
+**Related**:
+- [#488](https://github.com/getzep/graphiti/issues/488) - edge_search_filter_query_constructor creating incorrect query
+- [#534](https://github.com/getzep/graphiti/issues/534) - retrieve_episodes always returns no results
+
+**Analysis**: Search functionality has multiple bugs in filtering, BFS traversal, and reranking. Group ID handling is particularly problematic.
+
+---
+
+### 7. Database Configuration (4 issues)
+
+- [#851](https://github.com/getzep/graphiti/issues/851) - [BUG] Search only connects to 'neo4j' db, add_episode works with any name
+  - *Component*: `component:database`
+  - *Priority*: HIGH - inconsistent behavior
+
+- [#798](https://github.com/getzep/graphiti/issues/798) - [BUG] Database name not passed through Graphiti object
+  - *Component*: `component:database`
+  - *Priority*: HIGH - related to [#851](https://github.com/getzep/graphiti/issues/851)
+
+- [#715](https://github.com/getzep/graphiti/issues/715) - [Feature] Configure Neo4j database name (multi-DB support)
+  - *Component*: `component:database`
+
+**Analysis**: Database name configuration is broken. Hardcoded 'neo4j' default causes issues. Related to commit mentioned in CLAUDE.md about hardcoded database names.
+
+---
+
+### 8. Datetime/Timezone Issues (4 issues)
+
+- [#920](https://github.com/getzep/graphiti/issues/920) - [BUG] edge_operations.py timezone-naive/aware comparison (marked duplicate)
+  - *Component*: `component:core`
+  - *Status*: Duplicate (possibly fixed in commit 73015e9)
+
+- [#893](https://github.com/getzep/graphiti/issues/893) - [BUG] Kuzu driver valid_at datetime format
+  - *Component*: `component:database`
+
+- [#606](https://github.com/getzep/graphiti/issues/606) - Add support for datetime fields in custom entities
+  - *Component*: `component:core`
+
+**Analysis**: Recent commit 73015e9 "Fix datetime comparison errors by normalizing to UTC" may have addressed some of these. Needs verification.
+
+---
+
+### 9. API/Server Issues (4 issues)
+
+- [#961](https://github.com/getzep/graphiti/issues/961) - [Feature Request] Improve Episodes API (UUID, GET by ID, metadata)
+  - *Component*: `component:server`
+
+- [#921](https://github.com/getzep/graphiti/issues/921) - SDK client like zep-cloud/zep-python
+  - *Component*: `component:server`
+
+- [#566](https://github.com/getzep/graphiti/issues/566) - /messages endpoint doesn't persist episodes
+  - *Component*: `component:server`
+
+- [#904](https://github.com/getzep/graphiti/issues/904) - docker-compose.yml env vars override .env
+  - *Component*: `component:server`, `component:mcp`
+
+**Analysis**: API functionality gaps and configuration issues. Episode persistence bug is critical.
+
+---
+
+### 10. Error Handling & Validation (3 issues)
+
+- [#941](https://github.com/getzep/graphiti/issues/941) - TaskGroup errors (marked duplicate)
+  - *Component*: `component:core`
+
+- [#937](https://github.com/getzep/graphiti/issues/937) - ArgumentError with empty query entities
+  - *Component*: `component:core`
+
+- [#951](https://github.com/getzep/graphiti/issues/951) - Incorrect try import for AsyncOpenSearch
+  - *Component*: `component:database`
+
+**Analysis**: Input validation needs improvement to handle edge cases like empty strings.
+
+---
+
+### 11. Feature Requests - Core Functionality (10 issues)
+
+- [#935](https://github.com/getzep/graphiti/issues/935) - Create episodes based on DOM structure
+- [#934](https://github.com/getzep/graphiti/issues/934) - Flag contradictions on merging facts
+- [#925](https://github.com/getzep/graphiti/issues/925) - Monitor LLM conversations
+- [#905](https://github.com/getzep/graphiti/issues/905) - ColbertV2 embeddings with Fastembed
+- [#864](https://github.com/getzep/graphiti/issues/864) - How to forget knowledge
+- [#819](https://github.com/getzep/graphiti/issues/819) - Count token usage
+- [#669](https://github.com/getzep/graphiti/issues/669) - Metadata on chunks for RAG
+- [#465](https://github.com/getzep/graphiti/issues/465) - Support ignoring non-custom entities
+- [#467](https://github.com/getzep/graphiti/issues/467) - LLM inference expenses are high
+
+**Analysis**: Feature requests range from observability (#925, #819) to advanced RAG features (#669, #905). Token cost reduction ([#467](https://github.com/getzep/graphiti/issues/467)) is recurring concern.
+
+---
+
+### 12. Documentation/Questions (9 issues)
+
+- [#913](https://github.com/getzep/graphiti/issues/913) - How to update data in graph
+- [#909](https://github.com/getzep/graphiti/issues/909) - Reproduce LongMemEval results
+- [#869](https://github.com/getzep/graphiti/issues/869) - Portuguese: Change OpenAI model
+- [#853](https://github.com/getzep/graphiti/issues/853) - Document VCS/extension setup
+- [#828](https://github.com/getzep/graphiti/issues/828) - Get a flowchart
+- [#701](https://github.com/getzep/graphiti/issues/701) - Chinese video tutorial (informational)
+- [#484](https://github.com/getzep/graphiti/issues/484) - OpenAIGenericClient documentation
+- [#530](https://github.com/getzep/graphiti/issues/530) - Cursor AI + OpenRouter setup
+- [#517](https://github.com/getzep/graphiti/issues/517) - OpenRouter and Voyage setup
+
+*Component*: `component:docs`
+
+**Analysis**: Many questions indicate documentation gaps, especially around custom LLM provider setup and basic operations.
+
+---
+
+### 13. Code Quality/Refactoring (5 issues)
+
+- [#836](https://github.com/getzep/graphiti/issues/836) - [BUG] update_communities broken
+  - *Component*: `component:core`
+
+- [#811](https://github.com/getzep/graphiti/issues/811) - Refactor: hoist EXTRACT_EDGES_MAX_TOKENS constant
+  - *Component*: `component:core`
+
+- [#681](https://github.com/getzep/graphiti/issues/681) - Refactor: no internal ghost variables
+  - *Component*: `component:core`
+
+- [#451](https://github.com/getzep/graphiti/issues/451) - Minor type bug in bulk_utils
+  - *Component*: `component:bulk`
+
+- [#717](https://github.com/getzep/graphiti/issues/717) - Adopt uv workspace for monorepo
+  - *Component*: `component:core`, `component:server`, `component:mcp`
+
+**Analysis**: Technical debt items. [#717](https://github.com/getzep/graphiti/issues/717) (uv workspace) would improve developer experience for monorepo.
+
+---
+
+### 14. Cloud/Alternative Providers (2 issues)
+
+- [#739](https://github.com/getzep/graphiti/issues/739) - MCP server based on zep-cloud
+  - *Component*: `component:mcp`
+
+- [#538](https://github.com/getzep/graphiti/issues/538) - Azure Cosmos DB version (informational)
+
+---
+
+### 15. Embeddings/Reranking (3 issues)
+
+- [#728](https://github.com/getzep/graphiti/issues/728) - Voyage embedder installation issue
+  - *Component*: `component:core`
+
+- [#485](https://github.com/getzep/graphiti/issues/485) - Better Embedder error information
+  - *Component*: `component:core`
+
+- [#543](https://github.com/getzep/graphiti/issues/543) - Hard-coded model in OpenAIRerankerClient
+  - *Component*: `component:core`
+
+---
+
+### 16. Miscellaneous Bugs (5 issues)
+
+- [#800](https://github.com/getzep/graphiti/issues/800) - Blank disconnected nodes in sample project
+  - *Component*: `component:mcp`
+
+- [#686](https://github.com/getzep/graphiti/issues/686) - Relationships not extracted automatically
+  - *Component*: `component:core`
+
+- [#687](https://github.com/getzep/graphiti/issues/687) - Unable to add episodes with OpenAI agents SDK
+  - *Component*: `component:core`
+
+- [#587](https://github.com/getzep/graphiti/issues/587) - Node type not being set
+  - *Component*: `component:core`
+
+---
+
+## Summary Statistics
+
+- **Total Clustered Issues**: 100+
+- **Major Clusters**: 16
+- **Confirmed Duplicates**: 6 (marked)
+- **High Priority Bugs**: ~15-20
+- **Feature Requests**: ~20
+- **Documentation Gaps**: ~10
+
+## Component Breakdown
+
+- `component:core` - 25+ issues
+- `component:database` - 20+ issues (includes all DB drivers)
+- `component:mcp` - 12+ issues
+- `component:llm` - 12+ issues
+- `component:search` - 8+ issues
+- `component:bulk` - 5+ issues
+- `component:server` - 4+ issues
+- `component:docs` - 10+ issues
--- a/PRIORITY_ROADMAP.md
+++ b/PRIORITY_ROADMAP.md
@ -0,0 +1,283 @@
+# Priority Roadmap - GitHub Issues
+
+**Date**: 2025-10-07
+**Purpose**: Identify and prioritize critical issues requiring immediate attention
+
+---
+
+## P0 - Critical (Fix Immediately)
+
+### 1. MCP Server Protocol Deprecation
+**Issue [#923](https://github.com/getzep/graphiti/issues/923)** - Switch from SSE to Streamable HTTP
+
+- **Impact**: Using deprecated MCP protocol that will be removed
+- **Affected Users**: All MCP server users
+- **Risk**: Protocol will stop working when support is removed
+- **Effort**: Medium
+- **Component**: `component:mcp`
+
+**Action**: Migrate to new protocol ASAP
+
+---
+
+### 2. Database Name Configuration Broken
+**Issues [#851](https://github.com/getzep/graphiti/issues/851), #798** - Database name not passed/respected
+
+- **Impact**: Cannot use non-default Neo4j databases for search operations
+- **Affected Users**: Multi-database deployments, production environments
+- **Root Cause**: Hardcoded 'neo4j' database name in search operations
+- **Symptoms**:
+  - Search only works with default 'neo4j' database
+  - add_episode works with any database name (inconsistent)
+- **Effort**: Low-Medium
+- **Component**: `component:database`, `component:core`
+
+**Action**: Fix database name propagation through entire codebase
+
+---
+
+### 3. Duplicate Entity Detection Broken
+**Issue #875** (duplicate: [#963](https://github.com/getzep/graphiti/issues/963))
+
+- **Impact**: Core deduplication functionality not working
+- **Affected Users**: All users, especially with custom database names
+- **Symptoms**: Same entities created multiple times instead of being merged
+- **User Reports**: Tested with multiple LLM models, issue persists
+- **Effort**: Medium-High
+- **Component**: `component:core`
+
+**Action**: Debug entity resolution and deduplication logic
+
+---
+
+## P1 - High Priority (Fix This Sprint)
+
+### 4. Bulk Upload Completely Broken
+**Issues [#882](https://github.com/getzep/graphiti/issues/882), [#879](https://github.com/getzep/graphiti/issues/879), #871** - Multiple bulk upload failures
+
+- **Impact**: Bulk operations unusable
+- **Affected Users**: Anyone trying to import large datasets
+- **Symptoms**:
+  - IndexError during node resolution ([#882](https://github.com/getzep/graphiti/issues/882))
+  - ValidationError for missing 'duplicates' field ([#879](https://github.com/getzep/graphiti/issues/879))
+  - Invalid JSON errors ([#871](https://github.com/getzep/graphiti/issues/871))
+- **Effort**: Medium
+- **Component**: `component:bulk`
+
+**Action**: Fix validation schema and error handling in bulk pipeline
+
+---
+
+### 5. Datetime Comparison Issues
+**Issues [#920](https://github.com/getzep/graphiti/issues/920), [#893](https://github.com/getzep/graphiti/issues/893), #606**
+
+- **Impact**: Crashes when comparing dates
+- **Status**: May be partially fixed by commit 73015e9
+- **Affected Users**: All users with temporal queries
+- **Effort**: Low (if recent fix is complete)
+- **Component**: `component:core`, `component:database`
+
+**Action**: Verify recent datetime UTC normalization fix covers all cases
+
+---
+
+### 6. Search Group ID Handling
+**Issues [#810](https://github.com/getzep/graphiti/issues/810), [#838](https://github.com/getzep/graphiti/issues/838), #801** - Inconsistent group_id behavior
+
+- **Impact**: Search returns empty results or behaves inconsistently
+- **Affected Users**: Multi-tenant deployments using group_ids
+- **Symptoms**:
+  - Empty group_id handled differently in fulltext vs similarity search
+  - Cannot search across all groups
+- **Effort**: Low-Medium
+- **Component**: `component:search`
+
+**Action**: Standardize group_id handling across search methods
+
+---
+
+### 7. BFS Search Bugs
+**Issues [#772](https://github.com/getzep/graphiti/issues/772), #789** - BFS traversal broken
+
+- **Impact**: Graph traversal doesn't work as expected
+- **Symptoms**:
+  - max_depth parameter completely ignored ([#772](https://github.com/getzep/graphiti/issues/772))
+  - Duplicate edges with swapped source/target ([#789](https://github.com/getzep/graphiti/issues/789))
+- **Effort**: Medium
+- **Component**: `component:search`
+
+**Action**: Fix BFS implementation
+
+---
+
+## P2 - Medium Priority (Address Soon)
+
+### 8. MCP Server Configuration Issues
+**Issues [#945](https://github.com/getzep/graphiti/issues/945), [#840](https://github.com/getzep/graphiti/issues/840), [#848](https://github.com/getzep/graphiti/issues/848), #565** - Various MCP bugs
+
+- [#945](https://github.com/getzep/graphiti/issues/945): Custom OPENAI_BASE_URL causes NaN embeddings
+- [#840](https://github.com/getzep/graphiti/issues/840): "Failed to validate request" initialization timing
+- [#848](https://github.com/getzep/graphiti/issues/848): clear_graph fails silently (async session bug)
+- [#565](https://github.com/getzep/graphiti/issues/565): Cross-encoder ignores OPENAI_BASE_URL
+
+**Impact**: MCP server unreliable with custom configurations
+**Effort**: Low-Medium per issue
+**Component**: `component:mcp`
+
+---
+
+### 9. LLM Provider Compatibility
+**Issues [#878](https://github.com/getzep/graphiti/issues/878), [#902](https://github.com/getzep/graphiti/issues/902), [#912](https://github.com/getzep/graphiti/issues/912), #791** - Provider-specific bugs
+
+- [#902](https://github.com/getzep/graphiti/issues/902): OpenAI reasoning.effort parameter breaks API
+- [#878](https://github.com/getzep/graphiti/issues/878): GPT-5 doesn't support temperature parameter
+- [#791](https://github.com/getzep/graphiti/issues/791): Small model setting ignored, always defaults to gpt-4.1-nano
+- [#912](https://github.com/getzep/graphiti/issues/912): Pydantic validation errors with non-OpenAI models
+
+**Impact**: Specific LLM models/providers broken
+**Effort**: Low per issue
+**Component**: `component:llm`
+
+**Strategy**: Add provider capability detection and parameter filtering
+
+---
+
+### 10. FalkorDB Driver Issues
+**Issues [#972](https://github.com/getzep/graphiti/issues/972), [#815](https://github.com/getzep/graphiti/issues/815), [#757](https://github.com/getzep/graphiti/issues/757), [#731](https://github.com/getzep/graphiti/issues/731), #749** - FalkorDB broken
+
+- **Impact**: FalkorDB backend largely non-functional
+- **Effort**: High (multiple issues)
+- **Component**: `component:database`
+
+**Decision Point**: Fix comprehensively or deprecate? Appears unmaintained.
+
+---
+
+### 11. Error Handling Improvements
+**Issues [#937](https://github.com/getzep/graphiti/issues/937), #951** - Edge case crashes
+
+- [#937](https://github.com/getzep/graphiti/issues/937): Empty query strings cause ArgumentError
+- [#951](https://github.com/getzep/graphiti/issues/951): Incorrect import fallback for AsyncOpenSearch
+
+**Impact**: Crashes on edge cases
+**Effort**: Low per issue
+**Component**: `component:core`
+
+---
+
+### 12. API Server Issues
+**Issue [#566](https://github.com/getzep/graphiti/issues/566)** - /messages endpoint doesn't persist episodes
+
+- **Impact**: Core API functionality broken
+- **Effort**: Medium
+- **Component**: `component:server`
+
+**Action**: Debug why episodes aren't being persisted
+
+---
+
+### 13. Code Quality Issues
+**Issues [#836](https://github.com/getzep/graphiti/issues/836), [#811](https://github.com/getzep/graphiti/issues/811), [#681](https://github.com/getzep/graphiti/issues/681), #451** - Technical debt
+
+- [#836](https://github.com/getzep/graphiti/issues/836): update_communities broken (tuple unpacking error)
+- [#811](https://github.com/getzep/graphiti/issues/811): Hoist hardcoded token constant
+- [#681](https://github.com/getzep/graphiti/issues/681): Remove ghost variables
+- [#451](https://github.com/getzep/graphiti/issues/451): Type bug in bulk_utils
+
+**Impact**: Medium (functionality broken in [#836](https://github.com/getzep/graphiti/issues/836), others are maintenance)
+**Effort**: Low per issue
+
+---
+
+## P3 - Lower Priority / Feature Requests
+
+### 14. Feature Enhancements
+- [#961](https://github.com/getzep/graphiti/issues/961) - Improve Episodes API (UUID, GET by ID, metadata)
+- [#935](https://github.com/getzep/graphiti/issues/935) - Create episodes based on DOM
+- [#934](https://github.com/getzep/graphiti/issues/934) - Flag contradictions on merging facts
+- [#925](https://github.com/getzep/graphiti/issues/925) - Monitor LLM conversations
+- [#819](https://github.com/getzep/graphiti/issues/819) - Count token usage
+- [#747](https://github.com/getzep/graphiti/issues/747) - Progress reporting for bulk upload
+- [#669](https://github.com/getzep/graphiti/issues/669) - Metadata on chunks for RAG
+- [#465](https://github.com/getzep/graphiti/issues/465) - Support ignoring non-custom entities
+
+### 15. New Provider Support
+- [#907](https://github.com/getzep/graphiti/issues/907) - VSC Copilot models
+- [#905](https://github.com/getzep/graphiti/issues/905) - ColbertV2 embeddings
+- [#751](https://github.com/getzep/graphiti/issues/751) - Alibaba Cloud AI
+- [#724](https://github.com/getzep/graphiti/issues/724) - Gemini with GCP credentials
+- [#459](https://github.com/getzep/graphiti/issues/459) - Amazon Bedrock
+- [#739](https://github.com/getzep/graphiti/issues/739) - zep-cloud based MCP
+
+### 16. Documentation Improvements
+- [#913](https://github.com/getzep/graphiti/issues/913) - How to update data in graph
+- [#853](https://github.com/getzep/graphiti/issues/853) - VCS/extension setup
+- [#828](https://github.com/getzep/graphiti/issues/828) - Flowchart documentation
+- [#484](https://github.com/getzep/graphiti/issues/484) - OpenAIGenericClient documentation
+- All "How to" questions
+
+### 17. Alternative Database Support
+- [#947](https://github.com/getzep/graphiti/issues/947) - Apache AGE
+- [#933](https://github.com/getzep/graphiti/issues/933) - RDF support
+- [#781](https://github.com/getzep/graphiti/issues/781) - NebulaGraph
+- [#779](https://github.com/getzep/graphiti/issues/779) - Postgres/pgvector
+- [#644](https://github.com/getzep/graphiti/issues/644) - AWS Neptune
+- [#643](https://github.com/getzep/graphiti/issues/643) - Kuzu
+- [#642](https://github.com/getzep/graphiti/issues/642) - MemGraph
+
+---
+
+## Immediate Action Plan (Next 2 Weeks)
+
+### Week 1
+1. **Fix [#923](https://github.com/getzep/graphiti/issues/923)** - MCP protocol migration (CRITICAL)
+2. **Fix [#851](https://github.com/getzep/graphiti/issues/851)/[#798](https://github.com/getzep/graphiti/issues/798)** - Database name configuration
+3. **Fix [#875](https://github.com/getzep/graphiti/issues/875)** - Duplicate entity detection
+4. **Verify [#920](https://github.com/getzep/graphiti/issues/920)** - Datetime issues resolved by recent commit
+
+### Week 2
+5. **Fix [#882](https://github.com/getzep/graphiti/issues/882)/[#879](https://github.com/getzep/graphiti/issues/879)/[#871](https://github.com/getzep/graphiti/issues/871)** - Bulk upload pipeline
+6. **Fix [#810](https://github.com/getzep/graphiti/issues/810)** - Group ID handling in search
+7. **Fix [#772](https://github.com/getzep/graphiti/issues/772)/[#789](https://github.com/getzep/graphiti/issues/789)** - BFS search issues
+8. **Close duplicates** - Process 6+ confirmed duplicates
+
+### Ongoing
+- **Investigate duplicate clusters** - Consolidate related issues
+- **Document workarounds** - For issues that can't be fixed immediately
+- **Provider compatibility matrix** - Document which LLMs work fully
+
+---
+
+## Impact Summary
+
+**Critical Issues Blocking Production Use**:
+- Database name configuration (multi-DB deployments)
+- Duplicate entity detection (core functionality)
+- Bulk upload failures (data ingestion at scale)
+- MCP protocol deprecation (future compatibility)
+
+**High-Impact Bugs Affecting Many Users**:
+- Search group_id handling
+- BFS traversal issues
+- Datetime comparison problems
+- Various MCP server configuration bugs
+
+**Lower Impact**:
+- Specific LLM provider incompatibilities (workarounds available)
+- FalkorDB issues (alternative: Neo4j)
+- Feature requests and enhancements
+
+---
+
+## Component Labels to Apply
+
+Use these labels when triaging the issues above:
+
+- `component:core` - Core library
+- `component:mcp` - MCP server
+- `component:database` - Database drivers
+- `component:search` - Search functionality
+- `component:bulk` - Bulk operations
+- `component:server` - FastAPI server
+- `component:llm` - LLM providers
+- `component:docs` - Documentation