mnelo

mnelo = μνήμη + λόγος (Greek: memory + reason). Local-first knowledge-graph memory layer for AI agents — what Mem0 charges for, in one SQLite file: 4-way RRF + L2 maintenance + bilingual classifier. usearch f16 runs it on a $10/year VPS.

| English | 简体中文 |

the runtime your AI agent's memory lives on.

• always local — one SQLite file. cp memory.db is a full backup. Cloud-free, account-free, subscription-free.

• 4-way recall with RRF — vector / graph / meta / entity lanes fused without score normalization (p50 = 18 ms @ 5k vectors)

• knowledge graph native — entities + typed relations, every relation points back to its source chunk

• memory_type taxonomy + zero-LLM classifier — auto-tags every write as fact / preference / episode / decision / procedure / ephemeral; bilingual (简体/繁體/EN)

• session-state digest — 500–2000 char "where things stand" summary injected at session start (any MCP client)

• task & loop state machine — finite-state tasks, periodic loops, stuck-task proposals with CAS-protected transitions and a full audit trail

• optional autonomous maintenance layer — TTL, importance decay, fact-promotion, with full audit_log + undo. Ship-default off.

• standard MCP, no lock-in — 22 tools over streamable-http (recommended), SSE, stdio, or dual-mode (SSE + streamable-http on one port); works with Hermes, Claude Code, Cursor, or any MCP client

• fits a $10/year US VPS — vector backends (usearch f16 / zvec INT8) keep RAM + disk small enough for KVM1 1 GB / 25 GB SSD; full memory system + agent relay in one box

requirements

• Python 3.10+ — usearch>=2.26 (vector search backend) only ships wheels for Python 3.10 and newer. Python 3.9 and earlier are not supported. macOS (arm64/x86_64), Linux, Windows WSL2 all OK.

• ~200 MB disk for the embedder model cache (BAAI/bge-small-zh-v1.5, fetched on first run)

• Optional: sqlite-vec for vec0 fast path — auto-detected at runtime, falls back to usearch when unavailable

Related MCP server: alaya

install

git clone https://github.com/cure4u/mnelo.git
cd mnelo
bash scripts/install.sh        # one-shot: venv, pip, init_db, service
                               # daemon (macOS launchd / Linux systemd),
                               # auth token

or manual:

python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
python3 scripts/init_db.py
# start the server — streamable-http is the recommended transport
.venv/bin/python mcp_server.py --transport streamable-http \
  --host 127.0.0.1 --port 8086

verify:

python3 scripts/health_check.py

For non-technical users: hand this single prompt to any AI coding agent (Claude Code, Hermes, Cursor, …) and it installs + adopts mnelo in one go — see docs/AGENTS.md.

multi-agent via Tailscale

A single mnelo instance can serve multiple AI agents across machines — your MacBook, a $10/year VPS, a Raspberry Pi, or a friend's laptop on the same Tailscale mesh — all writing into one shared memory.db without id collisions.

What mnelo provides

• host: namespace guard — every agent writes under its own prefix (host:macbook, host:vps-agent-1, …) so writes never collide. Same DB, different views, no global locks.

• Tailscale CGNAT host whitelist — mcp_server.py accepts Tailscale 100.x.x.x IPs as legitimate bind targets, so mesh peers can dial in without exposing the service to the public internet.

• MneloRemoteClient — a drop-in client wrapper (api/mnelo_client.py) that locks source='hermes-gw' so the gateway agent's writes are tagged and queryable.

• install.sh --listen-mode — two modes at install time (interactive install only; non-interactive defaults to loopback):

  • loopback (default, single-machine) — --host 127.0.0.1, safest. Tailscale daemon forwards Service traffic here too if you have a *.ts.net Service registered in admin console.

  • Tailscale mesh (multi-agent) — --host 0.0.0.0, accept direct mesh-peer IP connections. The host whitelist still rejects LAN / public / non-CGNAT IPs, so this is only as open as your Tailscale ACL policy.

  • For finer-grained Service-vs-bare-IP routing decisions, see docs/AGENTS.md §1.5.

