omninode-memory 0.6.0__tar.gz

omninode_memory-0.6.0/.claude/architecture-handshake.md

@@ -0,0 +1,81 @@
+<!-- HANDSHAKE_METADATA
+source: omnibase_core/architecture-handshakes/repos/omnimemory.md
+source_version: 0.16.0
+source_sha256: f8f997a43e97d3b2c83972d1fec94ff9e0429ad76c10477979fe70db57443811
+installed_at: 2026-02-10T16:35:34Z
+installed_by: jonah
+-->
+
+# OmniNode Architecture – Constraint Map (omnimemory)
+
+> **Role**: Memory system – persistence, recall, embeddings, vector storage
+> **Handshake Version**: 0.1.0 <!-- contract format version; source_version in metadata tracks the template -->
+
+## Platform-Wide Rules
+
+1. **No backwards compatibility** - Breaking changes always acceptable. No deprecation periods, shims, or migration paths.
+2. **Delete old code immediately** - Never leave deprecated code "for reference." If unused, delete it.
+3. **No speculative refactors** - Only make changes that are directly requested or clearly necessary.
+4. **No silent schema changes** - All schema changes must be explicit and deliberate.
+5. **Frozen event schemas** - All models crossing boundaries (events, intents, actions, envelopes, projections) must use `frozen=True`. Internal mutable state is fine.
+6. **Explicit timestamps** - Never use `datetime.now()` defaults. Inject timestamps explicitly.
+7. **No hardcoded configuration** - All config via `.env` or Pydantic Settings. No localhost defaults.
+8. **Kafka is required infrastructure** - Use async/non-blocking patterns. Never block the calling thread waiting for Kafka acks.
+9. **No `# type: ignore` without justification** - Requires explanation comment and ticket reference.
+
+## Core Principles
+
+- Sub-100ms memory operations
+- ONEX 4.0 compliance
+- Strong typing (zero `Any` types)
+
+## This Repo Contains
+
+- Qdrant vector storage integration
+- Memgraph graph operations
+- Memory retrieval and management
+- Pattern storage and recall
+- 26+ Pydantic models (zero `Any` types)
+
+## Rules the Agent Must Obey
+
+1. **ALL version fields MUST use `ModelSemVer` directly** - No `str` fallbacks, no union types
+2. **Zero `Any` types** - Strong typing throughout
+3. **All models must have Field descriptions** - `Field(..., description="...")`
+4. **Models in `models/` directory** - Not `core/`
+5. **Follow model exemption pattern** when placing models with handlers
+
+## Non-Goals (DO NOT)
+
+- ❌ No `version: ModelSemVer | str` union types
+- ❌ No string-to-semver convenience validators
+
+## Forbidden Patterns
+
+```python
+# WRONG - Union types for backwards compatibility
+version: ModelSemVer | str  # NEVER
+
+# WRONG - Convenience validators accepting strings
+@field_validator("version", mode="before")
+def convert_string(cls, v):
+    if isinstance(v, str):
+        return ModelSemVer.from_str(v)
+    return v
+```
+
+## Required Pattern
+
+```python
+# CORRECT - ModelSemVer only, callers convert
+version: ModelSemVer = Field(..., description="Semantic version")
+
+# Callers convert BEFORE calling
+config = MyConfig(version=ModelSemVer.from_str("1.0.0"))
+```
+
+## When You See Old Code
+
+1. **DELETE IT** - Do not refactor, do not deprecate
+2. No migration path - Callers update or they break
+3. No compatibility layer - Clean break every time

omninode_memory-0.6.0/.env.example

