omem-os 0.0.1

AI Memory Operating System — Graph-RAG, temporal truth maintenance, actionable schemas, selective encryption, sub-200ms hybrid retrieval.

OMem

The Memory Operating System for AI Agents 🧠🔥

Persistent. Intelligent. Blazing Fast. No Cap.

Your AI agents be out here sounding smart for 5 minutes then forgetting everything like they got brain rot.

OMem gives them a real brain — one that actually learns, forgets the mid stuff, compresses the noise, and thinks on its own. Lowkey the glow-up AI memory desperately needed.

Quick Start · Benchmarks · MCP / Claude Desktop · CLI · Docs

---

Install (One Command, No Drama)

pip install omem-os

Live on PyPI: https://pypi.org/project/omem-os/

---

The Problem (Why Current Memory is Mid AF)

Your agent slays in the moment — but the second the chat ends? Poof. Gone.

You've tried:

• 🗃 Vector DBs — Just dumb storage. No vibes check. Returns pure noise. Sus.
• 📜 Long context windows — Expensive af, slow, hits limits, and drowns your agent in irrelevant delulu.
• 💾 Conversation buffers — Grows forever like unchecked brain rot. Zero multi-session rizz.

Real talk: These aren't memory systems. They're just fancy storage. None of them actually think.

---

OMem Hits Different

OMem is a full Memory Operating System — not another wrapper. It mirrors how a real brain works:

Store everything  →  Classify what actually slays  →  Retrieve the relevant tea
Compress the mid  →  Forget the useless            →  Resolve contradictions (finally)

It's giving cognitive layer energy. Not just a database with retrieval sauce.

---

Benchmarks (We Ate) 🏆

Tested on Apple M-series. Same dataset (5k memories, 500 queries, all-MiniLM-L6-v2) across all systems. Fair comparison, no cap.

⚡ Head-to-Head Performance

System	Setup	Add (ops/s)	RAG (ops/s)	RAG p99
OMem	4.0 ms	65 †	292	20 ms
ChromaDB	507 ms	277 ‡	280	4 ms
LanceDB	8 ms	82,000 ‡	182	7 ms
Mem0	15,000+ ms	< 1	18	638 ms

† Smart Ingestion — OMem's add() does: embed → auto-classify → dedup → entity-graph sync → async persist. Others just store pre-computed vectors.

‡ Raw storage only — No classification. No deduplication. No graph. No thoughts.

🏆 Why OMem Mogged the Competition

Metric	OMem vs Mem0	OMem vs ChromaDB	OMem vs LanceDB
RAG throughput	16× faster	1.0× (parity)	1.6× faster
p50 recall	0.007 ms	3.5 ms	5.3 ms
Setup time	125× faster	127× faster	parity
Smart features	✅ All 9	❌ 0/9	❌ 0/9

The tea: Mem0 is slow because it runs LLM extraction on every add. OMem replaces that with a Rust-native classification engine — zero LLM calls, zero API costs, zero latency drama. We ate and left no crumbs. 🍽️

