Wetopi Knowledge Plane — Memoria Técnica

1. Objetivo técnico

Diseñar una plataforma documental y de conocimiento que permita a humanos, Hermes y futuros agentes ADK compartir una única representación canónica de Wetopi.

Requisitos:

• Markdown como formato base.
• Git como source of truth.
• Publicación automática a docs.wetopi.net.
• Uso nativo por Hermes.
• Compatibilidad con la skill llm-wiki.
• Operación multiagente.
• Recuperación eficiente sin introducir repos completos en contexto.
• Relaciones explícitas entre documentos.
• Búsqueda lexical, semántica y por grafo.
• Integración con Hindsight.
• Integración con Ceph/S3.
• Índices completamente reconstruibles.
• Gobierno mediante PR y validaciones automáticas.

2. Componentes

2.1 wetopi-knowledge

Repositorio Git canónico.

Responsabilidades:

• wiki;
• arquitectura;
• ADR;
• runbooks;
• investigaciones;
• conceptos;
• registros operativos;
• documentación de servicios;
• metadata y relaciones.

No debe almacenar grandes logs, dumps, pcaps, binarios o artifacts temporales.

2.2 MkDocs

Responsabilidad:

Markdown → HTML

Pipeline objetivo:

merge main
   ↓
CI / webhook
   ↓
mkdocs build --strict
   ↓
validación
   ↓
publicación atómica
   ↓
docs.wetopi.net

MkDocs es una vista derivada, nunca source of truth.

2.3 Hermes llm-wiki

Hermes Agent incluye:

~/skills/research/llm-wiki

Versión conocida:

2.1.0

Capacidades:

• ingest;
• query;
• lint;
• raw;
• generación de páginas;
• conceptos;
• entidades;
• comparaciones;
• wikilinks;
• frontmatter;
• detección de problemas de integridad;
• integración opcional con Obsidian.

Wetopi debe reutilizar este comportamiento y añadir convenciones propias.

El WIKI_PATH de cada agente deberá apuntar a su worktree del repositorio wetopi-knowledge, no a una wiki privada aislada.

Ejemplo conceptual:

WIKI_PATH=/workspace/wetopi-knowledge

3. Estructura inicial del repositorio

wetopi-knowledge/
│
├── README.md
├── index.md
├── mkdocs.yml
├── AGENTS.md
│
├── infrastructure/
│   ├── index.md
│   ├── ovh/
│   ├── physical-nodes/
│   ├── proxmox/
│   ├── ceph/
│   └── networking/
│
├── platform/
│   ├── index.md
│   ├── rke2/
│   ├── cilium/
│   ├── traefik/
│   ├── argocd/
│   ├── infisical/
│   ├── litellm/
│   ├── hindsight/
│   ├── observability/
│   └── knowledge-plane/
│
├── wetopi-app/
├── wordpress-hosting/
├── operations/
├── agents/
│
├── architecture/
├── decisions/
├── concepts/
├── investigations/
├── incidents/
├── runbooks/
├── records/
│
├── _schema/
│   ├── README.md
│   ├── frontmatter.md
│   ├── document-types.md
│   ├── relations.md
│   └── naming.md
│
├── _templates/
│   ├── service.md
│   ├── adr.md
│   ├── investigation.md
│   ├── runbook.md
│   ├── concept.md
│   └── record.md
│
└── raw/
    └── README.md

raw/ sólo debe usarse para material pequeño y controlado compatible con Wiki-LLM. El raw voluminoso vive en S3.

4. Tipos documentales

ID	Tipo	Uso
SVC-*	Service	Servicio/plataforma
CON-*	Concept	Concepto transversal
ADR-*	Architecture Decision	Decisión arquitectónica
RFC-*	Request for Comments	Propuesta abierta
DES-*	Design	Diseño o Architecture Pack
RUN-*	Runbook	Procedimiento operativo
INV-*	Investigation	Investigación técnica
INC-*	Incident	Incidente
REC-*	Operational Record	Hecho operacional histórico
OBJ-*	Objective	Objetivo de trabajo
ART-*	Artifact	Evidencia externa

