unique-user-memory 2026.38.0.dev1__tar.gz → 2026.38.0.dev3__tar.gz

unique_user_memory-2026.38.0.dev1/README.md → unique_user_memory-2026.38.0.dev3/PKG-INFO

@@ -1,3 +1,17 @@
+Metadata-Version: 2.3
+Name: unique-user-memory
+Version: 2026.38.0.dev3
+Summary: 
+Author: Fabian Schläpfer
+Author-email: Fabian Schläpfer <fabian@unique.ch>
+License: Proprietary
+Requires-Dist: jinja2>=3.1.6
+Requires-Dist: pydantic>=2.8.2
+Requires-Dist: unique-sdk>=2026.38.0.dev4,<2026.38.0rc0
+Requires-Dist: unique-toolkit[monitoring]>=2026.38.0.dev14,<2026.38.0rc0
+Requires-Python: >=3.12, <4
+Description-Content-Type: text/markdown
+
 # Unique User Memory
 
 Persistent per-user memory for Unique AI agents.
@@ -25,7 +39,38 @@ The memory file is intentionally small and structured. It is rewritten as a full
 5. `UserMemoryPostprocessor` runs after the assistant response.
 6. The package asks the configured language model to either return `NOOP` or a complete rewritten profile.
 7. If a rewrite runs, an **Updating your memory** Step is shown while consolidating (no settings entry yet).
