Tools
Nexus Memory
By Universal Memory Layer for AI Agents — self-hosted, hybrid search, 3-way: Hermes Plugin · OpenClaw Plugin · MCP Server
Install
pip install -eConfiguration Example
mcp_servers:
nexus:
command: nexus-memoryREADME
<p align="center">
<img src="webui/static/assets/logo-transparent.png" width="72" height="72" alt=""/>
<img src="docs/images/nexus-banner.svg" alt="Nexus Memory" height="72"/>
</p>
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!
[](https://github.com/Neboy72/nexus-memory)
[](LICENSE)
[](https://www.python.org/)
[](https://qdrant.tech/)
[](https://github.com/Neboy72/nexus-memory/releases)
[](tests/)
[](https://modelcontextprotocol.io)
> **🤖 Bot Self-Install:** Tell your agent: *"Read AGENTS.md and install Nexus Memory."* It does the rest.
👉 [](AGENTS.md)
👉 [](https://github.com/Neboy72/nexus-memory) [](https://ko-fi.com/nexusmemory) [](https://github.com/sponsors/Neboy72)
---
## 🏗️ Architecture — Three Paths, One Brain
Nexus Memory uses a single Qdrant collection (`nexus`) backed by one embedder. The Hermes native plugin, the OpenClaw native plugin, and the MCP server all read/write the **same store** — same vectors, same metadata, same access levels.
```
┌──────────────────────┐ ┌──────────────────────┐ ┌──────────────────────┐
│ Hermes Agent │ │ OpenClaw │ │ Claude Code / Cursor│
│ (Native Plugin) │ │ (Native Plugin) │ │ Codex / Any MCP │
│ │ │ │ │ (MCP Client) │
└──────────┬───────────┘ └──────────┬───────────┘ └──────────┬───────────┘
│ qdrant_client │ TS+fetch() │ stdio
│ (direct) │ (Qdrant REST) │
▼ ▼ ▼
┌──────────────────────────────────────────────────────────────────┐
│ Qdrant (localhost:6333) │
│ Collection: "nexus" │
└──────────────────────────────────────────────────────────────────┘
```
> **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?
| Path | Best for | Setup | Overhead |
|------|----------|-------|----------|
| **Hermes Plugin** | Hermes Agent | `./scripts/install_hermes_plugin.sh` | None — direct Qdrant access |
| **OpenClaw Plugin** | OpenClaw | `./scripts/install_openclaw_plugin.sh` | None — Qdrant REST via fetch() |
| **MCP Server** | Claude Code, Cursor, Codex, any MCP agent | `nexus-memory` (stdio) | Light — one Python process |
---
## 🤖 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
```bash
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
```bash
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)
```bash
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.
```bash
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:
<details>
<summary>🔷 Hermes Agent</summary>
`~/.hermes/config.yaml`:
```yaml
mcp_servers:
nexus:
command: nexus-memory
```
Restart: `hermes gateway restart`
</details>
<details>
<summary>🔷 OpenClaw</summary>
`~/.openclaw/openclaw.json` (`mcp.servers.<name>.env` — nested, not top-level):
```json
{
"mcp": {
"servers": {
"nexus-memory": {
"command": "nexus-memory",
"env": { "VOYAGE_API_KEY": "vo-your-key-here" }
}
}
}
}
```
</details>
<details>
<summary>🔷 Claude Code</summary>
`~/.claude/settings.json` or `.mcp.json` in project root:
```json
{
"mcpServers": {
"nexus": {
"command": "python3",
"args": ["-m", "nexus_memory.mcp_server"]
}
}
}
```
</details>
<details>
<summary>🔷 Codex CLI</summary>
`~/.codex/config.toml`:
```toml
[mcp_servers.nexus]
command = "python3"
args = ["-m", "nexus_memory.mcp_server"]
```
</details>
<details>
<summary>🔷 GitHub Copilot (VS Code)</summary>
`.vscode/mcp.json` in your project:
```json
{
"mcpServers": {
"nexus": {
"command": "python3",
"args": ["-m", "nexus_memory.mcp_server"]
}
}
}
```
</details>
<details>
<summary>🔷 Cursor</summary>
Settings → Features → MCP Servers → Add:
- **Name:** nexus
- **Command:** `python3`
- **Arguments:** `-m nexus_memory.mcp_server`
</details>
<details>
<summary>🔷 Cline / Roo Code</summary>
MCP Server Config:
```json
{
"mcpServers": {
"nexus": {
"command": "python3",
"args": ["-m", "nexus_memory.mcp_server"]
}
}
}
```
</details>
<details>
<summary>🔷 Kilo Code</summary>
`.mcp.json` in your project:
```json
{
"mcpServers": {
"nexus": {
"command": "python3",
"args": ["-m", "nexus_memory.mcp_server"]
}
}
}
```
</details>
<details>
<summary>🔷 Pi Coding Agent</summary>
`~/.pi/config.json`:
```json
{
"mcpServers": {
"nexus": {
"command": "python3",
"args": ["-m", "nexus_memory.mcp_server"]
}
}
}
```
</details>
<details>
<summary>🔷 Continue.dev</summary>
`.mcp.json` or `~/.continue/config.json`:
```json
{
"mcpServers": {
"nexus": {
"command": "python3",
"args": ["-m", "nexus_memory.mcp_server"]
}
}
}
```
</details>
<details>
<summary>🔷 Odysseus (PewDiePie)</summary>
Settings → MCP Management → Add Server:
- **Name:** nexus
- **Command:** `python3`
- **Arguments:** `-m nexus_memory.mcp_server`
</details>
<details>
<summary>🔷 Any MCP-compatible agent</summary>
Standard MCP stdio config:
```json
{
"mcpServers": {
"nexus": {
"command": "python3",
"args": ["-m", "nexus_memory.mcp_server"]
}
}
}
```
</details>
---
## 🎯 MCP Tools
| Tool | Description | Parameters |
|------|-------------|------------|
| `remember` 💾 | Store a memory | `text` (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 memory | `memory_id` (req) |
| `update` ✏️ | Update in-place, preserve metadata | `memory_id` (req), `text`, `modified_by` |
| `subscribe` 🔔 | Register a webhook for memory events | `event_type` (req), `webhook_url` (req) |
| `unsubscribe` 🔕 | Remove a webhook subscription | `subscription_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 server | `confirm` (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.
| Category | Scope | Use Case |
|----------|-------|----------|
| `fact` ✅ | Permanent | Verified facts, decisions (default) |
| `belief` 🤔 | Drift-prone | Assumptions that may change over time |
| `session` 🔄 | Ephemeral | Current conversation context |
| `rule` 📏 | Permanent | Operating rules, policies |
| `preference` ❤️ | Permanent | User likes, dislikes, habits |
| `temp` ⏳ | Temporary | Short-lived notes, TTL-managed |
### Access Levels 🛡️
| Level | Visible to | Example |
|-------|-----------|---------|
| 🟢 `public` | All agents | Project know
... (truncated)
tools
Comments
Sign in to leave a comment