convez.ai
MCP ServerIntegração & APIsIntermediário
Neboy72

Nexus Memory

Neboy72/nexus-memory

Memória compartilhada e persistente para agentes MCP

Ver no GitHub
BomPluginScore · de 0 a 100

Camada universal de memória persistente para agentes de IA compatíveis com MCP. Permite que múltiplos agentes (Claude, Cursor, Cline, etc.) compartilhem um contexto centralizado auto-hospedado, evitando perda de informações entre sessões. Inclui interface web com visualização em grafo das memórias armazenadas.

Instalação

$npx convez-ai Neboy72/nexus-memory

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
3
Forks
1
Acompanhando
0
Saúde
100%
Último commit
há 1 dia
Versão
v0.22.58
Issues abertas
1
Contribuidores
1

Casos de uso

  • Manter contexto consistente entre múltiplos agentes de IA
  • Armazenar conhecimento de projetos e configurações de forma centralizada
  • Recuperar informações históricas automaticamente em novos ciclos de chat

Veredito

Solução técnica sólida para o problema real de amnésia em agentes MCP. A arquitetura com Qdrant e embeddings plugáveis é bem executada, embora o ecossistema MCP ainda seja emergente e a adoção dependa do crescimento de agentes compatíveis.

README

A tradução para o português deste README ainda está na fila.

Your agents forget. Your context gets lost. Your setup knowledge is scattered across chats, tools and repos.

Nexus Memory gives every MCP-compatible agent one persistent, self-hosted memory they all share.

Hermes • OpenClaw • Claude Code • Codex • Cursor • Cline • Roo Code • GitHub Copilot • Pi • Continue • Odysseus • Kilo Code …and more!

Stars License Python 3.11+ Qdrant Version Tests MCP

🤖 Bot Self-Install: Tell your agent: "Read AGENTS.md and install Nexus Memory." It does the rest.

👉 Bot Self-Install

👉 Star this repo     Ko-fi


Architecture


🤖 Quick Start

Tell your agent to install it

Send this prompt to any MCP-compatible agent:

Read https://raw.githubusercontent.com/Neboy72/nexus-memory/main/AGENTS.md and follow the installation instructions.

Your agent will check prerequisites, install everything, configure the provider, and verify. Zero manual steps.

🛠️ Or install manually

git clone https://github.com/Neboy72/nexus-memory.git
cd nexus-memory
pip install -e .

Choose your embedding (auto-detected at runtime, you pick):

  • 💚 Google / Vertex AI — GOOGLE_API_KEY in .env (768d)
  • 💜 Jina — JINA_API_KEY in .env (1024d)
  • 🦙 Ollama — ollama pull nomic-embed-text
  • ☁️ Voyage — VOYAGE_API_KEY in NEXUS_ENV_FILE or MCP env:-block (1024d)
  • ☁️ OpenAI — OPENAI_API_KEY in NEXUS_ENV_FILE or MCP env:-block (1536d)
  • 🏠 Local (default) — pip install nexus-memory[local] (sentence-transformers, no key)

Start the server:

nexus-memory

🌐 Web UI (optional)

Nexus Memory comes with a live graph visualization — your memories as an interactive force-directed graph.

pip install nexus-memory[webui]
nexus-memory webui

Opens a dashboard at http://127.0.0.1:9120 — filter by category, search, click nodes to inspect details, and see drift status at a glance.

🔌 Platform Configuration

Choose your agent:

~/.hermes/config.yaml:

mcp_servers:
  nexus:
    command: nexus-memory

Restart: hermes gateway restart

~/.openclaw/openclaw.json (mcp.servers.<name>.env — nested, not top-level):

{
  "mcp": {
    "servers": {
      "nexus-memory": {
        "command": "nexus-memory",
        "env": { "VOYAGE_API_KEY": "vo-your-key-here" }
      }
    }
  }
}

~/.claude/settings.json or .mcp.json in project root:

{
  "mcpServers": {
    "nexus": {
      "command": "python3",
      "args": ["-m", "nexus_memory.mcp_server"]
    }
  }
}

~/.codex/config.toml:

[mcp_servers.nexus]
command = "python3"
args = ["-m", "nexus_memory.mcp_server"]

.vscode/mcp.json in your project:

{
  "mcpServers": {
    "nexus": {
      "command": "python3",
      "args": ["-m", "nexus_memory.mcp_server"]
    }
  }
}

Settings → Features → MCP Servers → Add:

  • Name: nexus
  • Command: python3
  • Arguments: -m nexus_memory.mcp_server

MCP Server Config:

