Metadata-Version: 2.4
Name: omninode-memory
Version: 0.4.0
Summary: OmniNode document ingestion and semantic retrieval
Project-URL: Homepage, https://github.com/OmniNode-ai/omnimemory
Project-URL: Repository, https://github.com/OmniNode-ai/omnimemory
Project-URL: Documentation, https://github.com/OmniNode-ai/omnimemory/tree/main/docs
Project-URL: Issues, https://github.com/OmniNode-ai/omnimemory/issues
Project-URL: Changelog, https://github.com/OmniNode-ai/omnimemory/blob/main/CHANGELOG.md
Author-email: "OmniNode.ai" <contact@omninode.ai>
License: MIT
License-File: LICENSE
Keywords: embeddings,memory,omninode,onex,rag,semantic-search
Requires-Python: <4.0,>=3.12
Requires-Dist: aiohttp<4.0.0,>=3.12.15
Requires-Dist: alembic<2.0.0,>=1.13.0
Requires-Dist: asyncio-mqtt<1.0.0,>=0.16.0
Requires-Dist: asyncpg<1.0.0,>=0.29.0
Requires-Dist: cachetools<7.0.0,>=6.2.4
Requires-Dist: fastapi<1.0.0,>=0.120.1
Requires-Dist: httpx<1.0.0,>=0.28.0
Requires-Dist: mcp<2.0.0,>=1.8.0
Requires-Dist: omnibase-core<0.20.0,>=0.19.0
Requires-Dist: omnibase-infra<0.11.0,>=0.10.0
Requires-Dist: omnibase-spi<0.13.0,>=0.12.0
Requires-Dist: pinecone-client<5.0.0,>=4.1.0
Requires-Dist: psutil<8.0.0,>=7.0.0
Requires-Dist: psycopg2-binary<3.0.0,>=2.9.10
Requires-Dist: pydantic-settings<3.0.0,>=2.10.1
Requires-Dist: pydantic<3.0.0,>=2.10.0
Requires-Dist: python-dotenv<2.0.0,>=1.0.1
Requires-Dist: pyyaml<7.0.0,>=6.0.2
Requires-Dist: qdrant-client<1.17.0,>=1.7.0
Requires-Dist: redis<7.0.0,>=6.4.0
Requires-Dist: sqlalchemy<3.0.0,>=2.0.0
Requires-Dist: structlog<24.0.0,>=23.3.0
Requires-Dist: supabase<3.0.0,>=2.9.0
Requires-Dist: uvicorn[standard]<1.0.0,>=0.32.0
Description-Content-Type: text/markdown

# OmniMemory

[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
[![ONEX 4.0](https://img.shields.io/badge/ONEX-4.0-purple.svg)](https://github.com/OmniNode-ai/omnibase_core)
[![Linting: ruff](https://img.shields.io/badge/linting-ruff-261230.svg)](https://github.com/astral-sh/ruff)
[![Type checked: mypy](https://img.shields.io/badge/type%20checked-mypy%20strict-blue.svg)](https://mypy.readthedocs.io/)
[![Pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white)](https://github.com/pre-commit/pre-commit)

**Memory persistence, recall, and semantic retrieval for the OmniNode platform.** OmniMemory provides ONEX-compliant nodes and handlers for storing agent context, indexing embeddings, querying intent graphs, and managing the full memory lifecycle across distributed omni agents.

## Four-Node Architecture

```text
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│     EFFECT      │───▶│     COMPUTE     │───▶│     REDUCER     │───▶│  ORCHESTRATOR   │
│  (store/fetch)  │    │ (embed/analyze) │    │  (consolidate)  │    │  (coordinate)   │
└─────────────────┘    └─────────────────┘    └─────────────────┘    └─────────────────┘
```

- **EFFECT**: Memory storage, retrieval, and intent query against external backends
- **COMPUTE**: Semantic analysis, similarity scoring, embedding generation
- **REDUCER**: Memory consolidation, statistics aggregation, lifecycle state management
- **ORCHESTRATOR**: Agent coordination, multi-step memory lifecycle workflows

## What This Repo Provides

- **Memory nodes** — `memory_storage_effect`, `memory_retrieval_effect`, `intent_storage_effect`, `intent_query_effect`, `intent_event_consumer_effect`
- **Compute nodes** — `semantic_analyzer_compute`, `similarity_compute`
- **Reducer nodes** — `memory_consolidator_reducer`, `statistics_reducer`
- **Orchestrator nodes** — `memory_lifecycle_orchestrator`, `agent_coordinator_orchestrator`
- **Intent handlers** — `handler_intent`, `handler_subscription` with protocol-driven adapters
- **Protocol interfaces** — embedding provider, intent graph adapter, secrets provider
- **Audit layer** — I/O audit logging via `audit/`
- **Runtime plugin** — registered as `onex.domain_plugins` entry point (`PluginMemory`)

## Quick Start

```bash
git clone https://github.com/OmniNode-ai/omnimemory.git
cd omnimemory
uv sync
uv run pytest tests/ -m unit
```

For configuration options see [docs/environment_variables.md](docs/environment_variables.md).

Minimal example using the intent handler:
```python
import asyncio
from uuid import uuid4

from omnibase_core.container import ModelONEXContainer
from omnimemory.handlers.adapters.models import ModelIntentClassificationOutput
from omnimemory.handlers.handler_intent import HandlerIntent


async def main() -> None:
    container = ModelONEXContainer()
    handler = HandlerIntent(container)

    await handler.initialize(connection_uri="bolt://localhost:7687")

    # Store an intent
    result = await handler.store_intent(
        session_id="session_123",
        intent_data=ModelIntentClassificationOutput(
            intent_category="debugging",
            confidence=0.92,
            keywords=["error", "traceback"],
        ),
        correlation_id=str(uuid4()),
    )

    # Query session intents
    query_result = await handler.query_session(
        session_id="session_123",
        min_confidence=0.5,
    )

    await handler.shutdown()


asyncio.run(main())
```

## Directory Structure

```text
src/omnimemory/
├── audit/              # I/O audit logging
├── enums/              # Domain enumerations (memory types, operation types, lifecycle states)
├── errors/             # Structured error types
├── handlers/           # HandlerIntent, HandlerSubscription + adapters
├── models/             # Pydantic models (core, memory, intelligence, service, container, contracts)
├── nodes/              # EFFECT, COMPUTE, REDUCER, ORCHESTRATOR node implementations
├── protocols/          # Protocol interfaces (embedding, intent graph, secrets)
├── runtime/            # Plugin registration, wiring, dispatch, introspection
├── tools/              # Contract linter and stubs
└── utils/              # Shared utilities (audit logger, PII detection, retry, health)
```

## Development

Uses [uv](https://docs.astral.sh/uv/) for package management.

```bash
uv sync
uv run pytest tests/ -m unit
uv run mypy src/omnimemory/ --strict
uv run ruff check src/ tests/
uv run ruff format src/ tests/
```

## Documentation

**Reference**: [docs/](docs/)

Open an issue or email contact@omninode.ai.
