knowledge-master 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (26) hide show
  1. knowledge_master-0.1.0/LICENSE +21 -0
  2. knowledge_master-0.1.0/PKG-INFO +275 -0
  3. knowledge_master-0.1.0/README.md +237 -0
  4. knowledge_master-0.1.0/knowledge_master/__init__.py +0 -0
  5. knowledge_master-0.1.0/knowledge_master/__main__.py +4 -0
  6. knowledge_master-0.1.0/knowledge_master/chunking.py +106 -0
  7. knowledge_master-0.1.0/knowledge_master/cli.py +344 -0
  8. knowledge_master-0.1.0/knowledge_master/embeddings.py +21 -0
  9. knowledge_master-0.1.0/knowledge_master/intelligence.py +254 -0
  10. knowledge_master-0.1.0/knowledge_master/parsers/__init__.py +0 -0
  11. knowledge_master-0.1.0/knowledge_master/parsers/git_repo.py +115 -0
  12. knowledge_master-0.1.0/knowledge_master/parsers/markdown.py +58 -0
  13. knowledge_master-0.1.0/knowledge_master/server.py +194 -0
  14. knowledge_master-0.1.0/knowledge_master/store.py +164 -0
  15. knowledge_master-0.1.0/knowledge_master/watcher.py +104 -0
  16. knowledge_master-0.1.0/knowledge_master/web.py +568 -0
  17. knowledge_master-0.1.0/knowledge_master.egg-info/PKG-INFO +275 -0
  18. knowledge_master-0.1.0/knowledge_master.egg-info/SOURCES.txt +24 -0
  19. knowledge_master-0.1.0/knowledge_master.egg-info/dependency_links.txt +1 -0
  20. knowledge_master-0.1.0/knowledge_master.egg-info/entry_points.txt +3 -0
  21. knowledge_master-0.1.0/knowledge_master.egg-info/requires.txt +17 -0
  22. knowledge_master-0.1.0/knowledge_master.egg-info/top_level.txt +1 -0
  23. knowledge_master-0.1.0/pyproject.toml +55 -0
  24. knowledge_master-0.1.0/setup.cfg +4 -0
  25. knowledge_master-0.1.0/tests/test_chunking.py +29 -0
  26. knowledge_master-0.1.0/tests/test_intelligence.py +21 -0
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Milenko Mitrovic
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,275 @@
1
+ Metadata-Version: 2.4
2
+ Name: knowledge-master
3
+ Version: 0.1.0
4
+ Summary: Local-first knowledge graph for developers. Your AI agent's permanent memory.
5
+ Author: Milenko Mitrovic
6
+ License: MIT
7
+ Project-URL: Homepage, https://github.com/subzone/knowledge-master
8
+ Project-URL: Repository, https://github.com/subzone/knowledge-master
9
+ Project-URL: Issues, https://github.com/subzone/knowledge-master/issues
10
+ Keywords: rag,knowledge-graph,mcp,ai,developer-tools,vector-search
11
+ Classifier: Development Status :: 3 - Alpha
12
+ Classifier: Intended Audience :: Developers
13
+ Classifier: License :: OSI Approved :: MIT License
14
+ Classifier: Programming Language :: Python :: 3.11
15
+ Classifier: Programming Language :: Python :: 3.12
16
+ Classifier: Programming Language :: Python :: 3.13
17
+ Classifier: Topic :: Software Development :: Libraries
18
+ Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
19
+ Requires-Python: >=3.11
20
+ Description-Content-Type: text/markdown
21
+ License-File: LICENSE
22
+ Requires-Dist: falkordb<2.0,>=1.6.0
23
+ Requires-Dist: ollama<1.0,>=0.4.0
24
+ Requires-Dist: mcp<2.0,>=1.9.0
25
+ Requires-Dist: typer<1.0,>=0.15.0
26
+ Requires-Dist: gitpython<4.0,>=3.1.0
27
+ Requires-Dist: rich<15.0,>=14.0.0
28
+ Requires-Dist: fastapi<1.0,>=0.115.0
29
+ Requires-Dist: uvicorn<1.0,>=0.34.0
30
+ Provides-Extra: office
31
+ Requires-Dist: python-docx<2.0,>=1.1.0; extra == "office"
32
+ Requires-Dist: openpyxl<4.0,>=3.1.0; extra == "office"
33
+ Requires-Dist: pypdf<6.0,>=5.0; extra == "office"
34
+ Provides-Extra: dev
35
+ Requires-Dist: pytest>=8.0; extra == "dev"
36
+ Requires-Dist: ruff>=0.11; extra == "dev"
37
+ Dynamic: license-file
38
+
39
+ # ⚑ Knowledge Master
40
+
41
+ **Your codebase's memory.** A local knowledge graph that gives AI agents real understanding of your architecture β€” not just text search.
42
+
43
+ [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
44
+
45
+ ---
46
+
47
+ ## Why
48
+
49
+ Every time you start a new AI chat, it forgets everything. You re-explain your architecture, conventions, dependencies. Knowledge Master gives your AI **permanent, structured memory** about your entire system.
50
+
51
+ Unlike flat RAG tools that return "chunks about X", Knowledge Master builds a **graph** β€” so it can answer "what breaks if I change X?" by traversing actual relationships.
52
+
53
+ ## What it does
54
+
55
+ - πŸ” **Semantic search** across all your code, docs, and configs
56
+ - πŸ•ΈοΈ **Knowledge graph** β€” relationships between services, people, repos, technologies
57
+ - πŸ’₯ **Blast radius** β€” "what depends on this service/file/technology?"
58
+ - πŸ“ **Convention enforcement** β€” detects and enforces your team's patterns
59
+ - πŸ€– **MCP server** β€” plugs directly into AI agents (Kiro, Claude, Cursor)
60
+ - πŸ–₯️ **Web UI** β€” search, browse, visualize your knowledge graph
61
+ - πŸ”’ **Local-first** β€” nothing leaves your machine
62
+
63
+ ## Prerequisites
64
+
65
+ | Dependency | macOS | Ubuntu/Debian | Windows |
66
+ |---|---|---|---|
67
+ | **Docker** | `brew install colima && colima start` or Docker Desktop | `sudo apt install docker.io docker-compose-plugin` | [Docker Desktop](https://docker.com/products/docker-desktop/) |
68
+ | **Ollama** | `brew install ollama && ollama serve` | `curl -fsSL https://ollama.com/install.sh \| sh` | [Ollama installer](https://ollama.com/download) |
69
+ | **Python 3.11+** | `brew install python@3.12` | `sudo apt install python3.12 python3.12-venv` | [python.org](https://python.org/downloads/) |
70
+
71
+ ## Quick Start
72
+
73
+ ```bash
74
+ # Install (pick one)
75
+ pip install knowledge-master # from PyPI
76
+ pipx install knowledge-master # isolated install (recommended)
77
+
78
+ # Or from source
79
+ git clone https://github.com/subzone/knowledge-master.git
80
+ cd knowledge-master
81
+ python3 -m venv .venv && source .venv/bin/activate
82
+ pip install -e .
83
+
84
+ # One command setup
85
+ km start
86
+
87
+ # Index your first repo
88
+ km index ~/path/to/your/project
89
+
90
+ # Search
91
+ km search "authentication flow"
92
+
93
+ # Check blast radius
94
+ km blast-radius postgres
95
+
96
+ # Start web UI with graph visualization
97
+ km serve
98
+ ```
99
+
100
+ **Requirements:** Docker, Ollama, Python 3.11+
101
+
102
+ ## Features
103
+
104
+ ### Semantic Search with Graph Context
105
+ ```bash
106
+ $ km search "how does auth work"
107
+ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
108
+ β”‚ Score β”‚ Source β”‚ Context β”‚ Preview β”‚
109
+ β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€
110
+ β”‚ 0.847 β”‚ src/auth/service.py β”‚ repo:myapp, by:Alex β”‚ JWT token validat... β”‚
111
+ β”‚ 0.791 β”‚ docs/auth.md β”‚ repo:myapp β”‚ Authentication f... β”‚
112
+ β””β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
113
+ ```
114
+
115
+ ### Blast Radius Analysis
116
+ ```bash
117
+ $ km blast-radius auth-service
118
+ πŸ’₯ Blast radius: auth-service
119
+ β”œβ”€β”€ βš™οΈ user-service (Service, via DEPENDS_ON)
120
+ β”œβ”€β”€ βš™οΈ payment-service (Service, via DEPENDS_ON)
121
+ β”œβ”€β”€ πŸ“¦ frontend (Repo, via USES_SERVICE)
122
+ └── πŸ‘€ Alex (Person, via AUTHORED)
123
+
124
+ 4 entities affected
125
+ ```
126
+
127
+ ### Convention Enforcement
128
+ ```bash
129
+ $ km check-conventions ~/my-project
130
+ βœ“ src/ directory (structure)
131
+ βœ“ separate test directory (testing)
132
+ βœ— snake_case files (file-naming)
133
+ βœ“ Repository pattern (design-pattern)
134
+
135
+ 1 convention(s) violated
136
+ ```
137
+
138
+ ### Web UI & Graph Visualization
139
+
140
+ ```bash
141
+ $ km serve
142
+ Knowledge Master UI β†’ http://127.0.0.1:9999
143
+ ```
144
+
145
+ Interactive force-directed graph showing your entire knowledge topology:
146
+ - πŸ“¦ Repos (blue) β†’ πŸ”§ Technologies (red)
147
+ - βš™οΈ Services (orange) β†’ Dependencies
148
+ - πŸ‘€ People β†’ Authorship
149
+ - πŸ“ Conventions (purple)
150
+
151
+ ### MCP Integration (AI Agents)
152
+
153
+ Add to your Kiro/Claude agent config:
154
+
155
+ ```json
156
+ {
157
+ "mcpServers": {
158
+ "knowledge": {
159
+ "command": "km-server"
160
+ }
161
+ }
162
+ }
163
+ ```
164
+
165
+ Your AI agent gets these tools:
166
+ - `search` β€” semantic search with graph context
167
+ - `blast_radius` β€” dependency analysis
168
+ - `check_conventions` β€” verify code follows team patterns
169
+ - `index_repo` β€” add new repos to the knowledge base
170
+
171
+ ## Architecture
172
+
173
+ ```
174
+ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
175
+ β”‚ Your AI Agent β”‚
176
+ β”‚ (Kiro / Claude / Cursor) β”‚
177
+ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
178
+ β”‚ MCP Protocol
179
+ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β–Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
180
+ β”‚ Knowledge Master β”‚
181
+ β”‚ β”‚
182
+ β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚
183
+ β”‚ β”‚ Search β”‚ β”‚Blast Radiusβ”‚ β”‚ Conventionsβ”‚ β”‚
184
+ β”‚ β””β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”˜ β”‚
185
+ β”‚ β”‚ β”‚ β”‚ β”‚
186
+ β”‚ β”Œβ”€β”€β”€β”€β–Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β–Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β–Όβ”€β”€β”€β”€β”€β”€β” β”‚
187
+ β”‚ β”‚ FalkorDB (Graph + Vector) β”‚ β”‚
188
+ β”‚ β”‚ β”‚ β”‚
189
+ β”‚ β”‚ [Repo]──USES_TECH──▢[Tech] β”‚ β”‚
190
+ β”‚ β”‚ β”‚ β”‚ β”‚
191
+ β”‚ β”‚ β”œβ”€β”€DEFINES_SERVICE──▢[Service] β”‚ β”‚
192
+ β”‚ β”‚ β”‚ β”‚ β”‚ β”‚
193
+ β”‚ β”‚ β”œβ”€β”€FOLLOWS──▢[Convention] β”‚ β”‚
194
+ β”‚ β”‚ β”‚ β”‚ β”‚
195
+ β”‚ β”‚ [Person]──AUTHORED──▢[Document] β”‚ β”‚
196
+ β”‚ β”‚ β”‚ β”‚ β”‚
197
+ β”‚ β”‚ [Chunk + Embedding] β”‚ β”‚
198
+ β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚
199
+ β”‚ β”‚
200
+ β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚
201
+ β”‚ β”‚ Ollama (nomic-embed-text) β”‚ β”‚
202
+ β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚
203
+ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
204
+ ```
205
+
206
+ ## Commands
207
+
208
+ | Command | Description |
209
+ |---|---|
210
+ | `km start` | Boot Docker containers + pull embedding model |
211
+ | `km stop` | Stop containers |
212
+ | `km index <path>` | Index a git repo or docs directory |
213
+ | `km search <query>` | Semantic search with graph context |
214
+ | `km blast-radius <target>` | Show dependencies and affected entities |
215
+ | `km check-conventions <path>` | Verify code follows detected patterns |
216
+ | `km list` | Show indexed repos, techs, stats |
217
+ | `km remove <name>` | Remove a source from the knowledge base |
218
+ | `km serve` | Start web UI at http://127.0.0.1:9999 |
219
+ | `km status` | Check system health |
220
+
221
+ ## What gets extracted automatically
222
+
223
+ When you index a repo, Knowledge Master detects:
224
+
225
+ | Category | Examples |
226
+ |---|---|
227
+ | **Tech stack** | Languages, frameworks, packages from dependency files |
228
+ | **Services** | From docker-compose.yml and K8s manifests |
229
+ | **Dependencies** | Service-to-service relationships |
230
+ | **Conventions** | File naming (snake_case/kebab-case), folder structure, design patterns |
231
+ | **People** | Git commit authors and file ownership |
232
+ | **Code structure** | Functions, classes, chunked by AST-aware boundaries |
233
+
234
+ ## Comparison
235
+
236
+ | Feature | Knowledge Master | Generic RAG | GitHub Copilot | Glean |
237
+ |---|---|---|---|---|
238
+ | Graph relationships | βœ… | ❌ | ❌ | Partial |
239
+ | Blast radius analysis | βœ… | ❌ | ❌ | ❌ |
240
+ | Convention enforcement | βœ… | ❌ | ❌ | ❌ |
241
+ | Local-first (no cloud) | βœ… | βœ… | ❌ | ❌ |
242
+ | MCP integration | βœ… | ❌ | ❌ | ❌ |
243
+ | Multi-repo intelligence | βœ… | Partial | ❌ | βœ… |
244
+ | Cost | Free | Free | $19/mo | $15-30/mo |
245
+
246
+ ## Development
247
+
248
+ ```bash
249
+ # Run tests
250
+ pytest
251
+
252
+ # Lint
253
+ ruff check knowledge_master/
254
+
255
+ # Run MCP server directly
256
+ python -m knowledge_master.server
257
+
258
+ # Run CLI directly
259
+ python -m knowledge_master.cli status
260
+ ```
261
+
262
+ ## Troubleshooting
263
+
264
+ | Issue | Fix |
265
+ |---|---|
266
+ | `km start` fails with "Docker not running" | Start Docker: `colima start` (macOS) or `sudo systemctl start docker` (Linux) |
267
+ | `km start` fails with "Ollama not found" | Install Ollama from https://ollama.com and run `ollama serve` |
268
+ | `km index` is slow | First run downloads the embedding model (~274MB). Subsequent runs are fast. |
269
+ | Web UI shows "Connection refused" | Make sure containers are running: `km start` |
270
+ | Search returns poor results | Index more content. Quality improves with more context in the graph. |
271
+ | Port 9999 already in use | Use `km serve --port 8888` |
272
+
273
+ ## License
274
+
275
+ MIT
@@ -0,0 +1,237 @@
1
+ # ⚑ Knowledge Master
2
+
3
+ **Your codebase's memory.** A local knowledge graph that gives AI agents real understanding of your architecture β€” not just text search.
4
+
5
+ [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
6
+
7
+ ---
8
+
9
+ ## Why
10
+
11
+ Every time you start a new AI chat, it forgets everything. You re-explain your architecture, conventions, dependencies. Knowledge Master gives your AI **permanent, structured memory** about your entire system.
12
+
13
+ Unlike flat RAG tools that return "chunks about X", Knowledge Master builds a **graph** β€” so it can answer "what breaks if I change X?" by traversing actual relationships.
14
+
15
+ ## What it does
16
+
17
+ - πŸ” **Semantic search** across all your code, docs, and configs
18
+ - πŸ•ΈοΈ **Knowledge graph** β€” relationships between services, people, repos, technologies
19
+ - πŸ’₯ **Blast radius** β€” "what depends on this service/file/technology?"
20
+ - πŸ“ **Convention enforcement** β€” detects and enforces your team's patterns
21
+ - πŸ€– **MCP server** β€” plugs directly into AI agents (Kiro, Claude, Cursor)
22
+ - πŸ–₯️ **Web UI** β€” search, browse, visualize your knowledge graph
23
+ - πŸ”’ **Local-first** β€” nothing leaves your machine
24
+
25
+ ## Prerequisites
26
+
27
+ | Dependency | macOS | Ubuntu/Debian | Windows |
28
+ |---|---|---|---|
29
+ | **Docker** | `brew install colima && colima start` or Docker Desktop | `sudo apt install docker.io docker-compose-plugin` | [Docker Desktop](https://docker.com/products/docker-desktop/) |
30
+ | **Ollama** | `brew install ollama && ollama serve` | `curl -fsSL https://ollama.com/install.sh \| sh` | [Ollama installer](https://ollama.com/download) |
31
+ | **Python 3.11+** | `brew install python@3.12` | `sudo apt install python3.12 python3.12-venv` | [python.org](https://python.org/downloads/) |
32
+
33
+ ## Quick Start
34
+
35
+ ```bash
36
+ # Install (pick one)
37
+ pip install knowledge-master # from PyPI
38
+ pipx install knowledge-master # isolated install (recommended)
39
+
40
+ # Or from source
41
+ git clone https://github.com/subzone/knowledge-master.git
42
+ cd knowledge-master
43
+ python3 -m venv .venv && source .venv/bin/activate
44
+ pip install -e .
45
+
46
+ # One command setup
47
+ km start
48
+
49
+ # Index your first repo
50
+ km index ~/path/to/your/project
51
+
52
+ # Search
53
+ km search "authentication flow"
54
+
55
+ # Check blast radius
56
+ km blast-radius postgres
57
+
58
+ # Start web UI with graph visualization
59
+ km serve
60
+ ```
61
+
62
+ **Requirements:** Docker, Ollama, Python 3.11+
63
+
64
+ ## Features
65
+
66
+ ### Semantic Search with Graph Context
67
+ ```bash
68
+ $ km search "how does auth work"
69
+ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
70
+ β”‚ Score β”‚ Source β”‚ Context β”‚ Preview β”‚
71
+ β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€
72
+ β”‚ 0.847 β”‚ src/auth/service.py β”‚ repo:myapp, by:Alex β”‚ JWT token validat... β”‚
73
+ β”‚ 0.791 β”‚ docs/auth.md β”‚ repo:myapp β”‚ Authentication f... β”‚
74
+ β””β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
75
+ ```
76
+
77
+ ### Blast Radius Analysis
78
+ ```bash
79
+ $ km blast-radius auth-service
80
+ πŸ’₯ Blast radius: auth-service
81
+ β”œβ”€β”€ βš™οΈ user-service (Service, via DEPENDS_ON)
82
+ β”œβ”€β”€ βš™οΈ payment-service (Service, via DEPENDS_ON)
83
+ β”œβ”€β”€ πŸ“¦ frontend (Repo, via USES_SERVICE)
84
+ └── πŸ‘€ Alex (Person, via AUTHORED)
85
+
86
+ 4 entities affected
87
+ ```
88
+
89
+ ### Convention Enforcement
90
+ ```bash
91
+ $ km check-conventions ~/my-project
92
+ βœ“ src/ directory (structure)
93
+ βœ“ separate test directory (testing)
94
+ βœ— snake_case files (file-naming)
95
+ βœ“ Repository pattern (design-pattern)
96
+
97
+ 1 convention(s) violated
98
+ ```
99
+
100
+ ### Web UI & Graph Visualization
101
+
102
+ ```bash
103
+ $ km serve
104
+ Knowledge Master UI β†’ http://127.0.0.1:9999
105
+ ```
106
+
107
+ Interactive force-directed graph showing your entire knowledge topology:
108
+ - πŸ“¦ Repos (blue) β†’ πŸ”§ Technologies (red)
109
+ - βš™οΈ Services (orange) β†’ Dependencies
110
+ - πŸ‘€ People β†’ Authorship
111
+ - πŸ“ Conventions (purple)
112
+
113
+ ### MCP Integration (AI Agents)
114
+
115
+ Add to your Kiro/Claude agent config:
116
+
117
+ ```json
118
+ {
119
+ "mcpServers": {
120
+ "knowledge": {
121
+ "command": "km-server"
122
+ }
123
+ }
124
+ }
125
+ ```
126
+
127
+ Your AI agent gets these tools:
128
+ - `search` β€” semantic search with graph context
129
+ - `blast_radius` β€” dependency analysis
130
+ - `check_conventions` β€” verify code follows team patterns
131
+ - `index_repo` β€” add new repos to the knowledge base
132
+
133
+ ## Architecture
134
+
135
+ ```
136
+ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
137
+ β”‚ Your AI Agent β”‚
138
+ β”‚ (Kiro / Claude / Cursor) β”‚
139
+ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
140
+ β”‚ MCP Protocol
141
+ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β–Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
142
+ β”‚ Knowledge Master β”‚
143
+ β”‚ β”‚
144
+ β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚
145
+ β”‚ β”‚ Search β”‚ β”‚Blast Radiusβ”‚ β”‚ Conventionsβ”‚ β”‚
146
+ β”‚ β””β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”˜ β”‚
147
+ β”‚ β”‚ β”‚ β”‚ β”‚
148
+ β”‚ β”Œβ”€β”€β”€β”€β–Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β–Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β–Όβ”€β”€β”€β”€β”€β”€β” β”‚
149
+ β”‚ β”‚ FalkorDB (Graph + Vector) β”‚ β”‚
150
+ β”‚ β”‚ β”‚ β”‚
151
+ β”‚ β”‚ [Repo]──USES_TECH──▢[Tech] β”‚ β”‚
152
+ β”‚ β”‚ β”‚ β”‚ β”‚
153
+ β”‚ β”‚ β”œβ”€β”€DEFINES_SERVICE──▢[Service] β”‚ β”‚
154
+ β”‚ β”‚ β”‚ β”‚ β”‚ β”‚
155
+ β”‚ β”‚ β”œβ”€β”€FOLLOWS──▢[Convention] β”‚ β”‚
156
+ β”‚ β”‚ β”‚ β”‚ β”‚
157
+ β”‚ β”‚ [Person]──AUTHORED──▢[Document] β”‚ β”‚
158
+ β”‚ β”‚ β”‚ β”‚ β”‚
159
+ β”‚ β”‚ [Chunk + Embedding] β”‚ β”‚
160
+ β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚
161
+ β”‚ β”‚
162
+ β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚
163
+ β”‚ β”‚ Ollama (nomic-embed-text) β”‚ β”‚
164
+ β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚
165
+ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
166
+ ```
167
+
168
+ ## Commands
169
+
170
+ | Command | Description |
171
+ |---|---|
172
+ | `km start` | Boot Docker containers + pull embedding model |
173
+ | `km stop` | Stop containers |
174
+ | `km index <path>` | Index a git repo or docs directory |
175
+ | `km search <query>` | Semantic search with graph context |
176
+ | `km blast-radius <target>` | Show dependencies and affected entities |
177
+ | `km check-conventions <path>` | Verify code follows detected patterns |
178
+ | `km list` | Show indexed repos, techs, stats |
179
+ | `km remove <name>` | Remove a source from the knowledge base |
180
+ | `km serve` | Start web UI at http://127.0.0.1:9999 |
181
+ | `km status` | Check system health |
182
+
183
+ ## What gets extracted automatically
184
+
185
+ When you index a repo, Knowledge Master detects:
186
+
187
+ | Category | Examples |
188
+ |---|---|
189
+ | **Tech stack** | Languages, frameworks, packages from dependency files |
190
+ | **Services** | From docker-compose.yml and K8s manifests |
191
+ | **Dependencies** | Service-to-service relationships |
192
+ | **Conventions** | File naming (snake_case/kebab-case), folder structure, design patterns |
193
+ | **People** | Git commit authors and file ownership |
194
+ | **Code structure** | Functions, classes, chunked by AST-aware boundaries |
195
+
196
+ ## Comparison
197
+
198
+ | Feature | Knowledge Master | Generic RAG | GitHub Copilot | Glean |
199
+ |---|---|---|---|---|
200
+ | Graph relationships | βœ… | ❌ | ❌ | Partial |
201
+ | Blast radius analysis | βœ… | ❌ | ❌ | ❌ |
202
+ | Convention enforcement | βœ… | ❌ | ❌ | ❌ |
203
+ | Local-first (no cloud) | βœ… | βœ… | ❌ | ❌ |
204
+ | MCP integration | βœ… | ❌ | ❌ | ❌ |
205
+ | Multi-repo intelligence | βœ… | Partial | ❌ | βœ… |
206
+ | Cost | Free | Free | $19/mo | $15-30/mo |
207
+
208
+ ## Development
209
+
210
+ ```bash
211
+ # Run tests
212
+ pytest
213
+
214
+ # Lint
215
+ ruff check knowledge_master/
216
+
217
+ # Run MCP server directly
218
+ python -m knowledge_master.server
219
+
220
+ # Run CLI directly
221
+ python -m knowledge_master.cli status
222
+ ```
223
+
224
+ ## Troubleshooting
225
+
226
+ | Issue | Fix |
227
+ |---|---|
228
+ | `km start` fails with "Docker not running" | Start Docker: `colima start` (macOS) or `sudo systemctl start docker` (Linux) |
229
+ | `km start` fails with "Ollama not found" | Install Ollama from https://ollama.com and run `ollama serve` |
230
+ | `km index` is slow | First run downloads the embedding model (~274MB). Subsequent runs are fast. |
231
+ | Web UI shows "Connection refused" | Make sure containers are running: `km start` |
232
+ | Search returns poor results | Index more content. Quality improves with more context in the graph. |
233
+ | Port 9999 already in use | Use `km serve --port 8888` |
234
+
235
+ ## License
236
+
237
+ MIT
File without changes
@@ -0,0 +1,4 @@
1
+ """Allow running as: python -m knowledge_master"""
2
+ from .cli import app
3
+
4
+ app()
@@ -0,0 +1,106 @@
1
+ """Smart chunking engine - splits text by structure (headings, functions, paragraphs)."""
2
+
3
+ import hashlib
4
+ import re
5
+
6
+
7
+ def chunk_id(source: str, index: int) -> str:
8
+ """Deterministic chunk ID from source path and position."""
9
+ return hashlib.md5(f"{source}:{index}".encode()).hexdigest()
10
+
11
+
12
+ def chunk_markdown(text: str, max_tokens: int = 512) -> list[dict]:
13
+ """Split markdown by headings, keeping sections together."""
14
+ sections = re.split(r"(?=^#{1,3}\s)", text, flags=re.MULTILINE)
15
+ chunks = []
16
+ for section in sections:
17
+ section = section.strip()
18
+ if not section:
19
+ continue
20
+ # If section is too long, split by paragraphs
21
+ if len(section.split()) > max_tokens:
22
+ paragraphs = section.split("\n\n")
23
+ buffer = ""
24
+ for para in paragraphs:
25
+ if len((buffer + para).split()) > max_tokens and buffer:
26
+ chunks.append(buffer.strip())
27
+ buffer = para
28
+ else:
29
+ buffer = buffer + "\n\n" + para if buffer else para
30
+ if buffer.strip():
31
+ chunks.append(buffer.strip())
32
+ else:
33
+ chunks.append(section)
34
+ return chunks
35
+
36
+
37
+ def chunk_code(text: str, language: str = "", max_tokens: int = 400) -> list[dict]:
38
+ """Split code by function/class boundaries or fixed blocks."""
39
+ # Try to split by top-level definitions
40
+ patterns = {
41
+ "python": r"(?=^(?:def |class |async def ))",
42
+ "typescript": r"(?=^(?:export |function |class |const \w+ = ))",
43
+ "rust": r"(?=^(?:fn |pub fn |impl |struct |enum ))",
44
+ "go": r"(?=^(?:func ))",
45
+ }
46
+ pattern = patterns.get(language)
47
+ if pattern:
48
+ parts = re.split(pattern, text, flags=re.MULTILINE)
49
+ else:
50
+ # Fall back to splitting by blank lines / large gaps
51
+ parts = re.split(r"\n{3,}", text)
52
+
53
+ chunks = []
54
+ buffer = ""
55
+ for part in parts:
56
+ part = part.strip()
57
+ if not part:
58
+ continue
59
+ if len((buffer + part).split()) > max_tokens and buffer:
60
+ chunks.append(buffer.strip())
61
+ buffer = part
62
+ else:
63
+ buffer = buffer + "\n\n" + part if buffer else part
64
+ if buffer.strip():
65
+ chunks.append(buffer.strip())
66
+ return chunks
67
+
68
+
69
+ def chunk_text(text: str, max_tokens: int = 512) -> list[str]:
70
+ """Generic text chunking by paragraphs."""
71
+ paragraphs = text.split("\n\n")
72
+ chunks = []
73
+ buffer = ""
74
+ for para in paragraphs:
75
+ if len((buffer + para).split()) > max_tokens and buffer:
76
+ chunks.append(buffer.strip())
77
+ buffer = para
78
+ else:
79
+ buffer = buffer + "\n\n" + para if buffer else para
80
+ if buffer.strip():
81
+ chunks.append(buffer.strip())
82
+ return chunks
83
+
84
+
85
+ LANGUAGE_MAP = {
86
+ ".py": "python",
87
+ ".ts": "typescript",
88
+ ".tsx": "typescript",
89
+ ".js": "javascript",
90
+ ".rs": "rust",
91
+ ".go": "go",
92
+ ".java": "java",
93
+ ".md": "markdown",
94
+ ".markdown": "markdown",
95
+ }
96
+
97
+
98
+ def chunk_file(text: str, extension: str, max_tokens: int = 512) -> list[str]:
99
+ """Route to appropriate chunker based on file extension."""
100
+ lang = LANGUAGE_MAP.get(extension, "")
101
+ if lang == "markdown":
102
+ return chunk_markdown(text, max_tokens)
103
+ elif lang:
104
+ return chunk_code(text, lang, max_tokens)
105
+ else:
106
+ return chunk_text(text, max_tokens)