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

---

Directory Structure

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)
├── 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
├── 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:

---
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:

---
type: xpost
source_url: https://x.com/username/status/123456789
retrieved: 2026-06-05
author: "@username"
is_thread: true
quote_count: 5
---

YouTube:

---
type: youtube
source_url: https://youtube.com/watch?v=xxx
retrieved: 2026-06-05
channel: "Channel Name"
duration_sec: 1847
has_transcript: true
---

Sonstiges:

---
type: other
source_url: ""
retrieved: 2026-06-05
title: "Notiz"
tags: []
---

Wiki-Pages haben minimales Frontmatter

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

---

Erstellt: 2026-06-05 | Schema-Version: 1.0