From ba2ce3c821154282c6968cf526f34f548a9869c9 Mon Sep 17 00:00:00 2001
From: Enmanuel <egutierrez@dead.dd>
Date: Sun, 8 Mar 2026 21:56:58 +0000
Subject: [PATCH] docs: crear carpeta knowledges con README
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Carpeta raiz para documentos compartidos entre agentes
- README explica proposito, funcionamiento, diferencia con privado
- Ejemplo de flujo de colaboracion entre agentes
- Issue 0018: Shared Knowledge (fase 4)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 knowledges/README.md | 63 ++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 63 insertions(+)
 create mode 100644 knowledges/README.md

diff --git a/knowledges/README.md b/knowledges/README.md
new file mode 100644
index 0000000..9fba459
--- /dev/null
+++ b/knowledges/README.md
@@ -0,0 +1,63 @@
+# Shared Knowledge Base
+
+Esta carpeta contiene la **base de conocimiento compartida** entre todos los agentes del sistema.
+
+## Propósito
+
+Los agentes pueden leer, escribir y buscar documentos en esta carpeta usando las tools `shared_knowledge_*`. Esto permite que múltiples agentes colaboren acumulando y consultando conocimiento común.
+
+## Funcionamiento
+
+- **Documentos**: Los archivos `.md` en este directorio son los documentos de conocimiento compartidos entre agentes.
+- **Índice FTS5**: Los documentos se indexan automáticamente en `data/knowledge.db` (SQLite con Full-Text Search).
+- **Sincronización**: El índice se actualiza al arrancar cada agente con `Sync()`.
+- **WAL mode**: El DB usa WAL (Write-Ahead Logging) para permitir lecturas y escrituras concurrentes entre múltiples procesos.
+
+## Tools disponibles
+
+Los agentes con `tools.shared_knowledge.enabled: true` tienen acceso a:
+
+- `shared_knowledge_search` — buscar documentos por query
+- `shared_knowledge_read` — leer un documento por slug
+- `shared_knowledge_write` — crear o actualizar un documento
+- `shared_knowledge_list` — listar todos los documentos compartidos
+
+## Diferencia con knowledge privado
+
+Cada agente puede tener **dos bases de conocimiento**:
+
+1. **Knowledge privado** (`agents/<id>/knowledge/`): solo visible para ese agente, tools `knowledge_*`
+2. **Knowledge compartido** (`knowledges/`): visible para todos los agentes con shared_knowledge habilitado, tools `shared_knowledge_*`
+
+## Ejemplo de flujo
+
+```
+1. agente-A recibe: "investiga X y guarda lo que encuentres"
+   → LLM usa shared_knowledge_write(slug: "investigacion-x", content: "...")
+   → Se escribe knowledges/investigacion-x.md + actualiza FTS5
+
+2. agente-B recibe: "qué sabemos sobre X?"
+   → LLM usa shared_knowledge_search(query: "X")
+   → Encuentra el documento que escribió agente-A
+   → shared_knowledge_read(slug: "investigacion-x")
+   → Responde con la información
+```
+
+## Estructura
+
+```
+knowledges/
+  ├── README.md                    ← este archivo
+  ├── *.md                         ← documentos compartidos (commiteados)
+  └── data/
+      ├── knowledge.db             ← índice SQLite FTS5 (no commiteado)
+      ├── knowledge.db-shm
+      └── knowledge.db-wal
+```
+
+## Notas
+
+- Los archivos `.md` se commitean en el repositorio (forman parte del conocimiento compartido del equipo).
+- El directorio `data/` está en `.gitignore` — el índice se reconstruye automáticamente al arrancar.
+- No hay control de acceso por agente: cualquier agente con shared_knowledge habilitado puede leer y escribir.
+- Si dos agentes escriben el mismo slug, el último gana (sobreescritura).