{
  "mcpServers": {
    "nexus": {
      "command": "python3",
      "args": ["-m", "nexus_memory.mcp_server"]
    }
  }
}

.mcp.json in your project:

{
  "mcpServers": {
    "nexus": {
      "command": "python3",
      "args": ["-m", "nexus_memory.mcp_server"]
    }
  }
}

~/.pi/config.json:

{
  "mcpServers": {
    "nexus": {
      "command": "python3",
      "args": ["-m", "nexus_memory.mcp_server"]
    }
  }
}

.mcp.json or ~/.continue/config.json:

{
  "mcpServers": {
    "nexus": {
      "command": "python3",
      "args": ["-m", "nexus_memory.mcp_server"]
    }
  }
}

Settings → MCP Management → Add Server:

  • Name: nexus
  • Command: python3
  • Arguments: -m nexus_memory.mcp_server

Standard MCP stdio config:

{
  "mcpServers": {
    "nexus": {
      "command": "python3",
      "args": ["-m", "nexus_memory.mcp_server"]
    }
  }
}

🎯 MCP Tools

ToolDescriptionParameters
remember 💾Store a memorytext (req), category (req, default fact), access_level, source, source_url, confidence
recall 🔍Hybrid search (BM25 + Vector + RRF)query (req), limit, filter_level
forget 🗑️Delete a memorymemory_id (req)
update ✏️Update in-place, preserve metadatamemory_id (req), text, modified_by
subscribe 🔔Register a webhook for memory eventsevent_type (req), webhook_url (req)
unsubscribe 🔕Remove a webhook subscriptionsubscription_id (req)
list_subscriptions 📋List all active webhooks—
health ❤️Check server status—
check_update 🔄Check for newer version on GitHub—
do_update ⬆️Pull + install + restart serverconfirm (req, must be true)

Memory Categories (State-Prefixing)

category is a required parameter on remember. The server applies "fact" as a backward-compatible default if a client omits it or sends an unknown value.

CategoryScopeUse Case
fact ✅PermanentVerified facts, decisions (default)
belief 🤔Drift-proneAssumptions that may change over time
session 🔄EphemeralCurrent conversation context
rule 📏PermanentOperating rules, policies
preference ❤️PermanentUser likes, dislikes, habits
temp ⏳TemporaryShort-lived notes, TTL-managed

Access Levels 🛡️

LevelVisible toExample
🟢 publicAll agentsProject knowledge, technical info
🟡 trustedApproved agents onlyPersonal preferences, habits
🔴 privateOwner onlyFinancial data, passwords, bills

✨ Features

Hybrid Retrieval 🛡️

Pure vector search is vulnerable to RAG poisoning — adversarial documents that rank high semantically but contain garbage. Nexus Memory blends BM25 + Vector + Reciprocal Rank Fusion:

Query → ┌─ BM25 Index ──────→ Keyword Rankings
         │                          │
         └─ Vector Embeddings ──→ Semantic Rankings
                                        │
                               RRF Fusion ───→ Combined Rankings
MethodStrengthsWeaknesses
BM25 🔤Keyword-exact, poison-resistantMisses semantics
Vector 🧠Semantic matching, fuzzy queriesVulnerable to poisoning
Hybrid (RRF) 🏆Best of both—

Source-Tier Boosting 🏷️

TierSourcesBoost
🟢 Tier 1Agent, user, official docs1.2×
🟡 Tier 2Curated external1.0×
🔴 Tier 3Uncurated / unknown0.8×

MemoryCategory Enum 🏷️

Six scopes from Agentic Design Patterns (Ch8): fact, belief, session, rule, preference, temp. Every memory knows its purpose.

Provenance Tracking 📎

Every memory carries its origin: source_url, confidence (0.0–1.0), modified_by, timestamps. Full audit trail from creation to today.

Guardrails 🛡️

Content-length warnings for entries >5,000 chars. PII detection hints for emails and phone numbers in non-private entries.

Fact Lifecycle Model 🧬

Append-only state machine: pending → canonical | deprecated | rolled_back. Every revision is versioned with fact_id, version_id, content_hash, supersedes, and mandatory decision_event. No silent overwrites. No zombie facts.

Staging + Rollback 🔄

OperationWhat it does
create_pending()Stage new facts for review
promote()Promote staged → canonical
deprecate()Mark canonical as deprecated
rollback()Restore previous canonical version

Auto-Discovery + Graph Analytics 🔄

Zero-token relation discovery between canonical facts via Qdrant (O(n·k)) + heuristic classification. Graph analytics: hub scores, isolation scores, knowledge gaps, connected components. Facts connect themselves — no manual edges needed.

Skill Export 🎯

