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

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

Subconscious Outcomes (raw):

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

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

Wiki-Pages haben minimales Frontmatter

Standard (Fakten-Seiten):

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

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