NEXUS AIHub Persistent Memory

Shared persistent memory hub for AI models and agents. The plugin solves the lack of memory between sessions, allowing any agent (Claude, Antigravity, GPT, Gemini, Cursor, Kiro, Ollama) to store, query, update and rank memories by cosine semantic similarity — with a zero-dependency native fallback.

Technical summary

NEXUS AIHub Persistent Memory is the is_core plugin that provides a long-term vector memory repository for the NEXUS AI ecosystem: dual embedding engine (OpenAI API or native N-Gram TF-IDF 128D), hybrid search with entity disambiguation, 21 API actions, 4 slash commands, auto-capture via hooks, Central AI summarization with 3 fallback levels and 2 MySQL tables — with a complete 4-tab UI (search, creation, statistics and settings).

Executed scope

• plugin.json: v1.0.0, slug nexus-aihub-memory (no legacy_slugs), name "NEXUS AIHub Memória Persistente", category "ai", is_core: true, author "Percio Andrade".
• Backend (backend.php, 976 lines, strict_types) — 2 tables via 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 on workspace_id+category, workspace_id+memory_key) and nx_ai_memory_prompts (task_id, status pending/completed/dismissed, char_count).
• Embedding engine (aihub_memory_compute_embedding) — dual path: OpenAI API (text-embedding-3-small/large/ada-002, 4000-char truncation, 8s timeout) or native N-Gram TF-IDF 128-dimension fallback with CRC32 — zero external dependencies, no API key needed.
• Cosine similarity (aihub_memory_cosine_similarity) — dot product / (normA × normB), normalized float vectors.
• Hybrid search (aihub_memory_search) — composite score: base 0.5 + cosine × 0.5 + title match (+0.3) / content (+0.2) / tags (+0.2) bonus; entity disambiguation: extract_entities extracts tokens >2 chars filtering PT/EN stop words, with +0.2 per matching entity and -0.45 conflict penalty when a target entity is explicitly specified but absent — prevents false positives between distinct systems.
• Auto-capture (plugin.php hooks) — task_created → stores task_<id> memory if auto_capture_tasks enabled; comment_created → 3 steps: (1) proactive_response_check (detects 1=yes/2=no responses to proactive prompts), (2) auto-capture of AI agent comments (>20 chars, filtering admin/percio/user/system_event/aihub-memory), (3) proactive_check (if >1500 chars AND >7 comments, inserts nx_ai_memory_prompts record and asks in chat).
• AI summarization (aihub_memory_summarize_with_ai) — prompt requesting structured JSON (title, category, summary, tags); 3-level fallback: OpenAI API (gpt-4o-mini, 0.2 temp, 1000 tokens) → fastr_call_opencode → localhost:8081 (Ollama-compatible).
• Slash commands — /memory-search <term> (vector + text search), /memory-save [notes] (analyzes task context, prevents duplicates via memory_key), /memory-get <subject> (lists IDs + titles), /memory-update <ID> (re-synthesizes with new comments).
• Utilities — enrich_intel (Intel Hub enricher with similarity badge), context_prompt (injects memories into prompt context), export_json/import_json (full backup), deduplicate (removes duplicates with cosine ≥ 0.92), task_status (checks if a task already has a memory entry).
• 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 lines, indigo/slate theme, brain icon, "IA" group) — 4 tabs:

- Memory Hub — instant vector + keyword search, category and agent filters, responsive cards with access counts, full-screen max-w-4xl modal with Markdown rendering (marked.js) and high-contrast CSS. - Save Memory — form with datalist for custom categories/agents, auto-embedding on save. - Statistics — 4 KPI cards (total memories, accesses, active categories, registered agents) + Top 10 most queried table with category badges. - Settings — threshold fields, proactive limits, persona, embedding model, auto-capture toggles.

• AI-Hub dependency — warning banner when nexus-ai-hub/oci-manager is inactive; graceful fallback to heuristic synthesis.

Stack and tools

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

Modules

• Embedding engine — dual: OpenAI API (3 models) or native N-Gram TF-IDF 128D with CRC32 — zero external dependencies without a key.
• Hybrid search — cosine + text/tags + entity disambiguation with boost and conflict penalty.
• Auto-capture — task_created/comment_created hooks that record decisions automatically.
• Proactive Memory — detects high discussion volume and suggests saving via chat (1=yes, 2=no response).
• AI Synthesis — Central AI summarization with 3-level fallback (OpenAI → opencode → local Ollama).

Presence (nx_ai_memories)

aihub_memory_save does INSERT/UPDATE with workspace isolation (workspace_current_id()). The embedding is computed on title + content + tags and stored as JSON in the embedding_json field.

| Field | Type | Description | |---|---|---| | memory_key | VARCHAR(100) | Unique key per workspace (e.g. task_<id>, mem_<hash>) | | category | VARCHAR(50) | fact, decision, preference, context, code_pattern, task_log | | source_agent | VARCHAR(50) | Authoring agent (antigravity, claude, gpt, etc.) | | relevance_score | FLOAT | Relevance multiplier (0.1–5.0, default 1.0) | | access_count | INT | Access counter (incremented by get_by_id) |

Entity Disambiguation

The extract_entities engine filters PT/EN stop words and extracts significant tokens (>2 chars). During search:

• Boost (+0.2 × matching entities) for records with entities in common with the query.
• Penalty (-0.45) when the query specifies an explicit target entity absent from the record — prevents false positives between distinct systems (e.g. "MCP of system X" vs "MCP of NEXUS").

Interface (tab.php)

Alpine.js with 4 tabs (indigo/slate): Memory Hub (vector + keyword search, filters, cards, full-screen Markdown modal), Save Memory (form with datalist), Statistics (4 KPIs + Top 10 table) and Settings (thresholds, persona, toggles).

Security

• 100% parameterized queries (PDO).
• IDs cast to (int) before queries.
• Workspace isolation on all operations (workspace_current_id()).
• Embeddings truncated to 4000 chars on OpenAI calls.
• Safe heuristic fallback when APIs are unavailable.

Architecture

nexus-aihub-memory/
├── backend.php          # 976 lines: install, embeddings, search, AI synthesis, hooks
├── plugin.php           # 142 lines: tab, doc, 21 API actions, 2 hooks, Intel enricher
├── tab.php              # 843 lines: Alpine.js UI 4 tabs (indigo/slate)
├── doc.md               # Author documentation
├── fastr.json           # 4 commands: /memory-search, /memory-save, /memory-get, /memory-update
├── icon.svg             # brain icon
├── plugin.json          # metadata (v1.0.0, ai, is_core true)
├── README.md            # Author documentation (English)
└── README.pt-BR.md      # Author documentation (Portuguese)

Tables used: nx_ai_memories, nx_ai_memory_prompts. Dependency: nexus-ai-hub (for Central AI; heuristic fallback if absent).