oneMEM

One memory. Every AI. You own it.

Local, structured memory for AI agents — in one SQLite file on your machine.

oneMEM gives AI tools a shared local memory. It distills useful context into compact atomic facts and surfaces the minimum memory sufficient for a query. Every connected agent reads and writes the same SQLite file.

AI agents ───┐
Code editors ┼── MCP ── oneMEM ── ~/.onemem/onemem.db
Local tools ─┘

✨ Why oneMEM?

🚀 Quick Start

Requires Python 3.11+ and an API key for any LLM provider. Embeddings run locally.

# Install
uv tool install "onemem[all]"

# Setup (walks you through provider, key, model, capture, MCP wiring)
onemem init

# Try it
onemem add "Chose SQLite because it needs zero operations and one-file backups."
onemem ask "What storage did I choose, and why?"

📐 How oneMEM Works

oneMEM receives unstructured text (chat turns, notes, imported files), distills it into atomic facts, stores everything append-only in one SQLite file, and makes it retrievable through a deterministic hybrid search — no LLM in the read path. Any MCP-capable agent reads and writes the same memory.

Write Path

Read Path (Deterministic — No LLM)

📋 Commands

🔌 MCP Setup

oneMEM works with any MCP client that supports local stdio servers.

# Claude Code
claude mcp add --scope user onemem -- "$(command -v onemem-mcp)"

# Codex
codex mcp add onemem -- "$(command -v onemem-mcp)"

onemem init automatically detects and wires Claude Code and Codex during setup.

MCP Tools

🏗️ Supported Providers

Embeddings always use bge-base-en-v1.5 (768-d) running locally — no API key needed.

📊 Benchmarks

Measured on a 100-instance stratified sample of LongMemEval-S:

⚙️ Configuration

Edit ~/.onemem/config.toml (or use onemem config set):

[model]
provider = "openrouter"
model = "google/gemini-3.5-flash-lite"

[spend]
max_run_cost_usd = 20.0    # hard ceiling per batch import

[retrieval]
default_limit = 30         # max facts returned per recall
neighbour_max = 20         # neighbour facts gathered around a match

[ingestion]
concurrency = 20           # parallel LLM workers during bulk import

Where data lives

🛠️ Development

git clone https://github.com/shashank-tomar0/onemem.git
cd onemem
uv sync --all-extras
uv run pytest -q                    # 144 passing
./scripts/dev-onemem doctor         # run with isolated dev home

📁 Project Structure

onemem/
├── cli/                  # Click CLI (init, add, ask, watch, ...)
├── api/                  # FastAPI HTTP API
├── providers/            # LLM + embedding implementations
├── mcp_server.py         # MCP server (onemem_recall + onemem_log)
├── fact_retrieval.py     # Deterministic hybrid search
├── pipeline.py           # Ingest + process orchestration
├── entity_extractor.py   # LLM-based entity + fact extraction
├── schema.sql            # SQLite schema
└── config.py             # All tunable settings

📜 License

MIT — Based on Meniscus by magic_bubblez.