# LLM Knowledge Base: System Zarządzania Wiedzą (Karpathy Pattern)

Ten projekt to zaawansowana osobista baza wiedzy (Knowledge Base), która jest **aktywnie współtworzona i utrzymywana przez agenta AI (LLM)**. Zamiast tradycyjnego, ulotnego podejścia RAG (Retrieval-Augmented Generation), system ten stopniowo buduje i syntetyzuje wiedzę w trwałą, skompilowaną strukturę połączonych plików Markdown.

---

## 🧠 Filozofia i Architektura

System opiera się na trzech filarach:
1. **Karpathy Pattern (Knowledge as a Codebase)**: Surowe, niezmienne dokumenty (`raw/`) są jak kod źródłowy, a uporządkowana, powiązana baza wiedzy (`knowledge/`) jest skompilowanym plikiem binarnym — zoptymalizowanym pod kątem wyszukiwania, gęstości informacji i syntezy. Obsidian służy jako interfejs (frontend IDE), a LLM jako programista i administrator bazy (bookkeeper).
2. **12 Problemów Feynmana**: Metoda polegająca na trzymaniu w pamięci kluczowych pytań badawczych (w pliku `knowledge/feynman_problems.md`). Każde nowe źródło jest testowane pod kątem tego, czy wnosi wgląd do tych długoterminowych wyzwań.
3. **Local-First & AI Automation**: Priorytetem są lokalne pliki tekstowe, prywatność i niezależność od chmury. Agent AI wkracza tylko do zadań wymagających wysokiego poziomu syntezy (Ingest, Query, Lint), nie generując kosztów tokenów przy codziennym przeglądaniu bazy.

---

## 📂 Struktura Katalogów

```hs
brain/
├── raw/                      ← Źródła Prawdy (Niezmienne, dodawane przez człowieka)
│   ├── articles/             ← Artykuły z sieci, blogi
│   ├── inbox/                ← Pliki oczekujące na przetworzenie (ingest)
│   ├── notes/                ← Twoje surowe notatki i przemyślenia
│   └── transcripts/          ← Transkrypcje audio/video
│
├── knowledge/                ← Warstwa Syntezy (Zarządzana w 100% przez LLM)
│   ├── summaries/            ← Podsumowania poszczególnych źródeł z raw/
│   ├── concepts/             ← Słownik terminów i modeli mentalnych (np. gtd-ai)
│   ├── entities/             ← Strony narzędzi, organizacji i osób (np. obsidian)
│   ├── indices/              ← Listy indeksujące zawartość według typów i tematów
│   ├── journal/              ← Dziennik badawczy (Research Journal) do luźnych zapisków
│   ├── index.md              ← Master Index (Główna Mapa bazy wiedzy)
│   ├── log.md                ← Chronologiczny dziennik zmian i operacji ingestu
│   └── feynman_problems.md   ← Centralny rejestr 12 Ulubionych Problemów Feynmana
│
├── .agents/skills/           ← Zainstalowane umiejętności agenta AI (Obsidian-Skills)
├── GEMINI.md                 ← Zasady, instrukcje i konfiguracja dla Gemini CLI
├── lint_knowledge.ps1        ← Lokalny skrypt walidacyjny (linter powiązań i sierot)
└── replace_knowledge.ps1     ← Skrypt PowerShell do globalnych refaktoryzacji tekstu
```

---

## 🚀 Trzy Główne Przepływy (Workflows)

### 1. Ingest (Wdrażanie wiedzy)
Dodawanie nowych źródeł polega na umieszczeniu pliku w `raw/inbox/` i zleceniu agentowi:
> *"Zrób ingest nowo dodanych plików"*

**Co robi agent AI:**
1. Analizuje surowy tekst z `raw/inbox/`.
2. Tworzy dedykowaną stronę podsumowania w `knowledge/summaries/` (z metadanymi YAML i kluczowymi punktami).
3. **Mnożnik Ingestu**: Średnio jedno źródło aktualizuje lub tworzy 2.6 strony w bazie. Agent automatycznie tworzy/uzupełnia odpowiednie strony w `knowledge/concepts/` oraz `knowledge/entities/` i linkuje je ze sobą.
4. Testuje nowe wnioski pod kątem 12 Problemów Feynmana w `knowledge/feynman_problems.md` i dopisuje powiązania.
5. Aktualizuje odpowiednie indeksy tematyczne oraz plik `knowledge/log.md`.

