From 762f6b5624d5e47184a2910b1de7b435f82fd61d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Pawe=C5=82=20Doma=C5=84ski?= Date: Thu, 11 Jun 2026 08:11:30 +0000 Subject: [PATCH] Jun 11, 2026, 10:11 AM --- brain/README.md | 143 +++++++++++++++++++++++++++++++++--------------- 1 file changed, 100 insertions(+), 43 deletions(-) diff --git a/brain/README.md b/brain/README.md index a8d46c7..5f022b1 100644 --- a/brain/README.md +++ b/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*