NOX-Supermem

Pain-weighted hybrid memory for AI agents — yours by design.

The only agent memory that’s genuinely yours. SQLite on your disk, provider your choice, zero vendor lock-in.

_{NOX-Supermem packages the nox-mem engine for standalone, self-hosted use — CLI · MCP server · HTTP API.}

🏗️ How it works · 🚀 Install · 👤 Humans · 🤖 Agents · 📊 Numbers

Long-term memory engine that any agent (OpenClaw, Hermes, Claude Code, custom) can use to remember decisions, search past context, and never ask "where were we?" again. The engine lives in nox-mem/ and ships with no data — your memory starts empty.

_{Real terminal — stats · hybrid search · reflect (RAG with cited sources) · HTTP API for agents.}

---

🏗️ How it works

Five layers, one SQLite file:

1. Ingest — router auto-detects entity files (compiled / frontmatter / timeline sections), plain markdown, or graphify input. A privacy filter applies redaction patterns before anything is stored.
2. Store — chunks land in SQLite with an FTS5 index plus a 3072-d Gemini vector via sqlite-vec. Retention is typed: feedback/person never decay, lesson 180d, decision/project 365d, default 90d.
3. Retrieve — the query runs in parallel through FTS5 BM25 and Gemini semantic; RRF fusion (k=60) merges them, with language-aware weights.
4. Rank — salience (recency × pain × importance) composes additively with section and temporal boosts. Shadow discipline: ranking changes ship in shadow mode for 7 days before they ever touch a live query.
5. Answer — CLI, MCP, and HTTP surfaces with citation footers and an anti-hallucination guard.

Copy the SQLite file, you copy the memory. Switch the embedding provider, the store doesn't care.

---

🚀 Install

Pick your interface — same engine, one SQLite file behind all three:

Interface	Entry point	Best for
CLI	nox-mem <cmd>	humans, scripts, cron
MCP server	node nox-mem/dist/mcp-server.js	agents (OpenClaw, Hermes, Claude Code) — 20 tools
HTTP API	node nox-mem/dist/api-server.js	services, dashboards, remote agents

Prerequisites (Linux / macOS): Node 20+, plus build-essential and python3 (compile the native better-sqlite3 / sqlite-vec modules).

# Debian/Ubuntu
sudo apt-get update && sudo apt-get install -y build-essential python3 inotify-tools
node --version   # must be >= 20

⚡ Quick install (copy-paste)

npm install -g nox-mem                           # published on npm — that's the whole install

export GEMINI_API_KEY=AIza...                    # https://aistudio.google.com/apikey
export NOX_DB_PATH="$HOME/.nox-mem/nox.db"
export NOX_MEM_DIR="$HOME/.nox-mem/memory"
mkdir -p "$HOME/.nox-mem/memory"

nox-mem stats && nox-mem search "hello"

👤 Step by step — for humans

1. Install — from npm (easiest), or from source if you want the agent profiles/templates too:

# From npm (recommended)
npm install -g nox-mem
nox-mem --help

# …or from source (also gets perfis/ + templates/)
git clone https://github.com/totobusnello/nox-supermem.git
cd nox-supermem/nox-mem && npm ci && npm run build && npm install -g .

2. Configure — create a .env (template in nox-mem/.env.example):

# Required
GEMINI_API_KEY=AIza...                 # Google AI Studio key
NOX_DB_PATH=$HOME/.nox-mem/nox.db      # SQLite database (any path you can write)
NOX_MEM_DIR=$HOME/.nox-mem/memory      # folder of markdown memories

# HTTP API (optional) — code default port is 18800; 18802 recommended to avoid clashes
NOX_API_PORT=18802
NOX_API_HOST=127.0.0.1
# NOX_API_TOKEN=change-me              # if set, API requires Authorization: Bearer <token>

Load it before running the CLI in any shell, cron, or service:

set -a; source "$HOME/.nox-mem/.env"; set +a

⚠️ Without sourcing the env, vectorize/kg-* fail silently ("Done: 0 embedded").

3. Initialize & verify

nox-mem stats     # first run auto-creates the schema — no migrations to run
nox-mem doctor    # diagnostic: SQLite, FTS5, vector extension, config

