NEXUS AIHub Memória Persistente

Hub de memória persistente compartilhada para modelos e agentes de IA. O plugin resolve o problema de falta de memória entre sessões, permitindo que qualquer agente (Claude, Antigravity, GPT, Gemini, Cursor, Kiro, Ollama) grave, consulte, atualize e ranqueie memórias por similaridade semântica de cosseno — com fallback nativo sem dependências externas.

Resumo técnico

O NEXUS AIHub Memória Persistente é o plugin is_core que fornece um repositório vetorial de memória de longo prazo para o ecossistema de IA do NEXUS: motor dual de embeddings (OpenAI API ou N-Gram TF-IDF nativo 128D), busca híbrida com desambiguação por entidades, 21 actions de API, 4 slash commands, auto-capture via hooks, resumo via IA Central com 3 níveis de fallback e 2 tabelas MySQL — com UI completa em 4 abas (busca, criação, estatísticas e configurações).

Escopo executado

• plugin.json: v1.0.0, slug nexus-aihub-memory (sem legacy_slugs), name "NEXUS AIHub Memória Persistente", categoria "ai", is_core: true, author "Percio Andrade".
• Backend (backend.php, 976 linhas, strict_types) — 2 tabelas criadas por aihub_memory_install() (lazy, try/catch): nx_ai_memories (id, workspace_id, memory_key VARCHAR(100), category, source_agent, title, content LONGTEXT, embedding_json LONGTEXT, tags, relevance_score FLOAT, access_count, timestamps; INDEX em workspace_id+category, workspace_id+memory_key) e nx_ai_memory_prompts (task_id, status pending/completed/dismissed, char_count).
• Motor de Embeddings (aihub_memory_compute_embedding) — dual caminho: OpenAI API (text-embedding-3-small/large/ada-002, truncado em 4000 chars, timeout 8s) OU fallback nativo N-Gram TF-IDF de 128 dimensões com CRC32 — zero dependências externas, sem API Key.
• Similaridade de Cosseno (aihub_memory_cosine_similarity) — produto escalar / (normA × normB), vetores float normalizados.
• Busca híbrida (aihub_memory_search) — score composto: base 0.5 + cosseno × 0.5 + bonus de match título (+0.3) / conteúdo (+0.2) / tags (+0.2); desambiguação por entidades: extract_entities extrai tokens >2 chars filtrando stop words PT/EN, com boost +0.2 por entidade coincidente e penalidade -0.45 por entidade alvo conflitante — previne falsos positivos entre sistemas distintos.
• Auto-capture (plugin.php hooks) — task_created → grava memória task_<id> se auto_capture_tasks ativo; comment_created → 3 passos: (1) proactive_response_check (detecta respostas 1=sim/2=não a prompts proativos), (2) auto-capture de comentários de agentes IA (>20 chars, filtra admin/percio/user/system_event/aihub-memory), (3) proactive_check (se >1500 chars E >7 comments, insere prompt nx_ai_memory_prompts e pergunta no chat).
• Resumo via IA (aihub_memory_summarize_with_ai) — prompt que solicita JSON estruturado (title, category, summary, tags); 3 níveis de fallback: OpenAI API (gpt-4o-mini, 0.2 temp, 1000 tokens) → fastr_call_opencode → localhost:8081 (Ollama compatível).
• Slash commands — /memory-search <termo> (busca vetorial + texto), /memory-save [notas] (analisa contexto da tarefa, impede duplicatas por memory_key), /memory-get <assunto> (lista IDs + títulos), /memory-update <ID> (re-sintetiza com novos comentários).
• Utilidades — enrich_intel (enriquecedor Intel Hub com badge de similaridade), context_prompt (injeta memórias no contexto de prompts), export_json/import_json (backup completo), deduplicate (remove duplicatas com cosseno ≥ 0.92), task_status (verifica se tarefa já tem memória).
• Config (aihub_memory_settings_get/save) — api_key, embedding_model, auto_capture_tasks/comments/plugins, default_agent, similarity_threshold (0.1–0.9), proactive_enabled, proactive_min_chars (≥200), proactive_min_comments (≥2), proactive_persona_name, auto_capture_min_len (≥5).
• UI (tab.php, 843 linhas, tema indigo/slate, ícone brain, grupo "IA") — 4 abas:

