knowgraph 0.5.0

Knowledge Graph-Powered RAG system with enterprise resilience patterns

🧠 KnowGraph: Graph RAG & MCP Server for Code

The Cognitive Revolution for Your Codebase (Graph RAG for LLMs)

"Your code is not just text, it's a living graph." Shift from the probabilistic world of vector similarity (Standard RAG) to the deterministic clarity of Graph Theory and NetworkX.

⚡ Quick Start • 🔬 The Difference • 🧪 The Lab • 📚 Knowledge Base

---

🔬 Why KnowGraph? (The Scientific Edge)

Traditional AI assistants view your code as a "bag of similar words" (Vector Space). However, software engineering is topological; it relies on logical connections, not just textual proximity.

KnowGraph leverages Graph Theory and Network Science principles to offer 4 revolutionary capabilities:

Capability	Traditional RAG	🧠 KnowGraph
1. Topological Context	Retrieves random files.	Follows real connections (import, call, inherit) via Graph Traversal (BFS/DFS).
2. Centrality Analysis	Focuses on keyword frequency.	Identifies architecturally critical components (Hub Nodes) using PageRank.
3. Deterministic Provenance	High hallucination risk.	Cites the reasoning path and source files as irrefutable proof.
4. Cognitive Hierarchy	Analyzes files in isolation.	Interprets files in enriched context using parent READMEs and project purpose.

---

🚀 Performance Engine (v0.6.0)

KnowGraph is built for scale. The Smart Indexing Engine processes large repositories efficiently:

• ⚡ Hybrid Intelligence: Code files are analyzed using AST (Abstract Syntax Tree) via ASTAnalyzer for 100x speed and 0-token cost, while text files use Batch LLM processing through OpenAIProvider or MCPSamplingProvider.
• 🧠 Persistent Memory: Built-in SQLite Caching via CacheManager (.knowgraph_cache) ensures you never re-index unchanged files. Resumes instantly after interruptions.
• 🛡️ Smart Rate Limiter: The RateLimiter class automatically respects API limits (Free/Pro tiers) by dynamically throttling requests based on headers, preventing 429 errors.
• 🏎️ Concurrent Batching: SmartGraphBuilder processes 10 chunks per call with 20 parallel workers, maximizing throughput.
• 📊 Graph Algorithms: Leverages NetworkX for centrality calculations (Betweenness, Degree, Closeness, Eigenvector) to identify architecturally critical components.

---

🎯 Key Features

1. 📊 Time-Travel Debugging (Graph Versioning - v0.6.0)

KnowGraph now treats your knowledge graph as a versioned artifact, similar to Git for your code.

• Snapshots: Every knowgraph index creates a new, immutable version checkpoint.
• Diffing: See exactly how your knowledge graph evolved. Which nodes were added? Which relationships broke?
• Rollback: Broke something? Instantly revert to a previous healthy state with knowgraph version rollback.

# Compare current graph with the previous version
knowgraph version diff HEAD HEAD~1

# Rollback to a safe state
knowgraph version rollback v0.5.9-stable

2. 🔗 Conversational Intelligence (v0.6.0)

Your code doesn't live in a vacuum. It lives in the conversations you have with your AI assistant. KnowGraph now indexes Code + Conversations together.

• Multi-Editor Support: Supports Antigravity (Gemini), Cursor (.aichat), GitHub Copilot, and Claude Desktop.
• Semantic Linking: Automatically links chat discussions to the code files they mention.
• Unified Search: Query code and chat history simultaneously. "Show me the authentication code AND the discussion where we decided to use JWT."

# Auto-discover and index all AI conversations
knowgraph discover-conversations

3. ⚡ Smart Automation (Post-Indexing Hooks - v0.6.0)

The workflow doesn't end with indexing. KnowGraph triggers intelligent agents after every update.

• Auto-Tagging: Automatically tags nodes with concepts like "Security Critical", "Legacy Code", or "Performance Hotspot" based on analysis.
• Analytics: Generates growth reports and health metrics automatically.
• Dynamic Linking: Connects new code to existing documentation in real-time.

4. 🛡️ Resilience & Production Readiness (v0.5.0)

KnowGraph is built for production with enterprise-grade resilience patterns:

• 🔌 Circuit Breaker: Automatic failure detection and recovery.
• ⏱️ Rate Limiting: Token bucket algorithm with burst capacity.
• 🔄 Retry Logic: Exponential backoff with jitter.
• 🚦 Request Throttling: Adaptive concurrency control.
• 📋 API Versioning: Semantic versioning with automatic negotiation.