@@ -0,0 +1,192 @@
+# ============================================================================
+# OmniMemory - Environment Configuration
+# ============================================================================
+# Copy this file to .env and customize values as needed.
+# All variables have sensible defaults - only override what you need.
+#
+# Usage:
+#   cp .env.example .env
+#   docker compose up -d
+#
+# For production:
+#   docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d
+# ============================================================================
+
+# ----------------------------------------------------------------------------
+# PostgreSQL Connection (REQUIRED when postgres backend is enabled)
+# ----------------------------------------------------------------------------
+# Full connection URL for omnimemory's own PostgreSQL database.
+# This is omnimemory's dedicated database -- no shared/legacy databases.
+# The service will fail fast on startup if this is not set when postgres
+# is enabled (OMNIMEMORY__POSTGRES_ENABLED=true).
+#
+# Format: postgresql://user:password@host:port/dbname
+# OMNIMEMORY_DB_URL=postgresql://omnimemory:password@localhost:5432/omnimemory
+
+# ----------------------------------------------------------------------------
+# Docker Image Versions
+# ----------------------------------------------------------------------------
+# These control which versions of the database images are used.
+# Update these to upgrade or pin specific versions.
+
+# Qdrant Vector Database
+# Latest versions: https://hub.docker.com/r/qdrant/qdrant/tags
+QDRANT_VERSION=v1.16.3
+
+# Memgraph Graph Database
+# Latest versions: https://hub.docker.com/r/memgraph/memgraph/tags
+MEMGRAPH_VERSION=2.18.1
+
+# Valkey (Redis-compatible) Cache
+# Latest versions: https://hub.docker.com/r/valkey/valkey/tags
+VALKEY_VERSION=8
+
+# ----------------------------------------------------------------------------
+# Qdrant Configuration
+# ----------------------------------------------------------------------------
+# Vector database for semantic memory storage
+
+# MIGRATION NOTE: Renamed from QDRANT_PORT to QDRANT_HTTP_PORT
+# If you have an existing .env with QDRANT_PORT, rename it to QDRANT_HTTP_PORT
+
+# REST API port (default: 6333)
+# Used for HTTP API access and health checks
+QDRANT_HTTP_PORT=6333
+
+# gRPC port for high-performance operations (default: 6334)
+# Used for bulk operations and streaming
+QDRANT_GRPC_PORT=6334
+
+# ----------------------------------------------------------------------------
+# Memgraph Configuration
+# ----------------------------------------------------------------------------
+# Graph database for relationship queries
+
+# Bolt protocol port for client connections (default: 7687)
+# Used by Neo4j drivers and mgconsole
+MEMGRAPH_BOLT_PORT=7687
+
+# HTTP port for web interface (default: 7444)
+# Used for Memgraph Lab web UI
+MEMGRAPH_HTTP_PORT=7444
+
+# Internal memory limit in MB for Memgraph (development)
+# This controls Memgraph's internal memory allocation
+MEMGRAPH_MEMORY_LIMIT_MB=4096
+
+# Query execution timeout in seconds (production only)
+MEMGRAPH_QUERY_TIMEOUT_SEC=600
+
+# ----------------------------------------------------------------------------
+# Valkey Configuration
+# ----------------------------------------------------------------------------
+# High-performance cache (Redis-compatible)
+
+# Client connection port (default: 6379)
+VALKEY_PORT=6379
+
+# ----------------------------------------------------------------------------
+# Resource Limits - Development
+# ----------------------------------------------------------------------------
+# These control container resource allocation for development (docker-compose.yml)
+# Adjust based on your machine's available resources
+
+# Qdrant Resources (Development)
+QDRANT_CPU_LIMIT=2.0
+QDRANT_MEMORY_LIMIT=2G
+QDRANT_CPU_RESERVATION=0.25
+QDRANT_MEMORY_RESERVATION=512M
+
+# Memgraph Resources (Development)
+MEMGRAPH_CPU_LIMIT=2.0
+MEMGRAPH_CONTAINER_MEMORY=4G
+MEMGRAPH_CPU_RESERVATION=0.25
+MEMGRAPH_MEMORY_RESERVATION=512M
+
+# Valkey Resources (Development)
+VALKEY_CPU_LIMIT=1.0
+VALKEY_MEMORY_LIMIT=1G
+VALKEY_CPU_RESERVATION=0.1
+VALKEY_MEMORY_RESERVATION=128M
+
+# ----------------------------------------------------------------------------
+# Resource Limits - Production
+# ----------------------------------------------------------------------------
+# These control container resource allocation for production (docker-compose.prod.yml)
+# Production defaults are more generous than development
+
+# Qdrant Resources (Production)
+QDRANT_PROD_CPU_LIMIT=4.0
+QDRANT_PROD_MEMORY_LIMIT=4G
+QDRANT_PROD_CPU_RESERVATION=0.5
+QDRANT_PROD_MEMORY_RESERVATION=1G
+
+# Memgraph Resources (Production)
+MEMGRAPH_PROD_CPU_LIMIT=4.0
+MEMGRAPH_PROD_CONTAINER_MEMORY=8G
+MEMGRAPH_PROD_CPU_RESERVATION=0.5
+MEMGRAPH_PROD_MEMORY_RESERVATION=1G
+# Internal memory limit in MB (production - higher than dev)
+MEMGRAPH_PROD_MEMORY_LIMIT_MB=8192
+
+# Valkey Resources (Production)
+VALKEY_PROD_CPU_LIMIT=2.0
+VALKEY_PROD_MEMORY_LIMIT=2G
+VALKEY_PROD_CPU_RESERVATION=0.25
+VALKEY_PROD_MEMORY_RESERVATION=256M
+
+# ----------------------------------------------------------------------------
+# Authentication (Optional for Development, Required for Production)
+# ----------------------------------------------------------------------------
+# Leave empty/unset for local development (no auth)
+# Set values for production deployments
+#
+# IMPORTANT: For production, these MUST be set or services will fail to start
+#
+# PASSWORD COMPLEXITY RECOMMENDATIONS:
+#   - Minimum length: 32 characters recommended
+#   - Generate secure passwords with: openssl rand -base64 32
+#   - Avoid special characters that need escaping in shell/YAML: $ ` \ " ' ! & | ; < > ( ) { } [ ]
+#   - Safe special characters: - _ . @ # % ^ + =
+
+# Qdrant API Key
+# When set, all Qdrant API requests require this key in Authorization header
+# Recommended: Use a strong, randomly generated key (min 32 characters)
+# QDRANT_API_KEY=your-secure-api-key-here
+
+# Memgraph Credentials
+# When both are set, Memgraph requires authentication for all connections
+# Note: Memgraph fails on empty credentials, unlike Qdrant/Valkey
+# MEMGRAPH_USER=admin
+# MEMGRAPH_PASSWORD=your-secure-password-here
+
+# Valkey Password
+# When set, Valkey requires AUTH command before accepting other commands
+# VALKEY_PASSWORD=your-secure-password-here
+
+# ----------------------------------------------------------------------------
+# Quick Reference - Port Conflict Resolution
+# ----------------------------------------------------------------------------
+# If you have port conflicts, override the conflicting port(s):
+#
+# Example: Another service using port 6333
+#   QDRANT_HTTP_PORT=16333
+#
+# Example: Another service using port 7687
+#   MEMGRAPH_BOLT_PORT=17687
+#
+# Example: Another Redis/Valkey using port 6379
+#   VALKEY_PORT=16379
+
+# ----------------------------------------------------------------------------
+# Quick Reference - Resource Tuning
+# ----------------------------------------------------------------------------
+# For machines with limited resources (e.g., 8GB RAM laptop):
+#   QDRANT_MEMORY_LIMIT=1G
+#   MEMGRAPH_CONTAINER_MEMORY=2G
+#   VALKEY_MEMORY_LIMIT=512M
+#
+# For high-memory machines (e.g., 64GB+ workstation):
+#   QDRANT_MEMORY_LIMIT=8G
+#   MEMGRAPH_CONTAINER_MEMORY=16G
+#   VALKEY_MEMORY_LIMIT=4G