Los IDs son globales, estables e inmutables.

5. Frontmatter

Mínimo común:

---
id: SVC-CILIUM
type: service
title: Cilium
domain: platform
status: active
created_at: 2026-09-07
last_verified: 2026-09-07
owners:
  - platform
tags:
  - kubernetes
  - networking
---

Relaciones:

depends_on:
  - SVC-RKE2

related:
  - CON-EGRESS

governed_by:
  - ADR-0023

runbooks:
  - RUN-CILIUM-001

evidence:
  - ART-02881

6. Relaciones del grafo

Relaciones iniciales:

DEPENDS_ON
PROVIDES
USES
AFFECTS
GOVERNS
SUPERSEDES
DERIVED_FROM
EVIDENCE
RELATED_TO
IMPLEMENTS
OPERATED_BY
DOCUMENTED_BY
INVESTIGATES
RESOLVES
PRODUCED

Ejemplo:

ADR-0023 ──GOVERNS──────► SVC-CILIUM
INV-0192 ──INVESTIGATES─► SVC-CILIUM
INV-0192 ──EVIDENCE─────► ART-02881
ADR-0023 ──DERIVED_FROM─► INV-0192

7. Wikilinks

Wiki-LLM utiliza:

[[Cilium]]
[[RKE2]]
[[Egress Architecture]]
[[ADR-0023]]

El indexador debe resolver:

1. ID exacto;
2. slug;
3. alias;
4. título;
5. redirects/superseded.

frontmatter = relación estructurada
wikilink    = relación contextual

8. Knowledge Index

El índice se considera estado derivado.

Entrada:

*.md

Extracción:

• Markdown AST;
• headings;
• párrafos;
• code blocks;
• frontmatter YAML;
• wikilinks;
• URLs;
• IDs;
• aliases;
• relaciones;
• Git metadata;
• estado;
• autoridad;
• timestamps.

Salida:

documents
nodes
edges
chunks
fts
vectors
metadata

9. Backend inicial recomendado

Primera versión:

SQLite
 + FTS5
 + grafo relacional
 + vector extension / vector store embebido

No introducir inicialmente Neo4j, Qdrant u OpenSearch salvo que métricas reales demuestren necesidad.

10. Modelo conceptual de datos

documents

id
path
title
type
domain
status
authority
created_at
updated_at
last_verified
git_commit
content_hash

nodes

node_id
node_type
label
document_id

edges

source_id
relation
target_id
source
confidence

source:

frontmatter
wikilink
markdown-reference
inferred
semantic

chunks

chunk_id
document_id
heading_path
content
token_count

11. Retrieval híbrido

query
  │
  ├── lexical / FTS
  ├── semantic
  ├── exact IDs
  ├── aliases
  ├── graph expansion
  └── authority/status
       │
       ▼
     rerank
       │
       ▼
context pack

Debe favorecer:

accepted ADR
current architecture
active service docs
active runbooks

y penalizar:

draft
stale
deprecated
superseded

12. wetopi-knowledge-mcp

Interfaz v0:

knowledge_search
knowledge_read
knowledge_related
knowledge_graph
knowledge_tree
knowledge_grep

Opcional posterior:

knowledge_context

para compilar un Context Pack compacto.

13. Context Pack

Respuesta conceptual:

QUESTION
...

AUTHORITATIVE
- ADR-...
- SVC-...

OPERATIONAL
- RUN-...

RELATED
- CON-...

MEMORY
- Hindsight refs

EVIDENCE
- ART-...

El MCP proporciona contexto trazable; no debe convertirse necesariamente en el agente que responde o decide.

14. Integración Hindsight

Hindsight almacena:

Facts

Hechos duraderos verificados.

Experiences

Resultados de acciones u operaciones.

Observations

Estado contextual potencialmente cambiante.