-8. If the profile changed and `memory.md` uploads successfully (ingestion skipped, content hidden from chat), that Step is completed with a **Review your context memory** detail entry (same settings badge). On NOOP or failed upload the Step completes without the entry.
+8. Every rewrite passes through a mandatory CID/PII scrub call (see Content Policy below) before it is assembled for upload. When the scrub cannot vouch for the rewrite, the existing memory is kept unchanged.
+9. If the profile changed and `memory.md` uploads successfully (ingestion skipped, content hidden from chat), that Step is completed with a **Review your context memory** detail entry (same settings badge). On NOOP or failed upload the Step completes without the entry.
+
+## Content Policy — the current user's CID/PII only (UN-24886)
+
+The profile belongs to exactly one person: the signed-in user. It may contain
+personal data (PII) of that user only. It must never contain
+client-identifying data (CID) or PII of any other person or private entity —
+not other users, not clients, not prospects, not counterparties. Facts about
+the user's own work that involve a client are stored only in a fully
+de-identified form ("runs quarterly portfolio reviews", never "reviews the
+portfolio of J. Muster"). Credentials, payment data, health records, and
+government IDs are never stored for anyone, including the user.
+
+The policy text lives once, in `_CID_POLICY` in `user_memory_prompts.py`, and
+is embedded in every write-path stage so the rules cannot drift:
+
+| Stage | Role of the policy |
+| --- | --- |
+| Gate (`memory_gate_system_prompt`) | Turns whose only new facts are third-party CID/PII lean `NOOP` and never reach the rewrite. |
+| Consolidation (`consolidation_system_prompt`) | The rewrite itself must not extract forbidden content. |
+| Condensation (`condensation_system_prompt`) | Oversized (including legacy) profiles must drop violating bullets on every shrink, progressively cleaning old data. |
+| Scrub (`scrub_system_prompt` / `scrub_user_memory`) | Mandatory final gate on every consolidation rewrite. Answers `CLEAN`, returns a cleaned body, or vetoes the write. Fails closed: on any error the existing memory is kept and the unvalidated candidate is discarded. |
+
+Storage-level isolation (per-user home folder with exclusive owner ACL, see
+Storage Model) already prevents cross-user *access*; this policy governs
+cross-user and cross-client *content*.
+
+Note for follow-up client-memory work: this package is user memory only. A
+future client memory is a separate artefact with its own scoping and must not
+be built by loosening this policy — client-related durable knowledge is
+intentionally rejected here rather than stored under the user's profile.
 
 ## Storage Model
 
@@ -99,6 +144,27 @@ config = UserMemoryConfig(
 | `max_tokens` | `2000` | Maximum profile size. Must be between 500 and 8000 tokens. |
 | `root_folder` | `user-memory` | Subfolder name under each user's home folder (`/home-<user_id>/<root_folder>`) that holds the memory profile; also read as a legacy fallback at `/<root_folder>/<user_id>`. |
 
+## Observability
+
+The package registers Prometheus metrics on the shared `unique_toolkit.monitoring` registry (namespace `unique_user_memory`). They appear on whatever host already scrapes `GET /metrics` (assistants-core). Labels are closed enums — no company or user ids. LLM series include the model name so latency can be split per deployed model.
+
+QA dashboard: [User Memory](https://qa-grafana.alpine-bowfin.ts.net/d/unique-user-memory) (`unique-user-memory`). The dashboard is provisioned by the [assistants-core Helm chart](https://github.com/Unique-AG/monorepo/tree/master/python/assistants/bundles/core/deploy/helm-chart/files/grafana/dashboards).
+
+| Metric | Labels | What it answers |
+| --- | --- | --- |
+| `load_duration_seconds` / `load_total` | `outcome`: `success`, `empty`, `folder_failed`, `skipped_no_ids` | Is load slow? How often do we run without memory? |
+| `postprocessor_duration_seconds` / `postprocessor_total` | `outcome`: `updated`, `noop`, `upload_failed`, `skipped_no_ids`, `error` | Did this turn persist a new profile? |
+| `errors_total` | `stage`, `error_type` | Infra failures by stage (`folder_lookup`, `folder_create`, `download`, `upload`, `gate`, `consolidation`, `scrub`, `condense`, `postprocessor`). |
+| `llm_duration_seconds` / `llm_errors_total` | `purpose`: `gate`, `consolidation`, `scrub`, `condense`; `model`: the configured model name | Which LLM call is the latency or error hog, and how does that differ by model? |
+| `gate_decisions_total` | `decision`: `update`, `noop`, `fail_open` | Is the gate saving consolidations? Is fail-open spiking? |
+| `scrub_decisions_total` | `decision`: `clean`, `cleaned`, `veto` | CID/PII pass health. |
+| `consolidation_results_total` | `result`: `rewritten`, `noop`, `malformed`, `llm_error`, `scrub_veto`, `unchanged_after_scrub` | Why a rewrite did not persist. |
+| `storage_duration_seconds` / `storage_total` | `op`: `folder_lookup`, `folder_create`, `download`, `upload`; `outcome`: `success`, `error`, `not_found`, `refused_empty` | Is the content store the bottleneck? |
+| `memory_length_tokens` / `memory_length_chars` | `phase`: `load`, `write` | How large are profiles in tokens and characters versus `max_tokens`? |
+| `condense_total` | `trigger`: `load`, `post_consolidation`, `condense`; `result`: `llm_ok`, `hard_cut`, `llm_failed_then_hard_cut` | How often the budget shrink path fires. |
+
+Token usage for billing still flows through `LanguageModelInvocationStats`, not these series.
+
 ## Integration
 
 Typical orchestration code loads memory before the agent loop and registers the postprocessor for the same turn.

unique_user_memory-2026.38.0.dev1/PKG-INFO → unique_user_memory-2026.38.0.dev3/README.md

@@ -1,17 +1,3 @@
-Metadata-Version: 2.3
-Name: unique-user-memory
-Version: 2026.38.0.dev1
-Summary: 
-Author: Fabian Schläpfer
-Author-email: Fabian Schläpfer <fabian@unique.ch>
-License: Proprietary
-Requires-Dist: jinja2>=3.1.6
-Requires-Dist: pydantic>=2.8.2
-Requires-Dist: unique-sdk>=2026.38.0.dev1,<2026.38.0rc0
-Requires-Dist: unique-toolkit>=2026.38.0.dev5,<2026.38.0rc0
-Requires-Python: >=3.12, <4
-Description-Content-Type: text/markdown
-
 # Unique User Memory
 
 Persistent per-user memory for Unique AI agents.
@@ -39,7 +25,38 @@ The memory file is intentionally small and structured. It is rewritten as a full
 5. `UserMemoryPostprocessor` runs after the assistant response.
 6. The package asks the configured language model to either return `NOOP` or a complete rewritten profile.
 7. If a rewrite runs, an **Updating your memory** Step is shown while consolidating (no settings entry yet).
-8. If the profile changed and `memory.md` uploads successfully (ingestion skipped, content hidden from chat), that Step is completed with a **Review your context memory** detail entry (same settings badge). On NOOP or failed upload the Step completes without the entry.
+8. Every rewrite passes through a mandatory CID/PII scrub call (see Content Policy below) before it is assembled for upload. When the scrub cannot vouch for the rewrite, the existing memory is kept unchanged.
+9. If the profile changed and `memory.md` uploads successfully (ingestion skipped, content hidden from chat), that Step is completed with a **Review your context memory** detail entry (same settings badge). On NOOP or failed upload the Step completes without the entry.
+
+## Content Policy — the current user's CID/PII only (UN-24886)
+
+The profile belongs to exactly one person: the signed-in user. It may contain
+personal data (PII) of that user only. It must never contain
+client-identifying data (CID) or PII of any other person or private entity —
+not other users, not clients, not prospects, not counterparties. Facts about
+the user's own work that involve a client are stored only in a fully
+de-identified form ("runs quarterly portfolio reviews", never "reviews the
+portfolio of J. Muster"). Credentials, payment data, health records, and
+government IDs are never stored for anyone, including the user.
+
+The policy text lives once, in `_CID_POLICY` in `user_memory_prompts.py`, and
+is embedded in every write-path stage so the rules cannot drift:
+
+| Stage | Role of the policy |
+| --- | --- |
+| Gate (`memory_gate_system_prompt`) | Turns whose only new facts are third-party CID/PII lean `NOOP` and never reach the rewrite. |
+| Consolidation (`consolidation_system_prompt`) | The rewrite itself must not extract forbidden content. |
+| Condensation (`condensation_system_prompt`) | Oversized (including legacy) profiles must drop violating bullets on every shrink, progressively cleaning old data. |
+| Scrub (`scrub_system_prompt` / `scrub_user_memory`) | Mandatory final gate on every consolidation rewrite. Answers `CLEAN`, returns a cleaned body, or vetoes the write. Fails closed: on any error the existing memory is kept and the unvalidated candidate is discarded. |
+
+Storage-level isolation (per-user home folder with exclusive owner ACL, see
+Storage Model) already prevents cross-user *access*; this policy governs
+cross-user and cross-client *content*.
+
+Note for follow-up client-memory work: this package is user memory only. A
+future client memory is a separate artefact with its own scoping and must not
+be built by loosening this policy — client-related durable knowledge is
+intentionally rejected here rather than stored under the user's profile.
 
 ## Storage Model
 
@@ -113,6 +130,27 @@ config = UserMemoryConfig(
 | `max_tokens` | `2000` | Maximum profile size. Must be between 500 and 8000 tokens. |
 | `root_folder` | `user-memory` | Subfolder name under each user's home folder (`/home-<user_id>/<root_folder>`) that holds the memory profile; also read as a legacy fallback at `/<root_folder>/<user_id>`. |
 
+## Observability
+
+The package registers Prometheus metrics on the shared `unique_toolkit.monitoring` registry (namespace `unique_user_memory`). They appear on whatever host already scrapes `GET /metrics` (assistants-core). Labels are closed enums — no company or user ids. LLM series include the model name so latency can be split per deployed model.
+
+QA dashboard: [User Memory](https://qa-grafana.alpine-bowfin.ts.net/d/unique-user-memory) (`unique-user-memory`). The dashboard is provisioned by the [assistants-core Helm chart](https://github.com/Unique-AG/monorepo/tree/master/python/assistants/bundles/core/deploy/helm-chart/files/grafana/dashboards).
+
+| Metric | Labels | What it answers |
+| --- | --- | --- |
+| `load_duration_seconds` / `load_total` | `outcome`: `success`, `empty`, `folder_failed`, `skipped_no_ids` | Is load slow? How often do we run without memory? |
+| `postprocessor_duration_seconds` / `postprocessor_total` | `outcome`: `updated`, `noop`, `upload_failed`, `skipped_no_ids`, `error` | Did this turn persist a new profile? |
+| `errors_total` | `stage`, `error_type` | Infra failures by stage (`folder_lookup`, `folder_create`, `download`, `upload`, `gate`, `consolidation`, `scrub`, `condense`, `postprocessor`). |
+| `llm_duration_seconds` / `llm_errors_total` | `purpose`: `gate`, `consolidation`, `scrub`, `condense`; `model`: the configured model name | Which LLM call is the latency or error hog, and how does that differ by model? |
+| `gate_decisions_total` | `decision`: `update`, `noop`, `fail_open` | Is the gate saving consolidations? Is fail-open spiking? |
+| `scrub_decisions_total` | `decision`: `clean`, `cleaned`, `veto` | CID/PII pass health. |
+| `consolidation_results_total` | `result`: `rewritten`, `noop`, `malformed`, `llm_error`, `scrub_veto`, `unchanged_after_scrub` | Why a rewrite did not persist. |
+| `storage_duration_seconds` / `storage_total` | `op`: `folder_lookup`, `folder_create`, `download`, `upload`; `outcome`: `success`, `error`, `not_found`, `refused_empty` | Is the content store the bottleneck? |
+| `memory_length_tokens` / `memory_length_chars` | `phase`: `load`, `write` | How large are profiles in tokens and characters versus `max_tokens`? |
+| `condense_total` | `trigger`: `load`, `post_consolidation`, `condense`; `result`: `llm_ok`, `hard_cut`, `llm_failed_then_hard_cut` | How often the budget shrink path fires. |
+
+Token usage for billing still flows through `LanguageModelInvocationStats`, not these series.
+
 ## Integration
 
 Typical orchestration code loads memory before the agent loop and registers the postprocessor for the same turn.

{unique_user_memory-2026.38.0.dev1 → unique_user_memory-2026.38.0.dev3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "unique_user_memory"
-version = "2026.38.0.dev1"
+version = "2026.38.0.dev3"
 description = ""
 authors = [
     { name = "Fabian Schläpfer", email = "fabian@unique.ch" },
@@ -11,8 +11,8 @@ requires-python = ">=3.12,<4"
 dependencies = [
     "jinja2>=3.1.6",
     "pydantic>=2.8.2",
-    "unique-sdk>=2026.38.0.dev1,<2026.38.0rc0",
-    "unique-toolkit>=2026.38.0.dev5,<2026.38.0rc0",
+    "unique-sdk>=2026.38.0.dev4,<2026.38.0rc0",
+    "unique-toolkit[monitoring]>=2026.38.0.dev14,<2026.38.0rc0",
 ]
 
 [dependency-groups]

unique_user_memory-2026.38.0.dev3/unique_user_memory/metrics.py

@@ -0,0 +1,229 @@
+from __future__ import annotations
+
+import time
+from collections.abc import Iterator
+from contextlib import contextmanager
+from typing import Protocol
+
+from unique_toolkit.monitoring import MetricNamespace
+
+
+class _ObservesSeconds(Protocol):
+    def observe(self, amount: float) -> None: ...
+
+
+m = MetricNamespace("unique_user_memory")
+
+_DURATION_BUCKETS = (0.1, 0.25, 0.5, 1.0, 2.0, 5.0, 10.0, 20.0, 30.0, 60.0)
+_TOKEN_BUCKETS = (
+    0.0,
+    100.0,
+    250.0,
+    500.0,
+    1000.0,
+    1500.0,
+    2000.0,
+    3000.0,
+    5000.0,
+    8000.0,
+)
+_CHAR_BUCKETS = (
+    0.0,
+    200.0,
+    500.0,
+    1000.0,
+    2000.0,
+    4000.0,
+    8000.0,
+    16000.0,
+    32000.0,
+)
+
+# End-to-end
+load_duration = m.histogram(
+    "load_duration_seconds",
+    "load_user_memory() duration",
+    [],
+    buckets=_DURATION_BUCKETS,
+)
+load_total = m.counter(
+    "load_total",
+    "Memory load attempts by outcome",
+    ["outcome"],
+)
+
+postprocessor_duration = m.histogram(
+    "postprocessor_duration_seconds",
+    "UserMemoryPostprocessor.run() duration",
+    [],
+    buckets=_DURATION_BUCKETS,
+)
+postprocessor_total = m.counter(
+    "postprocessor_total",
+    "Postprocessor runs by outcome",
+    ["outcome"],
+)
+
+errors = m.counter(
+    "errors_total",
+    "User memory infrastructure failures",
+    ["stage", "error_type"],
+)
+
+# LLM
+llm_duration = m.histogram(
+    "llm_duration_seconds",
+    "User memory LLM call duration",
+    ["purpose", "model"],
+    buckets=_DURATION_BUCKETS,
+)
+llm_errors = m.counter(
+    "llm_errors_total",
+    "User memory LLM call failures",
+    ["purpose", "model", "error_type"],
+)
+
+# Decisions
+gate_decisions = m.counter(
+    "gate_decisions_total",
+    "Consolidation gate decisions",
+    ["decision"],
+)
+scrub_decisions = m.counter(
+    "scrub_decisions_total",
+    "CID/PII scrub decisions",
+    ["decision"],
+)
+consolidation_results = m.counter(
+    "consolidation_results_total",
+    "Full-profile rewrite results",
+    ["result"],
+)
+
+# Storage
+storage_duration = m.histogram(
+    "storage_duration_seconds",
+    "Folder and content store latency",
+    ["op"],
+    buckets=_DURATION_BUCKETS,
+)
+storage_total = m.counter(
+    "storage_total",
+    "Folder and content store calls",
+    ["op", "outcome"],
+)
+
+# Size / budget
+memory_length_tokens = m.histogram(
+    "memory_length_tokens",
+    "Memory profile size in tokens",
+    ["phase"],
+    buckets=_TOKEN_BUCKETS,
+)
+memory_length_chars = m.histogram(
+    "memory_length_chars",
+    "Memory profile size in characters",
+    ["phase"],
+    buckets=_CHAR_BUCKETS,
+)
+condense_total = m.counter(
+    "condense_total",
+    "Over-budget condensation attempts",
+    ["trigger", "result"],
+)
+
+
+def record_error(stage: str, exc: BaseException) -> None:
+    errors.labels(stage=stage, error_type=type(exc).__name__).inc()
+
+
+def record_load(outcome: str) -> None:
+    load_total.labels(outcome=outcome).inc()
+
+
+def record_postprocessor(outcome: str) -> None:
+    postprocessor_total.labels(outcome=outcome).inc()
+
+
+def record_gate(decision: str) -> None:
+    gate_decisions.labels(decision=decision).inc()
+
+
+def record_scrub(decision: str) -> None:
+    scrub_decisions.labels(decision=decision).inc()
+
+
+def record_consolidation(result: str) -> None:
+    consolidation_results.labels(result=result).inc()
+
+
+def record_storage(op: str, outcome: str) -> None:
+    storage_total.labels(op=op, outcome=outcome).inc()
+
+
+def record_condense(trigger: str, result: str) -> None:
+    condense_total.labels(trigger=trigger, result=result).inc()
+
+
+def model_label(model_name: object) -> str:
+    """Stable Prometheus label for a language-model name (enum or string)."""
+    value = getattr(model_name, "value", model_name)
+    return str(value)
+
+
+def observe_memory_length(*, phase: str, content: str, tokens: float) -> None:
+    memory_length_tokens.labels(phase=phase).observe(tokens)
+    memory_length_chars.labels(phase=phase).observe(len(content))
+
+
+def condense_trigger(invocation_source: str) -> str:
+    if invocation_source == "user_memory_load_condense":
+        return "load"
+    if invocation_source == "user_memory_post_consolidation_condense":
+        return "post_consolidation"
+    return "condense"
+
+
+@contextmanager
+def observe_unlabeled(histogram: _ObservesSeconds) -> Iterator[None]:
+    """Time a block on a histogram that has no labels.
+
+    ``metric_scope`` always calls ``labels()``, which prometheus_client
+    rejects when the instrument was declared with an empty label set.
+    """
+    start = time.perf_counter()
+    try:
+        yield
+    finally:
+        histogram.observe(time.perf_counter() - start)
+
+
+__all__ = [
+    "condense_total",
+    "condense_trigger",
+    "consolidation_results",
+    "errors",
+    "gate_decisions",
+    "llm_duration",
+    "llm_errors",
+    "load_duration",
+    "load_total",
+    "memory_length_chars",
+    "memory_length_tokens",
+    "model_label",
+    "observe_memory_length",
+    "observe_unlabeled",
+    "postprocessor_duration",
+    "postprocessor_total",
+    "record_condense",
+    "record_consolidation",
+    "record_error",
+    "record_gate",
+    "record_load",
+    "record_postprocessor",
+    "record_scrub",
+    "record_storage",
+    "scrub_decisions",
+    "storage_duration",
+    "storage_total",
+]