---
name: knowledge
description: Router de conhecimento Família A/B. Família A (operacional interna) consultada em paralelo para qualquer pergunta sobre processos, projectos, decisões, histórico. Família B (NotebookLM externa) só para conhecimento conceptual/teórico. v2.1.1
---

# /knowledge — Router Família A/B v2.1.1

> **Correcção arquitectural 08-04-2026:** a v2.0.0 tratava NotebookLM como fonte primária. Isso estava errado — NotebookLM não vê operações, não vê estado real, só tem ebooks e transcripts. Em `~/.claude/projects/-media-ealmeida-Dados-Hub/memory/feedback_knowledge-router-arquitectura.md` está o racional completo.

## Princípio de routing

**Não é fallback linear.** É router por tipo de pergunta:

- **Operacional / processual / histórico / decisões / projectos / código interno** → **Família A em paralelo**, consolidar com citação de origem.
- **Conceptual / teórico / externo / research / mercado / ebooks** → **Família B (NotebookLM)** com routing por tema (tabela em baixo).
- **Ambíguo** → perguntar ao utilizador qual o tipo.

## Família A — Operacional interna (paralelo, complementares)

| Fonte | Tool | Conteúdo |
|-------|------|----------|
| **LightRAG** | `mcp__lightrag__query_document` (modo `hybrid`) | Knowledge graph interno. **LightRAG-HKU 1.4.13** completo — REST API + WebUI em `rag.descomplicar.pt` + PG storage (workspace `default`) + AGE graph extension. **17 tools MCP disponíveis** (ver lista abaixo). 331 docs no Postgres (135 processed + 194 pending + 2 processing + 6 failed). |
| **memory-supabase** | `mcp__memory-supabase__search_memories(query, threshold=0.7, limit=10)` | Memórias persistentes cross-sessão com embeddings. Decisões, contexto, lacunas anteriores. |
| **Memória CC cross-projecto** | `Grep` recursivo em `~/.claude/projects/*/memory/*.md` | **101 ficheiros em 34 projectos (~261kB).** Harness só carrega automaticamente a memória do `cwd` — este grep é **obrigatório** para não perder contexto de outros projectos. |
| **Obsidian / Hub** | `Grep` em `/media/ealmeida/Dados/Hub/**/*.md` | PROCs, QRs, INDEX, frontmatter, procedimentos, histórico. |
| **Desk CRM** | `mcp__desk-crm-v3__*` (tasks, projects, tickets, customers) | Fonte de verdade operacional: tarefas, projectos, clientes, tickets, horas. |

### Workflow Família A

```
1. Classificar pergunta como operacional (default para queries internas)
2. Disparar em PARALELO (mesma mensagem, vários tool calls):
   - mcp__lightrag__query_document(query, mode="hybrid")
   - mcp__memory-supabase__search_memories(query, threshold=0.65, limit=8)  [graceful se MCP indisponível]
   - Grep ~/.claude/projects/*/memory/*.md
   - Grep Hub/**/*.md (limitar a pastas relevantes quando possível)
   - Desk CRM search (se query menciona cliente/projecto/tarefa)
3. Consolidar resposta citando origem de cada fragmento
4. Se Família A insuficiente → perguntar ao utilizador ou escalar para Família B
```

### 17 tools MCP LightRAG-HKU disponíveis

**Consulta / leitura:**
- `query_document(query, mode)` — RAG query. **Principal para router.** Modos: `naive`, `local`, `global`, `hybrid`, `mix` (default: `hybrid`).
- `get_documents()` — lista docs com status (processed/pending/processing/failed) e metadata.
- `get_pipeline_status()` — estado do pipeline de ingestão (busy, job, batchs).
- `get_graph_labels()` — entity types no knowledge graph.
- `check_lightrag_health()` — health check do server.

**Ingestão:**
- `insert_document(text)` — insere texto único, extrai entidades + relações.
- `insert_batch(texts[])` — batch de textos.
- `insert_file(path)` — insere ficheiro local.
- `upload_document(file)` — upload binário.
- `scan_for_new_documents()` — trigger scan do `INPUT_DIR` (`/root/mcp-lightrag/inbox/`).

**Edição de grafo:**
- `create_entities`, `edit_entities`, `delete_by_entities`, `merge_entities`
- `create_relations`, `edit_relations`
- `delete_by_doc_ids` — remove doc + entidades órfãs.

**UI web:** `https://rag.descomplicar.pt/webui/` com autenticação (`AUTH_ACCOUNTS` no `.env` do gateway).

**Nota sobre graceful fallback:** as tools `mcp__*` podem estar indisponíveis em sessões específicas por razões de auto-discovery do harness. Se a chamada falhar com "No such tool available", continuar o paralelismo com as outras fontes e reportar a lacuna no output final.

