ObsidianRAG SuperAgent

Sistema local de RAG para amplificação de agentes de IA via MCP + Obsidian. 100% local · 100% gratuito · máximo desempenho · segurança zero-trust.

---

Pré-requisitos

Dependência	Versão mínima	Instalação
Node.js LTS	20.x	https://nodejs.org
Ollama	latest	https://ollama.com
Obsidian	latest	https://obsidian.md
Plugin: Local REST API	latest	ver seção abaixo

---

Setup Inicial

1. Clonar e instalar dependências

git clone https://github.com/seu-usuario/obsidianrag-superagent
cd obsidianrag-superagent
npm install
npm run build

2. Instalar o modelo de embedding

ollama pull nomic-embed-text

Verifique:

ollama run nomic-embed-text "teste"

3. Configurar o Obsidian

3a. Instalar o plugin Local REST API

1. Abra o Obsidian → Settings → Community plugins → Browse
2. Pesquise Local REST API e instale
3. Ative o plugin
4. Em Settings → Local REST API:
   • Anote a API Key gerada
   • Confirme que está rodando na porta 27123

3b. Criar os vaults

Copie os scaffolds incluídos no repositório:

# Vault Global
cp -r vault-templates/global ~/obsidian/global-vault

# Vault do seu projeto (repita para cada projeto)
cp -r vault-templates/project ~/obsidian/meu-projeto-vault

Abra cada vault no Obsidian: File → Open vault → selecione a pasta.

4. Criar a configuração

mkdir -p ~/.obsidianrag
cp .obsidianrag.config.example.yaml ~/.obsidianrag/config.yaml

Edite ~/.obsidianrag/config.yaml e ajuste:

• vaults.global.path → caminho absoluto do seu vault global
• vaults.projects[].path → caminho absoluto do vault de cada projeto
• O id do projeto (vaults.projects[].id) será usado para identificar o vault nas tool calls do MCP

5. Indexar os vaults

# Indexar o vault global
npx obsidianrag index global

# Indexar o vault de um projeto
npx obsidianrag index meu-projeto

# Verificar status
npx obsidianrag status

6. Gerar o token de sessão MCP

npx obsidianrag start --generate-token
# → Token salvo em ~/.obsidianrag/session.token
# → Guarde este token; será usado na configuração do agente.

---

Configurando o MCP no agente

opencode

Adicione ao arquivo de configuração do opencode (~/.config/opencode/config.json ou equivalente):

{
  "mcpServers": {
    "obsidianrag": {
      "command": "node",
      "args": ["/caminho/para/obsidianrag-superagent/dist/src/interface/mcp/McpServer.js"],
      "env": {
        "OBSIDIANRAG_TOKEN": "SEU_TOKEN_AQUI",
        "OBSIDIANRAG_CONFIG": "/Users/seu-usuario/.obsidianrag/config.yaml"
      }
    }
  }
}

Claude Code

Adicione ao .claude/settings.json na raiz do projeto:

{
  "mcpServers": {
    "obsidianrag": {
      "command": "node",
      "args": ["/caminho/para/obsidianrag-superagent/dist/src/interface/mcp/McpServer.js"],
      "env": {
        "OBSIDIANRAG_TOKEN": "SEU_TOKEN_AQUI",
        "OBSIDIANRAG_CONFIG": "/Users/seu-usuario/.obsidianrag/config.yaml"
      }
    }
  }
}

Cursor / Windsurf

Adicione ao painel MCP Servers das configurações:

• Command: node /caminho/para/obsidianrag-superagent/dist/src/interface/mcp/McpServer.js
• Environment variables:
  • OBSIDIANRAG_TOKEN = seu token
  • OBSIDIANRAG_CONFIG = /Users/seu-usuario/.obsidianrag/config.yaml

---

Adicionando um Novo Projeto

1. Crie o vault Obsidian:

   cp -r vault-templates/project ~/obsidian/novo-projeto-vault

2. Abra o vault no Obsidian e configure como descrito no passo 3b.

3. Adicione o projeto à configuração em ~/.obsidianrag/config.yaml:

   projects:
     - id: 'novo-projeto'
       path: '~/obsidian/novo-projeto-vault'
       permissions:
         write: ['opencode']
         read: ['*']

4. Indexe:

   npx obsidianrag index novo-projeto
   npx obsidianrag status

---

CLI — Referência Rápida

# Indexação
npx obsidianrag index <vaultId> [--full | --incremental]

# Busca manual
npx obsidianrag search "query em linguagem natural" --vault global --top-k 5

# Escrever nota manualmente
npx obsidianrag write-note --vault meu-projeto --path "bugs/bug-001.md" --file ./nota.md

# Listagem e status
npx obsidianrag list-vaults
npx obsidianrag status

# Validação de schema
npx obsidianrag validate-schema --file ./minha-nota.md

# Migração de schema
npx obsidianrag migrate-schema --vault global --dry-run

# Dead Letter
npx obsidianrag dead-letter list
npx obsidianrag dead-letter retry --id <itemId>

# Benchmark de qualidade (Fase 4)
npx obsidianrag benchmark

---

Desenvolvimento

# Testes unitários (TDD)
npm test

# Testes com coverage
npm run test:coverage

# BDD (Cucumber)
npm run test:bdd

# Contract tests (Pact)
npm run test:contract

# Property-based tests
npm run test:property

# Mutation testing (demorado — use em release)
npm run test:mutation

# Build
npm run build

# Watch mode
npm run dev

---

Variáveis de Ambiente

Variável	Padrão	Descrição
OBSIDIANRAG_CONFIG	~/.obsidianrag/config.yaml	Caminho da config
OBSIDIANRAG_TOKEN	lido de ~/.obsidianrag/session.token	Token de sessão MCP
OBSIDIANRAG_LOG_LEVEL	info	Nível de log (debug/info/warn/error)

---

Arquitetura

Este projeto segue Clean Architecture + Hexagonal Architecture (Ports & Adapters) + DDD.

Interface (MCP / CLI)
    ↓
Application (casos de uso)
    ↓
Domain (entidades, ports, events) ← zero dependências externas
    ↑
Infrastructure (adapters: SQLite-vec, Ollama, Obsidian API)

Toda seta de dependência aponta para dentro. O Domain não conhece SQLite, Ollama ou MCP.

Para detalhes completos, consulte o PRD em docs/PRD.md.

---

Troubleshooting

Ollama não responde:

ollama serve              # iniciar o servidor
ollama list               # verificar se nomic-embed-text está instalado

Obsidian REST API não conecta:

• Verifique se o plugin está ativo em Settings → Community plugins
• Confirme que a porta 27123 está livre: lsof -i :27123
• Verifique se a API key no config.yaml corresponde à do plugin

Índice desatualizado após editar notas no Obsidian:

npx obsidianrag index <vaultId> --incremental

Nota rejeitada (Dead Letter):

npx obsidianrag dead-letter list
npx obsidianrag validate-schema --file ./minha-nota.md
# corrigir o frontmatter e re-tentar:
npx obsidianrag dead-letter retry --id <itemId>