knowledge-base/AGENTS.md

# 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
- `/wiki/ideas.md` — Ideen-Index (Subconscious Outcomes)

---

## 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)
│   ├── subconscious/   ← Subconscious Agent Outcomes (raw vom Cron)
│   ├── other/          ← Sonstiges (Screenshots, PDF, Notes)
│   └── ...             ← Weitere Typen jederzeit möglich
├── wiki/               ← LLM-kompilierte Wissensbasis
│   ├── index.md        ← Auto-generated catalog (Fakten)
│   ├── ideas.md        ← Ideen-Index (Subconscious Outcomes, getrennt von Fakten)
│   ├── log.md          ← Append-only changelog
│   ├── teams/          ← Personen, Rollen
│   ├── tools/          ← Tools, Instanzen, Credentials
│   ├── architecture/   ← Architektur-Entscheidungen
│   ├── concepts/       ← Konzepte, Erklärungen
│   ├── decisions/      ← Dated decisions
│   ├── ideas/          ← Kompilierte Ideen-Seiten (Subconscious Outcomes)
│   └── ...             ← 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
raw/subconscious/2026-06-06_plur1bus-priority-fix.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
wiki/ideas/2026-06-06_plur1bus-priority-fix.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
---
```

**Subconscious Outcomes (raw):**
```yaml
---
type: subconscious
source_url: "file:///home/node/workspace/.subconscious/state/outcomes.jsonl"
retrieved: 2026-06-07
title: "Subconscious Outcome: Kurzer Titel"
tags: [subconscious, execution-gap, accepted]
run_id: run-20260606-200013
outcome: accepted
convergence: 0.90
---
```

**Sonstiges:**
```yaml
---
type: other
source_url: ""
retrieved: 2026-06-05
title: "Notiz"
tags: []
---
```

### Wiki-Pages haben minimales Frontmatter

**Standard (Fakten-Seiten):**
```yaml
---
created: 2026-06-05
updated: 2026-06-05
sources: [blog/2026-06-04_understanding-agent-memory-systems.md]
tags: [architecture, agents]
---
```

**Ideen-Seiten (Subconscious Outcomes):**
```yaml
---
created: 2026-06-07
updated: 2026-06-07
sources: [subconscious/2026-06-06_plur1bus-priority-fix.md]
status: not-implemented
tags: [subconscious, execution-gap, system]
---
```

Status-Werte: `implemented | not-implemented | shelved`

---

## 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.

**Kardinalregel: Maximale Verlinkung.** Jede Quelle, jedes Paper, jeder Autor, jeder zitierte Begriff im Wiki MUSS verlinkt sein. Das Wiki lebt von Verlinkungen — ohne sie ist es tot. Mindestens:

- **Papers:** arXiv-URL + Semantic Scholar / DOI / OpenReview-Link
- **Autoren:** Autoren-Homepage oder GitHub, falls bekannt
- **Externe Konzepte:** Wikipedia- oder maßgebliche Sekundärquelle
- **Interne Konzepte:** Wiki-Cross-Reference mit `[[seite.md]]`
- **Rohdaten (X-Posts, Blogs, Videos):** direkte URL zur Quelle

**Faustregel:** Wenn ein Leser auf einen Namen/Begriff klicken können sollte, dann verlinke. Lieber ein Link zu viel als einer zu wenig.

*Hinzugefügt 2026-06-15 nach Feedback von @k9ert.*

### 2. Subconscious-Ingest: Outcome → Wiki

Wenn ein neues Subconscious Outcome (raw/subconscious/) hinzukommt:

1. **raw/subconscious/** schon da (gepusht vom Post-Processing-Script)
2. **Erstelle wiki/ideas/{slug}.md** mit Frontmatter + Inhalt + Status not-implemented
3. **Aktualisiere wiki/ideas.md** — füge Zeile in Tabelle
4. **Hänge Eintrag an log.md**
5. **Optional:** Verlinke mit bestehenden Seiten (concepts/subconscious-agent.md)

**Abgrenzung zu wiki/index.md:** ideas.md wird separat geführt, damit der Fakten-Index nicht mit Ideen überladen wird.

### 3. 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.

### 4. 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 | wiki/ideas | schema
```

Beispiele:
```
ingest(subconscious): plur1bus-priority-fix
wiki-update(ideas): added new accepted outcome
schema(ideas): add idea frontmatter template
lint(wiki): found 3 orphan pages, missing cross-refs
```

---

---

## 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.2 (2026-06-07: added raw/subconscious, wiki/ideas, ideas.md)*