# 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/ ← Legacy-Personenseiten (wird schrittweise nach people/ überführt) │ ├── tools/ ← Tools, Instanzen, Credentials │ ├── architecture/ ← Architektur-Entscheidungen │ ├── concepts/ ← Konzepte, Erklärungen (sub-organisiert seit v1.3) │ │ ├── llm/ ← LLM-spezifische Konzepte (Fusion, Behavior, GLM, SSR, etc.) │ │ ├── agents/ ← AI-Agents, Subconscious, Trading/Payment-Bots │ │ ├── policy/ ← AI-Policy, Regulation, Biosecurity │ │ ├── directives/ ← Projekt-Direktiven (Pro-Leben, Qualität, Bot-Policy) │ │ └── agi/ ← AGI-bezogene Konzepte (Aschenbrenner, etc.) │ │ └── hardware/ ← Hardware-Frontier (Neuromorphic, Edge-Inferenz, etc.) │ ├── people/ ← Personen-Artikel (jede im Wiki erwähnte Person bekommt einen Eintrag) │ ├── institutions/ ← Institutionen, Organisationen, Firmen, Labs, Stiftungen, Unis — NICHT nur Companies │ ├── 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 ← Legacy, wird zu wiki/people/ wiki/people/kai.md ← Ziel-Konvention ab Schema v1.5 wiki/institutions/openai.md ← Beispiel: Institution statt Company wiki/tools/forgejo-botreasury.md wiki/architecture/plur1bus-memory-stack.md wiki/concepts/llm/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.* **Kardinalregel: Reply-Sichtbarkeit mit URL-Übersicht.** Jeder Wikify-Reply an einen sichtbaren Channel (Telegram, DM, etc.) MUSS eine URL-Übersicht enthalten: - **🆕 Neue Wiki-Seiten:** Repo-Browse-Link + Commit-SHA + 1-Zeiler zur Inhaltsangabe - **🔧 Maßgeblich veränderte Seiten:** Repo-Browse-Link + Commit-SHA + kurze Änderungsnotiz - **Optional: Refactor-Notizen** (Strukturänderungen, neue Kategorien, etc.) Format-Vorlage: ``` **🆕 Neue Wiki-Seiten (N):** 1. [seite.md](https://...repo.../wiki/konzept/seite.md) — [abc1234](https://.../commit/abc1234) — 1-Zeiler 2. ... **🔧 Maßgeblich verändert:** - [seite.md](...) — [def5678](...) — was sich geändert hat ``` Faustregel: Pit/K9ert müssen ohne Klick ins Repo verstehen können, was neu ist und wo es liegt. Lieber ein Link zu viel als einer zu wenig. *Hinzugefügt 2026-06-16 nach Feedback von @k9ert in OME Topic 13 (#6620). Erweitert die 'Maximale Verlinkung'-Kardinalregel um interne Repo-Sichtbarkeit.* ### 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/agents/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 **Mechanischer Lint:** `scripts/wiki-lint.sh` führt deterministische Checks aus (Stubs, Frontmatter, Broken-Refs, Orphans, Dup-Cluster, File-Count, Stale, Raw-Coverage). Output: `scripts/wiki-lint-report.md`. Exit 1 bei Issues. Tests: `scripts/wiki-lint-test.sh` (17 Asserts, 3 Fixtures). **Kein LLM im Detection-Pfad** — Agent liest nur den Report und entscheidet, welche Subagents für Fixes zu spawnen sind. **Wiki-Link-Checker:** `scripts/check-wiki-links.py` validiert alle `[[...]]` Wikilinks source-relative (entspricht Forgejo/Gitea Markdown-Rendering-Verhalten). Akzeptiert auch `[[path|Label]]`. Exit 1 bei broken links. Code-Spans (`...`) und Template-Placeholders (`[[{slug}]]`) werden ignoriert. Auto-Fix: `scripts/fix-wiki-links.py` (5 Bug-Klassen: `wiki/`-Prefix, Path-Confusion, plain basename, `raw/`-Links, `../` Mismatch). **Pre-Commit-Hook:** `.git/hooks/pre-commit` ruft `scripts/check-wiki-links.py` vor jedem Commit. Installation: nach `git clone` einmalig `cp scripts/.check-wiki-links-wrapper.sh .git/hooks/pre-commit && chmod +x .git/hooks/pre-commit`. ### 5. Maintenance-ToDos Wiki-Pflege läuft über `wiki/tasks/maintenance-todo.md` (versioniert). Schema: - IDs: `WMT-XXX` (Wiki-Maintenance-ToDo) - Status: `planning` (Vorschlag wartet) → `in-progress` (Subagent läuft) → `done` (Datum + Commit-Hashes) - Pro ToDo: Category, Effort, Subagent-Template-Verweis - Subagent committet Arbeit + ToDo-Update im finalen Commit **On-Demand-Trigger:** Im RamaDama-Topic schreiben `wiki-do WMT-XXX` → Hauptagent parsed, schiebt ToDo auf `in-progress`, spawnt den passenden Subagent. **Subagent-Templates:** `scripts/subagents/{name}.md`. Jedes Template beschreibt Input, Aufgabe, Constraints, Commit-Pattern, Failover-Modellkette (`ollama/glm-5.1 → ollama/minimax-m3 → ollama/deepseek-v4-flash:cloud → ollama/glm-5`). **Reporting:** Jede Aktion → Topic-Post in RamaDama. Drei Report-Typen: Lint-Report (mechanisch), Subagent-Action-Report (was gemacht), Weekly-Summary. **Vollständige Architektur-Doku:** siehe `wiki/tasks/maintenance-todo.md` "Wie es läuft" + Memory `12fd8a00-f6c4-4a03-b195-5d7da3efa469`. --- ## 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.5 (2026-06-17: Neue Wiki-Kategorien `wiki/people/` und `wiki/institutions/` für Personen- und Institutions-Artikel. Bestehende `wiki/teams/`-Inhalte werden schrittweise nach `people/` überführt — ToDos WMT-009 + WMT-010 in `wiki/tasks/maintenance-todo.md`. Basis: User-Feedback k9ert 2026-06-17 #6800.)*