omninode_memory-0.6.0/.flake8

@@ -0,0 +1,4 @@
+[flake8]
+max-line-length = 88
+extend-ignore = E203
+exclude = .git,__pycache__,.venv,venv,build,dist,.eggs

omninode_memory-0.6.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,13 @@
+---
+name: Bug Report
+about: Report a reproducible bug
+title: '[Bug] '
+labels: bug
+---
+## Describe the bug
+## To Reproduce
+## Expected behavior
+## Environment
+- OS:
+- Python:
+- Package version:

omninode_memory-0.6.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,9 @@
+---
+name: Feature Request
+about: Suggest an enhancement
+title: '[Feature] '
+labels: enhancement
+---
+## Problem
+## Proposed solution
+## Alternatives considered

omninode_memory-0.6.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,12 @@
+## Summary
+
+## Changes
+-
+
+## Test plan
+- [ ] `uv run pytest tests/ -m unit`
+- [ ] `uv run pre-commit run --all-files`
+- [ ] `uv run mypy src/ --strict`
+
+## Related issues
+Closes #

omninode_memory-0.6.0/.github/dependabot.yml

@@ -0,0 +1,12 @@
+# SPDX-FileCopyrightText: 2025 OmniNode.ai Inc.
+# SPDX-License-Identifier: MIT
+version: 2
+updates:
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"

