vault-go 0.34.0 → 0.36.0

package/README.md

@@ -168,7 +168,7 @@ Projects are matched by path first and then by repository: vault-go reads the ch
 
 A folder without git joins the nearest existing project above it instead of becoming a project of its own; a git checkout always keeps its own project.
 
-Read tools (`vault_go_search`, `vault_go_search_index`, `vault_go_feed`, `vault_go_retrieve` and query-anchored `vault_go_timeline`) are scoped to the project of the MCP server's working directory when no `projectId` is given; a git worktree maps to its main checkout. Pass `scope: "account"` to search every project of the account. Outside a known project they fall back to the account, and no project is created. Memories marked private stay out of search and feed results unless `includePrivate: true` is set.
+Read tools (`vault_go_search`, `vault_go_search_index`, `vault_go_feed`, `vault_go_retrieve`, `vault_go_facts`, `vault_go_entities` and query-anchored `vault_go_timeline`) are scoped to the project of the MCP server's working directory when no `projectId` is given; a git worktree maps to its main checkout. Pass `scope: "account"` to search every project of the account. Outside a known project they fall back to the account, and no project is created. Memories marked private stay out of search and feed results unless `includePrivate: true` is set.
 
 `vault_go_retrieve` lets the central memory engine choose a bounded retrieval path while every explicit retrieval tool remains available. `vault_go_decision_status` reports sanitized rollout/circuit state. Jev and its credential remain in the engine; a healthy deployment does not by itself prove provider availability or decision quality. `vault_go_decide` sends a caller-authored state plus up to 8 typed questions (`noul`, `choice`, `score`) to the central Jev and returns probabilities; it runs only in `full` rollout, one call at a time, refuses secrets, e-mails, identifiers, URLs and absolute local paths before anything leaves Vault, and persists nothing. The caller still owns the decision.
 
