Skip to content

How Our System Fits Into the Code Intelligence Ecosystem

Purpose: Understanding our place alongside structural code analysis platforms Branch: research/code-understanding-platforms

Executive Summary

This document analyzes the current code intelligence landscape and explains how our Knowledge Graph System fills a critical gap that existing platforms don't address: understanding the narrative of human collaboration.

The Missing Piece

Current enterprise platforms (Sourcegraph, GitHub Copilot, Tabnine, Amazon Q) excel at structural code analysis: - They parse code into Abstract Syntax Trees (AST) - Index symbols, functions, classes, and types - Map technical dependencies and references - Answer questions about code structure

But they struggle with human narrative: - Why was this architectural decision made? - What trade-offs were discussed? - How did this concept evolve over time? - What contradictions exist in our approach? - Who understands this domain area?

Our Role in the Ecosystem

We solve the harder problem: making sense of unstructured human communication.

Structural code analysis is well-understood computer science: - Deterministic parsing - Precise symbol resolution - Language-specific but solvable

Narrative understanding is fundamentally harder: - Requires interpreting human intent - Context-dependent and probabilistic - Concepts evolve and contradict over time - Cross-document synthesis needed

Integration, Not Competition

Our system is designed to work alongside existing tools:

Question Type Tool to Use Why
"Where is this function called?" Sourcegraph Structural code navigation
"How do I implement feature X?" GitHub Copilot Code generation assistance
"Complete this code pattern" Tabnine Context-aware completion
"Why did we choose this approach?" Our System Narrative understanding
"What ADRs relate to authentication?" Our System Cross-document concept synthesis
"How has error handling evolved?" Our System Temporal concept analysis

Use them together. Navigate code structure with Sourcegraph, understand human decisions with our system.

1. Sourcegraph

Official Description

"Universal code search and intelligence platform"

Core Approach

Technology Stack: - SCIP (SCIP Code Intelligence Protocol): Language-agnostic code intelligence format - LSIF (Language Server Index Format): Precomputed code navigation data - Auto-indexing: Automated background workers that analyze code and produce indexes - Code Graph: Structured representation of code relationships

How It Works: 1. Executors clone Git repositories into secure sandboxes 2. Language-specific analyzers parse code into AST (Abstract Syntax Tree) 3. Generates SCIP/LSIF indexes with: - Symbol definitions and references - Cross-repository navigation paths - Type information and documentation 4. Indexes stored in SQLite bundles for fast querying 5. PageRank-style algorithm ranks search results by relevance

What It Understands: - ✅ Function/class definitions and usages - ✅ Cross-repository dependencies - ✅ Code references ("where is this function called?") - ✅ Type hierarchies and implementations - ❌ Why code was written (no commit history analysis) - ❌ Architectural decisions (no ADR/RFC integration) - ❌ Conceptual relationships beyond code structure

AI Integration (2025): - Cody: AI assistant that uses code graph + LLMs for context-aware answers - Deep Search: Agentic search tool for rapidly evolving codebases - Uses code graph to provide relevant context to LLMs

Performance Characteristics

  • 2x speedup in query latency (recent optimizations)
  • 50% reduction in memory/disk load
  • Works with codebases of any size (battle-tested at scale)

2. GitHub Copilot Spaces

Official Description

"Bring together the context Copilot needs — files, pull requests, issues, and repos"

Core Approach

Technology Stack: - Remote Code Search Indexes: Maintained by GitHub for quick codebase search - Spaces: Persistent context containers with files, repos, PRs, issues - Evergreen Indexing: Automatically updated as code changes - MCP Integration: Access spaces directly in IDEs

How It Works: 1. Users create "Spaces" and add relevant context: - Files from repos - Pull requests - Issues - Entire repositories 2. GitHub maintains up-to-date indexes of all context 3. LLM queries use indexed context for grounded responses 4. Available in github.com and IDE (via MCP server)

What It Understands: - ✅ File contents and structure - ✅ Pull request discussions - ✅ Issue descriptions and comments - ✅ Repository-wide patterns - ✅ Cross-file relationships - ⚠️ Some commit history (via PR integration) - ❌ Explicit conceptual relationships - ❌ Architectural decision rationale

