# OMem - AI Agent Memory System

OMem is a fast, cognitive memory framework for AI agents. It goes beyond standard Vector DB architectures by modeling memory lifecycles—supporting concepts like importance heuristics, forgetting curves, and consolidation (or "dreaming").

## Core Principles
1. **Speed**: Retrieval happens via a sub-millisecond Rust core using SIMD instructions.
2. **Intelligence**: OMem natively scores importance, auto-classifies facts, and groups insights.
3. **Ergonomics**: Developers use a unified `OMem` class with simple `.add()`, `.recall()`, and `.dream()` methods. 

## Project Layout
- `omem/api.py`: Main `OMem` interface exposing RAG, adding, and maintenance.
- `omem/core/engine/`: Handling of vectors, ingestion standardizations, and caching.
- `omem/core/brain/`: The "cognitive" logic. Importance scoring, context prefetching, and clustering/summarization (dreaming).
- `omem/integrations/`: Hooks and tools for Frameworks. Includes:
  - `CrewAI` tool wrappers
  - `LangChain` retrievers
  - `MCP Server` for connecting to local IDEs (Claude Code, Cursor, Copilot)
- `rust/`: PyO3 Rust extension (`omem_rust`) for the actual hybrid match ranking.
- `tests/`: Comprehensive test coverage suite.

## Integrating LLMs with OMem via MCP
OMem natively acts as an MCP (Model Context Protocol) server. Any LLM client (Claude Code, Cursor IDE, etc.) that supports MCP can connect to this repository's capabilities.
Start the server using the CLI:
`omem serve`

## Tech Stack
- Python 3.9+ 
- Rust (PyO3)
- Pydantic
- SQLite / FAISS
- Sentence Transformers

## How AI Should Help with this Codebase
- If asked about speed optimizations, consider writing them in `rust/`.
- If asked about new memory logics, add heuristics to `omem/core/brain/`.
- When writing tests or examples, use the `omem.api.OMem` class interface.