🧩 Feature Matrix (Who's Actually Built Different?)

Feature	OMem	ChromaDB	Mem0	LanceDB
Auto-Classification	✅	❌	❌	❌
Causal Graphs	✅	❌	❌	❌
Hybrid RAG (vector + keyword + recency + importance)	✅	❌	❌	❌
Forgetting & Decay	✅	❌	❌	❌
Memory Compression	✅	❌	❌	❌
Conflict Detection & TMS	✅	❌	❌	❌
CLI Tools	✅	❌	❌	❌
Zero Config	✅	✅	❌	✅
MCP Server (Claude/Cursor)	✅	❌	❌	❌

---

Quick Start (30 Seconds, Bet) ⚡

Installation

# From PyPI (recommended)
pip install omem-os

# Or from source (if you want the dev experience)
git clone https://github.com/mohitkumarrajbadi/omem
cd omem
SETUPTOOLS_USE_DISTUTILS=stdlib pip install -e .
omem health

macOS / Anaconda users — add this to ~/.zshrc once and thank me later:

export KMP_DUPLICATE_LIB_OK=TRUE
export HF_HUB_OFFLINE=1

60-Second Example (Watch It Slay)

from omem import OMem

brain = OMem()

# Add memories — it auto-detects the vibe + importance
brain.add("User prefers dark mode and Python for all backend work")
brain.add("Critical bug: race condition in payment module causes duplicate charges", importance=0.95)
brain.add("Architecture decision: migrated from REST to GraphQL for better performance")

# Retrieve what matters — not everything
results = brain.recall("What bugs do we have?")
print(results[0].content)
# → "Critical bug: race condition in payment module..." (the important one, no cap)

# See exactly why it got picked (this hits different)
for exp in brain.inspect("payment bugs"):
    print(exp.explain())
# → vector=0.91, keyword=0.85, recency=0.94, importance=1.5x boost

The Sleep Cycle — Let Your Agent Cook 🍳

brain.add("User clicked login button")
brain.add("User pressed sign-in")
brain.add("User tapped the login link")

result = brain.sleep()
# → compressed: 3 → 1  ("User repeatedly accessed login (3 instances)")
# → forgotten:  12 low-value memories removed
# → reflected:  4 new insights generated
# Chef's kiss. 🤌

---

How It Works

┌─────────────────────────────────────────────────────────┐
│            Your Agent  /  Claude  /  Cursor              │
└──────────────────────────┬──────────────────────────────┘
                           │  MCP or Python SDK
                           ▼
┌─────────────────────────────────────────────────────────┐
│                    OMem Unified API                      │
│        add · recall · sleep · inspect · serve           │
└────────────┬───────────────────────────┬────────────────┘
             │                           │
             ▼                           ▼
┌─────────────────────┐     ┌────────────────────────────┐
│     Rust Core       │     │        Brain Logic          │
│                     │     │                            │
│  • SIMD scoring     │     │  • Auto-classification     │
│  • FAISS HNSW       │     │  • Importance estimation   │
│  • Hybrid ranking   │     │  • Forgetting & decay      │
│  • Write buffer     │     │  • Reflection & compress   │
│  • RW lock          │     │  • Conflict TMS            │
└─────────────────────┘     └────────────────────────────┘
             │                           │
             └─────────────┬─────────────┘
                           ▼
             ┌──────────────────────────┐
             │  SQLite · PostgreSQL     │
             │  FAISS · Knowledge Graph │
             └──────────────────────────┘

The Retrieval Pipeline (4 Signals, Single SIMD Pass)

Final Score = (0.50 × vector_similarity)
            + (0.20 × keyword_overlap)
            + (0.15 × recency_decay)
            + (0.15 × importance_weight)
            × status_multiplier

Then optionally expanded via Graph-RAG: top results link to related entities in the knowledge graph, surfacing connected memories pure vector search would miss. Lowkey the smartest part of the whole system.

---

Real-World Usage

Customer Support Agent

from omem import OMem

memory = OMem(namespace="support")

memory.add("Customer John ([e-mail]) reported dashboard timeout on mobile Safari")
memory.add("Acme Corp is on Enterprise plan, SOC2 required by Q3")

context = memory.recall(
    "mobile issues Acme",
    context_type="bugs",    # boost bug-type memories
    time_range="recent",    # prioritize last 3 days
    k=5
)

Multi-Agent System (No Leakage, Fr)

researcher = OMem(namespace="researcher")
writer     = OMem(namespace="writer")

researcher.add("Study shows 40% retention improvement with personalized onboarding")

writer.recall("retention")       # → []  (fully isolated, no cross-contamination)
researcher.recall("retention", project_only=False)  # → finds it when you actually need it

Conflict Detection (Built Different)

brain.add("Python version: 3.9")
brain.add("Python version: 3.11")  # → auto-flagged as CONFLICTED

brain.resolve_conflict("Python version")
# → resolves in favor of most recent, deprecates the old one
# → no more contradictory context cooked into your agent's brain

---

Integrations

Claude Desktop & Cursor (MCP Server) ⭐

omem serve   # starts MCP stdio server — that's it

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "omem": {
      "command": "omem",
      "args": ["serve"]
    }
  }
}

What your AI gets:

Tool	What it does
remember	Store a fact, decision, or preference
recall	Semantic search with type + time filters
reflect	Generate high-level insights from memory
maintain	Compress, forget, and optimize memory
resolve_conflict	Detect and fix contradictions
summarize_state	Get a project architecture overview

Addressing the main concern:

"Won't injecting memory into every prompt bloat my context?"

Nah. OMem is a retrieval layer, not an injection layer. From 5,000 memories, it returns 3–5 targeted results (~200–500 tokens) — that's 97% less context than a naive approach, while giving the agent exactly what it needs. Context compression is the whole point. 💡

LangChain