Key Innovation: Combines structural code knowledge (files, functions) with discussion context (PRs, issues) in persistent workspaces.

Enterprise Features

  • Workspace indexing (local or GitHub-maintained)
  • Works with GitHub and Azure DevOps repositories
  • IDE integration via remote MCP server

3. Tabnine

Official Description

"AI Code Assistant with Total Enterprise Control"

Core Approach

Technology Stack: - RAG (Retrieval-Augmented Generation): Semantic retrieval of relevant code - SEM-RAG: Semantic RAG enhancement for better context - Local + Global Code Awareness: Two-level context system - Graph-based techniques: Maps relationships between services/functions/files

How It Works:

Level 1: Local Code Awareness (GA) 1. Analyzes open file and related files in IDE workspace 2. Extracts type information in current scope 3. Builds local RAG indices for fast retrieval 4. Uses semantic embeddings to find relevant snippets

Level 2: Global Code Awareness (Enterprise) 1. Continuously indexes organization's repositories 2. Real-time semantic and graph-based indexing 3. Maps relationships across services, functions, files 4. Retrieves context beyond local IDE workspace 5. Respects existing git-hosting permission models

What It Understands: - ✅ Local file context and dependencies - ✅ Organization-wide code patterns - ✅ Semantic relationships via embeddings - ✅ Cross-service relationships - ✅ Type systems and function signatures - ⚠️ Some architectural patterns (inferred from code structure) - ❌ Explicit architectural decisions (no ADR integration) - ❌ Historical evolution (no commit analysis)

Key Innovation: RAG-based approach enables semantic search beyond keyword matching, using embeddings to understand code meaning.

Enterprise Integration

  • Connects to GitHub, GitLab, Bitbucket
  • Permission-aware (users only access repos they have rights to)
  • Private deployment option for sensitive codebases

4. Amazon Q Developer (formerly CodeWhisperer)

Official Description

"AI-driven code generation, debugging, and security scanning"

Core Approach

Technology Stack: - Proprietary AWS foundation models - Reference tracking system for open-source compliance - Security scanning integrated into development workflow - SSO via IAM Identity Center (Enterprise)

How It Works: 1. Analyzes codebase to understand relationships across files 2. Uses AI to generate code based on context 3. Provides chat interface for questions and explanations 4. AI agents handle feature implementation, testing, docs, refactoring 5. Security scanning detects vulnerabilities

What It Understands: - ✅ Cross-file relationships - ✅ Code patterns and idioms - ✅ Security vulnerabilities - ✅ Open-source licensing requirements - ⚠️ Feature requirements (via agent interface) - ❌ Architectural rationale - ❌ Historical context (commit history)

Key Innovation: AI agents can autonomously implement features with minimal input - describe a feature, Q analyzes codebase, generates plan, executes changes.

Enterprise Features

  • SOC, ISO, HIPAA, PCI compliance
  • IP indemnity protection
  • Usage analytics and policy controls
  • Automatic data opt-out for Pro users

5. Code Knowledge Graphs (Research/Open Source)

Neo4j Codebase Knowledge Graph

Approach: - Uses Neo4j graph database to model code structure - Entities: classes, methods, packages, dependencies - Relationships: CALLS, EXTENDS, IMPLEMENTS, DEPENDS_ON - Built using tools like Strazh for .NET Core projects

What It Understands: - ✅ Fine-grained code structure (method-level) - ✅ Call graphs and dependency chains - ✅ Inheritance hierarchies - ✅ Package/module organization - ❌ Semantic meaning of code - ❌ Historical evolution - ❌ Architectural decisions

GraphGen4Code (IBM Research)

Approach: - Toolkit for building code knowledge graphs - Uses WALA for code analysis - Extracts documentation and forum content - Combines code structure with external knowledge

What It Understands: - ✅ Code structure (from static analysis) - ✅ API documentation - ✅ Forum discussions (Stack Overflow, etc.) - ✅ Links between code and external resources - ⚠️ Some semantic meaning (via documentation) - ❌ Repository history - ❌ Organizational context

Scale: - Applied to 1.3M Python files from GitHub - 2,300 Python modules - 47M forum posts

Use Cases: - Program search - Code understanding - Bug detection - Code automation

