n8n-nodes-alexandrie-memory

Nodes do n8n para transformar Markdown do Alexandrie em um sistema de memória com indexação e busca híbrida (semântica vetorial + full-text), persistido em PostgreSQL com pgvector. Tudo roda dentro do n8n, sem microserviço externo.

O que é

• Indexa arquivos .md/.mdx locais com parse de frontmatter e headings.
• Gera chunks semânticos por heading respeitando limite aproximado de tokens.
• Cria embeddings via OpenAI (text-embedding-3-small por padrão).
• Persiste em Postgres com pgvector e tsvector, usando índices adequados.
• Busca híbrida combinando similaridade de vetor e ts_rank full-text.

Requisitos

• n8n 2.1.5
• PostgreSQL com extensão pgvector
• Chave de API da OpenAI via ambiente (OPENAI_API_KEY)

Instalação no n8n

1. Copie este pacote para dentro do diretório de nodes customizados do n8n ou instale via npm localmente:
   • npm install /caminho/para/n8n-nodes-alexandrie-memory
2. Execute npm run build dentro do pacote para gerar dist/.
3. Reinicie o n8n para que os nodes apareçam.

Configuração do PostgreSQL + pgvector

Execute o SQL de setup abaixo no seu banco:

CREATE EXTENSION IF NOT EXISTS vector;

CREATE TABLE IF NOT EXISTS alexandrie_memory (
    id UUID PRIMARY KEY,
    namespace TEXT NOT NULL,
    file_path TEXT NOT NULL,
    heading TEXT,
    content TEXT NOT NULL,
    metadata JSONB,
    embedding VECTOR(1536),
    content_tsv TSVECTOR,
    hash TEXT NOT NULL,
    created_at TIMESTAMP DEFAULT NOW()
);

CREATE INDEX IF NOT EXISTS idx_alex_embedding
ON alexandrie_memory
USING ivfflat (embedding vector_cosine_ops);

CREATE INDEX IF NOT EXISTS idx_alex_tsv
ON alexandrie_memory
USING GIN (content_tsv);

CREATE INDEX IF NOT EXISTS idx_alex_namespace
ON alexandrie_memory (namespace);

Variáveis de ambiente

Crie um .env (ou configure no ambiente do n8n):

OPENAI_API_KEY=seu_token_aqui

Credenciais do Postgres no n8n

Crie uma credencial do tipo “Alexandrie Postgres” com:

• Connection String: postgres://usuario:senha@host:porta/database
• SSL: verdadeiro se seu banco requer SSL

Node: AlexandrieIndex

Indexa uma pasta local de Markdown para o Postgres.

Parâmetros:

• Caminho da pasta (folderPath)
• Namespace (namespace)
• Modo de indexação (reindexMode): full ou incremental
• Tamanho de chunk em tokens (chunkTokens) padrão 800 (range 200..2000)
• Modelo de embedding: padrão text-embedding-3-small
• Batch size de embeddings: padrão 50 (máximo 100)
• Exclusões: flags para ignorar node_modules e .git

Comportamento:

• Lê .md/.mdx recursivamente, extrai frontmatter e headings.
• Gera chunks por heading respeitando limite de tokens aproximado.
• Cria hash SHA256 por chunk (file_path + heading + conteúdo normalizado).
• Incremental: consulta hashes existentes por namespace e evita reprocessar.
• Gera embeddings em batches.
• Insere em Postgres em transações com prepared statements.
• Gera content_tsv com to_tsvector('portuguese', content).
• Loga progresso a cada 100 chunks.

Node: AlexandrieSearch

Executa busca híbrida.

Parâmetros:

• Namespace
• Query de texto
• Top K (default 5)
• Peso semântico (semanticWeight) default 0.7 (0..1)
• Filtros opcionais: file_path ou metadata (JSON)

Retorno:

• score
• file_path
• heading
• content (chunk)
• metadata
• created_at

Dicas de performance

• Mantenha batchSize entre 50 e 100 para embeddings.
• Use incremental para grandes coleções; evita reprocessar chunks idênticos.
• Selecione pastas de forma precisa para reduzir I/O.
• Garanta índices criados e ANALYZE após grandes inserções.

Troubleshooting

• “Chave OpenAI ausente”: verifique OPENAI_API_KEY.
• “Erro de conexão Postgres”: valide a connection string e SSL.
• “Extensão vector não habilitada”: execute CREATE EXTENSION IF NOT EXISTS vector;.
• “Busca lenta”: confirme índices ivfflat e GIN e ajuste semanticWeight.