### 2. Query (Zadawanie pytań)
Dzięki gęstej sieci połączeń możesz zadawać złożone pytania syntezujące wiele źródeł:
> *"Jakie są różnice metodologiczne między wdrażaniem bazy w filozofii a systemem GTD AI? Przygotuj porównanie w oparciu o nasze źródła."*

**Co robi agent AI:** Zamiast przeszukiwać gigabajty surowych PDF-ów, agent odpytuje master index, przechodzi po Knowledge BaseLinkach powiązanych koncepcji i generuje precyzyjną odpowiedź z cytowaniami. 
*Wskazówka: Wartościowe syntezy wygenerowane w sesjach czatu mogą być zapisywane z powrotem do bazy jako nowe strony koncepcyjne lub syntezy, dzięki czemu wiedza procentuje (compounding knowledge).*

### 3. Lint (Sprzątanie i walidacja)
Aby utrzymać bazę w idealnym zdrowiu, regularnie uruchamia się proces Lintingu:
> *"Uruchom linter wiedzy"*

System posiada wbudowany, dedykowany skrypt walidacyjny PowerShell. Możesz go uruchomić bezpośrednio z konsoli:
```powershell
powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\lint_knowledge.ps1
```
**Co robi linter:**
- Przeszukuje całą bazę pod kątem **uszkodzonych Knowledge BaseLinków** (linki wskazujące na nieistniejące pliki).
- Wykrywa **sieroty (orphans)** — strony koncepcyjne, podmioty lub podsumowania, które nie posiadają żadnych linków przychodzących z innych stron merytorycznych.
- Gwarantuje 100% spójności strukturalnej przed zatwierdzeniem zmian w systemie kontroli wersji Git.

---

## 💎 Zaawansowane Funkcje Systemu

### 🏷️ Markery Epistemiczne (Epistemic Markers)
Aby zachować pełen rygor badawczy, w plikach syntezowanych stosujemy oznaczanie rejestru zdań:
- **(brak znacznika)** — Bezpośrednie twierdzenie pochodzące z cytowanego źródła pierwotnego.
- **[W]** — *Knowledge Base synthesis*: Integracja i synteza merytoryczna dokonana przez model AI (LLM) na bazie wielu źródeł.
- **[P]** — *Personal stance*: Suwerenne stanowisko badawcze, hipoteza lub argument samego człowieka (użytkownika).
- **[?]** — *Speculative*: Informacja niepewna, trudna do zweryfikowania przez bazę (potencjalna halucynacja).

### ⚡ Umiejętności Obsidiana (Obsidian-Skills)
Agent AI posiada zainstalowane natywne reguły obsługi formatu Obsidian (Knowledge BaseLinki, callouty, Canvas). Zostały one wdrożone za pomocą komendy:
```powershell
npx skills add https://github.com/kepano/obsidian-skills.git
```
Dzięki temu model nie generuje błędnej składni i traktuje bazę notatek z taką samą precyzją, jak profesjonalny kompilator traktuje kod źródłowy.

### 📈 Skalowanie Bazy (Knowledge Scaling)
W miarę wzrostu bazy powyżej 150 stron, aby zapobiec eksplozji kosztów tokenów i spowolnieniu zapytań, baza stosuje **kaskadę nawigacyjną**:
1. Podział na klastry tematyczne w `index.md`.
2. Stworzenie dedykowanych **stron syntez (synthesis pages)** agregujących całe obszary (np. `syntheses/porownanie-strategii-automatyzacji-ai`).
3. Zastosowanie lokalnych serwerów **MCP (Model Context Protocol)** (np. `MCPVault`), które indeksują bazę lokalnie i kompresują odpowiedzi przekazywane do agenta AI o 40-60%.

### 📑 Kontrakt Agentów (CLAUDE.md / GEMINI.md)
Pliki te pełnią rolę instrukcji wdrożeniowych (kontraktu) dla agenta AI. Definiują nienaruszalne reguły bezpieczeństwa (np. zakaz modyfikacji szablonów i folderów systemowych) oraz aktualny fokus badawczy użytkownika, co pozwala na pełną powtarzalność pracy między bezstanowymi sesjami modeli językowych.

---
*Ostatnia pełna rekompilacja i walidacja bazy: 2026-06-09*