Comparison Table

Platform Focus Technology Context Level Historical Semantic
Sourcegraph Code navigation SCIP/LSIF indexing Repository ❌ Structural
GitHub Copilot Spaces AI assistance LLM + indexes Workspace + PRs ⚠️ (via PRs) LLM-based
Tabnine Code completion RAG + embeddings Local + Global ❌ Semantic (embeddings)
Amazon Q Developer Code generation AWS LLMs Cross-file ❌ LLM-based
Neo4j Code KG Code structure Graph DB Call graphs ❌ Structural
GraphGen4Code Code + docs WALA + crawling Code + forums ❌ Hybrid
Our System Dev narrative LLM extraction Commits + PRs + ADRs ✅ Conceptual

How Our Approach Differs

What We Do Differently

1. Narrative Focus, Not Structure - We don't parse code - we parse the story of code - Commit messages, PR descriptions, ADRs, documentation - Extracts why and how decisions were made - Understands evolution over time

2. Concept Extraction, Not Symbol Indexing - Platforms index symbols (functions, classes, variables) - We extract concepts (ideas, decisions, problems, solutions) - Relationships are conceptual (IMPLIES, SUPPORTS, CONTRADICTS) - Not tied to code structure

3. Multi-Document Synthesis - Combines commits, PRs, issues, ADRs, docs - Discovers relationships across document types - Traces ideas from decision (ADR) → implementation (commit) → deployment (PR)

4. Temporal Understanding - Tracks how concepts evolved - Identifies contradictions (old approach vs. new approach) - Shows decision trajectories - Grounding system validates concept truth over time

5. Semantic Queries, Not Keyword Search - Vector similarity search on concept embeddings - Find related ideas, not just matching text - Path finding between concepts - Graph traversal for concept neighborhoods

What We Don't Do (Yet)

❌ Code-level analysis (no AST parsing, no call graphs) ❌ Real-time IDE integration (no inline completions) ❌ Cross-repository symbol navigation (no "go to definition") ❌ Type inference (no language server integration) ❌ Security scanning (no vulnerability detection)

Our Example: git-repo-knowledge

Current Implementation

Location: examples/use-cases/git-repo-knowledge/

What It Does: 1. Extracts commits (extract_commits.py) - Uses GitPython to read git history - Converts to markdown with frontmatter metadata - Tracks last processed commit for incremental updates

  1. Extracts PRs (extract_prs.py)
  2. Uses GitHub CLI to fetch PR metadata
  3. Includes descriptions, labels, file changes

  4. Tracks last processed PR

  5. Ingests to Knowledge Graph (ingest.sh)

  6. Batch processing via kg ingest directory
  7. Separate ontologies for commits vs. PRs
  8. LLM extracts concepts from narratives
  9. Builds graph of conceptual relationships

Configuration: 

{
  "repositories": [{
    "name": "knowledge-graph-system",
    "path": "../../..",
    "ontology": "KG System Development",
    "last_commit": "22ae04f...",
    "last_pr": 90,
    "github_repo": "aaronsb/knowledge-graph-system",
    "enabled": true
  }]
}

Query Examples: 

# Find security-related work
kg search query "security encryption authentication"

# Trace concept evolution
kg search details <concept-id>

# Find related concepts
kg search related <concept-id> --depth 2

# Connect decisions to implementations
kg search connect "ADR-044" "Pull Request 66"

Strengths

✅ Simple: ~200 lines of Python + shell scripts ✅ Idempotent: Tracks state, only processes new items ✅ Incremental: Runs on schedule without re-processing ✅ Git hook ready: Could run on post-commit ✅ Conceptual: Extracts meaning, not just metadata ✅ Historical: Full temporal understanding ✅ Cross-cutting: Links commits, PRs, ADRs, docs

What It Deliberately Doesn't Do

Our example intentionally avoids trying to replicate structural code analysis:

❌ No AST parsing: We don't compete with Sourcegraph's code navigation ❌ No symbol indexing: We don't try to build call graphs ❌ No type resolution: We don't duplicate language server functionality ❌ No inline completions: We don't compete with Copilot/Tabnine

Why: These are solved problems with excellent existing tools. We focus on what they can't do: understanding human narrative.