omninode_memory-0.6.0/.github/required-checks.yaml

@@ -0,0 +1,90 @@
+# SPDX-FileCopyrightText: 2025 OmniNode.ai Inc.
+# SPDX-License-Identifier: MIT
+---
+# Required Status Checks for `main` Branch Protection
+#
+# This manifest documents the canonical list of required checks.
+# If you rename a CI job, you MUST update both this file and the
+# branch protection settings (Settings > Branches > main).
+#
+# Manifest added: OMN-2218
+# Branch protection applied: OMN-2186
+# Last verified: 2026-02-15
+# Pattern: OMN-1876 (omniclaude PR #137)
+#
+# Applied via: gh api repos/OmniNode-ai/omnimemory/branches/main/protection -X PUT
+# Mode: strict (branch must be up-to-date before merging)
+# Total required checks: 10
+
+required_checks:
+  # -- Phase 1: Quick Validation (parallel, ~2-5 min) -------------------------
+
+  - name: "Migration Freeze Check"
+    workflow: test.yml
+    job_id: migration-freeze
+    conditional: false
+    rationale: "Blocks new migrations during DB-per-repo refactor (OMN-2055)"
+
+  - name: "Code Quality"
+    workflow: test.yml
+    job_id: lint
+    conditional: false
+    rationale: "Comprehensive code quality validation (ruff format, ruff check, mypy strict)"
+
+  - name: "Pyright Type Checking"
+    workflow: test.yml
+    job_id: pyright
+    conditional: false
+    rationale: "Complementary type checking to mypy (basic mode)"
+
+  - name: "ONEX Validation"
+    workflow: test.yml
+    job_id: onex-validation
+    conditional: false
+    rationale: "ONEX pattern validation (pydantic, naming, enums, secrets, imports, model locations)"
+
+  - name: "Contract Validation"
+    workflow: test.yml
+    job_id: contract-validation
+    conditional: false
+    rationale: "Validates ONEX contract YAML files - structural correctness of node contracts"
+
+  - name: "I/O Audit"
+    workflow: test.yml
+    job_id: io-audit
+    conditional: false
+    rationale: "ONEX node purity enforcement - compute nodes must not contain forbidden I/O patterns"
+
+  - name: "Transport Import Guard"
+    workflow: test.yml
+    job_id: transport-import-guard
+    conditional: false
+    rationale: "ARCH-002: no direct transport/I/O imports in nodes/ (must use Protocol abstractions)"
+
+  - name: "Verify Architecture Handshake"
+    workflow: test.yml
+    job_id: check-handshake
+    conditional: true
+    condition: "Skipped on fork PRs (forks may not have access to cross-repo checkout)"
+    rationale: "Cross-repo architecture handshake with omnibase_core is current"
+
+  # -- Phase 2: Full Test Suite ------------------------------------------------
+
+  - name: "Tests"
+    workflow: test.yml
+    job_id: test
+    conditional: false
+    rationale: "Full test suite (depends on lint, pyright, onex-validation)"
+
+  # -- Phase 3: Aggregation ----------------------------------------------------
+
+  - name: "Test Summary"
+    workflow: test.yml
+    job_id: test-summary
+    conditional: false  # uses if: always() so it always runs
+    rationale: "Aggregator for all CI jobs. Treats check-handshake skipped as acceptable for fork PRs."
+
+# -- Explicitly excluded from required checks --------------------------------
+excluded_checks:
+  - name: "pre-commit"
+    reason: "pre-commit.ci runs independently. Local pre-commit hooks mirror CI jobs."

omninode_memory-0.6.0/.github/workflows/auto-tag-on-merge.yml

@@ -0,0 +1,12 @@
+name: Auto-Tag on Merge
+
+on:
+  pull_request:
+    types: [closed]
+
+jobs:
+  auto-tag:
+    if: github.event.pull_request.merged == true && contains(github.event.pull_request.labels.*.name, 'release')
+    uses: OmniNode-ai/omnibase_core/.github/workflows/auto-tag-reusable.yml@main
+    permissions:
+      contents: write

omninode_memory-0.6.0/.github/workflows/pre-commit.yml

