🦊 Nexus Memory

One brain for all your agents.

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!

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

👉

👉

🤖 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, best value)

• 🦙 Ollama — ollama pull nomic-embed-text

• ☁️ Voyage — VOYAGE_API_KEY in NEXUS_ENV_FILE or MCP env:-block (1024d, best quality)

• ☁️ 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

🔌 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

Memory Categories

Access Levels 🛡️

✨ 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

Source-Tier Boosting 🏷️

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 🔄

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 🔍

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

📊 vs Other Memory Solutions

*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.

🔧 Troubleshooting

🧪 Tests

pytest tests/ -v   # 224 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, best value)

• 🦙 Ollama — ollama pull nomic-embed-text

  • ☁️ Voyage — VOYAGE_API_KEY in .env

  • ☁️ OpenAI — OPENAI_API_KEY in .env

  • 🏠 Local — pip install sentence-transformers

• Optional: bm25s for hybrid search

📜 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.0 — One memory for all your agents