Nexus Memory

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

Nexus Memory gives every 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.

👉

👉        

Architecture: Two Paths, One Brain

Nexus Memory offers two integration paths: Native Plugin (auto-memory) and MCP Server (manual tools). Both read/write the same Qdrant collection: same vectors, same metadata, same access levels.

Key insight: A memory stored by Hermes via the native plugin is immediately visible to OpenClaw via its plugin and to Claude Code via MCP, and vice versa. One brain, many agents.

Which path should I use?

Related MCP server: GroundMemory

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

Path 1: Hermes Native Plugin

git clone https://github.com/Neboy72/nexus-memory.git ~/nexus-memory
cd ~/nexus-memory && pip install -e .
./scripts/install_hermes_plugin.sh

Path 2: OpenClaw Native Plugin

git clone https://github.com/Neboy72/nexus-memory.git ~/nexus-memory
cd ~/nexus-memory && pip install -e .
./scripts/install_openclaw_plugin.sh

Path 3: MCP Server (any MCP-compatible agent)

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

🛠️ Embedding Provider (auto-detected)

Pick one: the server auto-detects at runtime:

• 💚 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)

🌐 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

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.

Access Levels 🛡️

✨ Features

Auto-Recall & Auto-Capture 🔄

Native plugins (Hermes & OpenClaw) automatically inject relevant memories before every turn and extract new facts after every turn: zero manual tool calls needed. The MCP server provides the same capabilities via explicit recall / remember tools.

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 🏷️

Seven scopes from Agentic Design Patterns (Ch8): fact, belief, session, rule, preference, procedure, 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. Source URLs are verified via async HTTP HEAD on every recall: verified, unreachable, or unchecked.

Access Levels 🛡️

Three levels: public (all agents), trusted (approved agents), private (owner only). Enforced at the MCP tool level.

Webhooks 🔔

Register HTTP endpoints to receive notifications when memories change. Three event types: memory.remember, memory.update, memory.forget. Fire-and-forget delivery with 5s timeout. Subscriptions persist in ~/.nexus-webhooks.json.

🌐 Web UI

Live graph visualization with D3.js: interactive force-directed graph of your memory network. Filter by category, search, inspect node details, and see drift status at a glance.

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, age thresholds. Weighted 0-10 scoring.

Time Decay in Retrieval ⏰

Gauss-shaped score decay: recent memories rank higher, old ones fade gracefully. Configurable offset (30 days, no penalty) and scale (365 days, half-life). Only applies when timestamps are present - backwards compatible.

Auto-Backup 💾

Fully automatic daily backup every 6 hours. All memories (payload + vectors) exported as JSON to ~/.nexus-memory/backups/. Keeps last 7 backups. No user action needed.

Update Notifications 📦

On startup, checks GitHub for new releases. If an update is available, the agent proactively tells the user in chat: "Nexus Memory v0.X.X is available - shall I update?" Non-blocking, fails silently if GitHub is unreachable.

Pre-Update Safety Backup 🛡️

Before any do_update(), a full backup is created automatically. If the update fails or breaks something, memories are safe in the backup file and can be restored via the restore tool.

📊 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 self-hosted solution with hybrid retrieval, drift detection, provenance, fact lifecycle, staging/rollback, auto-discovery, graph analytics, skill export, memory categories, and access control: all in one package. It is also the only memory layer that offers native plugins for both Hermes and OpenClaw, plus an MCP server for every other agent: one brain, two paths, all agents.

🧩 Embedding Providers

One server. Multiple backends. Same API.

📦 Release History

🔧 Troubleshooting

🧪 Tests

pytest tests/ -v # 389 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!

☕️ Buy me a Ko-fi · ❤️ GitHub Sponsors

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