Product Knowledge Hub

Version-aware code intelligence for AI agents.

Query any version. Search any file. Verify any feature. Instantly.

---

Why This Exists

AI agents are powerful, but they lack awareness of your codebase across versions. They guess at code structure, assume features exist when they don't, and can't answer "how did this work in v1.0?"

Product Knowledge Hub gives your AI agent direct access to the Source of Truth—your codebase at any version. Agents can "teleport" into any release to retrieve accurate, version-specific facts without checking out git branches.

The Old Way (Guesswork)	The Knowledge Hub Way (Ground Truth)
Agent guesses at code structure	Agent searches actual code at the exact version
Agent assumes features exist	Agent verifies feature existence before proceeding
Context switching takes seconds/minutes (Git checkout)	Context switching takes milliseconds (Zero-Checkout)

---

Key Capabilities

• Zero-Checkout Architecture — Search code, read files, and grep patterns across 10+ versions simultaneously without touching your disk.

• Automatic BOM Mapping — Translates marketing versions (e.g., "v2.16") into exact technical commit hashes for every microservice and component.

• Native MCP Support — Plug-and-play with Claude Desktop, Cursor, or any MCP-compliant agent.

• Hallucination Guardrails — Agents can use check_capability to verify if a feature exists before attempting to test it.

---

Quick Start

Get up and running in less than 2 minutes.

1. Install & Sync

git clone https://github.com/dcohnlif/product-knowledge-hub.git
cd product-knowledge-hub
uv sync

2. Define Your Product

Option A: Use the setup wizard (recommended):

# Unix (macOS/Linux)
./setup.sh

# Windows
setup.bat

The wizard automatically creates product.yaml from the example template and guides you through configuration.

Option B: Edit manually — Copy the example and customize:

cp product.yaml.example product.yaml
# Edit product.yaml with your repository URLs

Single repository (most common):

name: "MyProject"
repositories:
  my-app:
    url: "https://github.com/myorg/my-app.git"   # <-- CHANGE THIS
    is_primary_operator: true   # Version tags are read from this repo
version_config:
  tag_prefixes: ["v*"]   # Scans for tags like v1.0.0, v2.0.0

Multiple repositories:

name: "MyProject"
repositories:
  frontend:
    url: "https://github.com/myorg/frontend.git"
    is_primary_operator: true   # Pick ONE repo where version tags live
  backend:
    url: "https://github.com/myorg/backend.git"
  docs:
    url: "https://github.com/myorg/docs.git"
version_config:
  tag_prefixes: ["v*"]

Tip: Run uv run cli.py validate product.yaml to check your configuration.

3. Initialize

# Clones repos (once) and generates the version matrix
uv run cli.py setup

4. Give Your Agent Superpowers

Start the MCP server to expose tools to your AI agent.

uv run cli.py serve

---

The Brain: MCP Tools

Once connected, your AI Agent gains access to these tools:

Tool	What It Does
search_code	Search code with regex at any version — "Find all API routes in v2.0"
read_file	Read any file at any version — "Show me App.tsx from v1.5"
list_versions	List all available versions in the knowledge base
check_capability	Verify if a feature exists in a version before proceeding
locate_ui_element	Find UI selectors (data-testid, aria-label) for test automation
verify_backend	Find API routes and type definitions
cross_reference	Link documentation concepts to implementation code
refresh_knowledge	Fetch latest tags and update the version matrix

---

Performance Comparison

Traditional Git Switching:

# Slow. Mutates disk. Breaks other processes.
git checkout v2.16.0  # 5-30s
grep -r "handleAuth" src/

Product Knowledge Hub:

# Instant. No side effects. Parallel-safe.
uv run cli.py search v2.16.0 "handleAuth" --repo my-app  # <200ms

---

Configuration Reference

The system is fully agnostic. It works for Monorepos, Polyrepos, K8s Operators, and standard Web Apps.

Advanced product.yaml Example

repositories:
  my-repo:
    url: "https://github.com/org/repo.git"
    version_paths: ["kustomization.yaml"]  # Auto-detect component versions
    version_pattern: "ref=\\s*([v0-9.]+)"

feature_heuristics:
  # Teach the agent how to verify feature existence
  dark_mode:
    repo: "frontend"
    pattern: "ThemeContext"
    description: "Dark mode theme support"

ui_search:
  default_repo: "frontend"
  search_paths: ["src/components", "src/pages"]
  selector_patterns: ['data-testid[="{].*']

---

Architecture

The system sits between your AI Agent and your Git Repositories, acting as a high-speed translation layer.

┌─────────────────────────────────────────────────────────────┐
│                                                             │
│   ┌──────────┐         ┌─────────────────┐                  │
│   │ AI Agent │◄───────►│  Knowledge Hub  │                  │
│   └──────────┘   MCP   └────────┬────────┘                  │
│                                 │                           │
│                    ┌────────────┴────────────┐              │
│                    │                         │              │
│              ┌─────▼─────┐           ┌───────▼───────┐      │
│              │    BOM    │           │   GitLens     │      │
│              │  Lookup   │           │  (git grep)   │      │
│              └─────┬─────┘           └───────┬───────┘      │
│                    │                         │              │
│              ┌─────▼─────────────────────────▼─────┐        │
│              │       Local Git Mirrors (repos/)    │        │
│              └─────────────────┬───────────────────┘        │
│                                │ fetch                      │
│                         ┌──────▼──────┐                     │
│                         │ GitHub/Lab  │                     │
│                         └─────────────┘                     │
│                                                             │
└─────────────────────────────────────────────────────────────┘

---

Use Cases

• Code Exploration — "Find all API endpoints in v2.5" or "How does authentication work in this version?"

• Documentation Assistants — Chatbots answer questions about any version by reading the actual code.

• Version Comparison — "What changed between v3 and v4?" — search both versions instantly.

• Support Tools — Look up code in the exact version a customer is running.

• Test Automation — Find exact Playwright/Cypress selectors, verify features exist before testing.

• Migration Helpers — Understand legacy code structure when planning upgrades.

---

CLI Commands

Command	Description
setup	Clone repos and generate version matrix
update	Fetch latest from all repos
versions	List available versions
search	Quick code search
read	Read file at version
serve	Start MCP server
status	Show hub status
config	Show configuration
validate	Validate a product.yaml

---

Claude Desktop Integration

Add to ~/.config/claude/mcp.json:

{
  "mcpServers": {
    "product-knowledge": {
      "command": "uv",
      "args": ["run", "cli.py", "serve"],
      "cwd": "/path/to/product-knowledge-hub"
    }
  }
}

---

Requirements

• Python 3.11+
• uv package manager
• Git 2.25+
• Disk space for repository clones

---

Testing

The project includes a comprehensive test suite with 157 tests covering all modules.

# Install dev dependencies
uv sync --dev

# Run all tests
uv run python -m pytest tests/ -v

# Run with coverage
uv run python -m pytest tests/ --cov=src --cov-report=term-missing

For detailed testing documentation, CI integration, and test categories, see tests/TESTS.md.

---

Contributing

We love contributions! Please see CONTRIBUTING.md.

License

Apache 2.0 — see LICENSE.