neuromem-core 0.2.2

One SQLite file. Zero cloud. One command to set up.

🏆 91.5% on LoCoMo · 📦 One SQLite File · ☁️ Zero Cloud · 💰 Zero Infrastructure Cost

Benchmark · Highlights · Base vs Pro · Install · First Run · API

🔬 Benchmark

Tested on LoCoMo, the standard benchmark for conversational memory. 1,540 questions across 10 conversations. All 8 systems share the same answer model, judge, scoring, top-k, and byte-identical answer prompt — only retrieval differs.

Neuromem achieves state-of-the-art accuracy for fully-local memory systems at zero ongoing infrastructure cost. Base runs entirely offline with no API keys. Pro adds one small LLM call per query for HyDE query expansion.

All scores use the same evaluation pipeline: GPT-4.1-mini answer generation, GPT-4o-mini judge (3x majority vote), temperature=0. Zero errors across 12,320 total answers. Scores use a lenient semantic-match judge; rankings are valid across all systems but absolute values are higher than published LoCoMo baselines using strict exact-match. Full methodology and reproduction scripts in benchmarks/.

⚡ Research Highlights

• 30+ percentage points more accurate than Mem0 on LoCoMo (91.5% vs 61.4%)
• 2x more cost-efficient per correct answer than Mem0
• Runs offline on any device with Python 3.10+ and 512MB RAM
• One SQLite file, zero API keys. The entire 6-layer system runs offline.
• Within 3.0pp of EverMemOS, the only higher-scoring system — and EverMemOS uses pre-computed retrieval rather than live search at query time.

Neuromem Pro nearly matches EverMemOS across all 4 question categories. Mem0 collapses on multi-hop reasoning (37.7% vs 90.7%).

🏗️ Base vs Pro

Same features, same 6-layer pipeline. Pro upgrades the embedding model and the cross-encoder reranker for higher retrieval accuracy.

Base works everywhere. Pro remembers better.

🚀 Quickstart

Claude Code / Claude Desktop

One command. Installs Neuromem and auto-configures Claude:

pip install neuromem-core[gpu,mcp] && neuromem-mcp --setup

That's it. Start a new Claude session — Neuromem walks you through choosing Base or Pro on first run, and you're ready to go.

Lightweight install (Base only, ~30MB instead of ~1.5GB):

pip install neuromem-core[mcp] && neuromem-mcp --setup

If you pick Pro later, Neuromem will prompt you to install the extra models.

Python library (no Claude)

pip install neuromem-core

from neuromem import Memory

m = Memory()
m.add("Prefers dark mode and TypeScript", user_id="alex")
m.add("Allergic to peanuts", user_id="alex")

results = m.search("What are Alex's preferences?", user_id="alex")
print(results[0]["content"])
# → "Prefers dark mode and TypeScript"

The database is created automatically at ~/.neuromem/memories.db.

🤖 What happens on first run?

Claude forgets you between sessions. Neuromem fixes that.

On your first session after installing, Neuromem will:

1. Welcome you and show your current version
2. Ask Base or Pro — you choose your accuracy tier
3. Optionally accept an API key — for enhanced search via HyDE query expansion (Anthropic, OpenRouter, or OpenAI)
4. Show you how it works — with example prompts to try

After setup, Neuromem runs automatically. It stores what you tell it and recalls it in future sessions — no manual work needed.

Make it automatic (optional)

Copy CLAUDE.md.example to your home directory as CLAUDE.md. This tells Claude to store your preferences and recall them without being asked:

cp CLAUDE.md.example ~/CLAUDE.md

Manual setup

If --setup doesn't detect your Claude installation, you can configure manually:

Claude Code:

claude mcp add neuromem -- python -m neuromem.mcp_server

Claude Desktop: add to claude_desktop_config.json (Settings > Developer > Edit Config):

{
  "mcpServers": {
    "neuromem": {
      "command": "python",
      "args": ["-m", "neuromem.mcp_server"]
    }
  }
}

If you installed in a virtualenv, use the full path to that Python (e.g. "/path/to/venv/bin/python").

📖 API

📊 Full Benchmark Details

Every benchmark script is self-contained and runs on Modal.

• Leaderboard & Reproduction: run any system yourself
• Full Technical Report: per-category breakdowns, latency, cost, hardware
• Evaluation Config: exact models, prompts, parameters

📝 Citation

@software{neuromem2026,
  title = {Neuromem: State-of-the-Art Local-First Agent Memory},
  author = {@Building\_Josh},
  organization = {Sauron},
  year = {2026},
  url = {https://github.com/buildingjoshbetter/neuromem},
  version = {0.2.0}
}

⚖️ License

Licensed under Apache 2.0. Free for personal and commercial use.