kaos-memory 0.0.1.dev0__tar.gz → 0.6.0__tar.gz

kaos_memory-0.6.0/.gitignore

@@ -0,0 +1,83 @@
+
+__pycache__/
+.coverage
+.DS_Store
+.eggs/
+.env
+.env.local
+.idea/
+.operator-sdk/
+.pytest_cache/
+.Python
+.venv
+.vscode/
+*.a
+*.egg-info/
+*.log
+*.o
+*.py[cod]
+*.so
+*.swo
+*.swp
+*~
+*$py.class
+# Analysis reports (local only, not committed)
+# Build artifacts
+# Docker
+# Generated KIND E2E values (created by hack/update-kind-e2e-values.sh)
+# Go
+# IDE
+# Kubernetes
+# Operator SDK
+# Planning documents (local only, not committed)
+# Python
+# Test outputs
+awesome-ai-apps
+bin/
+build/
+CLAUDE.md
+cover.out
+develop-eggs/
+dist/
+docker-compose.override.yml
+downloads/
+eggs/
+env/
+ENV/
+go.sum
+hack/kind-e2e-values.yaml
+htmlcov/
+kubeconfig
+kubeconfig.yaml
+lib/
+lib64/
+MEMORY_REPORT.md
+parts/
+PLAN_*
+PLAN-*.md
+PLAN-OTEL-RESULTS.md
+PLAN.md
+REPORT_*.md
+REPORT-*.md
+REPORT.md
+sdist/
+TASKS.md
+var/
+vendor/
+venv/
+wheels/
+PROGRESS.md
+.roborev.toml
+.husky/
+
+# Samples data (copied at build time from operator/config/samples)
+kaos-cli/kaos_cli/samples/data/*.yaml
+.obsidian/
+.planning/
+ROADMAP.md
+tmp/
+REPORT*
+PLAN*
+
+# Nested clone of the Agentic Identity Broker (separate repo; not part of KAOS)
+agentic-identity-broker/

kaos_memory-0.6.0/Dockerfile

@@ -0,0 +1,46 @@
+FROM python:3.12-slim
+
+WORKDIR /app
+
+# libpq is required at runtime by psycopg (pure-Python impl) for the pgvector
+# external storage backend; the slim base image does not ship it.
+RUN --mount=type=cache,target=/var/cache/apt \
+    apt-get update && apt-get install -y --no-install-recommends libpq5 && \
+    rm -rf /var/lib/apt/lists/*
+
+# Install UV for dependency management
+RUN --mount=type=cache,target=/root/.cache/pip \
+    pip install uv
+
+# Copy only dependency files first for better layer caching
+COPY pyproject.toml ./
+
+# Install dependencies using UV with cache mount (cached unless pyproject.toml changes).
+# The service image needs the full engine: install the `service` extra.
+RUN --mount=type=cache,target=/root/.cache/uv \
+    uv pip compile --extra service pyproject.toml -o requirements.txt && \
+    uv pip install --system -r requirements.txt
+
+# Copy source code (changes frequently, so copied last)
+COPY kaos_memory/ kaos_memory/
+COPY README.md ./
+
+# Install package (no deps - already installed above) for importlib.metadata
+RUN uv pip install --system --no-deps .
+
+# Default local-mode data directory (Chroma + SQLite + history live here on a PVC)
+RUN mkdir -p /data/memory && \
+    useradd -m -u 65532 memory && chown -R memory:memory /app /data
+USER memory
+
+ENV KAOS_MEMORY_STORAGE_TYPE=local \
+    KAOS_MEMORY_LOCAL_PATH=/data/memory \
+    KAOS_MEMORY_PORT=8080
+
+# Health check hits liveness (independent of store/model readiness)
+HEALTHCHECK --interval=30s --timeout=10s --start-period=20s --retries=3 \
+    CMD python -c "import httpx; httpx.get('http://localhost:8080/healthz').raise_for_status()" || exit 1
+
+EXPOSE 8080
+
+CMD ["python", "-m", "kaos_memory.app"]

kaos_memory-0.6.0/Makefile

@@ -0,0 +1,47 @@
+.PHONY: help build docker-build run-local test lint format clean
+
+IMG ?= axsauze/kaos-memory-service:latest
+
+help:
+	@echo "KAOS Memory Service build targets:"
+	@echo "  build               - Install dependencies using UV"
+	@echo "  docker-build        - Build the container image"
+	@echo "  run-local           - Run the service locally in local storage mode"
+	@echo "  test                - Run pytest tests"
+	@echo "  lint                - Run linting (black check + type check)"
+	@echo "  format              - Format code with black"
+	@echo "  clean               - Clean build artifacts"
+
+# Install dependencies
+build:
+	uv pip install -e .[service,dev,pydantic-ai]
+
+# Build the container image
+docker-build:
+	docker build -t $(IMG) .
+
+# Run the service locally in local (Chroma + SQLite) mode.
+# Override the model endpoint with KAOS_MEMORY_MODEL_BASE_URL for real extraction.
+run-local:
+	KAOS_MEMORY_STORAGE_TYPE=local \
+	KAOS_MEMORY_LOCAL_PATH=$(PWD)/tmp/memory-data \
+	KAOS_MEMORY_PORT=8080 \
+	python -m kaos_memory
+
+# Run tests
+test:
+	uv run pytest tests/ -v
+
+# Run linting checks (same as CI)
+lint:
+	black --check .
+	uvx ty@0.0.55 check
+
+# Format code with black
+format:
+	black .
+
+# Clean artifacts
+clean:
+	rm -rf build/ dist/ *.egg-info/ __pycache__ .pytest_cache .coverage htmlcov/
+	find . -type d -name __pycache__ -exec rm -rf {} + 2>/dev/null || true

kaos_memory-0.6.0/PKG-INFO

@@ -0,0 +1,103 @@
+Metadata-Version: 2.4
+Name: kaos-memory
+Version: 0.6.0
+Summary: KAOS production-grade agent memory - tiered stores, memory service, and client for Kubernetes agent orchestration
+License: Apache-2.0
+Requires-Python: >=3.12
+Requires-Dist: httpx>=0.25.0
+Requires-Dist: opentelemetry-api>=1.20.0
+Requires-Dist: pydantic>=2.0.0
+Provides-Extra: dev
+Requires-Dist: black>=24.0.0; extra == 'dev'
+Requires-Dist: opentelemetry-sdk>=1.20.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Provides-Extra: pydantic-ai
+Requires-Dist: pydantic-ai<3.0.0,>=2.0.0; extra == 'pydantic-ai'
+Provides-Extra: service
+Requires-Dist: chromadb>=1.5.0; extra == 'service'
+Requires-Dist: fastapi>=0.104.0; extra == 'service'
+Requires-Dist: mem0ai==2.0.10; extra == 'service'
+Requires-Dist: opentelemetry-exporter-otlp-proto-grpc>=1.20.0; extra == 'service'
+Requires-Dist: opentelemetry-instrumentation-fastapi>=0.41b0; extra == 'service'
+Requires-Dist: opentelemetry-instrumentation-httpx>=0.41b0; extra == 'service'
+Requires-Dist: opentelemetry-instrumentation-logging>=0.41b0; extra == 'service'
+Requires-Dist: opentelemetry-sdk>=1.20.0; extra == 'service'
+Requires-Dist: pgvector>=0.2.0; extra == 'service'
+Requires-Dist: psycopg[pool]>=3.1.0; extra == 'service'
+Requires-Dist: pydantic-settings>=2.0.0; extra == 'service'
+Requires-Dist: tiktoken>=0.7.0; extra == 'service'
+Requires-Dist: uvicorn>=0.24.0; extra == 'service'
+Description-Content-Type: text/markdown
+
+# KAOS Memory
+
+`kaos-memory` is the production-grade agent memory library for KAOS: one package that owns the wire contract, the tiered storage engine and HTTP service, the service client, and an optional Pydantic AI integration. It is packaged so consumers only pull what they use.
+
+| Install | Modules | Dependencies |
+| --- | --- | --- |
+| `kaos-memory` (core) | `kaos_memory.contract`, `kaos_memory.client` | Pydantic + httpx only |
+| `kaos-memory[service]` | `kaos_memory.app`, `kaos_memory.stores`, `kaos_memory.config` | + Mem0, Chroma/pgvector, tiktoken, FastAPI |
+| `kaos-memory[pydantic-ai]` | `kaos_memory.pydantic_ai` | + Pydantic AI |
+
+- **`kaos_memory.contract`** — the single source of truth for the HTTP contract: the `Scope`/`ScopeLevel` identity and the recall/write/forget request and response schemas. Carries no engine or web-framework dependency, so both the service and the client import the same definitions.
+- **`kaos_memory.client`** — `MemoryServiceClient`, the framework-agnostic best-effort HTTP client for the service (recall degrades to empty; write/forget are fail-soft unless `failure_mode="strict"`).
+- **`kaos_memory.pydantic_ai`** — direct Pydantic AI integration: message/turn adapters (`pydantic_message_to_turns`, `reconstruct_message_history`), server-side scope derivation (`scope_from_deps`), and the opt-in memory toolset (`MemoryTools`, `build_memory_toolset`).
+
+The service (`[service]` extra) composes two atomic, independently-testable stores:
+
+- **`LongTermStore`** — wraps [Mem0](https://github.com/mem0ai/mem0) as a library and exposes scope-mapped `write` / `recall` / `delete` / `delete_scope`. It is the only importer of `mem0`. Owner scoping is applied inside the vector query so recall never crosses tenants.
+- **`ShortTermStore`** — a scope-keyed relational short-term buffer bounding a verbatim recency window by a token budget, with an opt-in fold that compacts evicted turns into a versioned medium-term digest rather than truncating them. Folding is amortised by high/low water marks (evict down to the low mark on crossing the high mark), the digest is kept as append-only versions under a retention cap, and each fold's evicted batch is returned so callers can cascade it to long-term extraction. On Postgres the window is an UNLOGGED table and folds are serialised per scope by an advisory lock so replicas cannot double-fold.
+
+Both bind their models to a resolved OpenAI-compatible endpoint (a KAOS `ModelAPI`) via a single `ModelConfig`, and run in one of two storage modes:
+
+| Mode | Vector store | Short-term table | Topology |
+| --- | --- | --- | --- |
+| `local` | embedded Chroma | SQLite | single container on one PVC |
+| `external` | pgvector | Postgres | stateless, shared Postgres |
+
+## Scope model
+
+A `Scope` names whose memory an operation touches and maps onto a Mem0 owner identifier:
+
+| Scope level | Mem0 owner key |
+| --- | --- |
+| `private` | `agent_id` (this agent) |
+| `user` | `user_id` (a principal) |
+| `session` | `run_id` (one run) |
+| `shared` | a reserved shared owner id on `agent_id` |
+
+`shared` resolves to a reserved owner id rather than an empty filter because Mem0 rejects an owner-less search. This module ships only the correct translation; fail-closed enforcement is a later phase.
+
+## Development
+
+```bash
+make build            # install with dev extras into the active venv
+make test             # run the unit tests
+make lint             # black --check + ty type check
+make format           # black
+```
+
+### Running the pgvector / Postgres tests
+
+The `external`-mode tests are gated behind the `pgvector` marker and a DSN env var. Start a local container and point the tests at it:
+
+```bash
+docker run -d --name kaos-pgv \
+  -e POSTGRES_PASSWORD=pw -e POSTGRES_DB=memdb \
+  -p 55432:5432 pgvector/pgvector:pg16
+
+export KAOS_TEST_PGVECTOR_DSN=postgresql://postgres:pw@localhost:55432/memdb
+pytest tests/ -v
+```
+
+Without the DSN set, the `pgvector`-marked tests are skipped and the local Chroma/SQLite tests run on their own.
+
+## Layout
+
+| Module | Purpose |
+| --- | --- |
+| `config.py` | typed storage, model and short-term tier configuration |
+| `stores.py` | the whole storage layer: the `Scope` value object and Mem0 owner mapping, token counting, the OpenAI-compatible model client, the relational short-term store, and the Mem0-backed long-term adapter |
+
+The HTTP service, the agent-runtime client, and the operator wiring that resolves this configuration from a `MemoryStore` resource are built in subsequent phases.

kaos_memory-0.6.0/README.md

@@ -0,0 +1,71 @@
+# KAOS Memory
+
+`kaos-memory` is the production-grade agent memory library for KAOS: one package that owns the wire contract, the tiered storage engine and HTTP service, the service client, and an optional Pydantic AI integration. It is packaged so consumers only pull what they use.
+
+| Install | Modules | Dependencies |
+| --- | --- | --- |
+| `kaos-memory` (core) | `kaos_memory.contract`, `kaos_memory.client` | Pydantic + httpx only |
+| `kaos-memory[service]` | `kaos_memory.app`, `kaos_memory.stores`, `kaos_memory.config` | + Mem0, Chroma/pgvector, tiktoken, FastAPI |
+| `kaos-memory[pydantic-ai]` | `kaos_memory.pydantic_ai` | + Pydantic AI |
+
+- **`kaos_memory.contract`** — the single source of truth for the HTTP contract: the `Scope`/`ScopeLevel` identity and the recall/write/forget request and response schemas. Carries no engine or web-framework dependency, so both the service and the client import the same definitions.
+- **`kaos_memory.client`** — `MemoryServiceClient`, the framework-agnostic best-effort HTTP client for the service (recall degrades to empty; write/forget are fail-soft unless `failure_mode="strict"`).
+- **`kaos_memory.pydantic_ai`** — direct Pydantic AI integration: message/turn adapters (`pydantic_message_to_turns`, `reconstruct_message_history`), server-side scope derivation (`scope_from_deps`), and the opt-in memory toolset (`MemoryTools`, `build_memory_toolset`).
+
+The service (`[service]` extra) composes two atomic, independently-testable stores:
+
+- **`LongTermStore`** — wraps [Mem0](https://github.com/mem0ai/mem0) as a library and exposes scope-mapped `write` / `recall` / `delete` / `delete_scope`. It is the only importer of `mem0`. Owner scoping is applied inside the vector query so recall never crosses tenants.
+- **`ShortTermStore`** — a scope-keyed relational short-term buffer bounding a verbatim recency window by a token budget, with an opt-in fold that compacts evicted turns into a versioned medium-term digest rather than truncating them. Folding is amortised by high/low water marks (evict down to the low mark on crossing the high mark), the digest is kept as append-only versions under a retention cap, and each fold's evicted batch is returned so callers can cascade it to long-term extraction. On Postgres the window is an UNLOGGED table and folds are serialised per scope by an advisory lock so replicas cannot double-fold.
+
+Both bind their models to a resolved OpenAI-compatible endpoint (a KAOS `ModelAPI`) via a single `ModelConfig`, and run in one of two storage modes:
+
+| Mode | Vector store | Short-term table | Topology |
+| --- | --- | --- | --- |
+| `local` | embedded Chroma | SQLite | single container on one PVC |
+| `external` | pgvector | Postgres | stateless, shared Postgres |
+
+## Scope model
+
+A `Scope` names whose memory an operation touches and maps onto a Mem0 owner identifier:
+
+| Scope level | Mem0 owner key |
+| --- | --- |
+| `private` | `agent_id` (this agent) |
+| `user` | `user_id` (a principal) |
+| `session` | `run_id` (one run) |
+| `shared` | a reserved shared owner id on `agent_id` |
+
+`shared` resolves to a reserved owner id rather than an empty filter because Mem0 rejects an owner-less search. This module ships only the correct translation; fail-closed enforcement is a later phase.
+
+## Development
+
+```bash
+make build            # install with dev extras into the active venv
+make test             # run the unit tests
+make lint             # black --check + ty type check
+make format           # black
+```
+
+### Running the pgvector / Postgres tests
+
+The `external`-mode tests are gated behind the `pgvector` marker and a DSN env var. Start a local container and point the tests at it:
+
+```bash
+docker run -d --name kaos-pgv \
+  -e POSTGRES_PASSWORD=pw -e POSTGRES_DB=memdb \
+  -p 55432:5432 pgvector/pgvector:pg16
+
+export KAOS_TEST_PGVECTOR_DSN=postgresql://postgres:pw@localhost:55432/memdb
+pytest tests/ -v
+```
+
+Without the DSN set, the `pgvector`-marked tests are skipped and the local Chroma/SQLite tests run on their own.
+
+## Layout
+
+| Module | Purpose |
+| --- | --- |
+| `config.py` | typed storage, model and short-term tier configuration |
+| `stores.py` | the whole storage layer: the `Scope` value object and Mem0 owner mapping, token counting, the OpenAI-compatible model client, the relational short-term store, and the Mem0-backed long-term adapter |
+
+The HTTP service, the agent-runtime client, and the operator wiring that resolves this configuration from a `MemoryStore` resource are built in subsequent phases.

kaos_memory-0.6.0/kaos_memory/__init__.py

@@ -0,0 +1,56 @@
+"""KAOS production-grade agent memory.
+
+``kaos_memory`` is the one source of truth for KAOS memory: the wire contract,
+the tiered storage engine and HTTP service, the service client, and an optional
+Pydantic AI integration. It is packaged so consumers only pull what they use:
+
+- the core install exposes the :mod:`kaos_memory.contract` schemas and the
+  :class:`~kaos_memory.client.MemoryServiceClient` (Pydantic + httpx only);
+- the ``service`` extra adds the storage engine and FastAPI service
+  (:mod:`kaos_memory.app`, :mod:`kaos_memory.stores`, :mod:`kaos_memory.config`),
+  which pull the heavy engine dependencies (Mem0, Chroma/pgvector, tiktoken);
+- the ``pydantic-ai`` extra adds :mod:`kaos_memory.pydantic_ai` — message/turn
+  adapters and a memory toolset for direct Pydantic AI integration.
+
+Only the lightweight contract and client are imported eagerly here; the service
+and Pydantic AI surfaces are imported from their submodules so importing this
+package never drags in the engine or an agent framework.
+"""
+
+from kaos_memory.client import MemoryServiceClient
+from kaos_memory.contract import (
+    SHARED_OWNER,
+    FailureMode,
+    ForgetRequest,
+    ForgetResponse,
+    MediumTermContext,
+    RecallRequest,
+    RecallResponse,
+    Scope,
+    ScopeLevel,
+    ShortTermContext,
+    Turn,
+    WriteRequest,
+    WriteResponse,
+    scope_key,
+)
+
+__version__ = "0.4.8.dev0"
+
+__all__ = [
+    "MemoryServiceClient",
+    "Scope",
+    "ScopeLevel",
+    "SHARED_OWNER",
+    "scope_key",
+    "FailureMode",
+    "RecallRequest",
+    "RecallResponse",
+    "WriteRequest",
+    "WriteResponse",
+    "ForgetRequest",
+    "ForgetResponse",
+    "Turn",
+    "ShortTermContext",
+    "MediumTermContext",
+]