vault-go 0.6.0 → 0.8.0

package/README.md

@@ -14,6 +14,42 @@ bun --version
 
 ## Instalação MCP
 
+### Opção remota somente leitura
+
+Para pesquisa e contexto, é possível usar diretamente o endpoint Streamable
+HTTP da plataforma, sem instalar runtime ou banco local. Crie em **Segurança >
+Chaves de API** uma chave apenas com `memory:read` e configure:
+
+```sh
+export VAULT_GO_TOKEN='<chave-memory-read>'
+codex mcp add vault-go \
+  --url https://vault.resolveup.com.br/api/mcp \
+  --bearer-token-env-var VAULT_GO_TOKEN
+```
+
+Configuração genérica para clientes com transporte HTTP:
+
+```json
+{
+  "mcpServers": {
+    "vault-go": {
+      "type": "http",
+      "url": "https://vault.resolveup.com.br/api/mcp",
+      "headers": {
+        "Authorization": "Bearer ${VAULT_GO_TOKEN}"
+      }
+    }
+  }
+}
+```
+
+O endpoint remoto expõe somente projetos, busca, contexto, recentes, feed,
+linha do tempo, contexto de arquivos, estatísticas, estado vetorial e consultas
+às bases de conhecimento. Para captura automática, criação/reconstrução de
+bases, escrita, importação ou exclusão, use o cliente Bun completo abaixo.
+
+### Opção Bun completa
+
 Execução direta:
 
 ```sh
@@ -51,9 +87,13 @@ possível apontar outro diretório:
 }
 ```
 
-Para ambientes efêmeros, `VAULT_GO_TOKEN` aceita um access token e
-`VAULT_GO_API_URL` troca o endpoint. Prefira o login normal, porque ele permite
-renovação automática da sessão.
+Para ambientes efêmeros, `VAULT_GO_TOKEN` aceita um access token de sessão ou
+uma chave `vg_live_...` criada na tela **Segurança > Chaves de API**. Use
+somente os escopos necessários: `memory:read` para pesquisa/contexto,
+`memory:write` para eventos e lembranças e `memory:delete` para exclusão.
+`VAULT_GO_API_URL` troca o endpoint. O login normal permite renovação
+automática; a chave de API é indicada para automações com prazo e escopo
+limitados.
 
 ## Ferramentas MCP
 
@@ -64,6 +104,8 @@ renovação automática da sessão.
 - `vault_go_event`: eventos de prompt, ferramenta e resultado.
 - `vault_go_remember`: observações, decisões, descobertas e resumos.
 - `vault_go_search`: busca textual com ranking e trechos.
+- `vault_go_search_index`: índice compacto com filtros, trechos e custo estimado.
+- `vault_go_observations`: carrega em lote somente os IDs selecionados.
 - `vault_go_timeline`: contexto anterior e posterior a uma memória.
 - `vault_go_context`: contexto progressivo com limite de caracteres.
 - `vault_go_file_context`: histórico ligado aos arquivos lidos ou modificados.
@@ -72,10 +114,30 @@ renovação automática da sessão.
 - `vault_go_job_retry` e `vault_go_job_cancel`: controle idempotente do processamento.
 - `vault_go_export` e `vault_go_import`: transporte JSON tenant-scoped, atômico e idempotente.
 - `vault_go_embedding_status` e `vault_go_embedding_backfill`: busca híbrida e fila vetorial, sem expor chaves.
+- `vault_go_feed`: pagina memórias recentes por projeto, tipo e origem.
+- `vault_go_knowledge_bases` e `vault_go_knowledge_base`: lista e abre bases focadas.
+- `vault_go_knowledge_build` e `vault_go_knowledge_rebuild`: cria ou atualiza uma base a partir de filtros.
+- `vault_go_knowledge_query`: recupera contexto fundamentado e citações dentro da base.
+- `vault_go_knowledge_delete`: remove a base e preserva as memórias originais.
 - `vault_go_forget`: exclusão explícita de uma memória.
 
 O recurso `vault-go://status` fornece o resumo sanitizado em JSON.
 