### Formato de resposta Família A

```markdown
## [pergunta]

**LightRAG:** [excerto] _(entidade X, score Y)_
**memory-supabase:** [excerto] _(id N, tags)_
**memory/<projecto>:** [excerto] _(ficheiro)_
**Hub:** [excerto] _(caminho:linha)_
**Desk CRM:** [excerto] _(task #N, projecto #M)_

**Síntese:** [consolidação em 2-3 frases citando as fontes mais fortes]
```

**Regra:** nunca responder sem citar fonte. Se 0 fontes, dizer "sem hits em Família A" explicitamente.

---

## Família B — Conhecimento externo (NotebookLM)

**Quando usar:** só para perguntas **conceptuais, teóricas, de research externo ou mercado**. Nunca para operacional.

Exemplos de queries Família B:
- "Quais são as melhores práticas de Core Web Vitals em 2025?"
- "Como funciona o algoritmo de ranking do YouTube Shorts?"
- "Arquétipos de Jung aplicados a branding"
- "Stoicismo na gestão de equipas"

**Workflow Família B:**

1. Classificar tema → tabela de routing
2. Consultar **max 3 notebooks** (performance)
3. `mcp__notebooklm-mcp__notebook_query({ notebook_id, query })`
4. Se score <70 → fallback a Context7 (docs bibliotecas)

### Routing por tema (65 notebooks)

> Inventário completo: `~/.claude/projects/-media-ealmeida-Dados-Hub/memory/notebooklm-inventory.md`

**WordPress/Web**

| Keywords | Notebook | ID |
|----------|----------|----|
| wordpress, wp-cli, config | WordPress Config CLI | `fb2f26bd-8cb0-4d4c-bafc-4f1ebb51c51d` |
| elementor, templates, widgets | WordPress e Elementor | `5be0d1a6-00f2-4cd9-b835-978cb7721601` |
| woocommerce, loja, produtos | Documentacao WooCommerce | `bd06acff-4b9d-44aa-b3f7-60434bbd6b49` |
| kivicare, ehr, clinica | KiviCare EHR WP | `78621405-a5bc-433f-856f-296260a80bd9` |
| seguranca wp, malware, hardening | Ciberseguranca WordPress | `5f60adfd-2435-4725-8c12-9c11c5f51d75` |

**Marketing e Conteúdo**

| Keywords | Notebook | ID |
|----------|----------|----|
| marketing, digital, campanha, funil | Marketing Digital PT | `4c595973-ba10-420a-a3bf-e4389e424ad3` |
| marketing avancado, ads, growth | Marketing Digital Avancado | `76647e0f-3ae2-4c00-a0a8-f457aebf5655` |
| seo, keywords, ranking, serp | Marketing Digital PT | `4c595973-ba10-420a-a3bf-e4389e424ad3` |
| copywriting, persuasao, texto | Copywriting e Persuasao | `7b8fec17-d34f-4e3f-a8c6-8231e51f6323` |
| social media, branding, instagram | Social Media e Branding | `9053d0e8-dd39-460b-b5ea-e67af3e9a675` |
| video, producao, youtube | Producao de Video e Youtube | `058a896e-6c9a-4e51-ae7d-9adb2738bc5f` |
| youtube, monetizacao, compliance | YouTube Monetizacao e Compliance | `60a209a7-e205-4d57-a6f3-fef3de61e87a` |
| podcast, audio | Podcast Descomplicar | `a5bef96b-a1af-4293-9979-5da46f8d2301` |
| ecommerce, loja online | E-commerce Pratico | `226e384e-d4bc-48f4-bb82-7927360436cc` |
| ecommerce portugal, marketplace | E-Commerce Portugal | `8a430cf2-ed99-413d-b4bf-a1400deaf49e` |

**Desenvolvimento / Código (externo)**

| Keywords | Notebook | ID |
|----------|----------|----|
| programacao externa, padroes, api design | Programacao | `24947ffa-0019-448a-a340-2f4a275d2eb1` |
| claude code, mcp dev externo | Claude Code | `2876d1fe-5cea-4d98-8140-b0e1a81c6bc4` |
| mcp protocolo | Desenvolvimento de MCPs | `73102308-70ef-403e-9be9-eae0cfc62d55` |
| ai editor, cursor, copilot | AI Code Editors | `57d9c6c9-48ba-4d83-8f71-cc890f348a53` |
| github trends | GitHub Trends | `922b7532-ddf3-4dba-9d3c-6d5f83b89378` |
| open source, foss | Open Source Software and Platforms | `cabf9821-c1ff-44cb-9bfd-59bda3599792` |
| n8n, workflow automacao | n8n | `f2c809b8-1cb5-4dd0-aa7e-be2cfb6704d1` |
| perfex dev, hooks externos | Dev PerfexCRM | `80606de8-2783-4d36-b08d-5825e6f9a8da` |
| remotion, video code | Remotion | `f2b75baa-1ab1-48d3-8f7c-a6a9e516934c` |