@@ -0,0 +1,28 @@
+# SPDX-FileCopyrightText: 2025 OmniNode.ai Inc.
+# SPDX-License-Identifier: MIT
+
+name: Pre-commit
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  pre-commit:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: actions/setup-python@v6
+        with:
+          python-version: '3.12'
+
+      # SKIP hooks that require the full project installed (uv + omnimemory).
+      # These hooks have dedicated CI jobs in .github/workflows/test.yml:
+      #   - contract-linter  -> contract-validation job
+      #   - io-audit         -> io-audit job
+      #   - mypy             -> lint job (pre-push stage, not triggered here anyway)
+      - uses: pre-commit/action@v3.0.1
+        env:
+          SKIP: contract-linter,io-audit

omninode_memory-0.6.0/.github/workflows/release-dry-run.yml

@@ -0,0 +1,27 @@
+# SPDX-FileCopyrightText: 2025 OmniNode.ai Inc.
+# SPDX-License-Identifier: MIT
+name: Release Dry Run
+
+on:
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: 'Version tag to simulate (e.g. v0.4.0)'
+        required: true
+
+jobs:
+  dry-run:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+      - uses: astral-sh/setup-uv@v7
+        with:
+          python-version: '3.12'
+      - name: Build only (no publish)
+        run: uv build
+      - name: Verify artifacts
+        run: |
+          ls dist/*.whl dist/*.tar.gz
+          sha256sum dist/*.whl dist/*.tar.gz

omninode_memory-0.6.0/.github/workflows/release.yml

@@ -0,0 +1,101 @@
+# SPDX-FileCopyrightText: 2025 OmniNode.ai Inc.
+# SPDX-License-Identifier: MIT
+name: Release
+
+on:
+  push:
+    tags: ['v[0-9]*.[0-9]*.[0-9]*']
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: 'Version tag to release (e.g. v0.4.0)'
+        required: true
+
+permissions:
+  contents: write
+
+concurrency:
+  group: release-${{ github.repository }}-${{ github.ref_name }}
+  cancel-in-progress: false
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+          ref: ${{ github.event_name == 'workflow_dispatch' && inputs.tag || github.ref }}
+
+      - name: Assert clean working tree
+        run: |
+          git diff --exit-code
+          git diff --cached --exit-code
+          test -z "$(git ls-files --others --exclude-standard)"
+
+      - name: Validate tag matches pyproject.toml version
+        run: |
+          if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then
+            TAG="${{ inputs.tag }}"
+          else
+            TAG="${GITHUB_REF_NAME}"
+          fi
+          TAG="${TAG#v}"
+          PKG_VERSION=$(python3 -c "
+          import tomllib, sys
+          with open('pyproject.toml', 'rb') as f:
+              d = tomllib.load(f)
+          v = d.get('project', {}).get('version')
+          if not v:
+              raise SystemExit('ERROR: missing [project].version in pyproject.toml')
+          print(v)
+          ")
+          if [ "$TAG" != "$PKG_VERSION" ]; then
+            echo "ERROR: tag v${TAG} does not match pyproject.toml version $PKG_VERSION"
+            exit 1
+          fi
+          echo "Version validated: $PKG_VERSION"
+
+      - uses: astral-sh/setup-uv@v7
+        with:
+          python-version: '3.12'
+
+      - name: Build wheel + sdist
+        run: uv build
+
+      - name: Verify dist artifacts exist
+        run: |
+          ls -la dist/
+          ls dist/*.whl dist/*.tar.gz >/dev/null 2>&1 || {
+            echo "ERROR: expected wheel + sdist in dist/"
+            exit 1
+          }
+
+      - name: Publish to PyPI
+        run: |
+          uv publish --token "$UV_PUBLISH_TOKEN" dist/*.whl dist/*.tar.gz
+        env:
+          UV_PUBLISH_TOKEN: ${{ secrets.PYPI_TOKEN }}
+
+      - name: Generate checksums
+        run: sha256sum dist/*.whl dist/*.tar.gz > dist/SHA256SUMS.txt
+
+      - name: Set release tag
+        id: tag
+        run: |
+          if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then
+            echo "tag=${{ inputs.tag }}" >> $GITHUB_OUTPUT
+          else
+            echo "tag=${GITHUB_REF_NAME}" >> $GITHUB_OUTPUT
+          fi
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          tag_name: ${{ steps.tag.outputs.tag }}
+          files: |
+            dist/*.whl
+            dist/*.tar.gz
+            dist/SHA256SUMS.txt
+          generate_release_notes: true
+          prerelease: ${{ contains(github.ref_name, 'rc') }}