@sofianedjerbi/knowledge-tree-mcp/docs/llm/guides/path-generation-algorithm-guide.json

MCP server for hierarchical project knowledge management

{
  "title": "Path Generation Algorithm Guide",
  "priority": "REQUIRED",
  "problem": "Understanding how the Knowledge Tree MCP system automatically generates paths from entry titles is important for predicting entry locations and understanding the knowledge organization system.",
  "solution": "## Path Generation Process\n\n### 1. Title Analysis\nThe system analyzes the entry title to extract:\n- **Action words**: \"configure\", \"implement\", \"debug\", \"optimize\"\n- **Technology keywords**: \"redis\", \"react\", \"docker\", \"jwt\"\n- **Domain concepts**: \"authentication\", \"caching\", \"testing\", \"deployment\"\n\n### 2. Category Detection Scoring\nUses a weighted scoring system:\n```typescript\nSCORING_WEIGHTS = {\n  TAG_MATCH: 100,       // Exact tag matches (highest priority)\n  TECH_EXACT: 80,       // Exact technology name in title\n  TITLE_EARLY: 60,      // Technology mentioned in first 3 words\n  TITLE_LATE: 40,       // Technology mentioned later in title\n  FUZZY_MATCH: 20       // Partial keyword matches\n}\n```\n\n### 3. Technology Mapping\nMaps technology keywords to categories:\n```javascript\n{\n  \"redis\": \"database/redis\",\n  \"react\": \"frontend/react\", \n  \"docker\": \"containers/docker\",\n  \"jwt\": \"auth/jwt\",\n  \"typescript\": \"languages/typescript\"\n}\n```\n\n### 4. Category Classification\nStandard categories include:\n- **backend/**: Server-side frameworks and APIs\n- **frontend/**: Client-side frameworks and libraries\n- **database/**: Data storage and management\n- **auth/**: Authentication and authorization\n- **testing/**: Test frameworks and strategies\n- **deployment/**: CI/CD and infrastructure\n\n### 5. Path Construction\nFinal path format: `{prefix}/{category}/{subcategory}/{normalized-title}`\n\nExample transformations:\n```\n\"Configure Redis Connection Pool\" \n→ knowledge-tree/database/redis/configure-redis-connection-pool\n\n\"JWT Authentication Best Practices\"\n→ knowledge-tree/auth/jwt/jwt-authentication-best-practices\n\n\"React Hook Testing Strategies\"\n→ knowledge-tree/frontend/react/react-hook-testing-strategies\n```\n\n## Algorithm Details\n\n### Title Normalization\n1. Convert to lowercase\n2. Replace spaces with hyphens\n3. Remove special characters\n4. Deduplicate hyphens\n5. Trim leading/trailing hyphens\n\n```javascript\nfunction normalizeTitle(title) {\n  return title\n    .toLowerCase()\n    .replace(/[^a-z0-9\\s-]/g, '')\n    .replace(/\\s+/g, '-')\n    .replace(/-+/g, '-')\n    .replace(/^-|-$/g, '');\n}\n```\n\n### Category Detection Logic\n```javascript\nfunction detectCategory(title, tags, projectConfig) {\n  const matches = [];\n  \n  // 1. Check tags for exact technology matches\n  for (const tag of tags) {\n    if (technologies[tag.toLowerCase()]) {\n      matches.push({\n        category: technologies[tag.toLowerCase()],\n        score: SCORING_WEIGHTS.TAG_MATCH,\n        source: 'tag'\n      });\n    }\n  }\n  \n  // 2. Check title for technology keywords\n  const titleLower = title.toLowerCase();\n  for (const [tech, category] of Object.entries(technologies)) {\n    if (titleLower.includes(tech)) {\n      const words = titleLower.split(/\\s+/);\n      const isEarly = words.slice(0, 3).includes(tech);\n      matches.push({\n        category,\n        score: isEarly ? SCORING_WEIGHTS.TITLE_EARLY : SCORING_WEIGHTS.TITLE_LATE,\n        source: isEarly ? 'title-early' : 'title-late'\n      });\n    }\n  }\n  \n  // 3. Aggregate scores and return best match\n  return getBestMatch(aggregateScores(matches));\n}\n```\n\n### Conflict Resolution\nWhen multiple categories have similar scores:\n1. **Tag priority**: Tag matches override title matches\n2. **Specificity**: More specific categories win over general ones\n3. **Project config**: Project-specific mappings take precedence\n4. **Fallback**: Default to \"misc\" category if no clear match\n\n### Subcategory Assignment\nSubcategories are derived from:\n- Technology-specific patterns (e.g., \"react/hooks\", \"redis/caching\")\n- Action-based grouping (e.g., \"setup\", \"troubleshooting\", \"patterns\")\n- Project configuration overrides\n\n## Configuration and Customization\n\n### Project-Specific Mappings\nProjects can override default behavior:\n```json\n{\n  \"pathPrefix\": \"my-project\",\n  \"categories\": {\n    \"custom-category\": {\n      \"keywords\": [\"special\", \"custom\"],\n      \"subcategories\": [\"patterns\", \"examples\"]\n    }\n  },\n  \"technologies\": [\"my-framework\", \"custom-tool\"]\n}\n```\n\n### Auto-Tagging Integration\nThe system can suggest tags based on detected technologies:\n```javascript\n// If title contains \"redis\" and \"caching\"\nsuggestedTags = [\"redis\", \"caching\", \"database\", \"performance\"]\n```",
  "tags": [
    "path-generation",
    "auto-path",
    "algorithm",
    "categorization"
  ],
  "context": "The path generation algorithm is a key feature that eliminates manual path management. It analyzes entry titles, tags, and content to automatically assign appropriate categories and generate meaningful file paths that facilitate discovery and organization.",
  "examples": [
    {
      "title": "Path Generation Examples",
      "code": "Title: \"Setup Local Development Environment\"\nTags: [setup, development, environment]\nGenerated: knowledge-tree/development/setup/setup-local-development-environment\n\nTitle: \"Troubleshoot Database Connection Timeout\"\nTags: [troubleshooting, database, connection]\nGenerated: knowledge-tree/database/troubleshooting/troubleshoot-database-connection-timeout"
    }
  ],
  "created_at": "2025-08-03T16:37:35.530Z",
  "updated_at": "2025-08-04T11:14:42.154Z",
  "related_to": [
    {
      "path": "llm/documentation/knowledge-entry-structure-best-practices.json",
      "relationship": "implements",
      "description": "Explains the technical implementation of automatic path generation mentioned in the entry structure guide"
    }
  ]
}