The Engineering Context Layer for Repositories. Native GitHub Bot & MCP Server.
Transform raw PR diffs, complex issue threads, and distributed architectures into grounded, hallucination-free engineering handoffs and developer context.
📖 Integration Guide • 🔌 MCP Server Guide • 🗺️ Roadmap • 📜 KNOWLEDGE.md Specification
| 📄 Generic Bots & Chat LLMs | 🧠 Knowledge Engineering Context Layer |
|---|---|
| Hallucinated Code: Confidently invents non-existent APIs, endpoints, and arguments. | Strict Evidence Grounding: Every claim cites verified lines: [repo:path/file.py#L1-L20]. Unverified claims are explicitly stamped "Unknown". |
| Siloed & Single-Repo: Incapable of tracing cross-service contracts or companion repos. | Cross-Repository Intelligence: Discovers trees & traces contracts across frontend, backend, and shared microservices. |
| Silent Documentation Drift: Stale READMEs and guides trick new engineers into broken setups. | AST Doc-Verifier: Statically cross-references docs against Python/TypeScript AST and route symbols to surface discrepancies. |
| One-Size-Fits-All Jargon: Dumps confusing code dumps to beginners or trivial fluff to seniors. | Adaptive Depth Calibration: 1–10 point system dynamically scales explanation from conceptual analogies to AST/schema traces. |
| Context Overflows & Bloat: Dumps unconstrained files into prompts, blowing token budgets. | Hunk-Aware Bounded Context: Strict char and diff budgeting extracts high-signal diff chunks and conversation threads. |
| Walled Garden: Locked exclusively into a single web chat UI or browser tab. | Universal Interface: Native GitHub Bot (Actions/Webhook), stdio/SSE MCP Server (Cursor/Claude), CLI, and Streamlit UI. |
"Software engineers spend up to 60% of their time deciphering undocumented PRs, tracing distributed services, and debugging stale documentation. Knowledge bridges the gap between raw codebase reality and high-signal, verified engineering handoffs."
Knowledge is an open-source engineering context layer designed to run natively inside your developer workflows.
When a contributor or maintainer comments @Knowledge <question> or /knowledge <question> on any GitHub Issue or Pull Request, Knowledge:
- Classifies query intent across 7 engineering categories.
- Retrieves bounded, hunk-aware evidence across repository files, companion services, and discussion threads.
- Cross-references claims & AST symbols to verify implementation against documentation.
- Enforces repository guardrails parsed directly from
KNOWLEDGE.md. - Calibrates technical depth (1–10 internal score) based on the user's inquiry style.
- Posts a structured engineering handoff directly back into GitHub with exact line citations.
For AI coding agents (Cursor, Claude Desktop, Claude Code, Windsurf, Devin), Knowledge acts as a Native Model Context Protocol (MCP) Server, feeding real repository context instead of letting agents guess at your architecture.
- 🛡️ Zero-Hallucination & Strict Line Citations: Every claim is backed by immutable Git references, file lines, or commit diffs. Missing information is explicitly stamped as
"Unknown". - 🎯 Adaptive Technicality Calibration: Dynamic 1–10 scoring engine scales context from high-level architectural analogies (1–3) to low-level AST, SQL schema, and HTTP endpoint traces (7–10) without leaking point values.
- 🌐 Cross-Repository Intelligence: Automatically connects companion repositories (e.g. tracing a React
layout.tsxto a backend FastAPI endpoint or shared auth service). - 🔍 AST Doc-Verifier & Anti-Drift Engine: Statically inspects Python and TypeScript AST to detect discrepancies between written documentation and actual code signatures.
- 🔌 Native Model Context Protocol (MCP): Exposes architecture exploration, doc drift verification, and issue/PR lineage tools to modern IDE agents over stdio or SSE transports.
- 📜 Maintainer Guardrail Enforcement: Parses repository guidelines and protected boundary directives from
KNOWLEDGE.mddirectly into the LLM system prompt. - ⚡ Multi-LLM Provider Architecture: Zero-bloat REST adapters for Mistral AI, OpenAI, Anthropic Claude, Google Gemini, Groq, and local Ollama without heavy external SDK lock-in.
Knowledge is currently at v0.3.1, with its core evidence engine, multi-provider support, and MCP server fully active in production.
- 🟢 Completed: Native GitHub bot interactions, multi-LLM adapters (Mistral, OpenAI, Claude, Gemini, Groq, Ollama), bounded context retriever, AST doc-verifier, multi-repository intelligence, persistent repository memory, and Model Context Protocol (MCP) server.
- 🟡 In Progress: Human engineering Knowledge Transfer (KT) phrasing, interactive contribution guidance paths, and multi-file code drift auto-patching.
- 🔵 Upcoming: Repository learning roadmaps ("Teach me this repo in 30 minutes"), team engineering activity graphs, and unified engineering context platform.
We build in the open. Feature requests, architecture feedback, and pull requests are welcomed!
┌──────────────────────────────────────────────────────────┐
│ DEVELOPER INPUT │
└────────────────────────────┬─────────────────────────────┘
│
┌──────────────────────────────────┬───────┴──────────┬─────────────────────────────────┐
▼ ▼ ▼ ▼
┌───────────────────┐ ┌───────────────────┐┌───────────────────┐ ┌───────────────────┐
│ 🐙 GITHUB ACTION │ │ 🔌 MCP SERVER ││ ⚡ WEBHOOK SERVER │ │ 📊 STREAMLIT UI │
│ Issue / PR Comment│ │ Cursor / Claude ││ FastAPI (HMAC-256)│ │ Interactive Graph │
└─────────┬─────────┘ └─────────┬─────────┘└─────────┬─────────┘ └─────────┬─────────┘
│ │ │ │
└─────────────────────────────────┴──────────┬─────────┴─────────────────────────────────┘
│
▼
┌───────────────────────────────────┐
│ INTENT CLASSIFIER (7 Modes) │
│ PR, Issue, Architecture, Onboard │
└─────────────────┬─────────────────┘
│
▼
┌───────────────────────────────────┐
│ BOUNDED CONTEXT RETRIEVER │
│ Hunk-Aware Diff • Companion Repos│
│ KNOWLEDGE.md Rules • AST Symbols │
└─────────────────┬─────────────────┘
│
▼
┌───────────────────────────────────┐
│ ADAPTIVE DEPTH CALIBRATION │
│ 1-10 Dynamic Technicality Score │
└─────────────────┬─────────────────┘
│
▼
┌───────────────────────────────────┐
│ MULTI-LLM REST ENGINE │
│ Mistral • OpenAI • Claude • Ollama│
└─────────────────┬─────────────────┘
│
▼
┌───────────────────────────────────┐
│ GROUNDED ENGINEERING HANDOFF │
│ Scope • Verification • Guardrails │
│ Repository Line-Scoped Citations │
└───────────────────────────────────┘
Knowledge offers flexible integration pathways to match your workflow requirements:
┌─────────────────────────────────────────────────────────┐
│ CHOOSE YOUR ACCESS MODEL │
└────────────────────────────┬────────────────────────────┘
│
┌─────────────────────────────────┼─────────────────────────────────┐
▼ ▼ ▼
┌───────────────────┐ ┌───────────────────┐ ┌───────────────────┐
│ 🟢 GITHUB ACTIONS │ │ 🟡 MCP SERVER │ │ 🔵 WEBHOOK DAEMON │
│ 1-Minute Setup │ │ Cursor & Claude │ │ Dedicated Server │
│ Zero-Config CI │ │ Local IDE Agent │ │ Custom Domain/App │
└───────────────────┘ └───────────────────┘ └───────────────────┘
| Deployment Tier | Best For | Prerequisites | Security Model |
|---|---|---|---|
| 🟢 GitHub Actions | Any GitHub repository (Issues & PRs) | Copy .github/workflows/knowledge.yml |
Standard GitHub Actions token isolation |
| 🟡 Native MCP Server | Cursor, Claude Desktop, Claude Code | pip install -e ".[mcp]" |
Local stdio or authenticated SSE stream |
| 🔵 FastAPI Webhook | High-volume organizations & real-time bots | Python 3.10+ server / container | HMAC-SHA256 GitHub signature verification |
| 🟣 Streamlit Dashboard | Local context exploration & visual graphs | pip install -e ".[dashboard]" |
Local developer sandbox environment |
The fastest way to install Knowledge Bot into any repository is copying the workflow and adding your rulebook:
Your-Repo/
├── .github/workflows/
│ └── knowledge.yml # Copied from templates/knowledge.yml
├── knowledge_agent/ # Core package directory (copied whole)
├── knowledge_engine.py # Unified core engine facade
└── KNOWLEDGE.md # Repository rulebook & maintainer directives
💡 Automated Setup Prompt: Have Cursor or Claude Code do it for you! Simply paste docs/Integration.md into your coding assistant.
Navigate to Settings ➔ Secrets and variables ➔ Actions in your repository and configure your preferred provider API key:
| Secret Name | Provider | Default Model | Environment Variable Override |
|---|---|---|---|
MISTRAL_API_KEY |
Mistral AI | mistral-small-2506 |
MISTRAL_MODEL |
OPENAI_API_KEY |
OpenAI | gpt-4o-mini |
OPENAI_MODEL |
ANTHROPIC_API_KEY |
Anthropic Claude | claude-3-5-haiku-20241022 |
ANTHROPIC_MODEL |
GEMINI_API_KEY |
Google Gemini | gemini-1.5-flash |
GEMINI_MODEL |
GROQ_API_KEY |
Groq Ultra-Fast | llama-3.3-70b-versatile |
GROQ_MODEL |
Comment on any Issue or Pull Request:
@Knowledge How is authentication wired between the frontend and backend in this repo?
/knowledge Explain the changes in this PR and how to test them locally.
🛠️ Click here for Advanced Multi-Repo & Local Ollama Configurations
To allow Knowledge to investigate companion repositories, declare them in KNOWLEDGE.md:
## Related Repositories
- `acme/backend-api`: Core FastAPI backend, database models, and REST endpoints
- `acme/shared-ui`: Cross-project design system componentsOr via environment variable:
export KNOWLEDGE_RELATED_REPOS="acme/backend-api, acme/shared-ui"Run Knowledge completely offline without sending code to third-party APIs:
export LLM_PROVIDER=ollama
export OLLAMA_HOST=http://localhost:11434
export OLLAMA_MODEL=llama3.2:latestFine-tune character truncation limits:
export KNOWLEDGE_MAX_FILE_CHARS=3000 # Primary files (README, KNOWLEDGE.md)
export KNOWLEDGE_MAX_COMMENT_CHARS=2500 # Code and architecture matches
export KNOWLEDGE_MAX_DIFF_CHARS=1500 # Manifest files and diffsKnowledge exposes its bounded evidence engine, AST doc-verifier, and issue/PR lineage directly to AI coding assistants via the Model Context Protocol.
# Install with MCP dependencies
pip install -e ".[mcp]"
# stdio transport (Cursor, Claude Desktop, Claude Code)
knowledge-agent mcp --stdio
# Or SSE transport (Shared or daemon instances)
knowledge-agent mcp --sse --host 127.0.0.1 --port 8765Claude Desktop (claude_desktop_config.json)
{
"mcpServers": {
"knowledge": {
"command": "knowledge-agent",
"args": ["mcp", "--stdio"],
"env": {
"GITHUB_TOKEN": "ghp_your_github_pat_token",
"KNOWLEDGE_OWNER": "your-org",
"KNOWLEDGE_REPO": "your-repo"
}
}
}
}Cursor (.cursor/mcp.json)
{
"mcpServers": {
"knowledge": {
"command": "knowledge-agent",
"args": ["mcp", "--stdio"],
"env": {
"GITHUB_TOKEN": "ghp_your_github_pat_token",
"KNOWLEDGE_OWNER": "your-org",
"KNOWLEDGE_REPO": "your-repo"
}
}
}
}Exposed MCP Tools:
knowledge_get_architecture_context(query, repo_path)— Grounded mental model and evidence chain for any subsystem.knowledge_verify_doc_drift(doc_path, code_dir)— AST discrepancy detection between documentation claims and code symbols.knowledge_trace_issue_pr(issue_or_pr_number)— Lineage tracing between issue discussions, PR diffs, and affected components.
(Full tool signatures and SSE guides: docs/MCP.md)
Inspect repository context graphs, test query classifications, and visualize evidence clusters:
streamlit run apps/app.pyDeploy real-time webhook endpoints with HMAC-SHA256 signature verification:
# Start FastAPI Webhook daemon on port 8000
python apps/webhook_server.pySet
GITHUB_WEBHOOK_SECRETin your environment to automatically enforce cryptographic HMAC signature validation on all incoming GitHub webhooks.
Whether you are improving prompt fencing, expanding AST support to more languages, adding LLM adapters, or refining documentation—contributions are warmly welcomed!
git clone https://github.com/PrithvijitBose/Knowledge-Agent.git
cd Knowledge-Agentpython -m venv .venv
# Windows
.venv\Scripts\activate
# macOS / Linux: source .venv/bin/activate
pip install -e ".[dev,mcp,dashboard,server]"knowledge-agent --help
# Or: python -m knowledge_agent --helpThe test suite is 100% hermetic and offline (utilizing mock fixtures and zero external network dependencies):
# Run the complete test suite (270+ tests)
python -m pytest
# Run specific test modules
python -m pytest tests/test_adaptive_depth.py
python -m pytest tests/test_doc_verifier.py
python -m pytest tests/test_mcp_server.py- Create a feature branch:
git checkout -b feature/grounded-improvement - Commit with conventional commit messages:
git commit -m "feat(retriever): add AST support for Go interfaces" - Verify test suite passes:
python -m pytest - Push your branch and open a Pull Request on GitHub.
Connect with fellow contributors, suggest features, and get live help:
Knowledge is open-source software licensed under the MIT License.
MIT License
Copyright (c) 2026 Poorvith M P & Knowledge Contributors
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
(See full license text in LICENSE)