> **Nota:** código do projecto (`/Dev/*`, plugins locais, MCPs desenvolvidos internamente) é **Família A** (grep Hub + filesystem), não Família B.

**Infraestrutura**

| Keywords | Notebook | ID |
|----------|----------|----|
| cwp externo | CWP | `0ded7bd6-69b3-4c76-b327-452396bf7ea7` |
| cloud, devops patterns | Cloud e Infraestrutura TI | `f9a79b5a-649f-4443-afaf-7ff562b6c2e7` |
| proxmox | Proxmox | `276ccdde-6b95-42a3-ad96-4e64d64c8d52` |

**Design/UX**

| Keywords | Notebook | ID |
|----------|----------|----|
| design, branding externo | Design Profissional AItomatizado | `b568b13b-0eed-48c9-b513-5c5b7ec0b102` |
| ui, ux, wcag | UI/UX Design | `081ca512-8279-4850-b2b9-dff090267482` |
| tipografia, cores | Tipografia e Cor para Web | `f97a0d2b-a5b3-4640-b941-3cbb184b1b81` |

**Gestão e Estratégia**

| Keywords | Notebook | ID |
|----------|----------|----|
| gestao projectos, agile, scrum | Gestao de Projectos e Agile | `0c9c079c-a426-486c-99eb-1564d42d37ad` |
| operacoes externas, kpi | Gestao de Operacoes | `f9dc59c2-718b-4b12-bd06-095d4bfa3e34` |
| estrategia, empreendedorismo | Estrategia e Empreendedorismo | `79d43410-0e29-4be1-881d-84db6bdc239a` |
| transformacao digital, ia negocio | Transformacao Digital e IA | `ab876d0d-12a8-43d9-bc62-59c1c8e9d0f8` |
| ai automation stack | AI Automation Stack | `929ef67b-c131-4f01-abd0-8b078491a6b7` |
| ai agents curso | AI Agents Intensive Course | `f4be0e3f-4d9e-4c5c-a743-9f14427f2e43` |

**Produtos externos / Mercado**

| Keywords | Notebook | ID |
|----------|----------|----|
| zaia, chatbot | Zaia | `087d76f1-e929-49da-9e3c-4edc22b42b3f` |
| zender, whatsapp api | Zender 3 | `7095e5fa-1465-4496-b1a3-48f2e6e07f79` |
| solar, fotovoltaico | Solar FV Engenharia | `03d54e00-aefa-45dc-ba01-f3864a7c3112` |
| opensolar | OpenSolar | `0082bcaf-1e17-4b84-87cc-2256b1719b55` |

**Pessoal / SelfRescueProtocol** (só se explicitamente pessoal)

| Keywords | Notebook | ID |
|----------|----------|----|
| jung, arquetipos | Jung | `d5c67d7f-7fe8-4542-9e5c-22403f3193ee` |
| taoismo, wu wei | Taoism | `aea85baf-9ddf-4d79-bf07-81391a275b09` |
| adhd, phda | ADHD | `a4ff3fd7-fb7c-49a1-94ff-0433193e2338` |
| autismo | Autismo | `66eff78e-318f-4a8b-a3c7-039a4124b1ad` |
| heroi, jornada | Essencia de Heroi | `6dcd08e8-79d9-4ae0-b6bf-b2ee96717bf2` |
| kintsugi | Auto Kintsugi | `82a95c2f-be56-4c4a-a96f-96f6677a6991` |
| somatica, trauma | Psicologia Somatica | `3410893b-16a3-4178-9091-42650a41086f` |
| estoicismo | Marcus Aurelius / Stoic | `4b986ad4-49da-4604-a423-4fcdf20dd9da` |

---

## Classificador de pergunta (heurística)

Usar estes sinais para decidir Família A vs B:

| Sinal na pergunta | Família |
|---|---|
| Nome de cliente, projecto, tarefa #N, ticket #N | **A** |
| "quando", "histórico", "última vez", "decisão", "porque fizemos" | **A** |
| Nome de ficheiro, path, skill, plugin, MCP interno | **A** |
| "como funciona (abstracto)", "melhores práticas", "teoria de" | **B** |
| Nome de biblioteca externa + versão | **B** (+ Context7) |
| Pessoal explícito (jung, adhd, estoicismo, …) | **B** pessoal |
| Ambíguo | **perguntar** |

---

