Metadata-Version: 2.4
Name: omem-os
Version: 0.0.1
Summary: AI Memory Operating System — Graph-RAG, temporal truth maintenance, actionable schemas, selective encryption, sub-200ms hybrid retrieval.
Author-email: Mohit Kumar Rajbadi <mohitkumarrajbadi@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/mohitkumarrajbadi/omem
Project-URL: Repository, https://github.com/mohitkumarrajbadi/omem
Project-URL: Issues, https://github.com/mohitkumarrajbadi/omem/issues
Project-URL: Changelog, https://github.com/mohitkumarrajbadi/omem/releases
Keywords: ai,memory,rag,vector-search,embeddings,llm,agents,memory-os,compression,reflection,importance,multi-agent
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy<2.0.0,>=1.24.0
Requires-Dist: faiss-cpu>=1.7.4
Requires-Dist: click>=8.0.0
Requires-Dist: numba>=0.58.0
Requires-Dist: xxhash>=3.0.0
Requires-Dist: mcp>=1.0.0
Requires-Dist: psycopg2-binary>=2.9.0
Provides-Extra: embeddings
Requires-Dist: sentence-transformers>=2.2.0; extra == "embeddings"
Provides-Extra: langchain
Requires-Dist: langchain>=0.1.0; extra == "langchain"
Provides-Extra: external
Requires-Dist: openai>=1.0.0; extra == "external"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Provides-Extra: all
Requires-Dist: sentence-transformers>=2.2.0; extra == "all"
Requires-Dist: langchain>=0.1.0; extra == "all"
Requires-Dist: numba>=0.58.0; extra == "all"
Requires-Dist: pytest>=7.0; extra == "all"
Requires-Dist: pytest-cov>=4.0; extra == "all"
Dynamic: license-file

<div align="center">

<img src="https://img.shields.io/badge/version-0.0.1--pre--alpha-blueviolet?style=for-the-badge" alt="Version">
<img src="https://img.shields.io/badge/python-3.9%2B-blue?style=for-the-badge&logo=python" alt="Python">
<img src="https://img.shields.io/badge/rust-core-orange?style=for-the-badge&logo=rust" alt="Rust">
<img src="https://img.shields.io/badge/license-MIT-green?style=for-the-badge" alt="License">
<img src="https://img.shields.io/badge/MCP-compatible-purple?style=for-the-badge" alt="MCP">
<img src="https://img.shields.io/pypi/v/omem-os?style=for-the-badge&color=brightgreen" alt="PyPI">

<br><br>

# 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.

<br>

[**Quick Start**](#quick-start) · [**Benchmarks**](#benchmarks-we-ate) · [**MCP / Claude Desktop**](#integrations) · [**CLI**](#cli-reference) · [**Docs**](./DEVELOPER.md)

</div>

---

## Install (One Command, No Drama)

```bash
pip install omem-os
```

Live on PyPI: **[https://pypi.org/project/omem-os/](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

```bash
# 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:
> ```bash
> export KMP_DUPLICATE_LIB_OK=TRUE
> export HF_HUB_OFFLINE=1
> ```

### 60-Second Example (Watch It Slay)

```python
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 🍳

```python
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

```python
from omem import OMem

memory = OMem(namespace="support")

memory.add("Customer John (john@acme.com) 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)

```python
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)

```python
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) ⭐

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

Add to `claude_desktop_config.json`:

```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

```python
from omem.integrations.langchain import OMemRetriever

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

---

## CLI Reference

```bash
# 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

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

```bash
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](./DEVELOPER.md#memory-layer-faq--does-it-bloat-context).

**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. 🔥

```bash
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](./DEVELOPER.md) for architecture deep-dives, CLI reference, and contribution guidelines.

---

## License

MIT — see [LICENSE](./LICENSE)

---

<div align="center">

**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](https://github.com/mohitkumarrajbadi/omem/issues) · [Request Feature](https://github.com/mohitkumarrajbadi/omem/issues) · [Discussions](https://github.com/mohitkumarrajbadi/omem/discussions)

</div>