export_skill() searches canonical facts → clusters into Steps/Pitfalls/Prerequisites/Verification → generates complete SKILL.md. Turn learned facts into reusable agent skills.

Belief Drift Detection 🔍

ScoreStatus
🟢 < 1Healthy
🟡 1–3Attention needed
🔴 > 3Action required

Detects stale entries, old patterns ("X running as fallback" — but X was replaced), age thresholds. Weighted 0–10 scoring.


📊 vs Other Memory Solutions

FeatureNexus Memory 🦊Walrus Memory 🦭mem0HonchoagentmemoryHolographic
🔍 Semantic search✅ local or cloud✅ via API✅ Cloud✅ pgvector✅ Gemini✅ HRR algebra
🔀 Hybrid retrieval✅ BM25 + Vector + RRF❌✅ Multi-signal❌❌❌
🩺 Drift detection✅ Scored 0–10❌❌ *❌❌❌
🛡️ Anti-poisoning✅ Source tiers❌❌❌❌❌
🔗 Multi-Level Provenance✅ Source + Corroboration + Dep.✅ On-chain❌❌❌❌
🏷️ MemoryCategory Enum✅ 6 scopes❌❌❌❌❌
🧬 Fact Lifecycle✅ Append-only❌❌❌❌❌
🔄 Staging + Rollback✅ Promote/Deprecate/Rollback❌❌❌❌❌
🎯 Skill Export✅ Facts → SKILL.md❌❌❌❌❌
🔗 SkillGraph✅ 5 relation types, BFS/DFS❌❌❌❌❌
🔄 Auto-Discovery✅ 0 token cost❌❌❌❌❌
📊 Graph Analytics✅ Hub scores, gaps❌❌❌❌❌
🚀 Graph Boost✅ Search ranking boost❌❌❌❌❌
🛡️ Access Control✅ public/trusted/private✅ Permissions❌❌❌❌
🏠 Self-hosted✅ Your machine❌ Blockchain❌ Cloud❌ Cloud❌ Cloud✅ Local
💰 Cost🆓 FreeWAL tokenSubscriptionSubscriptionAPI costsFree
📦 Code size~9.6K PythonManaged serviceManaged serviceManaged service~50K TS~1.5K Python
⏱️ Setup time1 commandSignup + SDKAPI key + signupPostgres + pgvector30+ min + OAuth1 command

*Mem0 lists staleness as an "open problem" in their 2026 report but does not ship a solution.

Nexus Memory is the only solution with hybrid retrieval, drift detection, provenance, fact lifecycle, staging/rollback, auto-discovery, graph analytics, skill export, memory categories, and access control — all self-hosted, all in one package.


🧩 Embedding Providers

One server. Multiple backends. Same API.

ProviderTypeSetupDims
Voyage ☁️CloudVOYAGE_API_KEY in MCP env: block1024
OpenAI ☁️CloudOPENAI_API_KEY in MCP env: block1536
Google / Vertex AI 💚CloudGOOGLE_API_KEY in .env768
Jina 💜CloudJINA_API_KEY in .env1024
Ollama 🦙Localollama pull nomic-embed-text768
sentence-transformers 🏠Localpip install sentence-transformers384

🔧 Troubleshooting

SymptomCheckFix
mcp_nexus_* tools missinggrep 'nexus' ~/.hermes/logs/agent.logGateway restart
Qdrant not runningcurl http://127.0.0.1:6333/healthzbrew services start qdrant
Hybrid search missingpip list | grep bm25spip install bm25s
Voyage embedding failsecho $VOYAGE_API_KEYSet in ~/.hermes/.env
ModuleNotFoundErrorCheck PYTHONPATHSet PYTHONPATH=/path/to/nexus-memory

🧪 Tests

pytest tests/ -v   # 379 tests ✅

📋 Requirements

  • Python 3.11+
  • Qdrant v1.12+ running on localhost:6333
  • One embedding provider (auto-detected):
    • 💚 Google / Vertex AI — GOOGLE_API_KEY in .env (768d)
    • 💜 Jina — JINA_API_KEY in .env (1024d)
    • 🦙 Ollama — ollama pull nomic-embed-text
    • ☁️ Voyage — VOYAGE_API_KEY in .env (1024d)
    • ☁️ OpenAI — OPENAI_API_KEY in .env (1536d)
    • 🏠 Local — pip install sentence-transformers

📜 License

MIT — use it, modify it, ship it.


⭐️ Found it useful? Give it a star on GitHub — it helps others find it!

Built by Nebo · June 2026 · v0.2.5 — One memory for all your agents

Ver o original no GitHub

Bom para

Relacionados