Learned Knowledge / Wisdom

Conclusiones generalizadas.

Debe incluir punteros:

source_ids
document_ids
artifact_ids
occurred_at
confidence

No debe retener documentos completos.

15. Integración S3

Bucket conceptual:

s3://wetopi-agent-artifacts/

Ejemplo:

ART-20260907-0001/
  manifest.yaml
  summary.md
  tcpdump.pcap
  kubectl.txt
  metrics.csv

El índice documental ingiere normalmente sólo:

manifest.yaml
summary.md
metadata

16. Agent Documentation Contract

Al finalizar trabajo significativo:

1. ¿Ha generado evidencia?
   → ART / S3

2. ¿Ha generado conocimiento reutilizable?
   → Wiki

3. ¿Ha tomado/propuesto una decisión?
   → ADR/RFC

4. ¿Ha ocurrido un hecho operacional relevante?
   → REC/INC

5. ¿Debe mantenerse experiencia o aprendizaje?
   → Hindsight

6. ¿Qué relaciones deben añadirse?
   → IDs / graph

Debe integrarse en el harness.

17. Multiagente

Nunca:

agent → git push main

Siempre:

agent
 ↓
isolated worktree
 ↓
branch
 ↓
llm-wiki lint
 ↓
schema validation
 ↓
graph validation
 ↓
mkdocs build --strict
 ↓
PR

Auto-merge posible

• enlaces;
• metadata;
• correcciones triviales;
• índices generados;
• last_verified;
• cambios mecánicos.

Revisión requerida

• ADR;
• arquitectura;
• seguridad;
• procedimientos destructivos;
• cambios de política;
• eliminación de conocimiento;
• reestructuración masiva.

18. Wiki Curator

On PR

• schema lint;
• broken links;
• orphan detection;
• duplicate IDs;
• invalid relations;
• MkDocs strict;
• secret scanning.

Daily

• new orphan pages;
• stale pages;
• unresolved wikilinks;
• contradictory metadata.

Weekly

• semantic duplicate candidates;
• consolidation suggestions;
• taxonomy drift;
• pages requiring synthesis.

19. Retirada de BookStack

Discovery

Buscar:

bookstack
book.wetopi.net
BOOKSTACK_
platform-bookstack

en:

• GitHub;
• docs;
• Argo CD;
• Helm;
• manifests;
• Infisical;
• DNS;
• Traefik;
• monitoring;
• dashboards;
• agents;
• prompts;
• skills;
• scripts;
• CI/CD.

Content migration

1. exportar BookStack;
2. clasificar páginas;
3. convertir contenido válido a Markdown;
4. adaptar al schema Wiki-LLM;
5. añadir IDs y wikilinks;
6. PR de migración;
7. validar;
8. marcar migración completa.

Infrastructure removal

Después:

disable writes
backup
remove ingress
remove DNS
remove Argo app
remove manifests
remove secrets
remove DB/storage
remove monitoring
remove documentation references

La destrucción de datos es la última etapa.

20. Seguridad

El repositorio nunca contiene secret values.

Los artifacts deben tener clasificación y retention.

El Knowledge MCP debe permitir ACLs si en el futuro existen dominios restringidos.

21. Observabilidad

Métricas propuestas:

documents_indexed
index_duration_seconds
broken_links
orphan_pages
duplicate_ids
graph_nodes
graph_edges
vector_chunks
search_latency
search_zero_results
context_pack_tokens
stale_documents
pages_created
pages_updated
lint_failures
curator_suggestions

22. Principios

1. Una sola fuente de verdad.
2. Markdown antes que bases propietarias.
3. Índices reconstruibles.
4. Relaciones explícitas antes que inferencia.
5. Semantic search complementa estructura.
6. Memoria no reemplaza documentación.
7. Raw no entra en Git.
8. Todo conocimiento relevante tiene provenance.
9. Los agentes contribuyen mediante Git.
10. La curación forma parte del sistema.