4. Ingest, embed, search

nox-mem ingest /path/to/notes.md     # plain markdown is fine
nox-mem vectorize                    # embeds new chunks (needs GEMINI_API_KEY)
nox-mem search "what did we decide about pricing"
nox-mem primer                       # ~500-token context-recovery summary

🤖 Step by step — for agents (OpenClaw / Hermes / others)

Agents connect over MCP (preferred) or the HTTP API. The bootstrap is idempotent — each step verifies before continuing.

1. Deterministic bootstrap (run in order; stop on first failure)

# preconditions
node --version | grep -qE 'v(2[0-9]|[3-9][0-9])' || { echo "need Node >=20"; exit 1; }

# install from npm
npm install -g nox-mem

# config
export GEMINI_API_KEY="<key>" NOX_DB_PATH="/data/nox/nox.db" NOX_MEM_DIR="/data/nox/memory"
mkdir -p "$NOX_MEM_DIR"

# verify schema
nox-mem stats | grep -q "Chunks:" || { echo "schema init failed"; exit 1; }

# resolve the MCP server path for the config below
echo "MCP server: $(npm root -g)/nox-mem/dist/mcp-server.js"

2. Wire it as an MCP server (recommended) — 20 tools (nox_mem_search, nox_mem_ingest, nox_mem_primer, nox_mem_reflect, nox_mem_kg_query, nox_mem_decision_*, nox_mem_cross_search, …). Add to your agent's MCP config (Claude Code .mcp.json, OpenClaw/Hermes equivalent):

{
  "mcpServers": {
    "nox-mem": {
      "command": "node",
      "args": ["<npm-root-g>/nox-mem/dist/mcp-server.js"],
      "env": {
        "GEMINI_API_KEY": "AIza...",
        "NOX_DB_PATH": "/data/nox/nox.db",
        "NOX_MEM_DIR": "/data/nox/memory"
      }
    }
  }
}

The agent calls nox_mem_search to recall and nox_mem_ingest to store. Run nox_mem_primer at session start for context recovery. Reusable agent profiles (assistente-pessoal, financeiro, pesquisador) live in perfis/; generic SOUL/HEARTBEAT/IDENTITY templates in templates/.

3. Or wire it as an HTTP API

set -a; source /data/nox/.env; set +a
node "$(npm root -g)/nox-mem/dist/api-server.js"      # or: node nox-mem/dist/api-server.js from the repo

Endpoint	Purpose
GET /api/health	status + vectorCoverage (embedded vs total)
GET /api/search?q=...	hybrid search
GET /api/brief	salience-ranked session priming
POST /api/answer	RAG answer over memory
GET /api/kg, /api/kg/path	knowledge graph
GET /api/reflect	high-salience insights

If NOX_API_TOKEN is set, send Authorization: Bearer <token>.

---

📊 The numbers

The engine is the same core benchmarked in memoria-nox. All results 5-batch + 95% CI verified.

Memory & multi-hop SOTA

Benchmark	nox-mem	Best competitor	Δ
EverMemBench Overall (Gemini-3-flash)	63.28%	MemOS 42.55%	+20.73pp
EverMemBench MA composite	88.42%	MemOS 55.68%	+32.74pp
LoCoMo retrieval@10 strict	74.52%	Mem0 SOTA F1 66.88%	above
MuSiQue F1 (n=2,417, single-shot)	58.62%	IRCoT 35.80% / EX(SA) 49.70%	+22.82pp / +8.92pp
HotPotQA ans_F1 (n=7,405 distractor)	73.37%	DPR+FiD reader 65–72%	above band

Production characteristics

Dimension	nox-mem	Comparison
KG path latency	2.5ms p50	none sub-10ms published
KG path cost/query	$0.00	Mem0 Cloud $0.001 → 769× cheaper
Self-hosted footprint	399MB single-process	Zep/Mem0/MemOS run 4+ services
Backbone portability	−10.54pp on backbone swap	MemOS −16.72pp → 1.6× more portable
Monthly OPEX (embed + KG + VPS)	< $11/mo all-in	—

