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.

Active Guardrails 🛡️

The only memory system that doesn't just store knowledge — it guards it. Before any destructive operation (rm -rf, drop, kill -9, recreate_collection), the guardrail checks Qdrant for stored protection rules and blocks if the target matches a protected path or collection.

• Memory-driven: Storing a protection rule like "Never delete ~/nexus-memory-test/" automatically registers it as protected

• Pattern detection: rm, rmdir, del, drop, truncate, kill/pkill/killall, recreate_collection, write_file, pip uninstall, find -delete, git clean -fdx, dd

• Fail-open: Qdrant outage degrades to ALLOW (never blocks agent work by accident)

• Override with audit trail: Explicit reasoning required (min 10 chars), stored as private session memory

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.

Session→Memory Pipeline 🧠

Session→Memory Pipeline (v0.6.0): Native fact extraction at session end. When a session ends (CLI exit, /reset, gateway session expiry), the plugin automatically extracts 1-5 durable facts from the conversation and stores them with proper categorization.

• Two-tier extraction: LLM extraction (preferred, uses the configured model) with heuristic pattern-based fallback (always works, no external dependencies)

• Categorization: fact, rule, preference, belief — with confidence scores (0.0-1.0)

• Inline execution: Runs in MemoryManager's background executor (no race condition with shutdown)

• Auto-Supersession: Extracted facts go through the existing similarity-based dedup

• Zero config: Uses the existing model/provider config from Hermes, no extra setup

Before v0.6.0, on_session_end stored raw conversation text as a single "session" memory. Now it extracts structured, durable facts.

Knowledge Graph Layer 🔗

Knowledge Graph Layer (v0.7.0): Entity extraction and typed relationships alongside Qdrant vectors. Not just "what is similar" (vector search) but "how things connect" (graph traversal).

• Entity extraction: Two-tier (LLM + heuristic) extraction of named entities from conversations

• Entity types: device, service, person, location, organization, concept, software, protocol

• Typed relationships: 11 new relation types (installed_at, connected_to, manages, runs_on, part_of, owns, located_at, depends_on_service, uses, provides, controls)

• Graph traversal: Multi-hop BFS queries via NetworkX — "what connects to the Wallbox?"

• Entities as Qdrant points: category="entity" with entity_type, entity_name, entity_attributes in payload

• Automatic: Entities extracted alongside facts in on_session_end

• No new database: Uses existing Qdrant + NetworkX. Neo4j can be added later at scale.

Graph-Boosted Auto-Recall 🚀

Graph-Boosted Auto-Recall (v0.9.0): Auto-Recall now fetches 1-hop graph neighbors from the top 3 vector search results. Not just "what is similar" but "what is connected".

• All 3 plugins: Hermes, OpenClaw, Claude Code

• How it works: Vector search → top 3 results → graph edges → 1-hop neighbors → [graph:<relation>] tagged in context

• Access-level filtered: Graph neighbors respect access levels (OpenClaw + Claude Code)

• Capped at 5: Prevents context bloat

• Graceful fallback: No edges = no graph items, no crash

Example: Search for "Wallbox" → vector hits about ABL Wallbox + graph neighbors: Reev Backend ([graph:connected_to]), RFID cards ([graph:uses]), IP address ([graph:located_at]).

SICA Self-Improvement Cycle 🔄

SICA (v0.9.0): Automatic memory hygiene. Scans all memories for issues and patches them.

• Detect: Stale temp memories (>7 days), low-confidence (<0.5), contradictions via graph edges

• Act: Auto-deletes stale temp memories. Other issues become suggestions for review.

• Learn: Stores SICA session as memory for future iterations

• Harness-independent: Any plugin can call run_sica() directly

• Configurable: SICA_STALE_TEMP_DAYS, SICA_LOW_CONFIDENCE, SICA_MAX_SUGGESTIONS env vars

Cost-Aware Routing 💰

Cost-Aware Routing (v0.8.0): Tier-based embedding provider selection. Premium memories (facts, rules, entities) use high-quality providers (Voyage/OpenAI). Economy memories (sessions, temp) use local providers (Ollama). Auto-enables when 2+ providers are available.

Guardrails 🛡️

Active Guardrails (v0.5.0): Memory-driven prevention of destructive actions. Before any destructive operation (rm -rf, drop, kill -9, recreate_collection, find -delete, git clean -fdx), the guardrail checks Qdrant for stored protection rules and blocks if the target matches a protected path or collection.

• Memory-driven, not hardcoded: Storing a rule like "Never delete ~/nexus-memory-test/" in Nexus Memory automatically registers it as a protected resource

• Fail-open: Qdrant outage degrades to ALLOW (guardrails never block agent work by accident)

• Override with audit trail: Explicit reasoning required (min 10 chars), stored as private session memory for audit

• Pattern detection: rm, rmdir, del, drop, truncate, kill/pkill/killall, recreate_collection, write_file, pip uninstall, find -delete, git clean, dd

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, access control, and active guardrails: all in one package. It is also the only memory layer that actively prevents destructive actions by checking protection rules before execution — not just storing knowledge, but guarding it. Plus native plugins for Hermes, OpenClaw, and Claude Code, plus an MCP server for every other agent: one brain, three paths, all agents.

🧩 Embedding Providers

One server. Multiple backends. Same API.

📦 Release History

🔧 Troubleshooting

🧪 Tests

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