vault-go 0.25.1 → 0.26.0

package/README.md

@@ -146,7 +146,9 @@ Account and health: `vault_go_status`, `vault_go_cloud_health`, `vault_go_prefer
 
 Projects and sessions: `vault_go_projects`, `vault_go_project_create`, `vault_go_session_start`, `vault_go_session_end`, `vault_go_session_start_context`.
 
-Capture and recall: `vault_go_event`, `vault_go_remember`, `vault_go_forget`, `vault_go_search`, `vault_go_search_index`, `vault_go_observations`, `vault_go_timeline`, `vault_go_context`, `vault_go_file_context`, `vault_go_feed`, `vault_go_memory`, `vault_go_tool_uses`, `vault_go_stats`.
+Capture and recall: `vault_go_event`, `vault_go_remember`, `vault_go_forget`, `vault_go_search`, `vault_go_search_index`, `vault_go_retrieve`, `vault_go_observations`, `vault_go_timeline`, `vault_go_context`, `vault_go_file_context`, `vault_go_feed`, `vault_go_memory`, `vault_go_tool_uses`, `vault_go_stats`.
+
+`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.
 
 Knowledge bases: `vault_go_knowledge_bases`, `vault_go_knowledge_base`, `vault_go_knowledge_build`, `vault_go_knowledge_rebuild`, `vault_go_knowledge_query`, `vault_go_knowledge_delete`, `vault_go_prime_corpus`, `vault_go_query_corpus`, `vault_go_reprime_corpus`.
 

package/dist/capabilities.d.ts

