241 lines
No EOL
7.2 KiB
Markdown
241 lines
No EOL
7.2 KiB
Markdown
# AGENTS.md — RamaDama Knowledge Base Schema
|
|
|
|
This file defines how an LLM agent reads, writes, and maintains the knowledge base in this repository.
|
|
|
|
Read the full context first:
|
|
|
|
- `/README.md` — Konzeptuelle Grundlage nach Karpathy (raw → LLM → wiki → Q&A)
|
|
- `/wiki/index.md` — Aktuelles Inhaltsverzeichnis
|
|
- `/wiki/log.md` — Chronik der Änderungen
|
|
|
|
---
|
|
|
|
## Directory Structure
|
|
|
|
Die Struktur ist **offen für Neues**. Wenn ein roher Link-Typ nicht in die bestehenden Kategorien passt, leg einfach einen neuen Ordner an. Der Agent erkennt das und passt sich an.
|
|
|
|
```
|
|
knowledge-base/
|
|
├── AGENTS.md ← Diese Datei (Schema für den Agenten)
|
|
├── README.md ← Übersicht und Kontext
|
|
├── raw/ ← Immutable source documents
|
|
│ ├── youtube/ ← YouTube Videos (Transcript + Summary)
|
|
│ ├── blog/ ← Blog-Artikel (Web-Fetch)
|
|
│ ├── xpost/ ← X/Twitter Posts (vollständiger Thread)
|
|
│ ├── other/ ← Sonstiges (Screenshots, PDF, Notes)
|
|
│ └── ... ← Weitere Typen jederzeit möglich
|
|
├── wiki/ ← LLM-kompilierte Wissensbasis
|
|
│ ├── index.md ← Auto-generated catalog
|
|
│ ├── log.md ← Append-only changelog
|
|
│ ├── teams/ ← Personen, Rollen
|
|
│ ├── tools/ ← Tools, Instanzen, Credentials
|
|
│ ├── architecture/ ← Architektur-Entscheidungen
|
|
│ ├── concepts/ ← Konzepte, Erklärungen
|
|
│ ├── decisions/ ← Dated decisions
|
|
│ └── ... ← Weitere Kategorien jederzeit möglich
|
|
├── scripts/ ← Hilfsskripte
|
|
└── output/ ← Generated outputs (visuals, slides, reports)
|
|
```
|
|
|
|
---
|
|
|
|
## File Naming Conventions
|
|
|
|
### Raw Sources
|
|
|
|
Format: `{type}/{yyyy-mm-dd}_{kurzer-slug}.md`
|
|
|
|
```
|
|
raw/youtube/2026-06-05_karpathy-llm-wiki-explained.md
|
|
raw/blog/2026-06-04_understanding-agent-memory-systems.md
|
|
raw/xpost/2026-06-03_karpathy-knowledge-bases-tweet.md
|
|
```
|
|
|
|
### Wiki Pages
|
|
|
|
Format: kebab-case, sprechender Name, keine Daten im Dateinamen.
|
|
|
|
```
|
|
wiki/teams/kai-antigravity.md
|
|
wiki/tools/forgejo-botreasury.md
|
|
wiki/architecture/plur1bus-memory-stack.md
|
|
wiki/concepts/llm-knowledge-base.md
|
|
wiki/decisions/2026-06-05_kein-coding-guide-in-kb.md
|
|
```
|
|
|
|
---
|
|
|
|
## Frontmatter Standards
|
|
|
|
### Jede raw-Datei trägt Frontmatter
|
|
|
|
**Blog-Artikel:**
|
|
```yaml
|
|
---
|
|
type: blog
|
|
source_url: https://example.com/article
|
|
retrieved: 2026-06-05
|
|
title: "Titel des Artikels"
|
|
author: "Author Name"
|
|
tags: [agent-memory, architecture]
|
|
---
|
|
```
|
|
|
|
**X-Posts:**
|
|
```yaml
|
|
---
|
|
type: xpost
|
|
source_url: https://x.com/username/status/123456789
|
|
retrieved: 2026-06-05
|
|
author: "@username"
|
|
is_thread: true
|
|
quote_count: 5
|
|
---
|
|
```
|
|
|
|
**YouTube:**
|
|
```yaml
|
|
---
|
|
type: youtube
|
|
source_url: https://youtube.com/watch?v=xxx
|
|
retrieved: 2026-06-05
|
|
channel: "Channel Name"
|
|
duration_sec: 1847
|
|
has_transcript: true
|
|
---
|
|
```
|
|
|
|
**Sonstiges:**
|
|
```yaml
|
|
---
|
|
type: other
|
|
source_url: ""
|
|
retrieved: 2026-06-05
|
|
title: "Notiz"
|
|
tags: []
|
|
---
|
|
```
|
|
|
|
### Wiki-Pages haben minimales Frontmatter
|
|
|
|
```yaml
|
|
---
|
|
created: 2026-06-05
|
|
updated: 2026-06-05
|
|
sources: [blog/2026-06-04_understanding-agent-memory-systems.md]
|
|
tags: [architecture, agents]
|
|
---
|
|
```
|
|
|
|
---
|
|
|
|
## Workflows
|
|
|
|
### 1. Ingest: Neue Quelle verarbeiten
|
|
|
|
Wenn eine neue raw-Datei hinzukommt:
|
|
|
|
1. **Lies die Datei** (komplett)
|
|
2. **Prüfe Frontmatter** — setze fehlende Felder nach bestem Wissen
|
|
3. **Extrahiere Key Takeaways** (max 3-5 Sätze)
|
|
4. **Finde betroffene Wiki-Seiten** — welche bestehenden Seiten müssen aktualisiert werden?
|
|
5. **Aktualisiere Wiki-Seiten** — füge neue Erkenntnisse hinzu, neue Verlinkungen
|
|
6. **Erstelle neue Wiki-Seiten** wenn nötig (neues Konzept, neues Tool, neue Person)
|
|
7. **Aktualisiere index.md** — füge hinzu oder aktualisiere Eintrag
|
|
8. **Hänge Eintrag an log.md**
|
|
|
|
**Kardinalregel: raw-Dateien werden niemals verändert.** Sie sind die unveränderliche Quelle der Wahrheit.
|
|
|
|
### 2. Query: Fragen beantworten
|
|
|
|
1. **Lies index.md** — finde relevante Wiki-Seiten
|
|
2. **Lies die gefundenen Seiten** — extrahiere relevante Infos
|
|
3. **Synthetisiere Antwort** mit Quellenangabe
|
|
4. **Frage nach:** Soll die Antwort zurück ins Wiki gefiled werden?
|
|
|
|
Antwortformate: Markdown, Vergleichstabelle, Marp-Slides. Je nach Frage.
|
|
|
|
### 3. Lint: Health Check
|
|
|
|
Periodisch durchführen, wenn das Wiki wächst. Prüfe:
|
|
|
|
- **Widersprüche**: Behaupten zwei Seiten Gegenteiliges?
|
|
- **Veraltete Claims**: Hat eine neuere Quelle ältere widerlegt?
|
|
- **Orphan Pages**: Seiten ohne eingehende Links
|
|
- **Fehlende Seiten**: Wichtige Konzepte ohne eigenen Eintrag
|
|
- **Missing Cross-References**: Verpasste Verlinkungen
|
|
|
|
---
|
|
|
|
## DuckDB-MCP (für Such-Operationen)
|
|
|
|
Dieses Repository kann mit DuckDB-MCP durchsucht werden. Die Datenbank liegt unter `data/knowledge.duckdb`.
|
|
|
|
---
|
|
|
|
## Memory-Backend Integration
|
|
|
|
- Wiki-Inhalte, die für den laufenden Betrieb relevant sind (Credentials, Konfiguration), gehören auch in `TOOLS.md` und `MEMORY.md`
|
|
- Langfristiges Wissen gehört ins Wiki, nicht in die lokalen Agent-Memory-Files
|
|
- Das Wiki ist der Source of Truth für strukturiertes Wissen
|
|
|
|
---
|
|
|
|
## Git Commit Conventions
|
|
|
|
```
|
|
{type}({scope}): {kurzbeschreibung}
|
|
|
|
type: ingest | wiki-update | lint | schema | chore
|
|
scope: raw | wiki/concepts | wiki/tools | wiki/decisions | schema
|
|
```
|
|
|
|
Beispiele:
|
|
```
|
|
ingest(raw): karpathy-llm-wiki-explained (youtube)
|
|
wiki-update(decisions): KB structure decision finalized
|
|
lint(wiki): found 3 orphan pages, missing cross-refs
|
|
schema(raw): add xpost frontmatter template
|
|
```
|
|
|
|
---
|
|
|
|
---
|
|
|
|
## Autonomes Kuratieren (für Hector)
|
|
|
|
**Hector liest alle Gruppenchats aktiv mit und kuratiert relevante Inhalte selbständig ins Wiki.**
|
|
|
|
### Was heißt das konkret?
|
|
|
|
1. **Alle Kanäle überwachen:** OME-Gruppe, RamaDama-Topic, alle anderen Gruppen, News & Infos
|
|
2. **Relevanz erkennen:** Architekturdiskussionen, Tool-Entscheidungen, Konzepte, nützliche Links
|
|
3. **Inhalten Rohdaten ablegen:** Jeden relevanten Link/Post/Video als eigene raw-Datei mit Frontmatter speichern
|
|
4. **Wiki pflegen:** Neue Erkenntnisse in bestehende Wiki-Seiten einarbeiten, neue Seiten anlegen
|
|
5. **index.md + log.md:** Nach jedem Ingest aktualisieren
|
|
|
|
### Entscheidungsbaum (Curation vs. Reply)
|
|
|
|
Die zwei Bäume sind **unabhängig**:
|
|
|
|
- **Antworten?** → Group-Chat-Regeln in `AGENTS.md` (Know When to Speak)
|
|
- **Wikifyen?** → Ist der Inhalt wissensrelevant (Tool, Architektur, Entscheidung, Konzept, Person)?
|
|
|
|
Wenn wikifyen → **subagent spawnen** (isolated). Kein Reply nötig. Der Subagent kümmert sich um:
|
|
1. raw-Datei anlegen mit Frontmatter
|
|
2. Wiki-Seite(n) aktualisieren/erstellen
|
|
3. index.md und log.md updaten
|
|
|
|
### Wann eingreifen?
|
|
|
|
- **Kuratiere alles, was Wissen akkumuliert** — Entscheidungen, Tools, Architektur, Konzepte, Personen
|
|
- **Transiente Konversation** (Smalltalk, Status-Updates ohne Tiefe) — ignorieren
|
|
- **Unsicher? Frag im RamaDama-Topic nach.** Lieber einmal kurz nachfragen als falsch einsortieren
|
|
|
|
### Wie starten?
|
|
|
|
1. Clone: `git clone https://vmd185580.tailf38284.ts.net/hector-bot/knowledge-base.git`
|
|
2. Rohdaten-Sammeln: Links aus aktuellem Chat → als raw-Dateien ablegen
|
|
3. Ingest-Run: Agent verarbeitet raw/ → wiki/
|
|
|
|
*Erstellt: 2026-06-05 | Schema-Version: 1.1* |