Jun 11, 2026, 10:11 AM

brain/README.md

@@ -1,48 +1,105 @@
 # LLM Knowledge Base: System Zarządzania Wiedzą (Karpathy Pattern)
 
-Ten projekt to osobista baza wiedzy (Knowledge Base), która jest **aktywnie utrzymywana przez LLM**. Zamiast tylko przechowywać dokumenty, system ten incrementally buduje i syntetyzuje wiedzę w strukturę połączonych plików Markdown.
-
-## 🧠 Filozofia
-System opiera się na połączeniu dwóch idei:
-- **Karpathy Pattern**: Knowledge Base jako "codebase" wiedzy utrzymywany przez LLM.
-- **12 Problemów Feynmana**: Metoda polegająca na trzymaniu w pamięci (i tutaj - w pliku `knowledge/feynman_problems.md`) 12 kluczowych pytań. Każde nowe źródło jest testowane pod kątem tego, czy pomaga rozwiązać lub zrozumieć któryś z tych problemów.
-
-## 📂 Struktura Katalogów
-- `raw/`: **Źródła Prawdy**. Tu trafiają Twoje materiały (PDF, Markdown, notatki). Są one niemodyfikowalne.
-    - `articles/`: Artykuły z sieci, blogi.
-    - `notes/`: Twoje własne przemyślenia i surowe notatki.
-- `knowledge/`: **Warstwa Syntezy**. Pliki generowane i utrzymywane przez LLM.
-    - `sources/`: Analizy konkretnych dokumentów z `raw/`.
-    - `entities/`: Strony konkretnych narzędzi, osób i technologii (np. `n8n`).
-    - `concepts/`: Głębokie analizy idei i teorii (np. `human-in-the-loop`).
-    - `index.md`: Katalog całej treści (Mapa Knowledge Base).
-    - `log.md`: Dziennik zdarzeń (Co i kiedy zostało dodane).
-- `GEMINI.md`: Zasady i instrukcje dla Gemini CLI.
-
-## 🚀 Jak korzystać z systemu?
-
-### 1. Ingest (Dodawanie wiedzy)
-Wrzuć nowy plik do folderu `raw/` i wydaj polecenie:
-> *"Przetwórz nowe dokumenty z katalogu raw"*
-
-**Co zrobi LLM:** Przeczyta plik, stworzy podsumowanie w `knowledge/sources/`, zaktualizuje powiązane encje i koncepcje, oraz dopisze informację do indeksu i logu.
-
-### 2. Query (Zadawanie pytań)
-Zadaj dowolne pytanie techniczne lub teoretyczne:
-> *"Jakie narzędzia do automatyzacji researchu mamy w bazie?"*
-
-**Co zrobi LLM:** Najpierw sprawdzi `knowledge/index.md`, przeczyta odpowiednie strony z `knowledge/` i przygotuje odpowiedź z cytowaniami.
-
-### 3. Lint (Sprzątanie)
-Raz na jakiś czas poproś o przegląd bazy:
-> *"Wykonaj lint knowledge i znajdź brakujące połączenia"*
-
-**Co zrobi LLM:** Znajdzie "sieroty" (pliki bez linków), sprzeczności między starymi a nowymi źródłami lub zasugeruje stworzenie nowej strony koncepcyjnej dla często pojawiającego się tematu.
-
-## 🛠️ Narzędzia polecane
-- **Obsidian**: Najlepsze narzędzie do przeglądania tej bazy. Użyj "Graph View", aby zobaczyć jak Twoja wiedza się łączy.
-- **Gemini CLI**: Twój asystent, który wykonuje całą "brudną robotę" edytorską.
+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.
 
 ---
-*System zainicjalizowany: 2026-05-14*
 
+## 🧠 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 WikiLinkach 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 WikiLinkó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]** — *Wiki 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 (WikiLinki, 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*