What It Could Do More Of (Deepening Narrative Understanding)

While we deliberately don't pursue structural code analysis, there are areas where we could deepen our narrative intelligence:

  • Issue extraction: Complete the issue → commit → PR → deployment narrative
  • Review discussions: Capture architectural debates and design rationale from PR reviews
  • Cross-ontology synthesis: Better linking between multiple sources of narrative (commits + ADRs + docs)
  • Temporal contradiction detection: Identify when old approaches were replaced with new ones

Important: These would deepen our narrative focus, not add structural code features.

The git-repo-knowledge example showcases how narrative intelligence complements structural code analysis:

What developers experience: 

# Use Sourcegraph to navigate
"Show me all calls to validateToken()"  → Sourcegraph finds 47 references

# Then use our system to understand why
"Why did we implement token validation this way?"  → Our system traces the ADR decision + commits + PR discussion

The workflow: 1. Navigate code structure with Sourcegraph, Copilot, etc. 2. Understand human decisions with our system 3. Make informed changes with full context

Real-world scenario: - Junior dev needs to modify authentication - Sourcegraph shows them where the code lives - Our system shows them the architectural discussion that led to the current design - They understand trade-offs and can confidently make changes

The Future: AI Coding Agents and Narrative Explosion

The Coming Challenge

As AI coding agents (Copilot Workspace, Amazon Q, Cursor, etc.) become more prevalent, they will generate: - Extremely well-written commit messages explaining every change - Detailed PR descriptions with rationale and context - Comprehensive documentation for every feature - Thoughtful review comments on code changes

This creates a paradox:

More narrative, harder to understand: - Human developers will face an overwhelming volume of high-quality narrative - Every commit has a perfect 3-paragraph explanation - Every PR has detailed "Why" sections - Humans can't keep up reading all this content

The Context Window Reality

How AI agents actually work: - They operate in limited context windows (e.g., Claude Code: 200k tokens) - Each session produces "derivative summations" of their work: - Commit messages summarizing code changes - PR descriptions summarizing features - Documentation summarizing decisions - These summaries are outputs of constrained-context reasoning - The full context is lost after the session ends

The aggregation problem: 

Session 1 (9am): Claude Code writes auth feature → commits + PR summary
Session 2 (11am): Copilot refactors validation → commits + PR summary
Session 3 (2pm): Cursor fixes bug → commit summary
Session 4 (4pm): Q Developer adds tests → commits + PR summary
...
Day 30, Session 200: Where did we end up? Why did we make these choices?

A single developer might have 5-10 AI agent sessions per day. Over a month, that's 100-200 sessions. Over a year, thousands. Each produces summaries within its limited context window. Our system provides a highly effective way to aggregate and understand the full arc.

Self-demonstrating example: This very project: - Claude Code (me) has worked on this knowledge graph system across dozens of sessions - Each session ends with commits, PR descriptions, summaries - The system ingests its own development history - Query it to understand how architectural decisions evolved - The tool documents itself through use

Our unique value: We ingest all these small-context-window outputs and build long-term organizational memory: - Each AI session produces local summaries (200k context) - Our system aggregates across ALL sessions (unlimited temporal context) - Builds concept graph spanning months/years of AI-assisted development - Answers questions that span beyond any single AI agent's context window

Our Role Becomes Critical

This is exactly where narrative intelligence shines:

The problem we solve: 

Human Developer: "I need to understand authentication changes from the last 6 months"

Without our system:
- 347 commits with detailed messages (would take days to read)
- 23 PRs with comprehensive descriptions
- Dozens of review threads
- Multiple ADRs and docs

With our system:
- Query: "authentication evolution last 6 months"
- Get: Concept graph showing how authentication approach evolved
- See: Key decisions, contradictions resolved, trade-offs made
- Understand: The narrative arc in minutes, not days

We become the "narrative compression" layer: - AI agents generate verbose, high-quality narrative (great for context) - Our system extracts concepts and relationships (great for understanding) - Humans query the concept graph (great for staying current)

Unique Position in AI-Agent Future

System Type Role in AI-Agent Era Challenge
Sourcegraph Navigate AI-generated code Code complexity grows
GitHub Copilot Generate code + narrative Generates MORE narrative
Tabnine/Q Complete patterns Increases code velocity
Our System Synthesize AI-generated narrative Humans can't read it all

