constella 0.1.0

package/docs/pt/MCP.md

@@ -0,0 +1,313 @@
+[← Índice](./README.md) · [🇬🇧 English](../en/MCP.md) · [✦ Constella](../../README.pt-BR.md)
+
+# 🛰️ Servidor MCP — Pilotando a Nave Central a partir da Órbita
+
+![](../assets/divider-orbit.svg)
+
+Um servidor **Model Context Protocol** autossuficiente (`scripts/mcp-server.mjs`) que expõe a API REST pública da Constella como ferramentas MCP, permitindo que um host de IA externo — Claude Desktop, Cursor ou qualquer cliente MCP — pilote o seu plano de controle Constella por linguagem natural.
+
+---
+
+## Quando usar
+
+Recorra ao servidor MCP quando quiser que uma **IA externa** observe e dirija a Constella sem abrir a interface web:
+
+- Perguntar ao Claude Desktop "qual é o status da minha empresa de agentes?" e fazê-lo chamar `constella_status`.
+- Aprovar um plano pendente, ligar/desligar a execução 24/7 ou iniciar um novo trabalho de dentro do chat do Cursor.
+- Integrar a Constella a qualquer host agêntico que fale MCP, usando um Personal Access Token com escopo como única credencial.
+
+Esta é a direção **de saída para a Constella** (outbound): um host de IA *dirige* a Constella. É o espelho da própria constelação de agentes da Constella *consumindo* servidores MCP externos — veja [Duas direções de MCP](#-duas-direções-de-mcp--não-confunda) abaixo.
+
+---
+
+## Como funciona 🌌
+
+O servidor MCP é uma ponte fina e sem dependências. Ele fala **JSON-RPC sobre stdio** com o host MCP, e cada chamada de ferramenta é traduzida em uma única requisição à API REST pública v1 (`/api/v1/...`), autenticada com um Personal Access Token (PAT).
+
+```
+Host MCP (Claude Desktop / Cursor)
+        │  JSON-RPC sobre stdio
+        ▼
+scripts/mcp-server.mjs  ──Bearer cn_…──►  /api/v1/[[...path]]  ──►  núcleos da Constella
+```
+
+Propriedades-chave direto do código-fonte:
+
+- **Zero dependências.** O `scripts/mcp-server.mjs` importa apenas `node:readline` e usa o `fetch` global (Node 18+). Ele acompanha a distribuição compilada sem alterações.
+- **MCP feito à mão.** Implementa diretamente os métodos JSON-RPC `initialize`, `notifications/initialized`, `ping`, `tools/list` e `tools/call` — sem SDK.
+- **Mapeamento fino.** O `build(args)` de cada ferramenta retorna `{ method, path, body? }`, que `callApi` envia para `${BASE}/api/v1${path}` com `Authorization: Bearer ${PAT}` (e `x-constella-org` quando `CONSTELLA_ORG` está definido).
+- **Uma só credencial.** A camada REST (`authenticatePAT` em `src/server/api/pat-auth.ts`) é exclusivamente por PAT; não há sessão. O escopo (`read` / `write`) é validado no servidor.
+- **Timeout de requisição.** Cada chamada REST usa `AbortSignal.timeout(30_000)` — um teto de 30 segundos por chamada de ferramenta.
+
+---
+
+## Fluxo principal 🚀
+
+```mermaid
+sequenceDiagram
+    participant Host as Host MCP (Claude Desktop)
+    participant MCP as mcp-server.mjs
+    participant API as dispatcher /api/v1
+    participant Core as plan-ops / work-ops / kb
+
+    Host->>MCP: initialize (stdio)
+    MCP-->>Host: serverInfo {name: constella}
+    Host->>MCP: tools/list
+    MCP-->>Host: 13 ferramentas constella_*
+    Host->>MCP: tools/call constella_status
+    MCP->>API: GET /api/v1/status (Bearer cn_…)
+    API->>API: authenticatePAT + rate-limit
+    API->>Core: apiStatus(workspace)
+    Core-->>API: contagens
+    API-->>MCP: {ok:true, data:{…}}
+    MCP-->>Host: content[text] (JSON formatado)
+```
+
+O ciclo de vida, passo a passo:
+
+1. **Handshake.** O host envia `initialize`; o servidor responde com `protocolVersion` (ecoando a do host, padrão `2024-11-05`), `capabilities: { tools: {} }` e `serverInfo: { name: "constella", version: "1.0.0" }`.
+2. **Descoberta.** Em `tools/list`, o servidor retorna todas as ferramentas (`name`, `description`, `inputSchema`).
+3. **Invocação.** Em `tools/call`, ele localiza a ferramenta pelo nome, chama `build(arguments)`, dispara a requisição REST via `callApi` e embrulha a resposta JSON como `{ content: [{ type: "text", text }], isError: data?.ok === false }`.
+4. **Auth e escopo.** O dispatcher REST autentica o PAT, aplica um rate limit de janela deslizante (120 req/min/token) e rejeita rotas de escrita quando o token tem escopo `read`.
+
+---
+
+## Conceitos-chave ✦
+
+| Conceito | Onde | Significado |
+|---|---|---|
+| **MCP de saída** | `scripts/mcp-server.mjs` | Um host de IA externo dirige a Constella via REST autenticada por PAT. |
+| **PAT** | tabela `personalAccessToken` | Token `cn_…`, com hash SHA-256, escopo `read` ou `write`, texto puro exibido uma vez. |
+| **Trava de escopo** | `route.ts` `needWrite()` | Tokens `write` podem mutar; tokens `read` recebem `403` em mutações POST. |
+| **Seleção de org** | `CONSTELLA_ORG` → `x-constella-org` | Escolhe em qual org um usuário multi-org atua (validado por participação). |
+| **Rate limit** | `route.ts` `rateLimited()` | Janela deslizante de 60s em memória, máximo de 120 requisições por token. |
+| **Envelope** | `route.ts` `ok()` / `fail()` | Toda resposta é `{ ok: true, data }` ou `{ ok: false, error }`. |
+
+---
+
+## Variáveis de ambiente 🪐
+
+O servidor MCP é configurado exclusivamente por variáveis de ambiente passadas pelo host:
+
+| Variável | Padrão | Obrigatória | Finalidade |
+|---|---|---|---|
+| `CONSTELLA_PAT` | — | **Sim** | O Personal Access Token `cn_…`. Use um token **write** para permitir aprovar/execução/novo-trabalho; um token **read** para somente leitura. Se ausente, toda ferramenta retorna `{ ok: false, error: "CONSTELLA_PAT is not set" }`. |
+| `CONSTELLA_BASE_URL` | `http://localhost:3000` | Não | URL base do servidor Constella em execução. Barras finais são removidas. |
+| `CONSTELLA_ORG` | — | Não | Um `orgId` para usuários multi-org; enviado no cabeçalho `X-Constella-Org`. |
+
+> 🕳️ O token **nunca é registrado em log** por nenhum dos lados. O `pat-auth.ts` valida o bearer contra o `tokenHash` armazenado e resolve a org/workspace por um join de participação, de modo que um token não pode ser apontado para outro inquilino.
+
+---
+
+## Catálogo de ferramentas — cada `constella_*` mapeada à sua rota REST 🌠
+
+Todas as 13 ferramentas estão definidas no array `TOOLS` de `scripts/mcp-server.mjs`. Cada uma mapeia 1:1 para uma rota v1.
+
+| Ferramenta MCP | Escopo | REST | Entradas | O que faz |
+|---|---|---|---|---|
+| `constella_status` | read | `GET /status` | — | Contagens de goals, issues, tasks e o estado do plano. |
+| `constella_review` | read | `GET /review` | — | Resumo textual legível de plano, issues, tasks e próximos passos. |
+| `constella_goals` | read | `GET /goals` | — | Lista goals. |
+| `constella_issues` | read | `GET /issues` | — | Lista issues. |
+| `constella_tasks` | read | `GET /tasks` | — | Lista tasks. |
+| `constella_specs` | read | `GET /specs` | — | Lista specs. |
+| `constella_kb` | read | `POST /kb` | `q` (obrigatório) | Faz uma pergunta à Base de Conhecimento. |
+| `constella_approve_plan` | **write** | `POST /plan/approve` | — | Aprova o plano pendente e enfileira as tasks. |
+| `constella_reject_plan` | **write** | `POST /plan/reject` | `reason` (opcional) | Devolve o plano ao CEO para revisão. |
+| `constella_set_execution` | **write** | `POST /execution` | `on` (obrigatório, bool) | Liga ou desliga a execução autônoma 24/7. |
+| `constella_new_work` | **write** | `POST /work` | `brief` (obrigatório), `title` (opcional) | Inicia uma nova unidade de trabalho — o CEO redige specs/issues para aprovação. |
+| `constella_cancel_goal` | **write** | `POST /goals/{id}/cancel` | `id` (obrigatório) | Cancela um goal pelo id. |
+| `constella_archive_goal` | **write** | `POST /goals/{id}/archive` | `id` (obrigatório) | Arquiva um goal pelo id. |
+
+### Handlers no servidor
+
+Cada rota cai no switch `dispatch()` de `src/app/api/v1/[[...path]]/route.ts`, que reutiliza os mesmos núcleos sem sessão usados pelo controle remoto do Telegram:
+
+| Rota REST | Handler |
+|---|---|
+| `GET /status` | `apiStatus(ws)` |
+| `GET /review` | `reviewSummaryFor(ws)` |
+| `GET /goals` `/issues` `/tasks` `/specs` | `apiGoals` / `apiIssues` / `apiTasks` / `apiSpecs` |
+| `POST /kb`, `GET /kb?q=` | `kbAnswer(org.id, q)` |
+| `POST /plan/approve` | `approvePlanFor(org.id, ws)` |
+| `POST /plan/reject` | `requestPlanChangesFor(ws.id, reason)` |
+| `POST /execution` | `setAuto247For(ws.id, on)` |
+| `POST /work` | `startNewWorkFor(org.id, ws, { brief, title })` |
+| `POST /goals/{id}/cancel` | `cancelGoalFor(ws.id, id)` |
+| `POST /goals/{id}/archive` | `archiveGoalFor(org.id, ws.id, id)` |
+
+> Observação: a lista de ferramentas do lado do host **não** inclui uma ferramenta `me`, mas a API REST expõe `GET /api/v1` (ou `/me`), retornando usuário, org, workspace e escopo do token. Hosts podem acessá-la pela [API Pública](./PUBLIC_API.md) diretamente.
+
+---
+
+## Passo a passo: configurando um host MCP
+
+### 1. Gerar um Personal Access Token
+
+Na interface web da Constella: **Perfil → Personal access tokens → Novo token**. Escolha um escopo:
+
+- **read** — apenas para as ferramentas de status/review/listagem/KB.
+- **write** — para também permitir aprovar, rejeitar, execução, novo-trabalho, cancelar e arquivar.
+
+O valor `cn_…` em texto puro é exibido **uma única vez** (`createPAT` o retorna; apenas o hash SHA-256 é persistido). Copie imediatamente.
+
+### 2. Garanta que a Constella esteja rodando
+
+O servidor MCP conversa com um servidor ativo em `CONSTELLA_BASE_URL` (padrão `http://localhost:3000`). Inicie a Constella normalmente (`constella` / `npm start`).
+
+### 3. Registre o servidor no seu host
+
+**Claude Desktop** — edite `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "constella": {
+      "command": "node",
+      "args": ["C:/Users/Usuario/Documents/constella/scripts/mcp-server.mjs"],
+      "env": {
+        "CONSTELLA_PAT": "cn_seu_token_write_aqui",
+        "CONSTELLA_BASE_URL": "http://localhost:3000"
+      }
+    }
+  }
+}
+```
+
+**Cursor** — adicione o mesmo bloco sob `mcpServers` nas configurações de MCP do Cursor (`.cursor/mcp.json` ou a configuração MCP global). Para um usuário multi-org, adicione `"CONSTELLA_ORG": "<orgId>"` em `env`.
+
+### 4. Use
+
+Reinicie o host, abra um chat e peça em linguagem natural — o host descobrirá as 13 ferramentas `constella_*` via `tools/list` e as chamará conforme necessário:
+
+> "Use a Constella para me mostrar o status atual e, em seguida, aprove o plano pendente."
+
+---
+
+## Exemplos 🌌
+
+### Testar o servidor manualmente
+
+Você pode dirigir o protocolo stdio diretamente para confirmar a ligação:
+
+```bash
+CONSTELLA_PAT=cn_xxx CONSTELLA_BASE_URL=http://localhost:3000 \
+  node scripts/mcp-server.mjs <<'EOF'
+{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05"}}
+{"jsonrpc":"2.0","id":2,"method":"tools/list"}
+{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"constella_status","arguments":{}}}
+EOF
+```
+
+Cada linha é JSON-RPC delimitado por nova linha; o servidor responde um objeto JSON por linha.
+
+### Uma requisição `tools/call` e a resposta
+
+Requisição do host:
+
+```json
+{"jsonrpc":"2.0","id":7,"method":"tools/call",
+ "params":{"name":"constella_new_work",
+           "arguments":{"brief":"Adicionar um botão de modo escuro nas configurações","title":"Modo escuro"}}}
+```
+
+Resposta do servidor (o envelope REST é formatado dentro de um bloco de conteúdo de texto):
+
+```json
+{"jsonrpc":"2.0","id":7,"result":{
+  "content":[{"type":"text","text":"{\n  \"ok\": true,\n  \"data\": { ... }\n}"}],
+  "isError":false}}
+```
+
+Se o PAT tivesse escopo `read`, a camada REST retornaria `403` e o `ok` do conteúdo seria `false`, fazendo `isError` virar `true`.
+
+---
+
+## Estados possíveis 🕳️
+
+| Situação | Onde aparece | Resultado |
+|---|---|---|
+| `CONSTELLA_PAT` não definido | `callApi` | `{ ok: false, error: "CONSTELLA_PAT is not set" }` (sem chamada de rede). |
+| Bearer malformado / ausente | `authenticatePAT` | HTTP `401` `"missing or malformed bearer token"`. |
+| Hash de token desconhecido | `authenticatePAT` | HTTP `401` `"invalid token"`. |
+| Sem org / org arquivada | `authenticatePAT` | HTTP `404` / `409`. |
+| Token read em rota de escrita | `needWrite()` | HTTP `403` `"this token has read scope; a write-scope token is required"`. |
+| Acima de 120 req/min | `rateLimited()` | HTTP `429` `"rate limit exceeded (120 req/min)"`. |
+| Nome de ferramenta desconhecido | `tools/call` | Erro JSON-RPC `-32602` `unknown tool: …`. |
+| Método JSON-RPC desconhecido | `handle()` | Erro JSON-RPC `-32601` `method not found: …`. |
+| Handler lança exceção | `rl.on("line")` | Erro JSON-RPC `-32603` (interno). |
+| Linha de stdin não-JSON | `rl.on("line")` | Ignorada silenciosamente. |
+| REST retorna não-JSON | `callApi` | `{ ok: false, error: "non-JSON response (http <status>)" }`. |
+
+---
+
+## 🪐 Duas direções de MCP — não confunda
+
+A Constella toca o MCP em **duas direções opostas**:
+
+| Direção | Quem dirige quem | Mecanismo |
+|---|---|---|
+| **Saída (este doc)** | Um host de IA externo dirige a **Constella** | `scripts/mcp-server.mjs` → API REST pública v1, autenticada por PAT. |
+| **Entrada (agentes consomem MCPs externos)** | Os **agentes da Constella** dirigem servidores MCP externos | Configurado pela config `~/.claude` da CLI `claude`; **não** pela tabela `plugin` da Constella. |
+
+```mermaid
+flowchart LR
+    subgraph Saida["Saída"]
+      H["Claude Desktop / Cursor"] -->|stdio JSON-RPC| M["mcp-server.mjs"]
+      M -->|"Bearer cn_…"| R["/api/v1"]
+      R --> C["núcleos da Constella"]
+    end
+    subgraph Entrada
+      A["agente Constella (CLI claude)"] -->|"config MCP ~/.claude"| X["servidor MCP externo"]
+    end
+```
+
+A direção de entrada é configuração da CLI `claude` no nível do operador e não tem relação com o registro de [Plugins](./PLUGINS.md) da Constella. Veja [Agentes](./AGENTS.md) e [Arquitetura de IA](./AI_ARCHITECTURE.md) para entender como os agentes rodam.
+
+---
+
+## Integrações relacionadas
+
+- **[API Pública](./PUBLIC_API.md)** — a superfície REST v1 que o servidor MCP envolve; mesmos PATs e escopos.
+- **[Telegram](./TELEGRAM.md)** — outra superfície de controle remoto que reutiliza os mesmos núcleos sem sessão (`plan-ops.ts` / `work-ops.ts`).
+- **[Plugins](./PLUGINS.md)** — o registro de plugins nativos da Constella (GitHub, Telegram, Vault, Web Search); distinto do consumo de MCP externo.
+- **[KB & RAG](./KB_RAG.md)** — o que `constella_kb` consulta por baixo dos panos.
+
+---
+
+## Segurança 🔒
+
+- **Apenas PAT, com hash em repouso.** Só o `tokenHash` SHA-256 é armazenado (tabela `personalAccessToken`). O `cn_…` em texto puro aparece uma vez na criação e nunca é registrado em log por nenhum lado.
+- **Resolução de org segura por participação.** `getActiveOrg(userId, orgHeader)` valida a org solicitada por um join de participação — um token não pode ser apontado para outro inquilino.
+- **Imposição de escopo.** Mutações exigem `write`; o escopo `read` fica restrito às ferramentas estilo GET mais as consultas à KB.
+- **Limitação de taxa.** 120 requisições/min/token (janela deslizante de 60s), reiniciada no restart do servidor.
+- **Loopback por padrão.** Com `CONSTELLA_BASE_URL` padrão `http://localhost:3000`, o servidor MCP alcança a Constella pela interface de loopback, a menos que você aponte deliberadamente para outro lugar.
+- **Chamadas limitadas.** Cada requisição REST é limitada a 30 segundos (`AbortSignal.timeout(30_000)`).
+- **Menor privilégio.** Prefira um token **read** para hosts de monitoramento; reserve tokens **write** para hosts em que você realmente confie para aprovar planos e iniciar trabalhos.
+
+---
+
+## Solução de problemas 🛠️
+
+| Sintoma | Causa provável | Correção |
+|---|---|---|
+| Toda ferramenta retorna `"CONSTELLA_PAT is not set"` | Variável ausente no bloco `env` do host | Adicione `CONSTELLA_PAT` à entrada do servidor MCP e reinicie o host. |
+| `401 invalid token` | Token revogado, digitado errado ou de outra instância | Gere um PAT novo; confirme que `CONSTELLA_BASE_URL` aponta para a mesma instância. |
+| `403 … write-scope token is required` | Usando token read para aprovar/execução/novo-trabalho | Crie um token de escopo **write**. |
+| `429 rate limit exceeded` | Mais de 120 chamadas/min em um token | Reduza o ritmo ou use um segundo token. |
+| Conexão recusada / resposta não-JSON | Constella não está rodando ou URL base errada | Inicie a Constella; verifique `CONSTELLA_BASE_URL`. |
+| Host não mostra ferramentas da Constella | Servidor falhou ao iniciar | Veja os logs MCP do host; confirme o comando `node` e o caminho absoluto até `scripts/mcp-server.mjs`. |
+| `409 organization is archived` | A org do token foi arquivada | Use um token cuja org esteja ativa, ou defina um `CONSTELLA_ORG` válido. |
+
+---
+
+## Links relacionados
+
+- [API Pública](./PUBLIC_API.md)
+- [Telegram](./TELEGRAM.md)
+- [Plugins](./PLUGINS.md)
+- [Agentes](./AGENTS.md)
+- [Arquitetura de IA](./AI_ARCHITECTURE.md)
+- [KB & RAG](./KB_RAG.md)
+- [Segurança](./SECURITY.md)
+- [Arquitetura](./ARCHITECTURE.md)

package/docs/pt/MEMORY_RAG.md

@@ -0,0 +1,289 @@
+[← Índice](./README.md) · [🇬🇧 English](../en/MEMORY_RAG.md) · [✦ Constella](../../README.pt-BR.md)
+
+# Memory RAG — a nebulosa de memória do workspace 🌌
+
+![](../assets/divider-orbit.svg)
+
+Recuperação pura, restrita à organização, sobre o Markdown do workspace **e** as transcrições de conversa. É a gravidade que puxa o contexto relevante para a memória de trabalho de uma constelação pouco antes de ela agir — semântica quando uma estrela de embedding local está acesa, heurística por palavra-chave quando não está.
+
+---
+
+## Quando usar
+
+- Você quer entender como um agente "lembra" de conversas e documentos anteriores antes de um turno.
+- Você está depurando por que a recuperação retornou nada, ou retornou texto desatualizado.
+- Você está integrando os tokens de agente `[[REMEMBER …]]` / `[[CONSULT: …]]` / `[[KB: …]]`.
+- Você precisa saber quais diretórios são indexados, os tempos de debounce e como o file-watcher mantém a memória atualizada.
+
+Para a camada **curada e ciente de estado** (entradas tipadas, obsolescência, o grafo de conhecimento) veja [KB_RAG](./KB_RAG.md) e [KB_AGENT](./KB_AGENT.md). Para onde a recuperação é injetada num prompt, veja [AI_ARCHITECTURE](./AI_ARCHITECTURE.md).
+
+---
+
+## Como funciona 🪐
+
+O Memory RAG vive em `src/server/rag.ts`. É **recuperação pura**: ele embeda e armazena chunks, depois os ordena por similaridade de cosseno para uma consulta. Não há modelo de estado, nem flag de obsolescência, nem escrita de resposta — isso é trabalho da KB curada (`src/server/kb.ts`).
+
+Dois corpora são indexados numa única tabela, `rag_chunk`:
+
+1. **Markdown do workspace** — arquivos sob os diretórios indexados (`.claude`, `DOCS`, `PO`, `Reports`, `specs`, `issues`, além de `mock/`), chaveados pelo seu `path` relativo real.
+2. **Transcrições de conversa** — conversas da team-room, DM e Telegram, armazenadas sob caminhos sintéticos `chat/<channel>`.
+
+Cada linha guarda o texto do `chunk` e, quando um backend de embedding está acessível, seu `vector` (um array de floats codificado em JSON). Se nenhum backend estiver no ar, o chunk é armazenado **sem** vetor e a recuperação cai numa heurística por palavra-chave — nada é perdido, e um reindex preguiçoso melhora os chunks assim que os embeddings ficam disponíveis.
+
+### Backends de embedding
+
+`embed(text, kind)` tenta dois backends em ordem, depois desiste:
+
+| Ordem | Backend | URL (env) | Notas |
+|-------|---------|-----------|-------|
+| 1 | Ollama | `OLLAMA_URL` (padrão `http://127.0.0.1:11434`) `/api/embeddings`, modelo `CONSTELLA_EMBED_MODEL` (padrão `nomic-embed-text`) | Usado só se estiver rodando com o modelo de embedding baixado |
+| 2 | Servidor llama.cpp de embedding dedicado | `CONSTELLA_EMBED_URL` (padrão `http://127.0.0.1:8083`) `/v1/embeddings`, modelo `nomic-embed` | Iniciado automaticamente no boot via `ensureEmbedServer()` em `src/server/local-models.ts` |
+| — | nenhum | — | Retorna `null` → o chamador usa o fallback por palavra-chave |
+
+Ambas as chamadas têm timeout de 8 s (`AbortSignal.timeout(8000)`).
+
+> **Prefixos assimétricos.** O `nomic-embed-text` foi treinado com prefixos de instrução de tarefa e os **exige**: documentos são embedados como `search_document: …`, consultas como `search_query: …`. O `embed()` aplica o prefixo correto via o argumento `kind` (`"document"` | `"query"`). Misturá-los degrada a recuperação silenciosamente, então tanto o lado de indexação quanto o de consulta devem usar o mesmo modelo com o prefixo correspondente. O prefixo é aplicado incondicionalmente no caminho llama.cpp (sempre nomic) e só quando `CONSTELLA_EMBED_MODEL` casa com `/nomic/i` no caminho Ollama.
+
+### Chunking
+
+`chunksOf(md)` divide um documento em cabeçalhos Markdown H1–H3 (`\n(?=#{1,3}\s)`), apara, descarta vazios, depois:
+
+- mantém cada parte como um chunk se tiver `≤ 1200` chars,
+- caso contrário, fatia em janelas de 1200 chars,
+- e limita o documento em **40 chunks** (`.slice(0, 40)`).
+
+### Ordenação
+
+`cosine(a, b)` é um cosseno por produto escalar simples sobre o menor dos dois vetores. `retrieve()` ordena todos os chunks vetorizados por cosseno em relação ao vetor da consulta, pega os top `k` (padrão 5), e se não existirem vetores cai na pontuação por palavra-chave (contagem de termos da consulta com mais de 3 chars que aparecem no chunk). Se nem a pontuação por palavra-chave achar nada, retorna os primeiros até 3 chunks para que o agente sempre receba *algo*.
+
+---
+
+## Fluxo principal — recuperação de memória antes de um turno 🛰️
+
+Antes de um agente agir, `assembleAgentPrompt()` (em `src/server/context-manager.ts`) puxa memória em paralelo com o contexto do canal. Ele chama o `kbQuery()` **ciente de estado** (que compartilha a mesma tabela `rag_chunk` e os mesmos helpers `embed`/`cosine` do `retrieve()` puro), e lê o arquivo estático `.claude/memory.md`. O conhecimento recuperado é injetado como uma seção de prompt rotulada e aparável.
+
+```mermaid
+flowchart TD
+  A["Turno do agente começa<br/>(task / resposta de chat)"] --> B["assembleAgentPrompt()"]
+  B --> C["Monta a query<br/>(título+desc da task OU role+instrução, ≤400 chars)"]
+  C --> D{"embed(query, 'query')"}
+  D -->|Ollama :11434| E["vetor"]
+  D -->|llama.cpp :8083| E
+  D -->|sem backend| F["heurística por palavra-chave"]
+  E --> G["ordenação por cosseno sobre rag_chunk<br/>(arquivos + chat/<channel>)"]
+  F --> G
+  G --> H["top-k chunks + caminhos de origem"]
+  H --> I["Injeta como seção 'Knowledge'<br/>+ '.claude/memory.md' como 'Relevant memory'"]
+  I --> J["Prompt ajustado à janela do modelo<br/>(seções de baixa prioridade descartadas primeiro)"]
+  J --> K["Agente roda com memória no contexto"]
+```
+
+O `retrieve()` puro retorna `{ context, sources, mode }` onde `mode` é `"semantic" | "heuristic" | "none"`; a variante `kbQuery()` adiciona ciência de estado e `refs`. Ambos cortam `context` em 4000 chars.
+
+---
+
+## Memory RAG vs KB curada 🕳️
+
+Memory RAG e a KB curada compartilham armazenamento e embeddings mas respondem perguntas diferentes. Memória é *o que foi escrito e dito*; a KB é *o que é verdade agora*.
+
+| Aspecto | Memory RAG (`rag.ts`) | KB curada (`kb.ts`) |
+|---------|-----------------------|---------------------|
+| Função | `retrieve()` | `kbQuery()` / `kbAnswer()` |
+| Corpus | `.md` do workspace + transcrições `chat/<channel>` | Mesma tabela `rag_chunk`, mas ligada a linhas tipadas de `kb_entry` |
+| Ciência de estado | Nenhuma — retorna o que ordenar mais alto | Descarta chunks `obsolete=1` (entradas superseded / obsolete, goals cancelled / archived) |
+| Referências | Apenas `sources` (caminhos de arquivo) | `sources` + `refs` internas (jump-backs de spec / issue / goal / file) |
+| Sinal de "insuficiente" | Não | Booleano `sufficient` |
+| Logging | Não | Loga cada consulta em `kb_query_log` |
+| Dono | O watcher + o agente de Conhecimento (Vannevar) | O agente de Conhecimento (curadoria, dedupe, obsolescência) |
+
+Ambos caem na mesma heurística por palavra-chave e compartilham `embed`, `chunksOf`, `cosine`, `indexRag`, `indexChat`. Veja [KB_RAG](./KB_RAG.md) para a camada curada.
+
+---
+
+## Tokens de memória do agente — REMEMBER / CONSULT / KB
+
+Agentes dirigem a memória diretamente das suas respostas via tokens em colchetes. O runner e o caminho de resposta de chat fazem o parse desses tokens, agem sobre eles e os removem do texto visível (`src/server/kb.ts`).
+
+| Token | Direção | O que faz |
+|-------|---------|-----------|
+| `[[REMEMBER type=<t>: <fato>]]` | produtor | `extractRemembered()` transforma cada um num item de KB tipado para ingerir. O tipo deve estar em `KB_LEARN_TYPES` (decision, architecture, business-rule, integration, dependency, bug, fix, test, review, vuln, ui-pattern, stack, env-config, command, note), senão cai para `note`. Fatos com menos de 8 chars são ignorados. |
+| `[[CONSULT: <pergunta>]]` | consumidor | `answerConsults()` roda cada pergunta por `kbQuery()` (k=6) e posta a resposta de volta na thread para que ela esteja no contexto no próximo turno do agente. Perguntas com menos de 4 chars são puladas. |
+| `[[KB: reindex \| index-chat \| health]]` | manutenção | `runKbTools()`: `reindex` → `indexRag()` (reconstrói chunks de arquivo + chat), `index-chat` → `indexChat()` (re-embeda só as conversas), `health` → status do servidor de embedding (`up`/`down` + modelo). |
+
+`[[REMEMBER]]` (produtor) e `[[CONSULT]]` (consumidor) são o complemento escrita/leitura: um agente armazena um aprendizado, e um agente posterior o recupera. O runner também auto-extrai `[[REMEMBER]]` dos resultados de task com `sourceKind: "task"`, e as respostas de chat extraem com `sourceKind: "chat"` (`src/server/runner.ts`, `src/server/collab.ts`).
+
+---
+
+## Diretórios e caminhos indexados 🌠
+
+`inRagDirs(p)` decide o que é elegível à memória:
+
+| Padrão de caminho | Indexado? | Notas |
+|-------------------|-----------|-------|
+| `.claude/kb/…` | Não | Prompt/taxonomia do próprio agente de KB — nunca exposto |
+| `.claude/skills/…` | Não | A biblioteca de skills — nunca exposta |
+| `.claude/*.md` e `.claude/<sub>/…` | Sim | Outro Markdown de `.claude` (ex.: `BRIEF.md`, `memory.md`) |
+| `DOCS/`, `PO/`, `Reports/`, `specs/`, `issues/` (`*.md`) | Sim | O conjunto `RAG_DIRS` |
+| `mock/…` | Sim | Só arquivos de texto: `.md .html .css .js(x) .ts(x) .txt .json` |
+| `chat/<channel>` | Sim (sintético) | Escrito por `indexChat()`, não é um arquivo real |
+| qualquer outra coisa | Não | — |
+
+As transcrições de conversa são agrupadas por `channel` (`room`, `dm:<handle>`, `telegram`), cada linha renderizada como `Operator:` ou `@<handle>:`, e só a **cauda de 400 linhas** por canal é embedada para manter o índice limitado.
+
+---
+
+## Reindex e debounce — mantendo a memória atual
+
+A memória se mantém fresca automaticamente; o operador raramente precisa da ação manual **Reindex**. Três caminhos com debounce alimentam `rag_chunk`:
+
+| Gatilho | Função | Debounce | Escopo |
+|---------|--------|----------|--------|
+| Um arquivo do workspace muda (edição de agente ou externa) | `scheduleRagReindex(orgId, rel)` → `indexRagFile()` | **2500 ms** por `(org, file)` | Re-embeda só os chunks daquele caminho |
+| Uma mensagem é postada em qualquer canal | `scheduleChatReindex(orgId)` → `indexChat()` | **6000 ms** por org | Re-embeda só os chunks `chat/%` |
+| O file-watcher no worker | POST `/api/sync/file` | **400 ms** por `(org, file)` | Chama `indexFile()`, que por sua vez chama `scheduleRagReindex` |
+| Manual / agente | `indexRag()` (completo), `[[KB: reindex]]`, `[[KB: index-chat]]` | nenhum | Reconstrução completa ou só de chat |
+
+Note o debounce em dois estágios nas edições de arquivo: o watcher chokidar do worker coalesce eventos de filesystem ao longo de **400 ms** e faz POST para `/api/sync/file`; o `indexFile()` do lado do servidor então agenda um re-embed de RAG adicional de **2500 ms**. Assim, uma rajada de edições num arquivo resulta num único re-embed, não numa tempestade.
+
+```mermaid
+sequenceDiagram
+  participant FS as Disco do workspace
+  participant W as Worker (chokidar)
+  participant API as /api/sync/file
+  participant SYNC as indexFile()
+  participant RAG as scheduleRagReindex → indexRagFile()
+  FS->>W: add/change/unlink de arquivo
+  W->>W: debounce 400ms por (org,file)
+  W->>API: POST {orgId, rel, event}  (x-worker-secret)
+  API->>SYNC: indexFile() / deindexFile()
+  SYNC->>RAG: scheduleRagReindex(orgId, rel)
+  RAG->>RAG: debounce 2500ms por (org,file)
+  RAG->>RAG: re-embeda só os chunks deste caminho
+```
+
+Quando um arquivo é deletado, `deindexFile()` chama `deindexRagFile()` para remover os chunks daquele caminho — **o disco é a fonte da verdade**, então arquivos removidos não deixam resíduo de memória. Veja [SYNCED_BLOCKS](./SYNCED_BLOCKS.md) e [ARCHITECTURE](./ARCHITECTURE.md) para o motor de sincronização mais amplo.
+
+---
+
+## Tabelas
+
+### `rag_chunk` (o armazém de memória)
+
+| Coluna | Significado |
+|--------|-------------|
+| `id` | UUID |
+| `workspace_id` | escopo de org/workspace — **toda query é filtrada pelo workspace ativo** |
+| `path` | caminho relativo real do arquivo **ou** `chat/<channel>` |
+| `chunk` | o texto do chunk (≤ ~1200 chars) |
+| `vector` | array de floats em JSON, ou `NULL` se nenhum backend de embedding estava no ar |
+| `kb_entry_id` | (camada KB) link para o `kb_entry` tipado que produziu o chunk, se houver |
+| `obsolete` | (camada KB) `1` esconde o chunk do `kbQuery()` ciente de estado |
+
+`kb_entry_id` e `obsolete` são adicionados por `ensureKbTables()` para a camada curada; o `retrieve()` puro os ignora. Outras tabelas (`kb_entry`, `kb_query_log`, …) pertencem ao [KB_RAG](./KB_RAG.md).
+
+---
+
+## Passo a passo — rastreando uma recuperação
+
+1. Um turno de agente começa (uma task em `runner.ts`, ou uma resposta de chat em `collab.ts`).
+2. `assembleAgentPrompt()` monta uma query (título + descrição da task, ou role + instrução) cortada em 400 chars.
+3. Em paralelo: o contexto do canal é resumido, e `kbQuery(orgId, query, { k: 6 })` recupera memória.
+4. `kbQuery` seleciona chunks ativos do workspace; num índice vazio, constrói um uma vez via `indexRag()`, depois re-consulta.
+5. `embed(query, "query")` produz um vetor de consulta (Ollama → llama.cpp → null).
+6. Com um vetor e chunks vetorizados presentes, as linhas são ordenadas por cosseno; senão roda a pontuação por palavra-chave.
+7. Os top-`k` chunks viram a seção `Knowledge`; `.claude/memory.md` vira `Relevant memory`.
+8. O prompt é ajustado à janela de contexto do modelo; seções de baixa prioridade caem primeiro se exceder o orçamento.
+9. O agente roda. Se emitir `[[REMEMBER …]]`, esse aprendizado é ingerido e fica recuperável na próxima vez.
+
+---
+
+## Exemplos
+
+Agente capturando um aprendizado (produtor):
+
+```
+[[REMEMBER type=decision: Auth uses better-auth sessions (30d); do not roll a custom JWT.]]
+```
+
+Agente consultando a memória antes de agir (consumidor):
+
+```
+[[CONSULT: how is the file-upload size limit configured?]]
+```
+
+Agente atualizando o índice durante a execução (manutenção):
+
+```
+[[KB: index-chat]]
+[[KB: health]]
+```
+
+Uma chamada nua de `retrieve()` (semântica quando o servidor de embedding está no ar):
+
+```ts
+const { context, sources, mode } = await retrieve(orgId, "how do agents commit to git?", 5);
+// mode === "semantic" | "heuristic" | "none"
+```
+
+---
+
+## Estados possíveis
+
+`retrieve()` e `kbQuery()` reportam um `mode` de recuperação:
+
+| `mode` | Significado |
+|--------|-------------|
+| `semantic` | Um backend de embedding estava acessível e existiam chunks vetorizados → ordenação por cosseno |
+| `heuristic` | Sem vetores (backend fora no momento da indexação) → ordenação por sobreposição de termos |
+| `none` | Sem workspace, ou sem chunk algum mesmo após uma tentativa de construção |
+
+Saúde do servidor de embedding (via `[[KB: health]]` → `llamaServerStatus()`): `up` (com nome do modelo) ou `down`.
+
+Um detalhe auto-curativo: quando o servidor de embedding sobe **depois** de um índice ter sido construído sem vetores, a primeira query semântica reconstrói o índice **uma vez por processo** (guard `autoReindexed`) para que os chunks ganhem vetores — sem reindex manual.
+
+---
+
+## Integrações relacionadas
+
+- **[KB_RAG](./KB_RAG.md)** — a camada curada e ciente de estado sobre o mesmo armazém `rag_chunk`.
+- **[KB_AGENT](./KB_AGENT.md)** — Vannevar, dono da curadoria, dedupe e obsolescência.
+- **[AI_ARCHITECTURE](./AI_ARCHITECTURE.md)** — como a memória recuperada é ajustada à janela do prompt.
+- **[MODELS](./MODELS.md)** — servidores locais de embedding & chat (llama.cpp `:8083` / `:8082`, Ollama).
+- **[SYNCED_BLOCKS](./SYNCED_BLOCKS.md)** / **[ARCHITECTURE](./ARCHITECTURE.md)** — o file-watcher e o motor de sincronização.
+- **[TEAM_ROOM](./TEAM_ROOM.md)** / **[DM](./DM.md)** / **[TELEGRAM](./TELEGRAM.md)** — as conversas que alimentam os chunks `chat/<channel>`.
+
+---
+
+## Segurança 🔐
+
+- **Isolamento estrito por org.** Toda leitura e toda query filtram por `workspace_id`; só os chunks da org ativa são embedados ou retornados. Não há caminho de recuperação cross-tenant.
+- **Internos nunca expostos.** `inRagDirs()` exclui `.claude/kb/` (prompt/taxonomia do agente de KB) e `.claude/skills/` para que uma query não vaze os internos do próprio sistema.
+- **Endpoint de sync falha fechado.** `/api/sync/file` exige `x-worker-secret` (`CONSTELLA_WORKER_SECRET`) e rejeita com 401 se o segredo não estiver definido — ele aceita um `orgId` arbitrário, então deixá-lo aberto permitiria adulteração de índice cross-tenant.
+- **Segredos são removidos à montante.** O texto de conversa é higienizado antes de ser persistido/ingerido (veja [SECURITY](./SECURITY.md)); transcrições embedadas em `chat/<channel>` herdam essa higienização.
+
+---
+
+## Solução de problemas
+
+| Sintoma | Causa provável | Correção |
+|---------|----------------|----------|
+| `mode` é sempre `heuristic` | Nenhum backend de embedding acessível na indexação/consulta | Cheque `[[KB: health]]`; garanta que o servidor llama.cpp de embedding está no ar em `:8083` (ou Ollama em `:11434` com `nomic-embed-text` baixado) — veja [MODELS](./MODELS.md) |
+| Recuperação retorna nada | Índice vazio ou sem workspace | A primeira query auto-constrói via `indexRag()`; se ainda vazio, rode um reindex completo (`[[KB: reindex]]` ou a ação Reindex) |
+| Texto desatualizado continua voltando | Obsolescência da KB curada, não memória | O `retrieve()` puro não tem modelo de estado; use `kbQuery()`/curadoria — veja [KB_RAG](./KB_RAG.md) |
+| Edições não refletidas | Watcher não rodando, ou janela de debounce | O worker deve estar rodando (ele é dono do chokidar); mudanças re-embedam após o debounce de RAG de **2500 ms** |
+| Arquivo deletado ainda recuperado | O deindex não disparou | A deleção passa por `deindexFile → deindexRagFile`; confirme que o worker viu o evento `unlink` |
+| Conversa não lembrada | Reindex de chat pendente ou canal vazio | `scheduleChatReindex` faz debounce de **6000 ms**; force com `[[KB: index-chat]]` |
+
+---
+
+## Links relacionados
+
+- [KB_RAG](./KB_RAG.md)
+- [KB_AGENT](./KB_AGENT.md)
+- [AI_ARCHITECTURE](./AI_ARCHITECTURE.md)
+- [ARCHITECTURE](./ARCHITECTURE.md)
+- [SYNCED_BLOCKS](./SYNCED_BLOCKS.md)
+- [MODELS](./MODELS.md)
+- [AGENTS](./AGENTS.md)
+- [TEAM_ROOM](./TEAM_ROOM.md)
+- [TROUBLESHOOTING](./TROUBLESHOOTING.md)