wendkeep 0.85.0 → 0.86.0

package/docs/pt-BR/commands/mcp.md

@@ -63,20 +63,71 @@ O `init` gera a entrada genérica reproduzível:
 ```
 
 Reads: `wendkeep_project_status`, `wendkeep_context_status`, `wendkeep_memory_recall`,
-`wendkeep_memory_conflicts`, `wendkeep_change_list`, `wendkeep_change_show`,
-`wendkeep_change_status`, `wendkeep_spec_effective`, `wendkeep_task_show`,
-`wendkeep_task_evaluate`, `wendkeep_handoff_current`, `wendkeep_evidence_latest` e
-`wendkeep_observer_query`.
+`wendkeep_evidence_recall`, `wendkeep_memory_conflicts`, `wendkeep_change_list`,
+`wendkeep_change_show`, `wendkeep_change_status`, `wendkeep_spec_effective`,
+`wendkeep_task_show`, `wendkeep_task_evaluate`, `wendkeep_handoff_current`,
+`wendkeep_evidence_latest` e `wendkeep_observer_query`.
 
 Writes: `wendkeep_memory_assert`, `wendkeep_checkpoint_create`, `wendkeep_context_select`,
 `wendkeep_task_claim`, `wendkeep_task_complete` e `wendkeep_handoff_publish`.
 
+## Recall paginado e indexado de evidências
+
+`wendkeep_evidence_recall` é a superfície bounded para recuperar evidências do Vault. Ela seleciona
+candidatos pelo sidecar lexical persistente ou pelo SQLite/FTS5 opcional, reranqueia com o scorer
+canônico e devolve uma página compacta. `wendkeep_memory_recall` permanece disponível como API
+legada e não ganha silenciosamente o novo contrato.
+
+Entrada principal:
+
+- `project_root` e `query` são obrigatórios;
+- `limit` aceita 1 a 100 resultados por página;
+- `cursor` é opaco e só vale para a mesma consulta, filtros e índice lógico;
+- `max_bytes` aceita 2 a 524288 e limita exatamente o JSON serializado de `results`; o padrão é
+  64 KiB;
+- `candidate_limit` aceita 1 a 4096 candidatos;
+- `posting_budget` aceita 1 a 1048576 postings visitados;
+- `backend` aceita `auto`, `sqlite` ou `lexical`;
+- `filters` aceita igualdade por `authority`, `validity`, `entity_type`, `project_id`,
+  `change_slug`, `session_id`, `work_session_id` e `logical_path`, além de
+  `logical_path_prefix`. Cada filtro pode ser string ou lista de strings.
+
+Exemplo de chamada:
+
+```json
+{
+  "name": "wendkeep_evidence_recall",
+  "arguments": {
+    "project_root": "<projeto>",
+    "query": "contrato de autenticação",
+    "limit": 5,
+    "max_bytes": 65536,
+    "candidate_limit": 512,
+    "posting_budget": 65536,
+    "backend": "auto",
+    "filters": {
+      "authority": "verified",
+      "validity": "active",
+      "logical_path_prefix": "04-Decisões/"
+    }
+  }
+}
+```
+
+A resposta contém `results`, `next_cursor`, `has_more`, `as_of`, contagens e bytes da página. Cada
+resultado omite `content`, informa `content_bytes`, mantém um `excerpt` bounded e substitui
+`logical_path` por `logical_ref`, uma referência relativa ao Vault — nunca um caminho absoluto. O
+bloco `candidates` expõe backend, quantidade, postings, rebuild e fallback. Quando o orçamento de
+candidatos não cobriu todo o conjunto possível, `complete_candidate_set` é `false`; isso impede que
+o consumidor interprete uma seleção truncada como exaustiva.
+
 ## Resultado esperado
 
 O handshake e `tools/list` retornam JSON-RPC válido. Cada tool declara effect/capability e schemas
 versionados. Reads conhecidas não entram no mutation gate, mas mantêm binding explícito de
-projeto/worktree, paginação por cursor, budget padrão de 1 MiB, redaction, timeout e cancelamento.
-Observer aparece indisponível abaixo de Node 22.13 sem impedir Core no Node 18.
+projeto/worktree, paginação por cursor, budgets, redaction, timeout e cancelamento. Observer aparece
+indisponível abaixo de Node 22.13 sem impedir Core no Node 18. O recall indexado também funciona no
+Node 18 pelo fallback lexical; SQLite/FTS5 permanece opcional.
 
 Writes exigem `project_root`, `session_id`, `active_context_id`, `actor`, `reason`, capability exata
 e `lease.id`/`lease.expires_at`; o executor revalida a autorização causal e os gates da CLI. A
@@ -89,8 +140,16 @@ código e duração — nunca argumentos ou payload.
 - `MCP_CAPABILITY_REQUIRED` / `MCP_SCOPE_AUTH_REQUIRED`: capability ausente ou não autorizada.
 - `MCP_LEASE_EXPIRED`: obtenha autorização/lease nova; não altere timestamp manualmente.
 - `MCP_PROJECT_SCOPE_MISMATCH`: `project_root` e `worktree_root` pertencem a bindings diferentes.
-- `MCP_REQUEST_TOO_LARGE` / `MCP_RESPONSE_TOO_LARGE`: use `limit` e o cursor retornado.
+- `MCP_REQUEST_TOO_LARGE` / `MCP_RESPONSE_TOO_LARGE`: reduza os budgets e continue pelo cursor.
 - `MCP_RUNTIME_UNSUPPORTED`: use Node 22.13+ para Observer; Core permanece disponível.
+- `MCP_EVIDENCE_QUERY_REQUIRED`: informe uma consulta não vazia.
+- `MCP_EVIDENCE_CURSOR_INVALID`: cursor adulterado, stale ou usado com outra consulta/filtros.
+- `MCP_EVIDENCE_BUDGET_TOO_SMALL`: nem os metadados mínimos do próximo resultado cabem em
+  `max_bytes`.
+- `MCP_EVIDENCE_BACKEND_UNAVAILABLE`: o backend SQLite foi exigido, mas FTS5 não está disponível;
+  use `auto` ou `lexical`.
+- `MCP_EVIDENCE_ARTIFACT_UNSAFE`: um artefato derivado violou a fronteira física do Vault.
+- `MCP_EVIDENCE_RECALL_INVALID`: filtro, backend ou limite fora do contrato.
 
 ## Próximos passos
 

package/hooks/evidence-context.mjs

@@ -2,7 +2,13 @@
 // UserPromptSubmit: bounded, read-only retrieval from the local evidence index.
 import { pathToFileURL } from 'node:url';
 import { readHookInput, readSessionRegistry, writeHookOutput } from './obsidian-common.mjs';
-import { loadEvidenceIndex, recallEvidence, renderEvidenceContext } from './evidence-recall.mjs';
+import {
+  EVIDENCE_SEARCH_MAX_CANDIDATES,
+  loadEvidenceIndex,
+  recallEvidence,
+  renderEvidenceContext,
+  searchEvidenceCandidates,
+} from './evidence-recall.mjs';
 import { sanitizeMemoryText } from './memory-schema.mjs';
 import { resolveHookOperatingProfile } from './operating-profile-runtime.mjs';
 import {
@@ -11,16 +17,44 @@ import {
 } from './active-context-handoff-evidence.mjs';
 import { isBootstrapPrompt } from '../packages/integrations/src/prompt-content.mjs';
 
+function scopedRows(rows, activeContext, registry) {
+  return scopeEvidenceRows(rows, { activeContext, registry });
+}
+
+function indexedScopedEvidence(vaultBase, query, topK, activeContext, registry) {
+  const initialLimit = Math.min(
+    EVIDENCE_SEARCH_MAX_CANDIDATES,
+    Math.max(512, Number(topK || 0) * 64),
+  );
+  const first = searchEvidenceCandidates(vaultBase, query, {
+    candidateLimit: initialLimit,
+  });
+  let scoped = scopedRows(first.rows, activeContext, registry);
+  if (scoped.length >= topK || !first.has_more
+      || initialLimit >= EVIDENCE_SEARCH_MAX_CANDIDATES) return scoped;
+  const expanded = searchEvidenceCandidates(vaultBase, query, {
+    candidateLimit: EVIDENCE_SEARCH_MAX_CANDIDATES,
+  });
+  scoped = scopedRows(expanded.rows, activeContext, registry);
+  return scoped;
+}
+
 export function buildPromptEvidenceContext(vaultBase, prompt, {
   topK = 3, maxBytes = 3072, rows = null, activeContext = null, registry = null,
 } = {}) {
   const query = sanitizeMemoryText(String(prompt || '')).trim();
   if (!query || isBootstrapPrompt(query)) return '';
-  const evidence = rows || loadEvidenceIndex(vaultBase);
-  const scoped = scopeEvidenceRows(evidence, {
-    activeContext,
-    registry: registry || readSessionRegistry(vaultBase),
-  });
+  const effectiveRegistry = registry || readSessionRegistry(vaultBase);
+  let scoped;
+  if (rows) {
+    scoped = scopedRows(rows, activeContext, effectiveRegistry);
+  } else {
+    try {
+      scoped = indexedScopedEvidence(vaultBase, query, topK, activeContext, effectiveRegistry);
+    } catch {
+      scoped = scopedRows(loadEvidenceIndex(vaultBase), activeContext, effectiveRegistry);
+    }
+  }
   if (!scoped.length) return '';
   return sanitizeMemoryText(renderEvidenceContext(
     recallEvidence(scoped, query, { topK }),
@@ -53,4 +87,4 @@ if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href)
   } catch {
     writeHookOutput({});
   }
-}
+}

package/hooks/evidence-recall.mjs

@@ -1 +1,11 @@
 export * from '../packages/vault/src/evidence-recall.mjs';
+export * from '../packages/vault/src/evidence-recall-page.mjs';
+export * from '../packages/vault/src/evidence-search-index.mjs';
+export {
+  EVIDENCE_INDEX_STATE_FILE,
+  EVIDENCE_INDEX_STATE_VERSION,
+  buildIncrementalEvidenceIndex,
+  buildIncrementalEvidenceIndex as buildEvidenceIndex,
+  loadEvidenceIndexState,
+  refreshEvidenceIndex,
+} from '../packages/vault/src/evidence-index-store.mjs';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wendkeep",
-  "version": "0.85.0",
+  "version": "0.86.0",
   "description": "Vault-first persistent memory for AI coding agents, with an optional profile-aware governance runtime: OFF, FLOW, GUIDE, GOVERN, or ASSURE. Local-first and agent-agnostic (Claude Code, Codex, Cursor…).",
   "type": "module",
   "workspaces": [

package/packages/mcp/src/effects.mjs

@@ -6,6 +6,7 @@ const TOOLS = [
   ['wendkeep_project_status', 'read', 'project:status'],
   ['wendkeep_context_status', 'read', 'context:status'],
   ['wendkeep_memory_recall', 'read', 'memory:recall'],
+  ['wendkeep_evidence_recall', 'read', 'evidence:recall'],
   ['wendkeep_memory_conflicts', 'read', 'memory:conflicts'],
   ['wendkeep_change_list', 'read', 'change:list'],
   ['wendkeep_change_show', 'read', 'change:show'],
@@ -55,10 +56,10 @@ function deepFreeze(value) {
 
 export const MCP_EFFECT_MANIFEST = deepFreeze({
   schema_version: 1,
-  catalog_version: '2026-08-24',
+  catalog_version: '2026-08-27',
   server_aliases: ['wendkeep', 'wendkeep-native'],
   tools: TOOLS,
-  integrity: 'sha256:de96c2f3f5ae3d814440b541db778f87be4550ebd2ce9dd5ae2377f354770046',
+  integrity: 'sha256:1bb4d5dc62008ed23afa0d850a89bbbb77ea9cc31da79cde557aa2f02034fdde',
 });
 
 export function verifyMcpEffectManifest(manifest) {

package/packages/mcp/src/evidence-recall.mjs

@@ -0,0 +1,130 @@
+import {
+  EVIDENCE_RECALL_DEFAULT_LIMIT,
+  EVIDENCE_RECALL_DEFAULT_MAX_BYTES,
+  EVIDENCE_RECALL_MAX_LIMIT,
+  EvidenceRecallBudgetError,
+  EvidenceRecallCursorError,
+  recallEvidencePage,
+} from '../../vault/src/evidence-recall-page.mjs';
+import {
+  EVIDENCE_SEARCH_DEFAULT_CANDIDATES,
+  EVIDENCE_SEARCH_DEFAULT_POSTING_BUDGET,
+  EVIDENCE_SEARCH_MAX_CANDIDATES,
+  EVIDENCE_SEARCH_MAX_POSTING_BUDGET,
+  searchEvidenceCandidates,
+} from '../../vault/src/evidence-search-index.mjs';
+
+export const MCP_EVIDENCE_RECALL_MAX_BYTES = 512 * 1024;
+
+function integer(value, fallback, { min = 1, max } = {}) {
+  const number = Number(value ?? fallback);
+  if (!Number.isSafeInteger(number) || number < min || number > max) {
+    throw new RangeError(`value must be an integer between ${min} and ${max}`);
+  }
+  return number;
+}
+
+function backend(value) {
+  const normalized = String(value ?? 'auto').trim().toLowerCase();
+  if (!['auto', 'sqlite', 'lexical'].includes(normalized)) {
+    throw new TypeError('backend must be auto, sqlite, or lexical');
+  }
+  return normalized;
+}
+
+function filters(value) {
+  if (value === undefined || value === null) return {};
+  if (typeof value !== 'object' || Array.isArray(value)) {
+    throw new TypeError('filters must be an object');
+  }
+  return value;
+}
+
+function logicalReference(result) {
+  const { logical_path: logicalPath, ...rest } = result || {};
+  return {
+    ...rest,
+    logical_ref: String(logicalPath || ''),
+  };
+}
+
+function mappedError(error) {
+  if (String(error?.code || '').startsWith('MCP_')) return error;
+  let code = 'MCP_EVIDENCE_RECALL_FAILED';
+  if (error instanceof EvidenceRecallCursorError
+      || error?.code === 'EVIDENCE_RECALL_CURSOR_INVALID') {
+    code = 'MCP_EVIDENCE_CURSOR_INVALID';
+  } else if (error instanceof EvidenceRecallBudgetError
+      || error?.code === 'EVIDENCE_RECALL_BUDGET_TOO_SMALL') {
+    code = 'MCP_EVIDENCE_BUDGET_TOO_SMALL';
+  } else if (error?.code === 'EVIDENCE_SEARCH_SQLITE_UNAVAILABLE'
+      || error?.code === 'EVIDENCE_SEARCH_FTS5_UNAVAILABLE') {
+    code = 'MCP_EVIDENCE_BACKEND_UNAVAILABLE';
+  } else if (error?.code === 'VAULT_PATH_UNSAFE') {
+    code = 'MCP_EVIDENCE_ARTIFACT_UNSAFE';
+  } else if (error instanceof TypeError || error instanceof RangeError) {
+    code = 'MCP_EVIDENCE_RECALL_INVALID';
+  }
+  return Object.assign(new Error(error?.message || 'evidence recall failed'), {
+    code,
+    cause: error,
+  });
+}
+
+export function recallEvidenceForMcp(vaultBase, args = {}) {
+  try {
+    const query = String(args.query || '').trim();
+    if (!query) {
+      throw Object.assign(new Error('query is required'), {
+        code: 'MCP_EVIDENCE_QUERY_REQUIRED',
+      });
+    }
+    const limit = integer(args.limit, EVIDENCE_RECALL_DEFAULT_LIMIT, {
+      max: EVIDENCE_RECALL_MAX_LIMIT,
+    });
+    const maxBytes = integer(args.max_bytes, EVIDENCE_RECALL_DEFAULT_MAX_BYTES, {
+      min: 2,
+      max: MCP_EVIDENCE_RECALL_MAX_BYTES,
+    });
+    const candidateLimit = integer(
+      args.candidate_limit,
+      Math.max(EVIDENCE_SEARCH_DEFAULT_CANDIDATES, limit),
+      { max: EVIDENCE_SEARCH_MAX_CANDIDATES },
+    );
+    const postingBudget = integer(
+      args.posting_budget,
+      EVIDENCE_SEARCH_DEFAULT_POSTING_BUDGET,
+      { max: EVIDENCE_SEARCH_MAX_POSTING_BUDGET },
+    );
+    const normalizedFilters = filters(args.filters);
+    const candidates = searchEvidenceCandidates(vaultBase, query, {
+      candidateLimit,
+      postingBudget,
+      filters: normalizedFilters,
+      backend: backend(args.backend),
+      sqlite: 'auto',
+    });
+    const page = recallEvidencePage(candidates.rows, query, {
+      cursor: args.cursor || null,
+      filters: normalizedFilters,
+      limit,
+      maxBytes,
+    });
+    return {
+      schema_version: 1,
+      ...page,
+      results: page.results.map(logicalReference),
+      candidates: {
+        backend: candidates.backend,
+        count: candidates.candidate_count,
+        posting_entries: candidates.posting_entries,
+        has_more: candidates.has_more,
+        rebuilt: candidates.rebuilt,
+        fallback_reason: candidates.fallback_reason || '',
+      },
+      complete_candidate_set: candidates.has_more !== true,
+    };
+  } catch (error) {
+    throw mappedError(error);
+  }
+}

package/packages/mcp/src/executor.mjs

@@ -23,6 +23,7 @@ import {
 } from '../../vault/src/memory-store.mjs';
 import { scopeForMemoryKey } from '../../vault/src/memory-scope.mjs';
 import { sanitizeMemoryText } from '../../vault/src/memory-schema.mjs';
+import { recallEvidenceForMcp } from './evidence-recall.mjs';
 
 const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '../../..');
 const BIN = join(ROOT, 'bin', 'wendkeep.mjs');
@@ -305,6 +306,9 @@ export async function executeNativeMcpTool(tool, args, { signal } = {}) {
       topK: Math.min(Number(args.limit || 10), 100),
     }));
   }
+  if (tool.name === 'wendkeep_evidence_recall') {
+    return sanitize(recallEvidenceForMcp(ctx.vaultBase, args));
+  }
   if (tool.name === 'wendkeep_memory_conflicts') {
     return sanitize(listMemoryCandidates(ctx.vaultBase, { activeOnly: true }).candidates);
   }

package/packages/mcp/src/server.mjs

@@ -3,6 +3,9 @@ import { MCP_EFFECT_MANIFEST, resolveMcpToolEffect } from './effects.mjs';
 const DEFAULT_PAGE_SIZE = 50;
 const MAX_PAGE_SIZE = 100;
 const DEFAULT_TIMEOUT_MS = 10_000;
+const MAX_EVIDENCE_BYTES = 512 * 1024;
+const MAX_EVIDENCE_CANDIDATES = 4096;
+const MAX_EVIDENCE_POSTINGS = 1_048_576;
 
 function boundedInteger(value, fallback, maximum = MAX_PAGE_SIZE) {
   const parsed = Number.parseInt(value, 10);
@@ -42,6 +45,7 @@ function availability(tool, nodeVersion) {
 
 const TOOL_REQUIRED_ARGUMENTS = Object.freeze({
   wendkeep_context_status: ['session_id'],
+  wendkeep_evidence_recall: ['query'],
   wendkeep_change_show: ['change'],
   wendkeep_change_status: ['change'],
   wendkeep_task_show: ['session_id', 'task'],
@@ -55,6 +59,13 @@ const TOOL_REQUIRED_ARGUMENTS = Object.freeze({
   wendkeep_handoff_publish: ['payload'],
 });
 
+const stringOrStringList = {
+  oneOf: [
+    { type: 'string' },
+    { type: 'array', items: { type: 'string' }, uniqueItems: true },
+  ],
+};
+
 function inputSchema(tool) {
   const required = ['project_root'];
   required.push(...(TOOL_REQUIRED_ARGUMENTS[tool.name] || []));
@@ -87,6 +98,25 @@ function inputSchema(tool) {
       query: { type: 'string' },
       cursor: { type: 'string' },
       limit: { type: 'integer', minimum: 1, maximum: MAX_PAGE_SIZE },
+      max_bytes: { type: 'integer', minimum: 2, maximum: MAX_EVIDENCE_BYTES },
+      candidate_limit: { type: 'integer', minimum: 1, maximum: MAX_EVIDENCE_CANDIDATES },
+      posting_budget: { type: 'integer', minimum: 1, maximum: MAX_EVIDENCE_POSTINGS },
+      backend: { type: 'string', enum: ['auto', 'sqlite', 'lexical'] },
+      filters: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          authority: stringOrStringList,
+          validity: stringOrStringList,
+          entity_type: stringOrStringList,
+          project_id: stringOrStringList,
+          change_slug: stringOrStringList,
+          session_id: stringOrStringList,
+          work_session_id: stringOrStringList,
+          logical_path: stringOrStringList,
+          logical_path_prefix: stringOrStringList,
+        },
+      },
       payload: { type: 'object' },
     },
   };
@@ -339,4 +369,4 @@ export function createNativeMcpServer({
   };
 }
 
-export { supportsObserverSql };
+export { supportsObserverSql };