+Para reduzir o uso de contexto, prefira a recuperação em três camadas:
+
+1. Pesquise com `vault_go_search_index`, usando projeto, origem, conceitos,
+   arquivos e intervalo de datas quando conhecidos.
+2. Abra `vault_go_timeline` somente para os resultados que precisam de
+   contexto cronológico.
+3. Envie os IDs escolhidos a `vault_go_observations` para carregar o conteúdo
+   completo em um único lote tenant-scoped.
+
+As bases, filtros, vínculos e feed ficam exclusivamente no PostgreSQL da
+plataforma. A consulta retorna evidências e `synthesisAvailable: false`; o
+cliente MCP faz a síntese, evitando respostas inventadas e chaves ocultas no
+servidor. A síntese do servidor só será habilitada quando um provedor semântico
+for configurado explicitamente.
+
 ## Fluxo integrado
 
 ```text

package/dist/cloud.d.ts

@@ -8,6 +8,8 @@ export interface VaultMemoryApi {
     remember(input: Record<string, unknown>): Promise<unknown>;
     forget(id: string): Promise<unknown>;
     search(input: Record<string, unknown>): Promise<unknown>;
+    searchIndex(input: Record<string, unknown>): Promise<unknown>;
+    observations(ids: string[]): Promise<unknown>;
     timeline(input: Record<string, unknown>): Promise<unknown>;
     context(input: Record<string, unknown>): Promise<unknown>;
     fileContext(input: Record<string, unknown>): Promise<unknown>;
@@ -19,6 +21,13 @@ export interface VaultMemoryApi {
     importMemories(input: Record<string, unknown>): Promise<unknown>;
     embeddingStatus(): Promise<unknown>;
     embeddingBackfill(): Promise<unknown>;
+    feed(input: Record<string, unknown>): Promise<unknown>;
+    knowledgeBases(): Promise<unknown>;
+    knowledgeBase(id: string): Promise<unknown>;
+    buildKnowledgeBase(input: Record<string, unknown>): Promise<unknown>;
+    rebuildKnowledgeBase(id: string): Promise<unknown>;
+    queryKnowledgeBase(id: string, input: Record<string, unknown>): Promise<unknown>;
+    deleteKnowledgeBase(id: string): Promise<unknown>;
 }
 export declare class VaultCloudClient implements VaultMemoryApi {
     private readonly home;
@@ -33,6 +42,8 @@ export declare class VaultCloudClient implements VaultMemoryApi {
     remember(input: Record<string, unknown>): Promise<unknown>;
     forget(id: string): Promise<unknown>;
     search(input: Record<string, unknown>): Promise<unknown>;
+    searchIndex(input: Record<string, unknown>): Promise<unknown>;
+    observations(ids: string[]): Promise<unknown>;
     timeline(input: Record<string, unknown>): Promise<unknown>;
     context(input: Record<string, unknown>): Promise<unknown>;
     fileContext(input: Record<string, unknown>): Promise<unknown>;
@@ -44,6 +55,13 @@ export declare class VaultCloudClient implements VaultMemoryApi {
     importMemories(input: Record<string, unknown>): Promise<unknown>;
     embeddingStatus(): Promise<unknown>;
     embeddingBackfill(): Promise<unknown>;
+    feed(input: Record<string, unknown>): Promise<unknown>;
+    knowledgeBases(): Promise<unknown>;
+    knowledgeBase(id: string): Promise<unknown>;
+    buildKnowledgeBase(input: Record<string, unknown>): Promise<unknown>;
+    rebuildKnowledgeBase(id: string): Promise<unknown>;
+    queryKnowledgeBase(id: string, input: Record<string, unknown>): Promise<unknown>;
+    deleteKnowledgeBase(id: string): Promise<unknown>;
     private endpoint;
     private accessToken;
     private request;

package/dist/cloud.js

@@ -34,6 +34,12 @@ export class VaultCloudClient {
     async search(input) {
         return this.request('/memory/search', { method: 'POST', body: input });
     }
+    async searchIndex(input) {
+        return this.request('/memory/search/index', { method: 'POST', body: input });
+    }
+    async observations(ids) {
+        return this.request('/memory/memories/batch', { method: 'POST', body: { ids } });
+    }
     async timeline(input) {
         return this.request('/memory/timeline', { method: 'POST', body: input });
     }
@@ -78,6 +84,34 @@ export class VaultCloudClient {
     async embeddingBackfill() {
         return this.request('/memory/embeddings/backfill', { method: 'POST' });
     }
+    async feed(input) {
+        return this.request('/memory/feed', { query: input });
+    }
+    async knowledgeBases() {
+        return this.request('/memory/knowledge-bases');
+    }
+    async knowledgeBase(id) {
+        return this.request(`/memory/knowledge-bases/${encodeURIComponent(id)}`);
+    }
+    async buildKnowledgeBase(input) {
+        return this.request('/memory/knowledge-bases', { method: 'POST', body: input });
+    }
+    async rebuildKnowledgeBase(id) {
+        return this.request(`/memory/knowledge-bases/${encodeURIComponent(id)}/rebuild`, {
+            method: 'POST',
+        });
+    }
+    async queryKnowledgeBase(id, input) {
+        return this.request(`/memory/knowledge-bases/${encodeURIComponent(id)}/query`, {
+            method: 'POST',
+            body: input,
+        });
+    }
+    async deleteKnowledgeBase(id) {
+        return this.request(`/memory/knowledge-bases/${encodeURIComponent(id)}`, {
+            method: 'DELETE',
+        });
+    }
     endpoint(path) {
         const base = validateApiUrl(loadConfig(this.home).apiUrl);
         const prefix = base.pathname.replace(/\/$/u, '');
@@ -128,7 +162,13 @@ export class VaultCloudClient {
         };
         if (options.body)
             request.body = JSON.stringify(options.body);
-        const response = await this.cloudFetch(this.endpoint(path), request);
+        const endpoint = this.endpoint(path);
+        for (const [key, value] of Object.entries(options.query ?? {})) {
+            if (value !== undefined && value !== null && value !== '') {
+                endpoint.searchParams.set(key, String(value));
+            }
+        }
+        const response = await this.cloudFetch(endpoint, request);
         if (response.status === 401 && options.authenticated !== false && !options.retried) {
             return this.request(path, { ...options, retried: true });
         }

package/dist/server.js

@@ -26,6 +26,17 @@ async function run(operation) {
     }
 }
 const uuid = z.string().uuid();
+const knowledgeFilters = z.object({
+    projectId: uuid.optional(),
+    kinds: z.array(z.string().trim().min(1).max(100)).max(20).default([]),
+    memoryTypes: z.array(z.string().trim().min(1).max(100)).max(20).default([]),
+    concepts: z.array(z.string().trim().min(1).max(500)).max(50).default([]),
+    files: z.array(z.string().trim().min(1).max(2_000)).max(50).default([]),
+    query: z.string().trim().max(1_000).optional(),
+    dateStartEpoch: z.number().int().positive().optional(),
+    dateEndEpoch: z.number().int().positive().optional(),
+    limit: z.number().int().min(1).max(2_000).default(200),
+});
 export function createVaultGoServer(home = vaultHome(), cloud = new VaultCloudClient(home)) {
     const server = new McpServer({ name: 'vault-go', version: VERSION });
     server.registerTool('vault_go_status', {
@@ -50,7 +61,7 @@ export function createVaultGoServer(home = vaultHome(), cloud = new VaultCloudCl
         title: 'Criar projeto',
         description: 'Cria um projeto de memória no Vault.',
         inputSchema: {
-            name: z.string().trim().min(1).max(200),
+            name: z.string().trim().min(3).max(80),
             rootPath: z.string().trim().max(2_000).optional(),
         },
         annotations: { readOnlyHint: false, idempotentHint: false, openWorldHint: true },
@@ -116,10 +127,40 @@ export function createVaultGoServer(home = vaultHome(), cloud = new VaultCloudCl
             projectId: uuid.optional(),
             kind: z.string().trim().max(100).optional(),
             memoryType: z.string().trim().max(100).optional(),
+            platformSource: z.string().trim().max(100).optional(),
+            concepts: z.array(z.string().trim().min(1).max(500)).max(50).default([]),
+            files: z.array(z.string().trim().min(1).max(2_000)).max(50).default([]),
+            dateStartEpoch: z.number().int().positive().optional(),
+            dateEndEpoch: z.number().int().positive().optional(),
             limit: z.number().int().min(1).max(200).default(20),
         },
         annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true },
     }, async (input) => run(() => cloud.search(input)));
+    server.registerTool('vault_go_search_index', {
+        title: 'Pesquisar índice compacto',
+        description: 'Primeira camada de recuperação: retorna metadados, trechos e custo estimado sem carregar o conteúdo completo.',
+        inputSchema: {
+            query: z.string().trim().min(1).max(1_000),
+            projectId: uuid.optional(),
+            kind: z.string().trim().max(100).optional(),
+            memoryType: z.string().trim().max(100).optional(),
+            platformSource: z.string().trim().max(100).optional(),
+            concepts: z.array(z.string().trim().min(1).max(500)).max(50).default([]),
+            files: z.array(z.string().trim().min(1).max(2_000)).max(50).default([]),
+            dateStartEpoch: z.number().int().positive().optional(),
+            dateEndEpoch: z.number().int().positive().optional(),
+            limit: z.number().int().min(1).max(200).default(20),
+        },
+        annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true },
+    }, async (input) => run(() => cloud.searchIndex(input)));
+    server.registerTool('vault_go_observations', {
+        title: 'Carregar observações por ID',
+        description: 'Terceira camada de recuperação: carrega em lote somente as observações escolhidas no índice ou na linha do tempo.',
+        inputSchema: {
+            ids: z.array(uuid).min(1).max(100),
+        },
+        annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true },
+    }, async ({ ids }) => run(() => cloud.observations(ids)));
     server.registerTool('vault_go_timeline', {
         title: 'Abrir linha do tempo',
         description: 'Retorna memórias anteriores e posteriores a uma memória âncora.',
@@ -158,6 +199,68 @@ export function createVaultGoServer(home = vaultHome(), cloud = new VaultCloudCl
         inputSchema: {},
         annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true },
     }, async () => run(() => cloud.stats()));
+    server.registerTool('vault_go_feed', {
+        title: 'Feed de memórias',
+        description: 'Lista memórias recentes com paginação estável por cursor.',
+        inputSchema: {
+            projectId: uuid.optional(),
+            kind: z.string().trim().max(100).optional(),
+            memoryType: z.string().trim().max(100).optional(),
+            platformSource: z.string().trim().max(100).optional(),
+            cursor: z.string().trim().max(200).optional(),
+            limit: z.number().int().min(1).max(200).default(20),
+        },
+        annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true },
+    }, async (input) => run(() => cloud.feed(input)));
+    server.registerTool('vault_go_knowledge_bases', {
+        title: 'Listar bases de conhecimento',
+        description: 'Lista bases filtradas e persistidas na plataforma Vault.',
+        inputSchema: {},
+        annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true },
+    }, async () => run(() => cloud.knowledgeBases()));
+    server.registerTool('vault_go_knowledge_base', {
+        title: 'Abrir base de conhecimento',
+        description: 'Retorna a configuração e as memórias vinculadas a uma base.',
+        inputSchema: { id: uuid },
+        annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true },
+    }, async ({ id }) => run(() => cloud.knowledgeBase(id)));
+    server.registerTool('vault_go_knowledge_build', {
+        title: 'Criar base de conhecimento',
+        description: 'Cria uma base PostgreSQL a partir de filtros explícitos.',
+        inputSchema: {
+            name: z.string().trim().min(1).max(200),
+            description: z.string().trim().max(2_000).optional(),
+            filters: knowledgeFilters,
+        },
+        annotations: { readOnlyHint: false, idempotentHint: false, openWorldHint: true },
+    }, async (input) => run(() => cloud.buildKnowledgeBase(input)));
+    server.registerTool('vault_go_knowledge_rebuild', {
+        title: 'Reconstruir base de conhecimento',
+        description: 'Reaplica os filtros salvos para incluir as memórias atuais.',
+        inputSchema: { id: uuid },
+        annotations: { readOnlyHint: false, idempotentHint: true, openWorldHint: true },
+    }, async ({ id }) => run(() => cloud.rebuildKnowledgeBase(id)));
+    server.registerTool('vault_go_knowledge_query', {
+        title: 'Consultar base de conhecimento',
+        description: 'Retorna contexto fundamentado e citações para síntese pelo cliente MCP.',
+        inputSchema: {
+            id: uuid,
+            question: z.string().trim().min(1).max(1_000),
+            limit: z.number().int().min(1).max(100).default(20),
+        },
+        annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true },
+    }, async ({ id, ...input }) => run(() => cloud.queryKnowledgeBase(id, input)));
+    server.registerTool('vault_go_knowledge_delete', {
+        title: 'Excluir base de conhecimento',
+        description: 'Exclui a base e seus vínculos, preservando as memórias originais.',
+        inputSchema: { id: uuid },
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+    }, async ({ id }) => run(() => cloud.deleteKnowledgeBase(id)));
     server.registerTool('vault_go_jobs', {
         title: 'Fila de processamento',
         description: 'Lista jobs da conta sem expor o conteúdo dos eventos.',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vault-go",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "Servidor MCP Bun para pesquisar e registrar memória na plataforma Vault.",
   "type": "module",
   "bin": {