_{How to read these. All results are 5-batch with 95% CI on the backbone noted; EverMemBench / MA / backbone-portability are on Gemini-3-flash.
• LoCoMo is retrieval@10 strict (a retrieval metric) shown next to Mem0's reported F1 — different metrics, for scale, not a like-for-like claim.
• LongMemEval 1.0 is the oracle retrieval ceiling (gold answers in-corpus ⇒ nDCG@10 = 1.0), not an end-to-end inference score; standalone accuracy is ~68%.
• KG-path $0 / 769× cheaper compares nox-mem's pure-SQL graph path (no LLM call) to Mem0 Cloud's per-query price (which includes inference) — true for that path only, apples-to-oranges by design.
• < $11/mo assumes the cheapest Hostinger VPS + Google AI Studio free tier.
• +78.8% nDCG@10 is vs an internal local-embedding baseline.
Step-by-step on what's reproducible from this package vs the research harness: REPRODUCE.md. Methodology, paper, and full competitive analysis: memoria-nox. MemOS arXiv:2602.01313 · MuSiQue (Trivedi 2022) · HotPotQA (Yang 2018).}

---

🔌 Multi-provider

Default is Gemini via Google AI Studio for both LLM and embeddings (GEMINI_API_KEY). The RAG answer/reflect layer and embeddings are provider-pluggable at runtime — no rebuild:

• LLM (NOX_LLM_PROVIDER) — gemini (default) or openai, where openai drives any OpenAI-compatible endpoint: OpenAI, DeepSeek, OpenRouter, Together, or a local Ollama/vLLM. anthropic is interface-ready but not yet implemented.
• Embedding (NOX_EMBEDDING_PROVIDER) — gemini (default, 3072-d) or openai (any OpenAI-compatible embeddings endpoint). voyage is interface-ready but not yet implemented.

# DeepSeek LLM + OpenAI embeddings (both OpenAI-compatible)
NOX_LLM_PROVIDER=openai
NOX_LLM_BASE_URL=https://api.deepseek.com/v1
NOX_LLM_MODEL=deepseek-chat
NOX_LLM_API_KEY=sk-...

NOX_EMBEDDING_PROVIDER=openai
NOX_EMBEDDING_BASE_URL=https://api.openai.com/v1
NOX_EMBEDDING_MODEL=text-embedding-3-large
NOX_EMBEDDING_DIM=3072        # MUST equal the vec0 table dim
NOX_EMBEDDING_API_KEY=sk-...

ℹ️ Scope of provider routing today: the RAG answer layer (reflect / /api/answer) and embeddings honor the env vars above. Some internal LLM operations — knowledge-graph extraction, consolidation, digest, and query expansion — still call Gemini directly and require GEMINI_API_KEY even when another provider is set. Routing every path through the provider layer is on the roadmap.

⚠️ Dimension lock: the sqlite-vec table is created with a fixed dimension. Switching embedding provider or model requires re-embedding the entire corpus with a single model at a single dimension matching the vec0 table. text-embedding-3-large supports dimensions=3072 (same as the default Gemini table). Vectors from different models are not comparable — mixing silently corrupts semantic search. Full env reference: nox-mem/README.md.

---

🩺 Verify & troubleshoot

node "$(npm root -g)/nox-mem/dist/api-server.js" &
curl -s "http://127.0.0.1:${NOX_API_PORT:-18800}/api/health" | jq .vectorCoverage
# close to 1.0 = all chunks embedded; below 0.99 → run `nox-mem vectorize`

Symptom	Fix
vectorize says "0 embedded"	env not sourced — set -a; source .env; set +a
vec0 ... cannot open shared object	platform binary missing — npm i -g sqlite-vec or reinstall on the target OS
better-sqlite3 build error	install build-essential + python3, then npm ci again
API port in use	set NOX_API_PORT (code default is 18800)
path rejected by op-audit guard	set NOX_OP_AUDIT_ALLOWED_PREFIXES, or keep DB under NOX_DB_PATH/NOX_MEM_DIR (auto-allowed)

Full env-var reference and per-command notes: nox-mem/README.md.

---

License

MIT © 2026 Luiz Antonio Busnello (Toto). Use it, fork it, ship it.