Core Capabilities

• 🔍 Semantic Search: Natural language queries with context-aware retrieval via QueryEngine
• ⚡ Async/Await Support: 15x faster batch queries with concurrent processing using query_async()
• 🚀 Performance Caching: 22x speedup on repeated queries through CacheManager
• 📊 Impact Analysis: Predict ripple effects of code changes using ImpactAnalyzer
• 🎯 Hierarchical Context: Automatic lifting of parent README context for enriched understanding
• 🧠 Graph Traversal: BFS/DFS exploration of code relationships (imports, calls, inheritance)
• ✅ Graph Validation: Ensure knowledge graph consistency via GraphValidator

Performance Highlights (v0.6.1)

Feature	Performance	Improvement
Async I/O	Non-blocking file operations	100% async 🚀
LLM Batch	Parallel generation	3.7x faster ⚡
Indexing	10 concurrent workers	4-6x faster 🏎️
Memory	Lazy edge loading	-60% RAM 💾
Code Quality	Zero dead code	+240% coverage ✅

Previous Releases:

• Batch Queries (v0.6.0): 1.19s (5 queries) - 15.72x faster
• Warm Cache (v0.6.0): 0.18s - 22x faster
• Centrality (v0.6.0): 0.01s (cached) - 372x faster

See CHANGELOG.md for details.

---

⚡ Cognitive Upgrade in 30 Seconds (Quick Start)

Connect KnowGraph as an MCP server to boost your AI editor's IQ.

1. Installation

pip install knowgraph

2. Brain Link (Configuration)

Add the following to your Claude Desktop (claude_desktop_config.json) or Cursor settings:

{
  "mcpServers": {
    "knowgraph": {
      "command": "knowgraph",
      "args": ["serve"],
      "env": {
        "KNOWGRAPH_API_KEY": "sk-..."
      }
    }
  }
}

3. Index Your Knowledge Base

# Index local markdown files
knowgraph index /path/to/markdown/files

# Index a GitHub repository directly
knowgraph index https://github.com/user/repo

# Index conversations from your editor
knowgraph discover-conversations

4. Cheat Sheet: Version Control

# List all graph versions
knowgraph version list

# Show details of a specific version
knowgraph version show <version_id>

# See what changed between updates
knowgraph version diff <old_id> <new_id>

# Revert to a previous state
knowgraph version rollback <version_id>

---

🧪 The Lab: Cognitive Capability Tests

Run these scientific experiments (prompts) to witness the KnowGraph difference.

🧪 Click to Expand: Ready-to-use Commands

🤖 User (Stats): "Show me the node and edge statistics of my KnowGraph database."

🤖 User (Time Travel): "List the available versions of the knowledge graph and tell me what changed in the last update."

🤖 User (Conversational Memory): "Find the conversation where we discussed the 'Retry Logic' implementation and show me the relevant code snippets."

🦋 Experiment 1: The "Butterfly Effect" Analysis (Impact Analysis) - Predict chaotic consequences.

> 🤖 **User:** "Analyze the 'butterfly effect' if I delete `include/video_processor.hpp`. Show the chain of broken dependencies, both direct and indirect (N-Hop)."

🕸️ Experiment 2: Semantic Network Discovery (Conceptual Integration) - Meaning beyond keywords.

> 🤖 **User:** "Explain FFmpeg's 'memory management' strategies and 'buffering' mechanisms. Expand my query with technical terminology (Query Expansion) and provide logical proof (explanation) for your answer."

🦴 Experiment 3: Architectural X-Ray (Deep Architecture) - Reveal invisible connections.

> 🤖 **User:** "Trace the connection between the `RATE_LIMIT` value in `docker-compose.yml` and `rate_limiter.cpp` deep in the C++ code, including all intermediate layers, up to 8 hops deep (Deep Hop)."

---

📚 Knowledge Base

For those who want to dive into the deep tech:

• 📖 User Guide: Comprehensive guide covering versioning, indexing, querying, and troubleshooting.
• 🔧 MCP Rules & Detailed Prompts: Best practices for using KnowGraph with AI assistants.
• 🏗️ Architecture & Algorithms: Graph theory, node weighting algorithms, and system architecture.
• 📦 Repository Indexing: Guide for indexing Git repositories and code directories.

🤝 Contribute to Science

This project is open source and grows with collective intelligence. PRs are welcome.

📄 License

MIT