kruschdev/krusch-git

A persistent Git DAG indexer, AST chunker, and semantic codebase retrieval engine for AI coding agents. Stores the entire Directed Acyclic Graph (DAG) natively in PostgreSQL with pgvector, extracting code symbols, call edges, and chunked semantic vector embeddings.
> 📖 Read the Systems Deep Dive: Check out the published architecture essay krusch-git: Git DAG Indexing, Relational AST Symbols, and Hybrid Recency Search for AI Coding Agents on krusch.dev, or the local companion guide in docs/WHATMAKESITSPECIAL.md.
## 🧠 Why Krusch-Git?
In the standard AI coding agent ecosystem, searching codebases relies on rigid grep searches or expensive ad-hoc AST parsing. Krusch-Git fundamentally changes this by bridging Git directly with persistent semantic graphs:
1. Semantic Code Search: Find code based on what it does, not just exact token syntax.
2. AST Symbol & Edge Graph: Walks call graphs, definitions, and symbol dependencies across your repository.
3. Exponential Temporal Decay: Mathematically decays older vectors. Your agent prioritizes code written recently over stale or dead code.
4. Decoupled Architecture: Sits as an independent MCP server alongside krusch-context-mcp.
## ⚠️ Not a Replacement for Git
It is critical to understand that Krusch-Git does not replace Git or services like GitHub/GitLab. It does not handle branch merging, rebasing, or pull requests.
Instead, Krusch-Git is an agentic augmentation layer. You continue to use standard Git for your human-facing source control and team collaboration. Krusch-Git sits alongside it in your workflow, automatically ingesting your standard Git history to provide your AI agents with a mathematically optimized, semantically searchable clone of your codebase.
## 🔒 Reliability Audit & Pointer Resolution
To guarantee production-grade stability and complete continuity across complex monorepos, Krusch-Git underwent a thorough architectural audit and reliability overhaul:
1. Deterministic Pointer Resolution: In standard 'pointer' storage mode (used to keep the database lightweight), file content is stored as NULL in PostgreSQL. We introduced a dynamic resolver inside server/git-engine.js that maps relative blob paths to the local filesystem monorepo root. This automatically streams raw file contents from disk on demand, resolving previous null value crashes on the Express /api/blobs/:id route and kruschgitreadblob MCP tool.
2. Safe Semantic Search Previews: Standard semantic search tool calls throw TypeErrors if they attempt to stringify nullable database columns. Krusch-Git now safely extracts the pre-compiled summary column (generated using qwen2.5-coder:7b inline summaries) to serve as the context preview.
3. Starvation-Proof Queue Management: The fleet priority queue (PriorityQueue.process) inside lib/llm-queue.js is secured using a strict try ... finally block. This guarantees that concurrent slots are cleanly released (this.active--) under all task outcomes, preventing memory and slot leaks that would otherwise block multi-agent swarm operations.
4. Fidelity-Preserved Embedding Backfills: Upgraded backfillembeddings.js to automatically resolve local disk paths when processing pointer-mode blobs. This enables the embedding backfill process to compute full-fidelity, chunked centroid embeddings from the original code rather than falling back to lossy, shortened summary snippets.