## Comandos

| Comando | Uso |
|---------|-----|
| `/knowledge [pergunta]` | Router automático A/B com paralelismo |
| `/kb [pergunta]` | Alias curto |
| `/kb-save [conteúdo]` | Guardar na fonte adequada (LightRAG se operacional, Supabase se decisão, NotebookLM source_add se externo) |
| `/kb-gaps` | Listar lacunas detectadas em `memory-supabase` |

---

## Gravar conhecimento (/kb-save)

Router inverso por tipo:

| Tipo | Destino | Tool |
|---|---|---|
| Decisão / contexto / lacuna | memory-supabase | `mcp__memory-supabase__save_memory` com tags |
| Entidade / relação / doc interno | LightRAG | `mcp__lightrag__insert_document(text)` ou `insert_batch(texts)` |
| Procedimento operacional | Hub/06-Operacoes/Procedimentos/ | `Write` PROC-*.md |
| Conhecimento externo | NotebookLM notebook adequado | `mcp__notebooklm-mcp__source_add` |

---

## Detecção e reporte de lacunas

Quando query retorna 0 hits úteis em Família A (o caso relevante) ou <30% score em Família B:

```javascript
mcp__memory-supabase__save_memory({
  content: `LACUNA: "${query}" — Família A 0 hits, classificada como ${classificacao}.`,
  tags: ["lacuna-kb", classificacao],
  metadata: { query, timestamp, source_families: ["A","B"] }
});
```

Depois sugerir acção: criar PROC, adicionar ao LightRAG, adicionar fonte ao notebook adequado.

---

## Regras operacionais

1. **Família A é default.** Só escalar para B quando classificador sinalizar externo.
2. **Paralelismo obrigatório em Família A.** Todas as tools na mesma mensagem (regra global #1: "NEVER run independent tool calls sequentially").
3. **Grep cross-projecto obrigatório** em `~/.claude/projects/*/memory/*.md` — o harness só carrega a memória do `cwd`, este grep compensa esse gap.
4. **Nunca responder sem citar fonte.** Se 0 hits, dizer explicitamente.
5. **Max 3 notebooks** por query Família B.
6. **PT-PT sempre** na consolidação.
7. **Se a pergunta é sobre estado presente** (tarefas abertas, tickets, horas, facturas), ir **directo ao Desk CRM**, não a LightRAG/NotebookLM.

---

## Anti-patterns

- ❌ Começar por NotebookLM para perguntas operacionais (era o erro da v2.0.0)
- ❌ Só consultar o `cwd` e ignorar memory cross-projecto
- ❌ Responder sem citar fonte
- ❌ Chamar Família A em série — tem de ser paralelo
- ❌ Classificar "como funciona o nosso router /knowledge?" como Família B (é Família A — é sobre infra interna)
- ❌ Fallback linear A→B quando a pergunta é claramente externa (vai directo a B)

---

## Referências

- `references/routing-guide.md` — mapeamento detalhado de routing (pendente v2.1 — actualizar)
- `~/.claude/projects/-media-ealmeida-Dados-Hub/memory/feedback_knowledge-router-arquitectura.md` — decisão arquitectural
- `~/.claude/projects/-media-ealmeida-Dados-Hub/memory/notebooklm-inventory.md` — inventário completo 65 notebooks
- `04-Stack/CHANGELOG.md` sessão 3 de 08-04-2026 — recuperação LightRAG e clarificação tools reais

---

## Healing log

```jsonl
{"date":"2026-04-08","issue":"v2.0.0 tratava NotebookLM como fonte primaria para tudo","fix":"v2.1.0 router Familia A/B — NotebookLM so para externo","source":"user"}
{"date":"2026-04-08","issue":"v2.1.0 assumia FastMCP file-based (11 tools lightrag_*) apos migracao temporaria da outra sessao","fix":"v2.1.1 restaurado para LightRAG-HKU completo com 17 tools originais (query_document, insert_document, get_pipeline_status, etc), UI em rag.descomplicar.pt, PG storage 331 docs","source":"user"}
{"date":"2026-04-08","issue":"memoria Claude Code fragmentada em ~/.claude/projects/*/memory/ (101 ficheiros, 34 projectos)","fix":"grep cross-projecto obrigatorio no router Familia A","source":"user"}
{"date":"2026-04-08","issue":"mcp__memory-supabase__search_memories pode estar indisponivel no harness","fix":"graceful fallback no router — continuar paralelismo com outras fontes e reportar lacuna","source":"auto"}
```

---

**v2.1.1** | 08-04-2026 | LightRAG-HKU restaurado com 17 tools reais, UI rag.descomplicar.pt, PG storage 331 docs, graceful fallback para MCPs indisponíveis