omninode-memory 0.4.0

OmniNode document ingestion and semantic retrieval

OmniMemory

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

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│     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

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.

Minimal example using the intent handler:

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

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 for package management.

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/

Open an issue or email [e-mail].