obsidian-eval

Transforma vaults Obsidian em runtime de conhecimento programável — scan, grafo, queries, escrita e cross-vault wikilinks. Zero dependência do app Obsidian.

npm install -g @pavani/obsidian-eval

O que faz

obsidian-eval opera sobre qualquer diretório com .obsidian/ (vault Obsidian). Ele varre todos os .md, faz parse de frontmatter YAML, resolve wikilinks ([[...]]), constrói um grafo direcionado em memória e expõe comandos para navegar e validar o grafo.

Funciona como runtime para o ecossistema de vaults do workspace: long-running-agents (77 canonical docs), mhc-knowledge-base (domínio KODA), raw-knowledge (fontes ingeridas) e sisyphus-runtime (vault privado de handoffs e estado).

Comandos

scan

Varre o vault e imprime estatísticas.

obsidian-eval ./long-running-agents scan
# Vault:          /mnt/c/Users/pavan/long-running-agents
# Notes:          386
# Edges:          1240
# Orphans:        23
# Broken Links:   5

obsidian-eval --json ./long-running-agents scan

query

Executa expressões de consulta contra o grafo do vault. A DSL é puramente pattern matching — sem eval(), sem Function().

# Filtrar notas por frontmatter
obsidian-eval ./long-running-agents query "filter(n => n.frontmatter.type === 'canonical')"
obsidian-eval ./long-running-agents query "filter(n => n.frontmatter.tags.includes('evaluation'))"
obsidian-eval ./long-running-agents query "filter(n => n.path.startsWith('docs/'))"

# Filtrar por ausência de campo
obsidian-eval ./long-running-agents query "filter(n => !n.frontmatter.status)"

# Busca por tag ou campo
obsidian-eval ./long-running-agents query "findByTag('architecture')"
obsidian-eval ./long-running-agents query "findByField('maturity', 'N3')"

# Análise de grafo
obsidian-eval ./long-running-agents query "orphans()"
obsidian-eval ./long-running-agents query "brokenLinks()"
obsidian-eval ./long-running-agents query "inbound('docs/canonical/evaluation-rubrics.md')"
obsidian-eval ./long-running-agents query "outbound('docs/canonical/evaluation-rubrics.md')"

# Filtros compostos
obsidian-eval ./long-running-agents query "filter(n => n.frontmatter.type === 'canonical' && n.frontmatter.tags.includes('memory'))"

check

Valida integridade do vault: links quebrados e notas órfãs. Com --checks, sai com código 1 se houver violações (útil para CI).

obsidian-eval ./long-running-agents check --checks

graph-stats

Estatísticas do grafo: nodes, edges, orphans, broken links, grau médio.

obsidian-eval --json ./long-running-agents graph-stats

write

Cria ou sobrescreve uma nota markdown com frontmatter YAML. Cria diretórios intermediários automaticamente.

obsidian-eval ~/sisyphus-runtime write sessions/test.md \
  '{"type":"session-handoff","date":"2026-06-15"}' \
  '# Test Handoff

Conteúdo de teste.'

append-fact

Apensa uma entrada a um arquivo de fatos duráveis, sob uma seção ## <category>. Se o arquivo não existir, cria com frontmatter mínimo. Atualiza last_updated automaticamente.

obsidian-eval ~/sisyphus-runtime append-fact \
  facts/_global/constraints.md constraints \
  '- "Nova constraint" (source: sessão X)'

list-vaults e resolve-vault

Gerencia o registro de vaults conhecidos (nome → path absoluto).

obsidian-eval list-vaults
# long-running-agents → /mnt/c/Users/pavan/long-running-agents
# mhc-knowledge-base  → /mnt/c/Users/pavan/mhc-knowledge-base
# obsidian-eval       → /mnt/c/Users/pavan/obsidian-eval
# raw-knowledge        → /mnt/c/Users/pavan/raw-knowledge
# sisyphus-runtime     → /home/pavanpavan/sisyphus-runtime

obsidian-eval resolve-vault long-running-agents
# /mnt/c/Users/pavan/long-running-agents

Para sobrescrever ou adicionar vaults, use a env var OBSIDIAN_EVAL_VAULTS (JSON):

export OBSIDIAN_EVAL_VAULTS='{"novo-vault":"/path/absoluto"}'

Cross-vault wikilinks

Wikilinks com prefixo vault:<name>/ resolvem contra o vault registry, permitindo referências entre vaults:

# Em uma nota no sisyphus-runtime:
Consulte [[vault:long-running-agents/docs/canonical/evaluation-rubrics]]
Estado anterior: [[vault:sisyphus-runtime/sessions/long-running-agents/2026-06-15-handoff]]

O scan detecta e resolve esses links, e o check reporta links quebrados cross-vault.

API programática

import { scan, query, writeNote, resolveVaultRoot } from "@pavani/obsidian-eval";

const vault = scan("/mnt/c/Users/pavan/long-running-agents");
console.log(vault.notes.size);          // número de notas
console.log(vault.graph.edges.length);  // número de arestas

// Navegação
const backlinks = vault.graph.inbound("docs/canonical/evaluation-rubrics.md");
const broken = vault.graph.brokenLinks();
const orphans = vault.graph.orphans();

// Filtro
const canonicals = vault.graph.filter(
  n => n.frontmatter.type === "canonical"
);
const byTag = vault.graph.findByTag("memory");

// Query DSL
const results = query(vault, "filter(n => n.frontmatter.maturity === 'N3')");

Ecossistema

obsidian-eval é o runtime que unifica os vaults do workspace:

| Vault | Path | Propósito | |---|---|---| | long-running-agents | /mnt/c/Users/pavan/long-running-agents | 77 canonical docs, currículo N1-N4, 8 core concepts | | mhc-knowledge-base | /mnt/c/Users/pavan/mhc-knowledge-base | Domínio KODA, templates, validação | | raw-knowledge | /mnt/c/Users/pavan/raw-knowledge | Fontes ingeridas (papers, talks) | | sisyphus-runtime | ~/sisyphus-runtime | Vault privado: handoffs, fatos, estado | | obsidian-eval | /mnt/c/Users/pavan/obsidian-eval | O próprio repositório (dogfooding) |

Planos ativos em .omo/plans/. Consulte o AGENTS.md do workspace para o mapa completo.

Licença

MIT