- Hub de Memórias — busca instantânea por similaridade vetorial + keyword, filtros por categoria e agente, cards responsivos com contagem de acessos, modal full-screen max-w-4xl com renderização Markdown (marked.js) e CSS de alto contraste. - Gravar Memória — formulário com datalist para categorias/agentes personalizados, gravação com embedding automático. - Estatísticas — 4 KPI cards (total memórias, acessos, categorias ativas, agentes registrados) + tabela Top 10 mais consultadas com badges de categoria. - Configurações — campos de threshold, limites proativos, persona, modelo de embedding, toggle de auto-capture.

• Dependência AI-Hub — banner de aviso quando nexus-ai-hub/oci-manager não está ativo; fallback para sintetização heurística.

Stack e ferramentas

• PHP 8 (sem framework, strict_types)
• MySQL 8 (2 tabelas: nx_ai_memories, nx_ai_memory_prompts)
• OpenAI API (embeddings + gpt-4o-mini) com fallback TF-IDF nativo 128D
• Alpine.js + Tailwind CSS (indigo/slate, marked.js)
• REST API (api.php?action=...) com Bearer + CSRF
• Plugin NEXUS (PluginManager: tab, doc, API actions, Fastr, Intel Hub enricher, hooks)

Módulos

• Motor de Embeddings — dual: OpenAI API (3 modelos) ou N-Gram TF-IDF nativo 128D com CRC32 — sem dependências externas quando sem chave.
• Busca híbrida — cosseno + texto/tags + desambiguação por entidades com boost e penalidade.
• Auto-capture — hooks task_created/comment_created que registram decisões automaticamente.
• Proactive Memory — detecta volume alto de discussão e sugere salvar via chat (resposta 1=sim, 2=não).
• AI Synthesis — resumo via IA Central com 3 níveis de fallback (OpenAI → opencode → Ollama local).

Presença (nx_ai_memories)

aihub_memory_save faz INSERT/UPDATE com workspace isolation (workspace_current_id()). O embedding é computado em title + content + tags e armazenado como JSON no campo embedding_json.

| Campo | Tipo | Descrição | |---|---|---| | memory_key | VARCHAR(100) | Chave única por workspace (ex: task_<id>, mem_<hash>) | | category | VARCHAR(50) | fact, decision, preference, context, code_pattern, task_log | | source_agent | VARCHAR(50) | Agente autor (antigravity, claude, gpt, etc.) | | relevance_score | FLOAT | Multiplicador de relevância (0.1–5.0, default 1.0) | | access_count | INT | Contador de acessos (incrementado por get_by_id) |

Desambiguação por Entidades

O motor extract_entities filtra stop words PT/EN e extrai tokens significativos (>2 chars). Na busca:

• Boost (+0.2 × n entidades coincidentes) para registros com entidades em comum com a query.
• Penalidade (-0.45) quando a query especifica uma entidade-alvo explícita que não existe no registro — evita falsos positivos entre sistemas distintos (ex: "MCP do sistema X" vs "MCP do NEXUS").

Interface (tab.php)

Alpine.js com 4 abas (indigo/slate): Hub de Memórias (busca vetorial + keyword, filtros, cards, modal Markdown full-screen), Gravar Memória (form com datalist), Estatísticas (4 KPIs + tabela Top 10) e Configurações (thresholds, persona, toggles).

Segurança

• Queries 100% parametrizadas (PDO).
• IDs convertidos com (int) antes de consultas.
• Workspace isolation em todas as operações (workspace_current_id()).
• Embeddings truncados em 4000 chars na chamada OpenAI.
• Fallback heurístico seguro quando APIs indisponíveis.

Arquitetura

nexus-aihub-memory/
├── backend.php          # 976 linhas: install, embeddings, busca, AI synthesis, hooks
├── plugin.php           # 142 linhas: tab, doc, 21 API actions, 2 hooks, Intel enricher
├── tab.php              # 843 linhas: UI Alpine.js 4 abas (indigo/slate)
├── doc.md               # Documentação do autor
├── fastr.json           # 4 comandos: /memory-search, /memory-save, /memory-get, /memory-update
├── icon.svg             # Ícone brain
├── plugin.json          # Metadados (v1.0.0, ai, is_core true)
├── README.md            # Documentação do autor (inglês)
└── README.pt-BR.md      # Documentação do autor (português)

Tabelas usadas: nx_ai_memories, nx_ai_memory_prompts. Dependência: nexus-ai-hub (para IA Central; fallback heurístico se ausente).