@@ -178,9 +178,11 @@ Jobs and backup: `vault_go_jobs`, `vault_go_job`, `vault_go_job_retry`, `vault_g
 
 Engines and updates: `vault_go_engines`, `vault_go_engine_select`, `vault_go_generate_context`, `vault_go_update_status`, `vault_go_update_check`, `vault_go_update_install`, `vault_go_update_configure`.
 
+Temporal knowledge graph: `vault_go_facts`, `vault_go_entities`, `vault_go_entity_facts`, `vault_go_graph_status`. Facts are `subject —relation→ object` with a validity window; `vault_go_facts` answers "what is true now", "what changed" (`includeExpired: true` marks ended and superseded facts) and "what was true on date X" (`asOf`, an ISO date or datetime; a bare date means the end of that day, UTC). Facts and entities follow the same `scope`/`projectId` rules as the other read tools, and each fact carries the `memoryIds` to load with `vault_go_observations`. Until the graph is enabled for the account, these tools answer with a plain notice and point to `vault_go_search`.
+
 Graph and local code: `vault_go_graph`, `vault_go_graph_link`, `vault_go_graph_link_delete`, `vault_go_graph_presets`, `vault_go_graph_preset_save`, `vault_go_smart_outline`, `vault_go_smart_unfold`, `vault_go_smart_search`, `vault_go_smart_languages`.
 
-Computer Use by Vault: `vault_go_computer_status`, `vault_go_computer_permissions`, `vault_go_computer_list_apps`, `vault_go_computer_list_windows`, `vault_go_computer_get_app_state`, `vault_go_computer_query`, `vault_go_computer_click`, `vault_go_computer_perform_secondary_action`, `vault_go_computer_scroll`, `vault_go_computer_drag`, `vault_go_computer_type_text`, `vault_go_computer_paste_text`, `vault_go_computer_set_value`, `vault_go_computer_press_key`, `vault_go_computer_hotkey`. They drive local apps through the Vault Desktop native helper (installed and running), so every MCP client shares its permissions; on macOS grant Accessibility and Screen Recording to "Vault Desktop Computer Use" once. `get_app_state` returns the accessibility tree plus the window screenshot as an MCP image; `query` finds controls by text or role without a screenshot. Element indexes share one session per server. Typed text and values travel over stdin, never the process arguments. Set `VAULT_DESKTOP_CLI` to point at a custom CLI path, or `VAULT_GO_COMPUTER_USE=off` to hide the tools. The tool surface follows [open-computer-use](https://github.com/iFurySt/open-computer-use) (MIT).
+Computer Use by Vault: `vault_go_computer_status`, `vault_go_computer_permissions`, `vault_go_computer_list_apps`, `vault_go_computer_list_windows`, `vault_go_computer_get_app_state`, `vault_go_computer_query`, `vault_go_computer_click`, `vault_go_computer_perform_secondary_action`, `vault_go_computer_scroll`, `vault_go_computer_drag`, `vault_go_computer_type_text`, `vault_go_computer_paste_text`, `vault_go_computer_set_value`, `vault_go_computer_press_key`, `vault_go_computer_hotkey`. They drive local apps through the Vault Desktop native helper (installed and running), so every MCP client shares its permissions; on macOS grant Accessibility and Screen Recording to "Vault Desktop Computer Use" once. `get_app_state` returns the accessibility tree plus the window screenshot as an MCP image; `query` finds controls by text or role without a screenshot. With Vault Desktop 0.11.73 or later, actions run in the background on the target window: the user's pointer and frontmost app never change, and a dedicated agent cursor is drawn only over that window. Element indexes share one session per server. Typed text and values travel over stdin, never the process arguments. Set `VAULT_DESKTOP_CLI` to point at a custom CLI path, or `VAULT_GO_COMPUTER_USE=off` to hide the tools. The tool surface follows [open-computer-use](https://github.com/iFurySt/open-computer-use) (MIT).
 
 Workflows: `vault_go_workflow`, `vault_go_modes`, `vault_go_mode`, plus named prompts such as `vault_go_babysit`. Loading a mode gives the agent instructions; it does not start a background job.
 

package/dist/auth.d.ts

@@ -16,5 +16,6 @@ export declare function authenticateWithBrowser(home: string, options?: {
     openBrowser?: (url: string) => Promise<void>;
     timeoutMs?: number;
     report?: (message: string) => void;
+    pasteInput?: NodeJS.ReadableStream | null;
 }): Promise<AuthenticationResult>;
 export {};

package/dist/auth.js

@@ -3,6 +3,7 @@ import { copy, resolveLocale } from './locale.js';
 import { createServer } from 'node:http';
 import { randomBytes, createHash, timingSafeEqual } from 'node:crypto';
 import { execFile } from 'node:child_process';
+import { createInterface } from 'node:readline';
 import { credentialFilesGeneration, loadConfig, loadTokens, saveConfig, saveTokens, validateApiUrl, } from './config.js';
 function endpoint(home, path) {
     const apiUrl = validateApiUrl(loadConfig(home).apiUrl);
@@ -149,6 +150,25 @@ export async function authenticateWithBrowser(home, options = {}) {
     const received = new Promise((resolve, reject) => { claim = resolve; rejectClaim = reject; });
     // A timeout can occur while the browser opener is still running.
     void received.catch(() => { });
+    // Why: the same validation serves the local callback and a callback URL pasted in the
+    // terminal (login over SSH, where the browser's 127.0.0.1 is another machine).
+    const acceptCallback = (url) => {
+        const incoming = url.searchParams.get('state') ?? '';
+        const validState = /^[A-Za-z0-9_-]{43}$/.test(incoming) && timingSafeEqual(Buffer.from(incoming), Buffer.from(state));
+        const code = url.searchParams.get('code');
+        if (!validState || url.searchParams.getAll('state').length !== 1 || accepted)
+            return { kind: 'invalid', message: 'Retorno de autenticação inválido.' };
+        if (url.searchParams.has('error')) {
+            accepted = true;
+            rejectClaim?.(new Error(t.denied));
+            return { kind: 'denied' };
+        }
+        if (!code || !/^[A-Za-z0-9_-]{43}$/.test(code) || url.searchParams.getAll('code').length !== 1)
+            return { kind: 'invalid', message: 'Código inválido.' };
+        accepted = true;
+        claim?.(code);
+        return { kind: 'accepted' };
+    };
     const server = createServer((req, res) => {
         res.setHeader('Cache-Control', 'no-store');
         res.setHeader('Referrer-Policy', 'no-referrer');
@@ -165,29 +185,20 @@ export async function authenticateWithBrowser(home, options = {}) {
             res.writeHead(404).end();
             return;
         }
-        const incoming = url.searchParams.get('state') ?? '';
-        const validState = /^[A-Za-z0-9_-]{43}$/.test(incoming) && timingSafeEqual(Buffer.from(incoming), Buffer.from(state));
-        const code = url.searchParams.get('code');
-        if (!validState || url.searchParams.getAll('state').length !== 1 || accepted) {
-            res.writeHead(400).end('Retorno de autenticação inválido.');
+        const outcome = acceptCallback(url);
+        if (outcome.kind === 'invalid') {
+            res.writeHead(400).end(outcome.message);
             return;
         }
-        if (url.searchParams.has('error')) {
-            accepted = true;
+        if (outcome.kind === 'denied') {
             res.writeHead(400).end('Login não concluído. Volte ao terminal.');
-            rejectClaim?.(new Error(t.denied));
             return;
         }
-        if (!code || !/^[A-Za-z0-9_-]{43}$/.test(code) || url.searchParams.getAll('code').length !== 1) {
-            res.writeHead(400).end('Código inválido.');
-            return;
-        }
-        accepted = true;
         res.setHeader('Content-Type', 'text/html; charset=utf-8');
         res.end(options.callbackHtml ?? callbackPage(locale));
-        claim?.(code);
     });
     let timer;
+    let pasted;
     const abort = () => rejectClaim?.(new Error(t.denied));
     options.signal?.addEventListener('abort', abort, { once: true });
     try {
@@ -210,6 +221,31 @@ export async function authenticateWithBrowser(home, options = {}) {
         catch {
             report(t.openFailed);
         }
+        const pasteInput = options.pasteInput === undefined ? (process.stdin.isTTY ? process.stdin : null) : options.pasteInput;
+        if (pasteInput) {
+            report(t.pasteCallback);
+            pasted = createInterface({ input: pasteInput, terminal: false });
+            pasted.on('line', line => {
+                const text = line.trim();
+                if (!text || accepted)
+                    return;
+                let url;
+                try {
+                    url = new URL(text);
+                }
+                catch {
+                    report(t.pasteInvalid);
+                    return;
+                }
+                if (url.pathname !== '/callback' || !['127.0.0.1', 'localhost'].includes(url.hostname)) {
+                    report(t.pasteInvalid);
+                    return;
+                }
+                const outcome = acceptCallback(url);
+                if (outcome.kind === 'invalid')
+                    report(`${t.pasteInvalid} (${outcome.message})`);
+            });
+        }
         const code = await received;
         assertCurrent();
         const response = await fetcher(endpoint(home, '/auth/mobile/exchange'), {
@@ -231,6 +267,9 @@ export async function authenticateWithBrowser(home, options = {}) {
         options.signal?.removeEventListener('abort', abort);
         if (timer)
             clearTimeout(timer);
+        pasted?.close();
+        if (options.pasteInput === undefined && process.stdin.isTTY)
+            process.stdin.pause();
         server.closeAllConnections();
         await new Promise(resolve => server.close(() => resolve()));
     }

package/dist/cloud.d.ts

@@ -15,6 +15,10 @@ export interface VaultMemoryApi {
     saveGraphPreset?(input: Record<string, unknown>): Promise<unknown>;
     createGraphLink?(input: Record<string, unknown>): Promise<unknown>;
     deleteGraphLink?(id: string): Promise<unknown>;
+    temporalFacts?(input: Record<string, unknown>): Promise<unknown>;
+    temporalEntities?(input: Record<string, unknown>): Promise<unknown>;
+    temporalEntityFacts?(input: Record<string, unknown>): Promise<unknown>;
+    temporalStatus?(): Promise<unknown>;
     health(): Promise<unknown>;
     projects(): Promise<unknown>;
     createProject(input: Record<string, unknown>): Promise<unknown>;
@@ -131,6 +135,10 @@ export declare class VaultCloudClient implements VaultMemoryApi {
     saveGraphPreset(input: Record<string, unknown>): Promise<unknown>;
     createGraphLink(input: Record<string, unknown>): Promise<unknown>;
     deleteGraphLink(id: string): Promise<unknown>;
+    temporalFacts(input: Record<string, unknown>): Promise<unknown>;
+    temporalEntities(input: Record<string, unknown>): Promise<unknown>;
+    temporalEntityFacts(input: Record<string, unknown>): Promise<unknown>;
+    temporalStatus(): Promise<unknown>;
     private endpoint;
     private accessToken;
     private request;
@@ -138,5 +146,6 @@ export declare class VaultCloudClient implements VaultMemoryApi {
 }
 export declare class VaultCloudError extends Error {
     readonly status: number;
-    constructor(status: number, message: string);
+    readonly code?: string | undefined;
+    constructor(status: number, message: string, code?: string | undefined);
 }

package/dist/cloud.js

@@ -283,6 +283,17 @@ export class VaultCloudClient {
         await this.request(`/memory/graph/links/${encodeURIComponent(id)}`, { method: 'DELETE' });
         return { id, deleted: true };
     }
+    // Temporal graph reads are POST only to carry the body; they are safe to retry after a token refresh.
+    async temporalFacts(input) {
+        return this.request('/memory/temporal/facts', { retryRead: true, method: 'POST', body: input });
+    }
+    async temporalEntities(input) {
+        return this.request('/memory/temporal/entities', { retryRead: true, method: 'POST', body: input });
+    }
+    async temporalEntityFacts(input) {
+        return this.request('/memory/temporal/entity-facts', { retryRead: true, method: 'POST', body: input });
+    }
+    async temporalStatus() { return this.request('/memory/temporal/status'); }
     endpoint(path) {
         const base = validateApiUrl(loadConfig(this.home).apiUrl);
         const prefix = base.pathname.replace(/\/$/u, '');
@@ -398,10 +409,7 @@ export class VaultCloudClient {
         assertSession(this.home, session);
         const payload = text ? safeJson(text) : null;
         if (!response.ok) {
-            const message = payload && typeof payload === 'object' && 'error' in payload
-                ? String(payload.error)
-                : `Vault respondeu HTTP ${response.status}`;
-            throw new VaultCloudError(response.status, message);
+            throw new VaultCloudError(response.status, cloudErrorMessage(payload, response.status), cloudErrorCode(payload));
         }
         return payload;
     }
@@ -448,12 +456,39 @@ async function readResponseText(response, maxBytes) {
 }
 export class VaultCloudError extends Error {
     status;
-    constructor(status, message) {
+    code;
+    constructor(status, message, code) {
         super(message);
         this.status = status;
+        this.code = code;
         this.name = 'VaultCloudError';
     }
 }
+// The API answers `{error: "text"}` on older routes and `{error: {code, message}}` or `{error: "code", message}` on newer ones.
+function cloudErrorMessage(payload, status) {
+    if (!payload || typeof payload !== 'object' || !('error' in payload))
+        return `Vault respondeu HTTP ${status}`;
+    const body = payload;
+    if (body.error && typeof body.error === 'object') {
+        const nested = body.error;
+        if (typeof nested.message === 'string' && nested.message)
+            return nested.message;
+        if (typeof nested.code === 'string' && nested.code)
+            return nested.code;
+        return `Vault respondeu HTTP ${status}`;
+    }
+    return typeof body.message === 'string' && body.message ? body.message : String(body.error);
+}
+function cloudErrorCode(payload) {
+    if (!payload || typeof payload !== 'object')
+        return undefined;
+    const body = payload;
+    if (typeof body.code === 'string')
+        return body.code;
+    if (body.error && typeof body.error === 'object' && typeof body.error.code === 'string')
+        return body.error.code;
+    return typeof body.error === 'string' && /^[a-z][a-z0-9_]{1,63}$/.test(body.error) ? body.error : undefined;
+}
 function safeJson(text) {
     try {
         return JSON.parse(text);

package/dist/computer-tools.js

@@ -13,7 +13,7 @@ const observe = {
 };
 const ACTION = { readOnlyHint: false, destructiveHint: false, openWorldHint: false };
 const READ = { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false };
-const SAFETY = 'Não envie, compre, apague nem altere contas sem pedido explícito do usuário. Ação não verificada (verification.state=unverified) não é sucesso comprovado.';
+const SAFETY = 'Roda em segundo plano na janela alvo: não move o mouse do usuário nem tira o foco do app em que ele está, e um cursor dedicado do agente aparece só sobre aquela janela (Vault Desktop 0.11.73+). Não envie, compre, apague nem altere contas sem pedido explícito do usuário. Ação não verificada (verification.state=unverified) não é sucesso comprovado.';
 function observeFlags(input, bridge) {
     return {
         app: undefined,
@@ -63,7 +63,7 @@ export function registerComputerTools(server, bridge = new ComputerUseBridge(),
         inputSchema: { app }, annotations: READ,
     }, ({ app: target }) => invoke(() => bridge.call('list-windows', { app: target })));
     server.registerTool('vault_go_computer_get_app_state', {
-        description: 'Lê a árvore de acessibilidade da janela de um app e anexa um screenshot. Chame uma vez por turno antes de agir; os números da árvore são os elementIndex das ações e expiram após mudanças na UI.',
+        description: 'Lê a árvore de acessibilidade da janela de um app e anexa um screenshot, sem trazer a janela para frente. Chame uma vez por turno antes de agir; os números da árvore são os elementIndex das ações e expiram após mudanças na UI.',
         inputSchema: { app, ...observe }, annotations: READ,
     }, (input) => action('get-app-state', input, {}));
     server.registerTool('vault_go_computer_query', {

package/dist/crystal-tools.js

@@ -87,7 +87,7 @@ export async function callCrystalTool(home, name, args) {
         result: z.object({
             isError: z.boolean().optional(),
             content: z.array(z.object({ type: z.literal('text'), text: z.string() })),
-            structuredContent: z.record(z.unknown()).optional(),
+            structuredContent: z.record(z.string(), z.unknown()).optional(),
         }),
     }).safeParse(payload);
     if (!envelope.success)

package/dist/locale.d.ts

@@ -9,6 +9,8 @@ export declare const copy: {
         opening: string;
         fallback: string;
         openFailed: string;
+        pasteCallback: string;
+        pasteInvalid: string;
         connected: string;
         key: string;
         engine: string;
@@ -49,6 +51,8 @@ export declare const copy: {
         opening: string;
         fallback: string;
         openFailed: string;
+        pasteCallback: string;
+        pasteInvalid: string;
         connected: string;
         key: string;
         engine: string;
@@ -89,6 +93,8 @@ export declare const copy: {
         opening: string;
         fallback: string;
         openFailed: string;
+        pasteCallback: string;
+        pasteInvalid: string;
         connected: string;
         key: string;
         engine: string;

package/dist/locale.js

@@ -18,6 +18,8 @@ export const copy = {
         opening: "Abrindo o autenticador do AI Vault Memory no navegador…",
         fallback: "Se necessário, abra este endereço no mesmo computador:",
         openFailed: "Não foi possível abrir automaticamente. Use o endereço acima.",
+        pasteCallback: "Em outro computador (SSH)? Depois de entrar, copie o endereço 127.0.0.1 que não abriu e cole aqui:",
+        pasteInvalid: "Endereço inválido. Cole o endereço completo que começa com http://127.0.0.1",
         connected: "Conta conectada",
         key: "Chave de API",
         engine: "Escolher motor de contexto",
@@ -58,6 +60,8 @@ export const copy = {
         opening: "Opening the AI Vault Memory authenticator in your browser…",
         fallback: "If needed, open this address on the same computer:",
         openFailed: "Could not open automatically. Use the address above.",
+        pasteCallback: "On another computer (SSH)? After signing in, copy the 127.0.0.1 address that failed to load and paste it here:",
+        pasteInvalid: "Invalid address. Paste the full address starting with http://127.0.0.1",
         connected: "Account connected",
         key: "API key",
         engine: "Choose context engine",
@@ -98,6 +102,8 @@ export const copy = {
         opening: "Abriendo el autenticador de AI Vault Memory en el navegador…",
         fallback: "Si es necesario, abre esta dirección en el mismo equipo:",
         openFailed: "No se pudo abrir automáticamente. Usa la dirección anterior.",
+        pasteCallback: "¿En otro equipo (SSH)? Después de entrar, copia la dirección 127.0.0.1 que no abrió y pégala aquí:",
+        pasteInvalid: "Dirección inválida. Pega la dirección completa que empieza con http://127.0.0.1",
         connected: "Cuenta conectada",
         key: "Clave de API",
         engine: "Elegir motor de contexto",

package/dist/parity-tools.js

@@ -73,7 +73,7 @@ export function registerParityTools(server, home, cloud) {
     add('graph_link_delete', 'Exclui uma ligação manual da conta pelo UUID.', { id: uuid }, ({ id }) => cloud.deleteGraphLink ? cloud.deleteGraphLink(id) : unavailable(), false, true);
     add('graph_presets', 'Lista configurações salvas do grafo.', {}, () => cloud.graphPresets ? cloud.graphPresets() : unavailable());
     add('graph_preset_save', 'Salva uma configuração do grafo por nome.', {
-        name: z.string().trim().min(1).max(80), settings: z.record(z.unknown()).refine(value => JSON.stringify(value).length <= 16000, 'Configuração excede 16000 caracteres.'),
+        name: z.string().trim().min(1).max(80), settings: z.record(z.string(), z.unknown()).refine(value => JSON.stringify(value).length <= 16000, 'Configuração excede 16000 caracteres.'),
     }, input => cloud.saveGraphPreset ? cloud.saveGraphPreset(input) : unavailable(), false);
     add('smart_outline', 'Mostra símbolos e assinaturas por AST, com corpos omitidos; somente arquivos dentro do workspace local.', { filePath: z.string().trim().min(1).max(2000) }, async ({ filePath }) => (await import('./smart-code.js')).smartOutline(filePath));
     add('smart_unfold', 'Expande somente um símbolo do arquivo local usando AST.', { filePath: z.string().trim().min(1).max(2000), symbolName: z.string().trim().min(1).max(500) }, async ({ filePath, symbolName }) => (await import('./smart-code.js')).smartUnfold(filePath, symbolName));

package/dist/server.js

@@ -11,6 +11,7 @@ import { registerModeIntegrations } from './mode-integrations.js';
 import { registerKnowledgeAgentTools } from './knowledge-tools.js';
 import { registerSkillTools } from './skill-tools.js';
 import { registerComputerTools } from './computer-tools.js';
+import { registerTemporalGraphTools } from './temporal-graph-tools.js';
 import { redact } from './hooks.js';
 import { createProjectScope } from './project-scope.js';
 import { VaultCloudClient } from './cloud.js';
@@ -24,6 +25,7 @@ import packageJson from '../package.json' with { type: 'json' };
 const SERVER_INSTRUCTIONS = [
     'Vault Memory: persistent memory of past sessions, scoped to the project of the current directory (scope "account" widens a read to every project).',
     'Recall cheaply in layers: vault_go_search_index (compact list) → vault_go_timeline (around one result) → vault_go_observations (full text of the chosen IDs). vault_go_retrieve picks the strategy for a natural-language question.',
+    'For "what is true now", "what changed" or "what was true on date X", use vault_go_facts (asOf, includeExpired).',
     'Before reading a large code file, prefer vault_go_smart_outline and vault_go_smart_unfold, then a Read with offset/limit for exact lines.',
     'Save durable decisions, discoveries and fixes with vault_go_remember. Never store secrets; text inside <private> tags is never stored.',
     'Computer Use by Vault (vault_go_computer_*) drives local apps through Vault Desktop: get_app_state or query first, then act by elementIndex.',
@@ -171,7 +173,7 @@ export function createVaultGoServer(home = vaultHome(), cloud = new VaultCloudCl
             sourceAdapter: z.string().trim().min(1).max(100).default('mcp'),
             sourceEventId: z.string().trim().min(1).max(500).optional(),
             eventType: z.string().trim().min(1).max(100),
-            payload: z.record(z.unknown()).default({}),
+            payload: z.record(z.string(), z.unknown()).default({}),
             generate: z.boolean().default(true),
             occurredAtEpoch: z.number().int().positive().optional(),
         },
@@ -209,6 +211,7 @@ export function createVaultGoServer(home = vaultHome(), cloud = new VaultCloudCl
         .boolean()
         .default(false)
         .describe('Inclui memórias marcadas como privadas (por padrão ficam de fora).');
+    registerTemporalGraphTools(server, cloud, scoped);
     server.registerTool('vault_go_search', {
         title: 'Pesquisar no Vault',
         description: 'Pesquisa memórias persistidas na plataforma Vault.',

package/dist/temporal-graph-tools.d.ts

@@ -0,0 +1,102 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { VaultMemoryApi } from './cloud.js';
+import type { ProjectScope } from './project-scope.js';
+type Scoper = (input: Record<string, unknown> & {
+    projectId?: string | undefined;
+    scope?: ProjectScope | undefined;
+}) => Promise<Record<string, unknown>>;
+export type TemporalFact = {
+    id: string;
+    fact: string;
+    relation: string;
+    source: {
+        id: string;
+        name: string;
+    };
+    target: {
+        id: string;
+        name: string;
+    };
+    validAt: string | null;
+    invalidAt: string | null;
+    createdAt: string;
+    expiredAt: string | null;
+    memoryIds: string[];
+    projectIds: string[];
+};
+export type FactStatus = 'current' | 'ended' | 'superseded' | 'not_yet_valid';
+export declare const GRAPH_UNAVAILABLE_MESSAGE = "O grafo temporal ainda n\u00E3o est\u00E1 habilitado nesta conta (temporal graph not enabled yet). Nada est\u00E1 errado: use vault_go_search ou vault_go_search_index para recuperar mem\u00F3rias.";
+/**
+ * "What was true on 2026-03-01" means the end of that day, so a bare date
+ * becomes its last UTC millisecond; full datetimes pass through unchanged.
+ */
+export declare function normalizeAsOf(value: string | undefined): string | undefined;
+/** Classifies a fact against the reference instant (asOf or now). */
+export declare function factStatus(fact: Pick<TemporalFact, 'validAt' | 'invalidAt' | 'expiredAt'>, reference: number): FactStatus;
+/** Compact text for the model plus the full structured payload for clients that read structuredContent. */
+export declare function formatFacts(facts: TemporalFact[], options: {
+    asOf?: string | undefined;
+    includeExpired: boolean;
+    header?: string;
+}): {
+    text: string;
+    structured: {
+        facts: {
+            status: FactStatus;
+            id: string;
+            fact: string;
+            relation: string;
+            source: {
+                id: string;
+                name: string;
+            };
+            target: {
+                id: string;
+                name: string;
+            };
+            validAt: string | null;
+            invalidAt: string | null;
+            createdAt: string;
+            expiredAt: string | null;
+            memoryIds: string[];
+            projectIds: string[];
+        }[];
+        count: number;
+        asOf: string | null;
+        includeExpired: boolean;
+        memoryIds: string[];
+    };
+};
+type Entity = {
+    id: string;
+    name: string;
+    summary?: string;
+    labels?: string[];
+    createdAt?: string;
+};
+export declare function formatEntities(value: unknown): {
+    text: string;
+    structured: {
+        entities: Entity[];
+        count: number;
+    };
+};
+type ErrorContext = {
+    notFound?: string | undefined;
+};
+/** Maps API failures: graph_unavailable is an expected state, not an error; validation errors stay actionable. */
+export declare function temporalErrorResult(error: unknown, context?: ErrorContext): {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    structuredContent: Record<string, unknown>;
+} | {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    isError: boolean;
+};
+export declare function registerTemporalGraphTools(server: McpServer, cloud: VaultMemoryApi, scoped: Scoper): void;
+export {};

package/dist/temporal-graph-tools.js

@@ -0,0 +1,234 @@
+import { z } from 'zod';
+import { errorMessage } from './mcp-result.js';
+export const GRAPH_UNAVAILABLE_MESSAGE = 'O grafo temporal ainda não está habilitado nesta conta (temporal graph not enabled yet). Nada está errado: use vault_go_search ou vault_go_search_index para recuperar memórias.';
+const DATE_ONLY = /^\d{4}-\d{2}-\d{2}$/;
+/**
+ * "What was true on 2026-03-01" means the end of that day, so a bare date
+ * becomes its last UTC millisecond; full datetimes pass through unchanged.
+ */
+export function normalizeAsOf(value) {
+    if (!value)
+        return undefined;
+    return DATE_ONLY.test(value) ? `${value}T23:59:59.999Z` : value;
+}
+const asOfSchema = z
+    .string()
+    .trim()
+    .refine((value) => DATE_ONLY.test(value) || z.string().datetime({ offset: true }).safeParse(value).success, 'asOf deve ser uma data ISO (2026-03-01) ou data-hora ISO (2026-03-01T12:00:00Z).')
+    .refine((value) => !Number.isNaN(Date.parse(normalizeAsOf(value))), 'asOf inválido.')
+    .optional()
+    .describe('Data ISO: retorna o que era verdade naquele momento. Uma data sem hora vale até o fim do dia (UTC). Omitido: agora.');
+const includeExpiredSchema = z
+    .boolean()
+    .default(false)
+    .describe('false (padrão): só fatos válidos no momento consultado. true: inclui fatos encerrados ou substituídos, marcados como tal.');
+const time = (value) => {
+    if (!value)
+        return undefined;
+    const parsed = Date.parse(value);
+    return Number.isNaN(parsed) ? undefined : parsed;
+};
+/** Classifies a fact against the reference instant (asOf or now). */
+export function factStatus(fact, reference) {
+    const expired = time(fact.expiredAt);
+    if (expired !== undefined && expired <= reference)
+        return 'superseded';
+    const invalid = time(fact.invalidAt);
+    if (invalid !== undefined && invalid <= reference)
+        return 'ended';
+    const valid = time(fact.validAt);
+    if (valid !== undefined && valid > reference)
+        return 'not_yet_valid';
+    return 'current';
+}
+const day = (value) => {
+    if (!value)
+        return '?';
+    return /^\d{4}-\d{2}-\d{2}T00:00:00(\.0+)?(Z|[+-]00:?00)$/.test(value) ? value.slice(0, 10) : value.replace(/\.\d+(?=Z|[+-])/, '');
+};
+const STATUS_LABEL = {
+    current: () => 'VIGENTE',
+    ended: (fact) => `ENCERRADO em ${day(fact.invalidAt)}`,
+    superseded: (fact) => `SUBSTITUÍDO em ${day(fact.expiredAt)}`,
+    not_yet_valid: (fact) => `AINDA NÃO VIGENTE (a partir de ${day(fact.validAt)})`,
+};
+function asFacts(value) {
+    if (!value || typeof value !== 'object' || !Array.isArray(value.facts)) {
+        throw new Error('Resposta do grafo temporal inválida.');
+    }
+    return value.facts;
+}
+function factLine(fact, index, reference) {
+    const status = factStatus(fact, reference);
+    const window = `válido ${day(fact.validAt)} → ${fact.invalidAt ? day(fact.invalidAt) : 'hoje'}`;
+    const memories = fact.memoryIds?.length ? ` | memoryIds: ${fact.memoryIds.join(', ')}` : '';
+    return `${index + 1}. [${STATUS_LABEL[status](fact)}] ${fact.source?.name ?? '?'} —${fact.relation}→ ${fact.target?.name ?? '?'}: ${fact.fact} (${window})${memories}`;
+}
+/** Compact text for the model plus the full structured payload for clients that read structuredContent. */
+export function formatFacts(facts, options) {
+    const reference = options.asOf ? Date.parse(options.asOf) : Date.now();
+    const enriched = facts.map((fact) => ({ ...fact, status: factStatus(fact, reference) }));
+    const moment = options.asOf ? `em ${options.asOf}` : 'agora';
+    const filter = options.includeExpired ? 'incluindo encerrados/substituídos' : 'só vigentes';
+    const lines = [
+        ...(options.header ? [options.header] : []),
+        `${facts.length} fato(s) ${moment}, ${filter}.`,
+        ...facts.map((fact, index) => factLine(fact, index, reference)),
+    ];
+    const memoryIds = [...new Set(facts.flatMap((fact) => fact.memoryIds ?? []))];
+    if (memoryIds.length)
+        lines.push(`Fontes: vault_go_observations ids=${JSON.stringify(memoryIds.slice(0, 100))}`);
+    else if (!facts.length)
+        lines.push('Nenhum fato encontrado; tente outra consulta, scope "account" ou vault_go_search.');
+    return {
+        text: lines.join('\n'),
+        structured: { facts: enriched, count: facts.length, asOf: options.asOf ?? null, includeExpired: options.includeExpired, memoryIds },
+    };
+}
+export function formatEntities(value) {
+    if (!value || typeof value !== 'object' || !Array.isArray(value.entities)) {
+        throw new Error('Resposta do grafo temporal inválida.');
+    }
+    const entities = value.entities;
+    const lines = [
+        `${entities.length} entidade(s).`,
+        ...entities.map((entity, index) => {
+            const labels = entity.labels?.filter((label) => label !== 'Entity').join(', ');
+            return `${index + 1}. ${entity.name}${labels ? ` [${labels}]` : ''} (entityId: ${entity.id})${entity.summary ? ` — ${entity.summary}` : ''}`;
+        }),
+        entities.length
+            ? 'Use vault_go_entity_facts com entityId para ver os fatos de uma entidade.'
+            : 'Nenhuma entidade encontrada; tente outra consulta, scope "account" ou vault_go_search.',
+    ];
+    return { text: lines.join('\n'), structured: { entities, count: entities.length } };
+}
+function textResult(text, structuredContent) {
+    return { content: [{ type: 'text', text }], structuredContent };
+}
+function isGraphUnavailable(error, context) {
+    if (!error || typeof error !== 'object')
+        return false;
+    const { status, code, message } = error;
+    if (code === 'graph_unavailable' || (typeof message === 'string' && message.includes('graph_unavailable')))
+        return true;
+    // 503 is the documented answer; a 404 on a search route means a deployment that predates the temporal routes.
+    return status === 503 || (status === 404 && !context.notFound);
+}
+/** Maps API failures: graph_unavailable is an expected state, not an error; validation errors stay actionable. */
+export function temporalErrorResult(error, context = {}) {
+    if (isGraphUnavailable(error, context)) {
+        return textResult(GRAPH_UNAVAILABLE_MESSAGE, { available: false, enabled: false, reason: 'graph_unavailable', fallback: 'vault_go_search' });
+    }
+    const status = error && typeof error === 'object' ? error.status : undefined;
+    const message = errorMessage(error);
+    const text = status === 400
+        ? `Requisição inválida para o grafo temporal: ${message}`
+        : status === 404 && context.notFound ? context.notFound : message;
+    return { content: [{ type: 'text', text }], isError: true };
+}
+async function guarded(operation, context = {}) {
+    try {
+        const { text, structured } = await operation();
+        return textResult(text, structured);
+    }
+    catch (error) {
+        return temporalErrorResult(error, context);
+    }
+}
+const unavailable = () => {
+    throw Object.assign(new Error('graph_unavailable'), { status: 503, code: 'graph_unavailable' });
+};
+export function registerTemporalGraphTools(server, cloud, scoped) {
+    const uuid = z.string().uuid();
+    const annotations = { readOnlyHint: true, idempotentHint: true, openWorldHint: true };
+    const scope = z
+        .enum(['project', 'account'])
+        .default('project')
+        .describe('project (padrão): só o projeto do diretório atual quando projectId não é informado; account: todos os projetos da conta.');
+    const query = z.string().trim().min(1).max(1_000);
+    // The temporal API filters by a list; the MCP keeps the single-project convention of the other read tools.
+    const projectIds = async (input) => {
+        const resolved = await scoped({ projectId: input.projectId, scope: input.scope });
+        return typeof resolved.projectId === 'string' ? { projectIds: [resolved.projectId] } : {};
+    };
+    server.registerTool('vault_go_facts', {
+        title: 'Fatos do grafo temporal',
+        description: 'Pesquisa fatos (sujeito —relação→ objeto) com janela de validade no grafo temporal. Use para "o que é verdade agora", "o que mudou" ou "o que era verdade na data X" (asOf). '
+            + 'Fatos encerrados ou substituídos aparecem marcados quando includeExpired=true. Cada fato traz memoryIds para carregar as fontes com vault_go_observations.',
+        inputSchema: {
+            query,
+            asOf: asOfSchema,
+            includeExpired: includeExpiredSchema,
+            projectId: uuid.optional(),
+            scope,
+            limit: z.number().int().min(1).max(50).default(20),
+        },
+        annotations,
+    }, async ({ query, asOf, includeExpired, projectId, scope, limit }) => guarded(async () => {
+        if (!cloud.temporalFacts)
+            unavailable();
+        const at = normalizeAsOf(asOf);
+        const response = await cloud.temporalFacts({
+            query,
+            ...(await projectIds({ projectId, scope })),
+            ...(at ? { asOf: at } : {}),
+            includeExpired,
+            limit,
+        });
+        return formatFacts(asFacts(response), { asOf: at, includeExpired });
+    }));
+    server.registerTool('vault_go_entities', {
+        title: 'Entidades do grafo temporal',
+        description: 'Pesquisa entidades do grafo temporal (pessoas, projetos, serviços, arquivos...) com resumo e rótulos. Use o entityId retornado em vault_go_entity_facts.',
+        inputSchema: {
+            query,
+            projectId: uuid.optional(),
+            scope,
+            limit: z.number().int().min(1).max(50).default(20),
+        },
+        annotations,
+    }, async ({ query, projectId, scope, limit }) => guarded(async () => {
+        if (!cloud.temporalEntities)
+            unavailable();
+        return formatEntities(await cloud.temporalEntities({ query, ...(await projectIds({ projectId, scope })), limit }));
+    }));
+    server.registerTool('vault_go_entity_facts', {
+        title: 'Fatos de uma entidade',
+        description: 'Lista os fatos em torno de uma entidade (entityId de vault_go_entities), com asOf para "o que era verdade na data X" e includeExpired para ver o histórico de mudanças.',
+        inputSchema: {
+            entityId: uuid,
+            asOf: asOfSchema,
+            includeExpired: includeExpiredSchema,
+            limit: z.number().int().min(1).max(100).default(50),
+        },
+        annotations,
+    }, async ({ entityId, asOf, includeExpired, limit }) => guarded(async () => {
+        if (!cloud.temporalEntityFacts)
+            unavailable();
+        const at = normalizeAsOf(asOf);
+        const response = await cloud.temporalEntityFacts({ entityId, ...(at ? { asOf: at } : {}), includeExpired, limit });
+        const entity = response?.entity;
+        const header = entity
+            ? `Entidade: ${entity.name} (entityId: ${entity.id})${entity.summary ? ` — ${entity.summary}` : ''}`
+            : undefined;
+        const formatted = formatFacts(asFacts(response), { asOf: at, includeExpired, ...(header ? { header } : {}) });
+        return { text: formatted.text, structured: { entity: entity ?? null, ...formatted.structured } };
+    }, { notFound: 'Entidade não encontrada nesta conta; obtenha o entityId com vault_go_entities.' }));
+    server.registerTool('vault_go_graph_status', {
+        title: 'Status do grafo temporal',
+        description: 'Mostra se o grafo temporal está habilitado e o andamento da ingestão de memórias (episódios concluídos, pendentes, com falha e ignorados).',
+        inputSchema: {},
+        annotations,
+    }, async () => guarded(async () => {
+        if (!cloud.temporalStatus)
+            unavailable();
+        const status = (await cloud.temporalStatus());
+        if (!status || typeof status !== 'object')
+            throw new Error('Resposta do grafo temporal inválida.');
+        const episodes = status.episodes ?? {};
+        const text = status.enabled
+            ? `Grafo temporal habilitado. Episódios: ${episodes.done ?? 0} concluídos, ${episodes.pending ?? 0} pendentes, ${episodes.failed ?? 0} com falha, ${episodes.skipped ?? 0} ignorados. Último processamento: ${status.lastProcessedAt ?? 'nunca'}.`
+            : GRAPH_UNAVAILABLE_MESSAGE;
+        return { text, structured: status };
+    }));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vault-go",
-  "version": "0.34.0",
+  "version": "0.36.0",
   "description": "MCP server and installer for Vault Memory: search, capture, and use account memory across AI clients.",
   "type": "module",
   "bin": {
@@ -161,6 +161,8 @@
     "dist/memory-archive.d.ts",
     "dist/agent-cost.js",
     "dist/agent-cost.d.ts",
+    "dist/temporal-graph-tools.js",
+    "dist/temporal-graph-tools.d.ts",
     "grammars/"
   ],
   "scripts": {
@@ -229,7 +231,7 @@
     "@ast-grep/napi": "0.45.3",
     "@modelcontextprotocol/sdk": "1.32.1",
     "@tree-sitter-grammars/tree-sitter-zig": "1.1.2",
-    "zod": "3.25.76"
+    "zod": "4.6.7"
   },
   "devDependencies": {
     "@semantic-release/commit-analyzer": "13.0.1",
@@ -242,6 +244,6 @@
     "typescript": "^5.9.3"
   },
   "overrides": {
-    "@hono/node-server": "2.0.11"
+    "@hono/node-server": "2.1.3"
   }
 }