The harder problem: Making sense of perfect, verbose, AI-generated human communication at scale.

Our advantage: We're designed for this: - LLM-based concept extraction (understands AI-written text naturally) - Temporal analysis (tracks how AI agent decisions evolve) - Cross-document synthesis (links AI-generated commits + PRs + docs) - Contradiction detection (finds when AI agents changed approach)

Human-in-the-Loop at Scale

Current HITL (Human-in-the-Loop) model: 1. AI agent proposes code + writes detailed explanation 2. Human reviews explanation 3. Human approves or rejects

The bottleneck: Humans can't keep up with narrative volume as AI velocity increases.

Our solution: Concept-level review instead of document-level review: 

# Instead of reading 50 AI-generated commit messages:
kg search query "database migration strategy changes"

# See conceptual evolution:
- "Manual migration scripts" (deprecated)
→ "Automated migration with rollback" (current approach)
→ "Zero-downtime migrations" (upcoming)

# Understand in 30 seconds what would take 30 minutes to read

The Integration Dimension: MCP as the Bridge

A New Capability Emerges

When our narrative intelligence system is coupled with structural code analysis systems through MCP (Model Context Protocol), a unique dimension becomes accessible:

What MCP enables: 

AI Agent Query: "Why do we validate tokens this way?"

Via MCP:
1. Agent calls Sourcegraph MCP → gets code structure (where validateToken lives)
2. Agent calls our MCP → gets narrative (ADR-054 OAuth decision + PR #96 discussion)
3. Agent synthesizes both → complete answer with code + rationale

Result: A dimension not accessible through either system alone

The power of dual graphs: - Structural graph (Sourcegraph): code → calls → dependencies - Narrative graph (Our system): concepts → decisions → evolution - MCP integration: Bridges both graphs in real-time

New queries become possible: 

# Q: "Show me all code that implements 'zero-trust security'"
# 1. Our system finds the concept "zero-trust security"
# 2. Identifies commits that evidenced this concept
# 3. MCP call to Sourcegraph finds files changed in those commits
# 4. Return: Both narrative (why) and structure (where)

# Q: "This function seems complex - why was it designed this way?"
# 1. Sourcegraph identifies the function and its history
# 2. Our system finds ADRs, PRs, and discussions about it
# 3. Return: Implementation complexity + architectural rationale

MCP Makes It Real

Without MCP: Systems stay siloed - Use Sourcegraph OR our system - Manual context switching - Separate tools, separate workflows

With MCP: Systems compose - AI agents use BOTH simultaneously - Automatic context fusion - One query, multi-dimensional answer - The whole becomes greater than parts

This dimension becomes uniquely accessible: - Sourcegraph alone: knows structure, not narrative - Our system alone: knows narrative, not structure - Together via MCP: knows structure ↔ narrative relationships

Summary: Complementary by Design

They do what they do best: Parse code structure We do what we do best: Understand human (and AI-generated) narrative MCP does what it does best: Composes both into new capabilities

Together: Complete code intelligence ecosystem with emergent properties

The future we're building for: - AI agents write most code - AI agents write excellent documentation - Humans need to understand it all - Our system makes that possible - MCP makes the integration seamless

Appendix: Additional Research Sources

Academic Papers

  • "A Toolkit for Generating Code Knowledge Graphs" (IBM Research, 2021)
  • "Semantic-Enriched Code Knowledge Graph" (ACM TOSEM, 2023)
  • Various LSIF and SCIP specification documents

Commercial Documentation

  • Sourcegraph Docs: https://docs.sourcegraph.com/code_intelligence
  • GitHub Copilot Workspace: https://githubnext.com/projects/copilot-workspace
  • Tabnine Docs: https://docs.tabnine.com/
  • Amazon Q Developer: https://aws.amazon.com/codewhisperer/q/

Open Source Projects

  • GraphGen4Code: https://github.com/wala/graph4code
  • Sourcegraph Code Intel Extensions: https://github.com/sourcegraph/code-intel-extensions
  • Tree-sitter (parsing): https://tree-sitter.github.io/tree-sitter/