vault-go 0.7.0 → 0.8.1

package/README.md

@@ -50,12 +50,24 @@ bases, escrita, importação ou exclusão, use o cliente Bun completo abaixo.
 
 ### Opção Bun completa
 
-Execução direta:
+Para instalar e registrar no Codex, execute em um terminal:
 
 ```sh
 bunx --bun vault-go@latest
 ```
 
+Quando executado diretamente em um terminal, o pacote detecta o modo
+interativo e chama `codex mcp add` com os argumentos corretos. O mesmo fluxo
+pode ser solicitado explicitamente:
+
+```sh
+bunx --bun vault-go@latest install
+```
+
+O `bunx` sozinho baixa o pacote para o cache; o instalador da biblioteca é que
+registra o servidor na configuração do Codex. Reinicie o Codex depois da
+primeira instalação.
+
 Configuração MCP genérica:
 
 ```json
@@ -104,6 +116,8 @@ limitados.
 - `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.
@@ -121,6 +135,15 @@ limitados.
 
 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

package/dist/cli.d.ts

@@ -0,0 +1,4 @@
+export declare const CODEX_MCP_NAME = "vault-go";
+export declare const CODEX_MCP_COMMAND: readonly ["bunx", "--bun", "vault-go@latest"];
+export declare function shouldInstallFromCli(argument: string | undefined, stdinIsTTY: boolean, stderrIsTTY: boolean): boolean;
+export declare function installCodexMcp(): number;

package/dist/cli.js

@@ -0,0 +1,34 @@
+import { spawnSync } from 'node:child_process';
+export const CODEX_MCP_NAME = 'vault-go';
+export const CODEX_MCP_COMMAND = ['bunx', '--bun', 'vault-go@latest'];
+export function shouldInstallFromCli(argument, stdinIsTTY, stderrIsTTY) {
+    if (argument === 'install' || argument === 'setup' || argument === '--install') {
+        return true;
+    }
+    return argument === undefined && stdinIsTTY && stderrIsTTY;
+}
+export function installCodexMcp() {
+    const existing = spawnSync('codex', ['mcp', 'get', CODEX_MCP_NAME], {
+        encoding: 'utf8',
+    });
+    if (existing.error && 'code' in existing.error && existing.error.code === 'ENOENT') {
+        process.stderr.write('vault-go: o comando "codex" não foi encontrado. Instale o Codex CLI e tente novamente.\n');
+        return 1;
+    }
+    if (existing.status === 0) {
+        process.stderr.write(`vault-go: o MCP "${CODEX_MCP_NAME}" já está registrado no Codex.\n`);
+        return 0;
+    }
+    process.stderr.write('vault-go: registrando o MCP no Codex...\n');
+    const installed = spawnSync('codex', ['mcp', 'add', CODEX_MCP_NAME, '--', ...CODEX_MCP_COMMAND], { stdio: 'inherit' });
+    if (installed.error) {
+        process.stderr.write(`vault-go: não foi possível executar o instalador: ${installed.error.message}\n`);
+        return 1;
+    }
+    if (installed.status !== 0) {
+        process.stderr.write('vault-go: o Codex não conseguiu registrar o MCP.\n');
+        return installed.status ?? 1;
+    }
+    process.stderr.write('vault-go: MCP instalado. Reinicie o Codex para carregá-lo.\n');
+    return 0;
+}

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>;
@@ -40,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>;

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 });
     }

package/dist/index.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env bun
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { installCodexMcp, shouldInstallFromCli } from './cli.js';
 import { createVaultGoServer, VERSION } from './server.js';
 const argument = process.argv[2];
 if (argument === '--version' || argument === '-v') {
@@ -7,7 +8,7 @@ if (argument === '--version' || argument === '-v') {
     process.exit(0);
 }
 if (argument === '--help' || argument === '-h') {
-    process.stdout.write(`vault-go ${VERSION}\n\nServidor MCP cloud por stdio, executado com Bun.\n\nVariáveis:\n  VAULT_GO_HOME         Diretório de configuração (padrão: ~/.memvault)\n  MEMVAULT_CONFIG_DIR   Mesmo diretório usado pelo agente\n`);
+    process.stdout.write(`vault-go ${VERSION}\n\nServidor MCP cloud por stdio, executado com Bun.\n\nUso:\n  bunx --bun vault-go@latest           Instala no Codex quando executado em um terminal\n  bunx --bun vault-go@latest install   Instala no Codex explicitamente\n  bunx --bun vault-go@latest serve     Inicia o servidor MCP por stdio\n\nVariáveis:\n  VAULT_GO_HOME         Diretório de configuração (padrão: ~/.memvault)\n  MEMVAULT_CONFIG_DIR   Mesmo diretório usado pelo agente\n`);
     process.exit(0);
 }
 async function main() {
@@ -15,8 +16,13 @@ async function main() {
     const transport = new StdioServerTransport();
     await server.connect(transport);
 }
-main().catch((error) => {
-    const message = error instanceof Error ? error.stack ?? error.message : String(error);
-    process.stderr.write(`vault-go falhou: ${message}\n`);
-    process.exitCode = 1;
-});
+if (shouldInstallFromCli(argument, process.stdin.isTTY === true, process.stderr.isTTY === true)) {
+    process.exitCode = installCodexMcp();
+}
+else {
+    main().catch((error) => {
+        const message = error instanceof Error ? error.stack ?? error.message : String(error);
+        process.stderr.write(`vault-go falhou: ${message}\n`);
+        process.exitCode = 1;
+    });
+}

package/dist/server.js

@@ -127,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.',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vault-go",
-  "version": "0.7.0",
+  "version": "0.8.1",
   "description": "Servidor MCP Bun para pesquisar e registrar memória na plataforma Vault.",
   "type": "module",
   "bin": {
@@ -22,6 +22,8 @@
   "files": [
     "dist/index.js",
     "dist/index.d.ts",
+    "dist/cli.js",
+    "dist/cli.d.ts",
     "dist/server.js",
     "dist/server.d.ts",
     "dist/config.js",