from omem.integrations.langchain import OMemRetriever

retriever = OMemRetriever(omem_instance=brain)
chain = RetrievalQA.from_chain_type(llm=llm, retriever=retriever)

---

CLI Reference

# Setup
omem init                         # initialize at ~/.omem/brain.db
omem health                       # system health check

# Write
omem add "content" -i 0.9 -n myproject -t DECISION

# Read
omem search "query" -k 10 -c architecture -t recent
omem list -n myproject -t DECISION -l 50
omem inspect "query"              # debug retrieval scoring
omem stats && omem namespaces

# Maintenance
omem maintain --all               # compress + reflect + forget + dream

# Import / Export
omem export -f json -o dump.json
omem load dump.json -n myproject

# Integrations
omem serve                        # MCP server for Claude / Cursor
omem dashboard --port 7900        # web memory dashboard
omem demo                         # end-to-end interactive walkthrough
omem benchmark --n 10000          # run performance test

---

Architecture Details

Memory Types (Auto-Classified on Every Add)

Type	Examples
SEMANTIC	Facts, general knowledge
DECISION	Choices made, preferences
CAUSAL	Bug root causes, cause-effect chains
PROCEDURAL	How-to steps, workflows
EPISODIC	Events, experiences
REFLECTION	AI-generated insights
ACTIVE	Critical / urgent items
WORKING	Temporary, current-task context

Storage Backends

Backend	Use Case
SQLite (default)	Local, single-process, zero config
In-memory	Testing, ephemeral agents
PostgreSQL	Production, multi-process, distributed

---

Configuration

brain = OMem(
    backend="sqlite",              # "sqlite" | "memory" | "postgres"
    db_path="~/.omem/brain.db",
    model="all-MiniLM-L6-v2",
    embedding_provider="local",
)

HF_HUB_OFFLINE=1              # disable HuggingFace Hub checks (faster startup)
KMP_DUPLICATE_LIB_OK=TRUE     # fix OpenMP conflict on macOS/Anaconda
TOKENIZERS_PARALLELISM=false  # suppress tokenizer warning

---

Roadmap

Status	Feature
✅ Shipped	Hybrid RAG, Auto-classification, Forgetting, Compression, MCP Server
✅ Shipped	Truth Maintenance System, Knowledge Graph, Graph-RAG, PostgreSQL backend
✅ Shipped	CLI, Dashboard, PyPI package (pip install omem-os)
🔄 In Progress	LOCOMO benchmark validation, distributed mode
📅 Planned	Custom embedding providers (OpenAI, Cohere), memory versioning

---

FAQ

Q: Does this run an LLM internally?
A: Nah. We use lightweight heuristics + a tiny ~90MB embedding model. Zero LLM API drama, fr. No API keys needed, no external calls, no costs.

Q: How is this different from ChromaDB or Pinecone?
A: Those are vector storage systems. OMem is a memory operating system — with lifecycle management (importance → decay → forget), deduplication, conflict detection, knowledge graphs, and a cognitive maintenance cycle. Completely different category.

Q: Will it bloat my agent's context window?
A: The opposite. OMem retrieves 3–5 relevant memories per query (~300 tokens) instead of injecting your entire history. See the Context FAQ in DEVELOPER.md.

Q: Is it production-ready?
A: v0.0.1 is an early pre-alpha release. Available on PyPI for testing. SQLite handles hundreds of thousands of memories. PostgreSQL backend for multi-process deployments. APIs may change between releases.

Q: What about privacy?
A: Everything runs 100% locally by default. Your memories never leave your machine. No telemetry. PostgreSQL backend is self-hosted.

Q: Do I need Rust installed?
A: Only if building from source for SIMD acceleration. pip install omem-os works out of the box — no Rust needed.

---

Contributing

Come help us make this even more bussin. 🔥

git clone https://github.com/mohitkumarrajbadi/omem
cd omem
python -m venv .venv && source .venv/bin/activate
SETUPTOOLS_USE_DISTUTILS=stdlib pip install -e ".[dev]"
pytest tests/ -v
python benchmarks/competitor.py   # run head-to-head benchmarks

Check DEVELOPER.md for architecture deep-dives, CLI reference, and contribution guidelines.

---

License

MIT — see LICENSE

---

Built for the AI girlies and guys who are tired of mid memory 🧠

If OMem makes your agents actually intelligent, drop a ⭐ — it means the world.

Report Bug · Request Feature · Discussions