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?"

📐 Architecture

graph TB
    subgraph INPUTS ["Inputs"]
        CLI["🖥️ CLI<br/>onemem &lt;command&gt;"]
        MCP["🤖 MCP Server<br/>onemem-mcp"]
        API["🌐 HTTP API<br/>FastAPI /events"]
        WATCH["👁️ Watch<br/>Claude Code / Codex transcripts"]
    end

    subgraph WRITE ["✍️ Write Path"]
        INTAKE["① ingest_event()<br/>chunk → dedup by content hash → store"]
        EXTRACT["② extract_entities()<br/>LLM reads event → atomic facts + named entities"]
        RECONCILE["③ reconcile + store<br/>normalize entities → link fact_entity_edges → store facts"]
        EMBED_W["④ embed_facts()<br/>bge-base-en-v1.5 768-d local embedding"]
    end

    subgraph SQLITE ["📦 SQLite — ~/.onemem/onemem.db"]
        EVENTS[("events<br/>raw content, append-only")]
        EXTR[("extractions<br/>provenance ledger")]
        FACTS[("facts<br/>atomic claims")]
        ENTITIES[("entities<br/>canonical names")]
        EDGES[("fact_entity_edges<br/>which entities each fact mentions")]
        EMBED[("fact_embeddings<br/>sqlite-vec vec0, cosine")]
        FTS[("facts_fts<br/>FTS5 keyword index")]
    end

    subgraph READ ["📖 Read Path"]
        PARAMS["① LLM param extraction<br/>question → topic keywords + date range"]
        RETRIEVE["② Deterministic Retrieval"]
        VECTOR["Vector Door<br/>cosine similarity"]
        KEYWORD["Keyword Door<br/>FTS5 BM25"]
        ENTITY_D["Entity Door<br/>fact_entity_edges"]
        FUSION["Fusion<br/>magnitude noisy-OR"]
        CUT["③ Adaptive Cut<br/>score-curve ratio, bounded [10, limit]"]
        COLLAPSE["Source Collapse<br/>if facts ≥ raw event tokens → return raw"]
        SYNTH["④ LLM Synthesis<br/>(optional natural-language answer)"]
    end

    CLI --> INTAKE
    MCP --> INTAKE
    API --> INTAKE
    WATCH --> INTAKE

    INTAKE --> EVENTS
    EVENTS --> EXTRACT
    EXTRACT --> FACTS
    EXTRACT --> ENTITIES
    EXTRACT --> EXTR
    RECONCILE --> EDGES
    EMBED_W --> EMBED
    FACTS --> FTS

    CLI --> PARAMS
    MCP --> PARAMS

    PARAMS --> RETRIEVE
    RETRIEVE --> VECTOR
    RETRIEVE --> KEYWORD
    RETRIEVE --> ENTITY_D
    VECTOR --> FUSION
    KEYWORD --> FUSION
    ENTITY_D --> FUSION
    FUSION --> CUT
    CUT --> COLLAPSE
    COLLAPSE --> SYNTH

    EMBED --> VECTOR
    FTS --> KEYWORD
    EDGES --> ENTITY_D

Key design principles:

• Append-only — raw events are never overwritten; facts are only ever added
• Deterministic retrieval — no LLM in the read path; same query always returns the same result
• Small models at the edges — LLM only at write time (distill) and optionally at read time (synthesize)

🔄 User Flow

flowchart LR
    START(["🧠 User has a thought"])

    subgraph WRITE ["✍️ Write"]
        direction TB
        ADD["onemem add<br/>'note'"]
        IMPORT["onemem import<br/>./docs/"]
        WATCH2["onemem watch<br/>(background capture)"]
        MCP_LOG["onemem_log<br/>(invisible agent write)"]
    end

    subgraph PROCESS ["⚙️ Process"]
        direction TB
        LLM_EXTRACT["LLM distills<br/>facts + entities"]
        RECON["Entity reconciliation<br/>normalize + deduplicate"]
        LOCAL_EMBED["Local embedding<br/>bge-base 768-d"]
    end

    subgraph STORE ["📦 Store"]
        SQLITE[("SQLite<br/>events → facts<br/>→ embeddings<br/>→ FTS5 index")]
    end

    subgraph READ ["📖 Read"]
        direction TB
        ASK["onemem ask<br/>'question'"]
        MCP_RECALL["onemem_recall<br/>(AI agent call)"]
        SQL["onemem sql<br/>'SELECT...'"]
        LIST["onemem list events"]
    end

    START --> WRITE
    WRITE --> PROCESS
    PROCESS --> STORE
    STORE --> READ
    READ --> ANSWER(["✨ User gets answer"])

    style WRITE fill:#dcfce7,stroke:#16a34a,color:#15803d
    style PROCESS fill:#fef9c3,stroke:#ca8a04,color:#a16207
    style STORE fill:#e0e7ff,stroke:#4f46e5,color:#4338ca
    style READ fill:#dbeafe,stroke:#2563eb,color:#1d4ed8

⚡ All Commands — Visual Reference

📋 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
│   ├── openai_compat.py      # OpenAI-compatible endpoints
│   ├── anthropic.py          # Anthropic native API
│   └── local_embedding.py    # bge-base-en-v1.5
├── 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.