• Per-agent config (config.toml) — [rate_limit], [validation], [task], [client] sections are per-deployment tunable, so each machine's policy can differ without code edits.

Minimal setup (5 minutes)

On the server machine (the one that owns memory.db):

# 1. install (interactive; answer "2" for Tailscale mesh mode)
bash scripts/install.sh

# 2. find your Tailscale IP
tailscale ip -4                  # → 100.x.x.x

# 3. share auth token with client machines (it's at ~/.config/mnelo/auth_token)
cat ~/.config/mnelo/auth_token

On each client machine (MacBook, VPS, R Pi, …):

pip install -r requirements.txt

# 4. point at the server (its Tailscale IP)
export MNELO_MEMORY_URL="http://100.x.x.x:8086/mcp"

# 5. set the auth token (from step 3)
export MNELO_AUTH_TOKEN="<paste-from-server-step-3>"

# 6. verify connection (also tailscale ip -4 curl test, see AGENTS §1.5)
python3 scripts/health_check.py

That's it — no port forwarding, no public certificates. Tailscale mesh handles transport encryption and ACLs; mnelo handles auth token + namespace isolation.

Reference

• Full listen-mode decision tree (when to use 127.0.0.1 vs 0.0.0.0, Tailscale Service vs bare IP, known firewall gotchas, R Pi / VPS client setup): see docs/AGENTS.md §1.5

• Multi-agent remote client wrapper code: see api/mnelo_client.py

• Cheap VPS deployment story + auth token: see docs/OPERATIONS.md

docs

Everything else lives in docs/:

• docs/AGENTS.md — adopt mnelo as your memory

• docs/RUNBOOK.md — install, service daemon, client connection, recovery

• docs/OPERATIONS.md — backup / restore, repo ↔ live sync, cheap US VPS deployment, known limitations

• docs/VECTOR_BACKENDS.md — usearch (f16) vs zvec (INT8 + native FTS) + AVX2 detection + crash triage

• docs/L2_MAINTENANCE.md — autonomous maintenance layer detail

• docs/BENCHMARKS.md — latency / memory footprint / multilingual / test coverage

• docs/COMPARISON.md — vs Mem0 / Letta / Zep / Cognee

• docs/research/ — deep-dive research notes (e.g. mem0借鉴研究 — 借鉴清单 + ROI 排序 + 落地建议)

• docs/ARCHITECTURE.md — module layout

• docs/DESIGN.md — design blueprint (docs/DESIGN_TASK_LOOP.md for the task/loop subsystem)

• docs/SCHEMA.md — SQLite schema (14 tables)

design tenets

1. Local first. No cloud API calls, ever. Embedder runs offline after pre-download.

2. Single file. SQLite. cp memory.db = full backup.

3. Standard MCP, no lock-in. 22 tools over streamable-http / SSE / stdio; works with any MCP client.

4. Generic-first. Features default to protocol-generic (any MCP client); client-specific glue is a thin, documented adapter.

5. Content-neutral by design. mnelo doesn't judge content — it faithfully stores and retrieves whatever the calling agent supplies. It guards the mechanism (injection, identity, integrity), not the content.

6. Single source of truth. Derived views (digest, canonical facts) never carry information the source chunks don't have.

7. Boring & predictable. No magic. Fail-fast over silent degradation. Explicit opt-in over defaults-that-surprise.

8. Measured. All numbers in docs/BENCHMARKS.md are reproducible — python -m benchmarks latency reruns them.

run tests

python3 -m pytest tests/ -q
# 1,075 tests collected; coverage & latency numbers in
# docs/BENCHMARKS.md → Test coverage

license

MIT. See LICENSE.

acknowledgements

• usearch / zvec — vector backends; default auto chain tries zvec (INT8, needs AVX2+) first, falls back to usearch (f16)

• sqlite-vec — legacy: vec0 table kept for migrate / repair / init_db tooling; the runtime search backend no longer writes it

• fastembed — embedder wrapper

• BAAI/bge-small-zh-v1.5 — CN embedding model

• MCP — protocol spec

Hermes = the messenger god. mnelo = his memory layer.