@@ -23,6 +23,11 @@ export declare const CAPABILITIES: {
         readonly status: "available";
         readonly tools: readonly ["vault_go_search_index", "vault_go_observations", "vault_go_timeline", "vault_go_feed"];
         readonly difference: "Vault uses UUID identifiers. Search accepts an optional query, offset and date ordering; timeline accepts an explicit UUID or resolves an anchor from a query; feed uses stable cursor pagination.";
+    }, {
+        readonly upstream: readonly ["automatic retrieval routing", "typed memory decisions"];
+        readonly status: "available";
+        readonly tools: readonly ["vault_go_retrieve", "vault_go_decision_status"];
+        readonly requires: "Jev runs only in the central memory engine. Status is sanitized; deployment availability does not prove provider health or decision quality. Explicit retrieval tools remain available.";
     }, {
         readonly upstream: readonly ["get_tool_uses"];
         readonly status: "available";
@@ -134,6 +139,11 @@ export declare function getCapabilities(home: string, cloud: VaultMemoryApi, ver
         readonly status: "available";
         readonly tools: readonly ["vault_go_search_index", "vault_go_observations", "vault_go_timeline", "vault_go_feed"];
         readonly difference: "Vault uses UUID identifiers. Search accepts an optional query, offset and date ordering; timeline accepts an explicit UUID or resolves an anchor from a query; feed uses stable cursor pagination.";
+    }, {
+        readonly upstream: readonly ["automatic retrieval routing", "typed memory decisions"];
+        readonly status: "available";
+        readonly tools: readonly ["vault_go_retrieve", "vault_go_decision_status"];
+        readonly requires: "Jev runs only in the central memory engine. Status is sanitized; deployment availability does not prove provider health or decision quality. Explicit retrieval tools remain available.";
     }, {
         readonly upstream: readonly ["get_tool_uses"];
         readonly status: "available";

package/dist/capabilities.js

@@ -11,6 +11,7 @@ export const CAPABILITIES = {
     capabilities: [
         { upstream: ['important_workflow'], status: 'available', tools: ['vault_go_workflow'] },
         { upstream: ['search', 'get_observations', 'timeline'], status: 'available', tools: ['vault_go_search_index', 'vault_go_observations', 'vault_go_timeline', 'vault_go_feed'], difference: 'Vault uses UUID identifiers. Search accepts an optional query, offset and date ordering; timeline accepts an explicit UUID or resolves an anchor from a query; feed uses stable cursor pagination.' },
+        { upstream: ['automatic retrieval routing', 'typed memory decisions'], status: 'available', tools: ['vault_go_retrieve', 'vault_go_decision_status'], requires: 'Jev runs only in the central memory engine. Status is sanitized; deployment availability does not prove provider health or decision quality. Explicit retrieval tools remain available.' },
         { upstream: ['get_tool_uses'], status: 'available', tools: ['vault_go_tool_uses'], requires: 'Verified POST /memory/events/batch contract. Historical output exists only when captured; private fields and secrets are redacted from retrieval.' },
         { upstream: ['session_start_context', 'multi-project context'], status: 'available', tools: ['vault_go_session_start_context', 'vault_go_context', 'vault_go_file_context', 'vault_go_context_chain', 'vault_go_context_chain_configure'], requires: 'Context chains require explicit local configuration and share one bounded character budget. Native hooks cover Claude, Codex, Grok, Agy and Gemini; OpenCode 1.x remains context-only.' },
         { upstream: ['smart_search', 'smart_outline', 'smart_unfold'], status: 'available', tools: ['vault_go_smart_search', 'vault_go_smart_outline', 'vault_go_smart_unfold', 'vault_go_smart_languages'], requires: 'Real grammars for all 24 upstream languages plus HTML. Availability is reported per running platform; SCSS has no Linux ARM64 prebuild. Workspace reads and results are bounded.' },

package/dist/cloud.d.ts

@@ -24,6 +24,8 @@ export interface VaultMemoryApi {
     remember(input: Record<string, unknown>): Promise<unknown>;
     forget(id: string): Promise<unknown>;
     search(input: Record<string, unknown>): Promise<unknown>;
+    retrieve?(input: Record<string, unknown>): Promise<unknown>;
+    decisionStatus?(): Promise<unknown>;
     searchIndex(input: Record<string, unknown>): Promise<unknown>;
     observations(ids: string[]): Promise<unknown>;
     timeline(input: Record<string, unknown>): Promise<unknown>;
@@ -69,6 +71,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>;
+    retrieve(input: Record<string, unknown>): Promise<unknown>;
+    decisionStatus(): Promise<unknown>;
     searchIndex(input: Record<string, unknown>): Promise<unknown>;
     observations(ids: string[]): Promise<unknown>;
     timeline(input: Record<string, unknown>): Promise<unknown>;

package/dist/cloud.js

@@ -2,6 +2,46 @@ import { recordActivity } from './activity.js';
 import { loadConfig, loadTokens, saveTokens, validateApiUrl, vaultHome, } from './config.js';
 const KNOWLEDGE_BASE_RESPONSE_MAX_BYTES = 8 * 1024 * 1024;
 const KNOWLEDGE_BASE_RESPONSE_LIMIT_ERROR = 'A base de conhecimento excede o limite de resposta de 8 MiB.';
+const observationTypes = new Set(['decision', 'discovery', 'fix', 'feature', 'refactor', 'other']);
+const retentionClasses = new Set(['transient', 'supporting', 'durable', 'critical']);
+const actionableBands = new Set(['low', 'medium', 'high']);
+const uuidPattern = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/iu;
+const record = (value) => Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+const probability = (value) => value === undefined || (typeof value === 'number' && Number.isFinite(value) && value >= 0 && value <= 1);
+function validSignals(value) {
+    return record(value) && observationTypes.has(String(value.observationType)) && retentionClasses.has(String(value.retentionClass)) && actionableBands.has(String(value.actionableBand)) && typeof value.decisionId === 'string' && uuidPattern.test(value.decisionId);
+}
+function validDecision(value) {
+    return record(value) && ['applied', 'fallback'].includes(String(value.status)) && observationTypes.has(String(value.observationType)) && retentionClasses.has(String(value.retention)) && value.persist === true && probability(value.novelInformation) && probability(value.actionable);
+}
+function authoritativeDecisionResponse(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return value;
+    const result = { ...value };
+    if ('decision' in result) {
+        if (!validDecision(result.decision))
+            delete result.decision;
+    }
+    if ('decisionSignals' in result) {
+        if (!validSignals(result.decisionSignals))
+            delete result.decisionSignals;
+    }
+    if (result.decisions && typeof result.decisions === 'object' && !Array.isArray(result.decisions)) {
+        result.decisions = Object.fromEntries(Object.entries(result.decisions).filter(([, decision]) => validDecision(decision)));
+    }
+    return result;
+}
+function withoutClientDecisions(input) {
+    const { decision: _decision, decisions: _decisions, decisionSignals: _signals, decision_signals: _snakeSignals, ...safe } = input;
+    if (!Array.isArray(safe.records))
+        return safe;
+    return { ...safe, records: safe.records.map(record => {
+            if (!record || typeof record !== 'object' || Array.isArray(record))
+                return record;
+            const { decision: _recordDecision, decisions: _recordDecisions, decisionSignals: _recordSignals, decision_signals: _recordSnakeSignals, ...safeRecord } = record;
+            return safeRecord;
+        }) };
+}
 export class VaultCloudClient {
     home;
     cloudFetch;
@@ -53,7 +93,7 @@ export class VaultCloudClient {
         return this.request('/memory/events', { method: 'POST', body: input });
     }
     async remember(input) {
-        return this.request('/memory/memories', { method: 'POST', body: input });
+        return authoritativeDecisionResponse(await this.request('/memory/memories', { method: 'POST', body: withoutClientDecisions(input) }));
     }
     async forget(id) {
         await this.request(`/memory/memories/${encodeURIComponent(id)}`, { method: 'DELETE' });
@@ -62,6 +102,12 @@ export class VaultCloudClient {
     async search(input) {
         return this.request('/memory/search', { method: 'POST', body: input });
     }
+    async retrieve(input) {
+        return this.request('/memory/retrieve', { method: 'POST', body: input });
+    }
+    async decisionStatus() {
+        return this.request('/memory/decisions/status');
+    }
     async searchIndex(input) {
         return this.request('/memory/search/index', { method: 'POST', body: input });
     }
@@ -107,7 +153,7 @@ export class VaultCloudClient {
         return this.request(`/memory/export?${query.toString()}`);
     }
     async importMemories(input) {
-        return this.request('/memory/import', { method: 'POST', body: input });
+        return authoritativeDecisionResponse(await this.request('/memory/import', { method: 'POST', body: withoutClientDecisions(input) }));
     }
     async backupStatus() { return this.request('/memory/backup/status'); }
     async exportBackupPage(input) {

package/dist/hook-queue.js

@@ -101,6 +101,20 @@ function generationFailureCode(error) {
         return 'awareness_failed';
     return 'generation_or_persistence_failed';
 }
+function appliedObservationType(result, sourceId, fallback) {
+    if (!result || typeof result !== 'object' || Array.isArray(result))
+        return fallback;
+    const decisions = result.decisions;
+    if (!decisions || typeof decisions !== 'object' || Array.isArray(decisions))
+        return fallback;
+    const decision = decisions[sourceId];
+    if (!decision || typeof decision !== 'object' || Array.isArray(decision))
+        return fallback;
+    const observationType = decision.observationType;
+    return typeof observationType === 'string' && ['decision', 'discovery', 'fix', 'feature', 'refactor', 'other'].includes(observationType)
+        ? observationType
+        : fallback;
+}
 export async function enqueueGeneration(home, job) {
     if (isUnusableGenerationText(job.text) || job.text.length > 16_000)
         return;
@@ -147,8 +161,9 @@ export async function processGenerationQueue(home = vaultHome(), cloud = new Vau
             // Cache successful generation before persistence, so a network retry does not pay for the model twice.
             await mutate(home, jobs => jobs.map(item => item.id === job.id ? { ...item, result } : item));
             const memoryType = result.type ?? 'discovery';
-            await cloud.importMemories({ projectId: job.projectId, records: [{
-                        sourceId: `vault-go:event:${job.id}`,
+            const sourceId = `vault-go:event:${job.id}`;
+            const importResult = await cloud.importMemories({ projectId: job.projectId, records: [{
+                        sourceId,
                         ...(job.sessionId ? { sessionId: job.sessionId } : {}),
                         kind: job.kind,
                         memoryType,
@@ -157,9 +172,10 @@ export async function processGenerationQueue(home = vaultHome(), cloud = new Vau
                         facts: result.facts, concepts: result.concepts,
                         filesRead: job.filesRead ?? [], filesModified: job.filesModified ?? [],
                     }] });
+            const awarenessType = appliedObservationType(importResult, sourceId, memoryType);
             if (owner !== ownerKey(home))
                 throw new Error('Account changed.');
-            const awareness = await pushAwareness(home, { ...(job.agentId ? { agentId: job.agentId } : {}), observations: [{ type: memoryType, title: result.title || job.title || 'Memória', facts: result.facts, concepts: result.concepts }] });
+            const awareness = await pushAwareness(home, { ...(job.agentId ? { agentId: job.agentId } : {}), observations: [{ type: awarenessType, title: result.title || job.title || 'Memória', facts: result.facts, concepts: result.concepts }] });
             if (awareness.error)
                 throw new Error('Awareness delivery failed; retry with cached generation.');
             await mirrorCrystalMemory({ home, cloud, job, result });
@@ -168,7 +184,7 @@ export async function processGenerationQueue(home = vaultHome(), cloud = new Vau
                 try {
                     await (options.notifyObservation ?? ((observation) => notifyTelegramObservation(home, observation)))({
                         id: job.id,
-                        type: memoryType,
+                        type: awarenessType,
                         title: result.title,
                         concepts: result.concepts,
                     });

package/dist/server.js

@@ -191,6 +191,33 @@ export function createVaultGoServer(home = vaultHome(), cloud = new VaultCloudCl
         },
         annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true },
     }, async (input) => run(() => cloud.search(input)));
+    server.registerTool('vault_go_retrieve', {
+        title: 'Recuperação automática do Vault',
+        description: 'Delega ao motor central a escolha tipada entre busca, contexto de arquivo, linha do tempo, base de conhecimento, grafo ou nenhum resultado. Falhas usam busca determinística.',
+        inputSchema: {
+            query: z.string().trim().min(1).max(1_000),
+            projectId: uuid.optional(),
+            files: z.array(z.string().trim().min(1).max(2_000)).max(50).default([]),
+            knowledgeBaseId: uuid.optional(),
+            limit: z.number().int().min(1).max(200).default(20),
+            maxChars: z.number().int().min(1_000).max(100_000).optional(),
+        },
+        annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true },
+    }, async (input) => run(() => {
+        if (!cloud.retrieve)
+            throw new Error('Native retrieval is unavailable on this deployment.');
+        return cloud.retrieve(input);
+    }));
+    server.registerTool('vault_go_decision_status', {
+        title: 'Status da camada de decisão',
+        description: 'Retorna somente o status operacional sanitizado do Jev central. Configuração não comprova saúde do provedor nem qualidade das decisões.',
+        inputSchema: {},
+        annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true },
+    }, async () => run(() => {
+        if (!cloud.decisionStatus)
+            throw new Error('Decision status is unavailable on this deployment.');
+        return cloud.decisionStatus();
+    }));
     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.',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vault-go",
-  "version": "0.25.1",
+  "version": "0.26.0",
   "description": "MCP server and installer for Vault Memory: search, capture, and use account memory across AI clients.",
   "type": "module",
   "bin": {