OmniMemory

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

Where This Fits

OmniMemory holds three distinct ownership roles in the ONEX platform:

1. Domain owner for memory persistence and retrieval semantics. OmniMemory defines the authoritative models, protocols, and lifecycle rules for all memory operations: what a memory item is, how it is stored, how it is retrieved, and how it ages. These primitives do not move to other packages.

2. Runtime plugin owner for memory nodes. PluginMemory (registered as the onex.domain_plugins entry point) is the kernel lifecycle hook for the memory domain. It wires message types, verifies handler imports, initializes the dispatch engine, and subscribes to Kafka topics at runtime.

3. Storage integration owner for Qdrant, Memgraph, Valkey, and Kreuzberg adapters. The concrete adapter implementations for all memory-layer storage backends live in omnimemory. These adapters implement the domain protocols and are injected at runtime via the DI container.

What is migrating to omnimarket: The runnable ONEX node handler implementations (those with contract.yaml) are moving to omnimarket. Protocols, models, adapters, and the runtime plugin stay here. See OmniMemory → OmniMarket Node Migration Boundary.

What This Repo Owns

• Domain models — all memory, crawl, persona, intent, and intelligence Pydantic models in src/omnimemory/models/
• Protocol interfaces — ProtocolEmbeddingClient, ProtocolEmbeddingProvider, ProtocolIntentGraphAdapter, ProtocolSecretsProvider, and all base protocols in src/omnimemory/protocols/
• Storage adapters — Qdrant, Memgraph, Valkey, and filesystem adapter implementations in handlers/adapters/ and nodes/*/adapters/
• Runtime plugin — PluginMemory in src/omnimemory/runtime/ registered as onex.domain_plugins
• Memory-layer data services — Qdrant, Memgraph, Valkey, Kreuzberg (owned via docker-compose.yml)
• Node handlers — 13 contract-carrying nodes in src/omnimemory/nodes/ (migrating to omnimarket)

What This Repo Does Not Own

Architecture

Follows the ONEX Four-Node Architecture (EFFECT, COMPUTE, REDUCER, ORCHESTRATOR) applied to memory operations.

Node inventory

• Effect nodes — memory_storage_effect, memory_retrieval_effect, agent_learning_retrieval_effect, intent_storage_effect, intent_query_effect, kreuzberg_parse_effect, persona_storage_effect
• Compute nodes — semantic_analyzer_compute, similarity_compute, persona_builder_compute
• Reducer nodes — navigation_history_reducer, memory_consolidator_reducer (stub — no contract.yaml)
• Orchestrator nodes — memory_lifecycle_orchestrator, agent_coordinator_orchestrator

node_persona_lifecycle_orchestrator and node_persona_retrieval_effect were decommissioned in an earlier cleanup pass; they never had a contract.yaml and are no longer present in the repository. node_filesystem_crawler_effect and node_intent_event_consumer_effect have since been removed as well, once their omnimarket counterparts became canonical.

Verified against src/omnimemory/nodes/ on 2026-08-26: 14 node directories, 13 with contract.yaml; node_memory_consolidator_reducer is the contract-less stub.

Memory evolution (planned phases)

The architecture plan (omni_home/docs/plans/2026-04-07-plan-omnimemory-architecture.md) describes five enhancement phases: surprise gating on the write path, activation decay for retrieval ranking, memory cube isolation for multi-agent boundaries, Hebbian association strengthening, and hybrid vector+FTS search. These are planned, not yet implemented.

Infrastructure Ownership

OmniMemory's docker-compose.yml owns the memory-layer data services:

Not owned here — these services are managed by other repositories:

See OmniMemory Memory Data Ownership for detailed service boundaries and adapter ownership.

Quick Start

Memory services only

git clone https://github.com/OmniNode-ai/omnimemory.git
cd omnimemory

# Start platform infra first (Kafka + PostgreSQL — owned by omnibase_infra)
infra-up

# Start memory data services
docker compose up -d

# Verify all services are healthy
docker compose ps

Default service ports (all configurable via .env):

• Qdrant REST: localhost:6333
• Memgraph Bolt: localhost:7687
• Valkey: localhost:6379
• Kreuzberg parser: localhost:8090

See Starting OmniMemory Services in the knowledge base for the full startup runbook including health checks and troubleshooting.

Install and run tests

uv sync --group dev
uv run pytest tests/ -m unit

For configuration options see OmniMemory Environment Variables.

Minimal usage example

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")

    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_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 (memory, crawl, persona, intent, intelligence)
├── nodes/              # EFFECT, COMPUTE, REDUCER, ORCHESTRATOR node implementations
│   └── <node>/
│       ├── adapters/   # Stays in omnimemory (protocol implementations)
│       └── handlers/   # Migrating to omnimarket
├── adapters/           # Shared utilities with adapter_* prefix (PII detection, retry, health, metrics)
├── protocols/          # Protocol interfaces (embedding, intent graph, secrets)
├── runtime/            # PluginMemory, DI container wiring, dispatch, introspection
└── tools/              # Contract linter and validators

Development and Test Commands

# Install all dependencies
uv sync --group dev

# Format and lint
uv run ruff format src/ tests/
uv run ruff check --fix src/ tests/

# Type checking
uv run mypy src/omnimemory/ --strict

# Run all tests
uv run pytest tests/ -v

# Unit tests only (no external services required)
uv run pytest tests/ -m unit

# Pre-commit validation
pre-commit run --all-files

Migration Status

Nodes are migrating to omnimarket. The migration preserves the protocol-adapter-handler split: handlers move, adapters stay.

See OmniMemory → OmniMarket Node Migration Boundary.

Documentation

OmniMemory's documentation lives in the OmniNode knowledge base. This README is the repository's landing page; everything below is the full index of OmniMemory pages there. Every path under docs/ that was migrated is now a pointer stub to its page — with three deliberate exceptions listed under Kept in this repository below, which remain full documents because they are out of scope for the public knowledge base.

Architecture

• ONEX Four-Node Architecture — the EFFECT / COMPUTE / REDUCER / ORCHESTRATOR archetypes applied to memory
• ARCH-002: Kafka Abstraction Rule — why nodes never speak to a broker directly

Reference

• Environment Variables — every setting, type, default and constraint
• Memory Data Ownership — which repository owns which storage service
• Runtime Plugin System — how PluginMemory wires into the ONEX kernel
• Handler Reuse Matrix — which omnibase_infra handler each memory node reuses

Guides

• PII Handling — detection, sanitization and storage-path integration
• Performance Testing — SLA targets, benchmarks and how to read them
• Market Migration Boundary — what moves to omnimarket and what stays

Runbooks

• Starting OmniMemory Services — bringing the storage layer up, health checks, troubleshooting

Kept in this repository — operating context and platform-convention files that must ship beside the code: CLAUDE.md · AGENT.md · CONTRIBUTING.md · SECURITY.md · CODE_OF_CONDUCT.md · LICENSE · CHANGELOG.md

The three full documents still under docs/ — CI/agent-config and point-in-time records that the public knowledge base does not carry: docs/ci/CI_MONITORING_GUIDE.md · docs/stub_protocols.md · docs/db-split/fk-audit.md

Security, Contributing, and License

• SECURITY.md
• CONTRIBUTING.md
• CODE_OF_CONDUCT.md
• LICENSE

Open an issue or email contact@omninode.ai.