Add comprehensive issue triage documentation
Created three documentation files to organize and prioritize 100+ open GitHub issues: - ISSUE_TRIAGE.md: Full categorization into 16 clusters by component and theme - DUPLICATES.md: Identified 6 confirmed duplicates and 7 potential duplicate clusters - PRIORITY_ROADMAP.md: Prioritized critical issues (P0-P3) with immediate action plan Key findings: - P0 issues: MCP protocol deprecation, database name config, duplicate detection - Component breakdown: core (25+), database (20+), mcp (12+), llm (12+), search (8+) - Estimated 15-25 issues can be consolidated through deduplication 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Daniel Chalef
parent
73015e980e
commit
d78d73e666
3 changed files with 800 additions and 0 deletions
156
DUPLICATES.md
Normal file
156
DUPLICATES.md
Normal file
|
|
@ -0,0 +1,156 @@
|
|||
# Duplicate GitHub Issues
|
||||
|
||||
**Date**: 2025-10-07
|
||||
|
||||
## Confirmed Duplicates (Already Marked)
|
||||
|
||||
### #963 - Duplicate Entities in Neo4j
|
||||
- **Status**: Marked as duplicate
|
||||
- **Original Issue**: #875 - Duplicate Entities in Neo4j with custom db name
|
||||
- **Labels**: bug, duplicate
|
||||
- **Action**: Can be closed with reference to #875
|
||||
- **Notes**: Same core issue - deduplication not working properly
|
||||
|
||||
---
|
||||
|
||||
### #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
|
||||
- **Action**: Close with reference to original issue
|
||||
|
||||
---
|
||||
|
||||
### #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 - MCP with GPT-oss Models
|
||||
- **Title**: MPC does not work with GPT-oss:20 or 120B
|
||||
- **Status**: Marked as duplicate
|
||||
- **Duplicate Of**: #831 - [BUG] GPT-oss:20 and 120
|
||||
- **Labels**: bug, duplicate
|
||||
- **Action**: Close with reference to #831
|
||||
|
||||
---
|
||||
|
||||
### #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 - Empty group_id handling issues
|
||||
- **Action**: Close with reference to #810 or related search issue
|
||||
|
||||
---
|
||||
|
||||
### #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**, **#798**, **#715** - All relate to database name handling
|
||||
- **#851** - Search only connects to 'neo4j' db
|
||||
- **#798** - Database name not passed through Graphiti object
|
||||
- **#715** - Feature request to configure Neo4j database name
|
||||
|
||||
**Analysis**: These may be describing the same underlying issue. #715 appears to be the feature request, while #851 and #798 are bugs from the missing feature.
|
||||
|
||||
**Recommendation**: Fix the root cause and consolidate. Keep #715 as the tracking issue if implementing multi-DB support properly.
|
||||
|
||||
---
|
||||
|
||||
### Bulk Upload Failures
|
||||
|
||||
**#882**, **#879**, **#871**, **#658** - Bulk upload failures
|
||||
- **#882** - IndexError during node resolution
|
||||
- **#879** - ValidationError 'duplicates' field missing
|
||||
- **#871** - Invalid JSON and index errors
|
||||
- **#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**, **#757**, **#731** - FalkorDB query errors
|
||||
- **#815** - falkordb query error
|
||||
- **#757** - quickstart_falkordb example query error
|
||||
- **#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**, **#945** - OPENAI_BASE_URL issues
|
||||
- **#565** - Cross-encoder ignores OPENAI_BASE_URL
|
||||
- **#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**, **#831** - Ollama issues
|
||||
- **#868** - Cannot get minimal example to work with Ollama
|
||||
- **#831** - GPT-oss:20 and 120 (Ollama models)
|
||||
|
||||
**Analysis**: Both relate to Ollama model compatibility issues.
|
||||
|
||||
---
|
||||
|
||||
### Search Result Issues
|
||||
|
||||
**#534**, **#801**, **#810** - Search returning empty/no results
|
||||
- **#534** - retrieve_episodes always returns no results
|
||||
- **#801** - episode_fulltext_search empty results (marked duplicate)
|
||||
- **#810** - Empty group_id handled inconsistently
|
||||
|
||||
**Analysis**: Likely all related to search filtering/group_id handling issues.
|
||||
|
||||
---
|
||||
|
||||
### Documentation/Setup Questions (Can Be Consolidated)
|
||||
|
||||
**#517**, **#530** - OpenRouter setup questions
|
||||
- **#517** - How to setup with OpenRouter and Voyage
|
||||
- **#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
|
||||
361
ISSUE_TRIAGE.md
Normal file
361
ISSUE_TRIAGE.md
Normal file
|
|
@ -0,0 +1,361 @@
|
|||
# GitHub Issues Triage & Categorization
|
||||
|
||||
**Date**: 2025-10-07
|
||||
**Total Open Issues**: 100+
|
||||
**Analysis Scope**: Issues #451 - #972
|
||||
|
||||
## Issue Clusters
|
||||
|
||||
### 1. Database Driver Support
|
||||
|
||||
#### FalkorDB Issues (6 issues)
|
||||
- **#972** - [BUG] Vector type mismatch in cosine distance operations
|
||||
- *Component*: `component:database`
|
||||
- *Status*: Open
|
||||
|
||||
- **#815** - [BUG] falkordb query
|
||||
- *Component*: `component:database`
|
||||
- *Status*: Open
|
||||
|
||||
- **#757** - [BUG] run quickstart_falkordb example, get query error
|
||||
- *Component*: `component:database`
|
||||
- *Status*: Open
|
||||
|
||||
- **#749** - [BUG] Official Docker Image doesn't support FalkorDB
|
||||
- *Component*: `component:database`, `component:mcp`
|
||||
- *Status*: Open
|
||||
|
||||
- **#731** - Episode insertion fails due to malformed Cypher query
|
||||
- *Component*: `component:database`
|
||||
- *Status*: Open
|
||||
|
||||
- **#719** - FalkorDB support in MCP-Server
|
||||
- *Component*: `component:mcp`, `component:database`
|
||||
- *Status*: Open
|
||||
|
||||
#### New Database Support Requests (6 issues)
|
||||
- **#947** - Apache AGE Graph DB support
|
||||
- **#933** - Support RDF
|
||||
- **#781** - More graph database support (NebulaGraph mentioned)
|
||||
- **#779** - Postgres with pgvector support
|
||||
- **#644** - AWS Neptune driver
|
||||
- **#643** - Kuzu driver support (may already be implemented?)
|
||||
- **#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** - [BUG] Switch from SSE (deprecated) to Streamable HTTP
|
||||
- *Priority*: HIGH - using deprecated protocol
|
||||
- *Component*: `component:mcp`
|
||||
|
||||
- **#945** - [BUG] Custom OPENAI_BASE_URL causes NaN embeddings
|
||||
- *Component*: `component:mcp`, `component:llm`
|
||||
|
||||
- **#848** - [BUG] clear_graph tool fails silently (async session bug)
|
||||
- *Component*: `component:mcp`
|
||||
|
||||
- **#840** - [BUG] Failed to validate request (initialization timing)
|
||||
- *Component*: `component:mcp`
|
||||
|
||||
- **#723** - DEFAULT_MAX_TOKENS 8192 too restrictive
|
||||
- *Component*: `component:mcp`
|
||||
|
||||
- **#578** - MCP server with Gemini model
|
||||
- *Component*: `component:mcp`, `component:llm`
|
||||
|
||||
- **#565** - Cross-encoder ignores OPENAI_BASE_URL
|
||||
- *Component*: `component:mcp`, `component:llm`
|
||||
|
||||
- **#509** - MCP server add_nodes tool call doesn't work
|
||||
- *Component*: `component:mcp`
|
||||
|
||||
**Duplicates in this cluster**:
|
||||
- **#867** + **#831** - GPT-oss:20 and 120B models (duplicate)
|
||||
- **#787** - Rate limit even with SEMAPHORE_LIMIT=1 (marked duplicate)
|
||||
|
||||
**Analysis**: MCP server has protocol deprecation issue (#923) and multiple configuration/provider issues. Should be high priority for users relying on MCP integration.
|
||||
|
||||
---
|
||||
|
||||
### 3. LLM Provider Compatibility (8 issues)
|
||||
|
||||
- **#902** - [BUG] OpenAI internal call broken (reasoning.effort param)
|
||||
- *Component*: `component:llm`
|
||||
|
||||
- **#878** - [BUG] GPT-5 temperature parameter unsupported
|
||||
- *Component*: `component:llm`
|
||||
|
||||
- **#912** - [BUG] Pydantic validation error with deepseek-r1:7b
|
||||
- *Component*: `component:llm`
|
||||
|
||||
- **#791** - [BUG] Small model setting defaults to gpt-4.1-nano
|
||||
- *Component*: `component:llm`
|
||||
|
||||
- **#790** - [BUG] Failed to parse structured response with Gemini
|
||||
- *Component*: `component:llm`
|
||||
|
||||
- **#868** - [BUG] Cannot work with Ollama
|
||||
- *Component*: `component:llm`
|
||||
|
||||
- **#763** - [BUG] LLMConfig.max_tokens not respected
|
||||
- *Component*: `component:llm`
|
||||
|
||||
- **#760** - [BUG] Hallucinations with default models
|
||||
- *Component*: `component:llm`
|
||||
|
||||
**Additional LLM Provider Requests**:
|
||||
- **#907** - VSC Copilot models
|
||||
- **#751** - Alibaba Cloud AI model
|
||||
- **#724** - Gemini with Google Cloud Credentials
|
||||
- **#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** - [BUG] Duplicate entities in Neo4j (marked duplicate)
|
||||
- *Component*: `component:core`
|
||||
- *Status*: Duplicate (see #875)
|
||||
|
||||
- **#875** - [BUG] Duplicate entities with custom db name
|
||||
- *Component*: `component:core`, `component:database`
|
||||
- *Priority*: HIGH - core deduplication functionality broken
|
||||
|
||||
- **#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** - [BUG] IndexError during node resolution
|
||||
- *Component*: `component:bulk`
|
||||
|
||||
- **#879** - ValidationError 'duplicates' field missing
|
||||
- *Component*: `component:bulk`
|
||||
|
||||
- **#871** - Invalid JSON and index errors
|
||||
- *Component*: `component:bulk`
|
||||
|
||||
**Related**:
|
||||
- **#747** - Add progress reporting to bulk upload
|
||||
- **#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** - [BUG] Empty group_id handled inconsistently in search
|
||||
- *Component*: `component:search`
|
||||
|
||||
- **#801** - [BUG] episode_fulltext_search empty results (marked duplicate)
|
||||
- *Component*: `component:search`
|
||||
|
||||
- **#838** - Allow searching across all groups when group_ids is None
|
||||
- *Component*: `component:search`
|
||||
|
||||
- **#772** - [BUG] BFS max_depth parameter ignored
|
||||
- *Component*: `component:search`
|
||||
|
||||
- **#789** - [BUG] BFS returns duplicate edges with swapped source/target
|
||||
- *Component*: `component:search`
|
||||
|
||||
- **#777** - [BUG] MMR reranker RuntimeWarning, no results
|
||||
- *Component*: `component:search`
|
||||
|
||||
**Related**:
|
||||
- **#488** - edge_search_filter_query_constructor creating incorrect query
|
||||
- **#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** - [BUG] Search only connects to 'neo4j' db, add_episode works with any name
|
||||
- *Component*: `component:database`
|
||||
- *Priority*: HIGH - inconsistent behavior
|
||||
|
||||
- **#798** - [BUG] Database name not passed through Graphiti object
|
||||
- *Component*: `component:database`
|
||||
- *Priority*: HIGH - related to #851
|
||||
|
||||
- **#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** - [BUG] edge_operations.py timezone-naive/aware comparison (marked duplicate)
|
||||
- *Component*: `component:core`
|
||||
- *Status*: Duplicate (possibly fixed in commit 73015e9)
|
||||
|
||||
- **#893** - [BUG] Kuzu driver valid_at datetime format
|
||||
- *Component*: `component:database`
|
||||
|
||||
- **#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** - [Feature Request] Improve Episodes API (UUID, GET by ID, metadata)
|
||||
- *Component*: `component:server`
|
||||
|
||||
- **#921** - SDK client like zep-cloud/zep-python
|
||||
- *Component*: `component:server`
|
||||
|
||||
- **#566** - /messages endpoint doesn't persist episodes
|
||||
- *Component*: `component:server`
|
||||
|
||||
- **#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** - TaskGroup errors (marked duplicate)
|
||||
- *Component*: `component:core`
|
||||
|
||||
- **#937** - ArgumentError with empty query entities
|
||||
- *Component*: `component:core`
|
||||
|
||||
- **#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** - Create episodes based on DOM structure
|
||||
- **#934** - Flag contradictions on merging facts
|
||||
- **#925** - Monitor LLM conversations
|
||||
- **#905** - ColbertV2 embeddings with Fastembed
|
||||
- **#864** - How to forget knowledge
|
||||
- **#819** - Count token usage
|
||||
- **#669** - Metadata on chunks for RAG
|
||||
- **#465** - Support ignoring non-custom entities
|
||||
- **#467** - LLM inference expenses are high
|
||||
|
||||
**Analysis**: Feature requests range from observability (#925, #819) to advanced RAG features (#669, #905). Token cost reduction (#467) is recurring concern.
|
||||
|
||||
---
|
||||
|
||||
### 12. Documentation/Questions (9 issues)
|
||||
|
||||
- **#913** - How to update data in graph
|
||||
- **#909** - Reproduce LongMemEval results
|
||||
- **#869** - Portuguese: Change OpenAI model
|
||||
- **#853** - Document VCS/extension setup
|
||||
- **#828** - Get a flowchart
|
||||
- **#701** - Chinese video tutorial (informational)
|
||||
- **#484** - OpenAIGenericClient documentation
|
||||
- **#530** - Cursor AI + OpenRouter setup
|
||||
- **#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** - [BUG] update_communities broken
|
||||
- *Component*: `component:core`
|
||||
|
||||
- **#811** - Refactor: hoist EXTRACT_EDGES_MAX_TOKENS constant
|
||||
- *Component*: `component:core`
|
||||
|
||||
- **#681** - Refactor: no internal ghost variables
|
||||
- *Component*: `component:core`
|
||||
|
||||
- **#451** - Minor type bug in bulk_utils
|
||||
- *Component*: `component:bulk`
|
||||
|
||||
- **#717** - Adopt uv workspace for monorepo
|
||||
- *Component*: `component:core`, `component:server`, `component:mcp`
|
||||
|
||||
**Analysis**: Technical debt items. #717 (uv workspace) would improve developer experience for monorepo.
|
||||
|
||||
---
|
||||
|
||||
### 14. Cloud/Alternative Providers (2 issues)
|
||||
|
||||
- **#739** - MCP server based on zep-cloud
|
||||
- *Component*: `component:mcp`
|
||||
|
||||
- **#538** - Azure Cosmos DB version (informational)
|
||||
|
||||
---
|
||||
|
||||
### 15. Embeddings/Reranking (3 issues)
|
||||
|
||||
- **#728** - Voyage embedder installation issue
|
||||
- *Component*: `component:core`
|
||||
|
||||
- **#485** - Better Embedder error information
|
||||
- *Component*: `component:core`
|
||||
|
||||
- **#543** - Hard-coded model in OpenAIRerankerClient
|
||||
- *Component*: `component:core`
|
||||
|
||||
---
|
||||
|
||||
### 16. Miscellaneous Bugs (5 issues)
|
||||
|
||||
- **#800** - Blank disconnected nodes in sample project
|
||||
- *Component*: `component:mcp`
|
||||
|
||||
- **#686** - Relationships not extracted automatically
|
||||
- *Component*: `component:core`
|
||||
|
||||
- **#687** - Unable to add episodes with OpenAI agents SDK
|
||||
- *Component*: `component:core`
|
||||
|
||||
- **#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
|
||||
283
PRIORITY_ROADMAP.md
Normal file
283
PRIORITY_ROADMAP.md
Normal file
|
|
@ -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** - 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, #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)
|
||||
|
||||
- **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, #879, #871** - Multiple bulk upload failures
|
||||
|
||||
- **Impact**: Bulk operations unusable
|
||||
- **Affected Users**: Anyone trying to import large datasets
|
||||
- **Symptoms**:
|
||||
- IndexError during node resolution (#882)
|
||||
- ValidationError for missing 'duplicates' field (#879)
|
||||
- Invalid JSON errors (#871)
|
||||
- **Effort**: Medium
|
||||
- **Component**: `component:bulk`
|
||||
|
||||
**Action**: Fix validation schema and error handling in bulk pipeline
|
||||
|
||||
---
|
||||
|
||||
### 5. Datetime Comparison Issues
|
||||
**Issues #920, #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, #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, #789** - BFS traversal broken
|
||||
|
||||
- **Impact**: Graph traversal doesn't work as expected
|
||||
- **Symptoms**:
|
||||
- max_depth parameter completely ignored (#772)
|
||||
- Duplicate edges with swapped source/target (#789)
|
||||
- **Effort**: Medium
|
||||
- **Component**: `component:search`
|
||||
|
||||
**Action**: Fix BFS implementation
|
||||
|
||||
---
|
||||
|
||||
## P2 - Medium Priority (Address Soon)
|
||||
|
||||
### 8. MCP Server Configuration Issues
|
||||
**Issues #945, #840, #848, #565** - Various MCP bugs
|
||||
|
||||
- **#945**: Custom OPENAI_BASE_URL causes NaN embeddings
|
||||
- **#840**: "Failed to validate request" initialization timing
|
||||
- **#848**: clear_graph fails silently (async session bug)
|
||||
- **#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, #902, #912, #791** - Provider-specific bugs
|
||||
|
||||
- **#902**: OpenAI reasoning.effort parameter breaks API
|
||||
- **#878**: GPT-5 doesn't support temperature parameter
|
||||
- **#791**: Small model setting ignored, always defaults to gpt-4.1-nano
|
||||
- **#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, #815, #757, #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, #951** - Edge case crashes
|
||||
|
||||
- **#937**: Empty query strings cause ArgumentError
|
||||
- **#951**: Incorrect import fallback for AsyncOpenSearch
|
||||
|
||||
**Impact**: Crashes on edge cases
|
||||
**Effort**: Low per issue
|
||||
**Component**: `component:core`
|
||||
|
||||
---
|
||||
|
||||
### 12. API Server Issues
|
||||
**Issue #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, #811, #681, #451** - Technical debt
|
||||
|
||||
- **#836**: update_communities broken (tuple unpacking error)
|
||||
- **#811**: Hoist hardcoded token constant
|
||||
- **#681**: Remove ghost variables
|
||||
- **#451**: Type bug in bulk_utils
|
||||
|
||||
**Impact**: Medium (functionality broken in #836, others are maintenance)
|
||||
**Effort**: Low per issue
|
||||
|
||||
---
|
||||
|
||||
## P3 - Lower Priority / Feature Requests
|
||||
|
||||
### 14. Feature Enhancements
|
||||
- **#961** - Improve Episodes API (UUID, GET by ID, metadata)
|
||||
- **#935** - Create episodes based on DOM
|
||||
- **#934** - Flag contradictions on merging facts
|
||||
- **#925** - Monitor LLM conversations
|
||||
- **#819** - Count token usage
|
||||
- **#747** - Progress reporting for bulk upload
|
||||
- **#669** - Metadata on chunks for RAG
|
||||
- **#465** - Support ignoring non-custom entities
|
||||
|
||||
### 15. New Provider Support
|
||||
- **#907** - VSC Copilot models
|
||||
- **#905** - ColbertV2 embeddings
|
||||
- **#751** - Alibaba Cloud AI
|
||||
- **#724** - Gemini with GCP credentials
|
||||
- **#459** - Amazon Bedrock
|
||||
- **#739** - zep-cloud based MCP
|
||||
|
||||
### 16. Documentation Improvements
|
||||
- **#913** - How to update data in graph
|
||||
- **#853** - VCS/extension setup
|
||||
- **#828** - Flowchart documentation
|
||||
- **#484** - OpenAIGenericClient documentation
|
||||
- All "How to" questions
|
||||
|
||||
### 17. Alternative Database Support
|
||||
- **#947** - Apache AGE
|
||||
- **#933** - RDF support
|
||||
- **#781** - NebulaGraph
|
||||
- **#779** - Postgres/pgvector
|
||||
- **#644** - AWS Neptune
|
||||
- **#643** - Kuzu
|
||||
- **#642** - MemGraph
|
||||
|
||||
---
|
||||
|
||||
## Immediate Action Plan (Next 2 Weeks)
|
||||
|
||||
### Week 1
|
||||
1. **Fix #923** - MCP protocol migration (CRITICAL)
|
||||
2. **Fix #851/#798** - Database name configuration
|
||||
3. **Fix #875** - Duplicate entity detection
|
||||
4. **Verify #920** - Datetime issues resolved by recent commit
|
||||
|
||||
### Week 2
|
||||
5. **Fix #882/#879/#871** - Bulk upload pipeline
|
||||
6. **Fix #810** - Group ID handling in search
|
||||
7. **Fix #772/#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
|
||||
Loading…
Add table
Reference in a new issue