Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 3 additions & 1 deletion docs/architecture/clickhouse.md
Original file line number Diff line number Diff line change
Expand Up @@ -366,7 +366,9 @@ Operators can add retention to `audit_log`, `agent_events`, `memory`, `memory_em
`conversations`, `chunks` and `documents` with `LOOM_RETENTION_<TABLE>_DAYS`, and tiering
with `LOOM_TIERING_<TABLE>_WARM_DAYS` plus `LOOM_TIERING_WARM_VOLUME_NAME`. Per-namespace
`retention_days` or `warm_days` overrides become a `multiIf` in the same TTL expression
(`server/storage/retention_overrides.py`). The worker leader applies them at boot and
(`server/storage/retention_overrides.py`). Audit deletion uses only its dedicated
`LOOM_RETENTION_AUDIT_LOG_DAYS`; namespace `warm_days` can still tier audit rows.
The worker leader applies them at boot and
`retention_reconcile` keeps them in step, skipping unchanged tables because each
`MODIFY TTL` is a mutation. When the last window on a table is cleared, the same pass
issues `ALTER TABLE … REMOVE TTL`; none of these tables has a schema TTL. Every window
Expand Down
2 changes: 1 addition & 1 deletion docs/architecture/storage-layout.md
Original file line number Diff line number Diff line change
Expand Up @@ -1137,7 +1137,7 @@ it holds no provider identity or credential.
| `events` | MT `(org, namespace, kind, ts)`, by `toYYYYMM(ts)`, TTL | stays | Log | census, `events.delete`, user scope too | — | the event stream, 30-day TTL; named in `server/observability/events_stream.py`, `server/insights/store/admin.py` |
| `agent_events` | MT `(org, namespace, agent, ts)`, by `toYYYYMM(ts)` | stays | Log | step `agent_events.scrub` | — | ordinary op ledger, monthly partitions; named in `server/observability/events.py` |
| `agent_events_private` | MT `(org, namespace, agent, ts)`, by `toYYYYMM(ts)` | stays | Log | step `agent_events.scrub` | — | marked requests and mirror-worker events, without analyst grants; named in `server/observability/events.py` |
| `audit_log` | MT `(org, namespace, event_type, ts)`, by `toYYYYMM(ts)` | stays | Log | no content | — | hash-only audit rows, kept unless an operator's retention (`retention_reconcile`) expires them; named in `server/memory/store/pg_publish.py`, `server/observability/audit.py` |
| `audit_log` | MT `(org, namespace, event_type, ts)`, by `toYYYYMM(ts)` | stays | Log | no content | — | hash-only audit rows, kept unless the dedicated audit retention expires them; namespace retention does not expire audit rows; named in `server/memory/store/pg_publish.py`, `server/observability/audit.py` |
| `audit_checkpoints` | MT `window_start` | stays | Log | no content | — | verifier checkpoints over windows of `audit_log` across every org; named in `server/insights/store/audit.py`, `server/observability/otel_probes.py` |
| `search_trace_log` | MT `(org, namespace, ts)`, by `toYYYYMM(ts)`, TTL | stays | Log | census, `search_trace_log.delete` | — | search traces, 180-day TTL; named in `server/insights/store/deploy_delta.py`, `server/tasks/store/runs.py` |
| `search_misses` | MT `(org, namespace, ts)`, by `toYYYYMM(ts)`, TTL | stays | Log | census, `search_misses.delete`, user scope too | — | searches that found nothing, normalised query and asker only, 16-day TTL; named in `server/knowledge/store/gaps.py`, `server/erasure/store/steps_ledgers.py` |
Expand Down
5 changes: 5 additions & 0 deletions docs/features/memory/retention-and-erasure.md
Original file line number Diff line number Diff line change
Expand Up @@ -85,6 +85,11 @@ Postgres still serves, so the boot refuses `LOOM_RETENTION_MEMORY_DAYS`,
`retention_days` leaves `chunks` too, so a document that stays keeps the chunks search
finds it by; `LOOM_RETENTION_CHUNKS_DAYS` still applies.

Namespace `retention_days` never expires `audit_log` rows. Only
`LOOM_RETENTION_AUDIT_LOG_DAYS` sets their deletion window; its default of 0 keeps them
indefinitely. Namespace `warm_days` can still move audit rows to warm storage. Removing a
namespace retention window does not change the deployment's explicit audit retention.

The `retention_reconcile` worker applies the last two rows as one idempotent
`ALTER TABLE … MODIFY TTL` per table, per `(org, namespace)` when overrides exist, and
removes a table's TTL once no namespace and no deployment window is left on it. On
Expand Down
3 changes: 2 additions & 1 deletion docs/operations/maintenance.md
Original file line number Diff line number Diff line change
Expand Up @@ -190,7 +190,8 @@ the retention gauges (`loom.retention.*`) only count candidates.
`memory`, `memory_embeddings`, `conversations`, `chunks` and `documents`.
- **Per namespace.** `retention_days` in the namespace's registration
(`namespace.register`); the managed tables' TTL becomes one `multiIf` over every
namespace that sets it.
namespace that sets it. Audit deletion uses only `LOOM_RETENTION_AUDIT_LOG_DAYS`;
namespace `warm_days` still applies to audit tiering.
- The workers' leader applies the `MODIFY TTL` at boot. After that only the
`retention_reconcile` worker writes table TTLs, so a policy change reaches the tables
within `LOOM_RETENTION_RECONCILE_INTERVAL_SECONDS` and a burst of registrations does
Expand Down
2 changes: 1 addition & 1 deletion docs/reference/configuration.md
Original file line number Diff line number Diff line change
Expand Up @@ -1872,7 +1872,7 @@ Opt-in retention, applied as idempotent ALTER TABLE MODIFY TTL by server/storage

| Variable | Type | Default | Live | Meaning |
| --- | --- | --- | --- | --- |
| `LOOM_RETENTION_AUDIT_LOG_DAYS` | `int` | `0` | | Days `loom.audit_log` rows are kept; 0 = forever. A person's Undo of a retirement holds by its record there: one aged out stops holding, and the conflict resolver may judge and retire that pair again. |
| `LOOM_RETENTION_AUDIT_LOG_DAYS` | `int` | `0` | | Days `loom.audit_log` rows are kept; 0 = forever, independent of namespace retention. A person's Undo of a retirement holds by its record there: one aged out stops holding, and the conflict resolver may judge and retire that pair again. |
| `LOOM_RETENTION_AGENT_EVENTS_DAYS` | `int` | `0` | | Days `loom.agent_events` rows are kept; 0 = forever. |
| `LOOM_RETENTION_MEMORY_DAYS` | `int` | `0` | | Days `loom.memory` rows are kept; 0 = forever. The Postgres authority refuses it. |
| `LOOM_RETENTION_MEMORY_EMBEDDINGS_DAYS` | `int` | `0` | | Days `loom.memory_embeddings` rows are kept; 0 = forever. The Postgres authority refuses it. |
Expand Down
7 changes: 4 additions & 3 deletions loom.example.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -5300,9 +5300,10 @@ settings:
# server/storage/retention_overrides.py: a retention_*_days setting deletes a table's
# rows older than that many days.

# Days `loom.audit_log` rows are kept; 0 = forever. A person's Undo of a retirement
# holds by its record there: one aged out stops holding, and the conflict resolver may
# judge and retire that pair again. [restart]
# Days `loom.audit_log` rows are kept; 0 = forever, independent of namespace
# retention. A person's Undo of a retirement holds by its record there: one aged out
# stops holding, and the conflict resolver may judge and retire that pair again.
# [restart]
# retention_audit_log_days: 0

# Days `loom.agent_events` rows are kept; 0 = forever. [restart]
Expand Down
2 changes: 1 addition & 1 deletion schemas/loom-settings.schema.json
Original file line number Diff line number Diff line change
Expand Up @@ -6339,7 +6339,7 @@
"retention_audit_log_days": {
"default": 0,
"type": "integer",
"description": "Days `loom.audit_log` rows are kept; 0 = forever. A person's Undo of a retirement holds by its record there: one aged out stops holding, and the conflict resolver may judge and retire that pair again."
"description": "Days `loom.audit_log` rows are kept; 0 = forever, independent of namespace retention. A person's Undo of a retirement holds by its record there: one aged out stops holding, and the conflict resolver may judge and retire that pair again."
},
"retention_chunks_days": {
"default": 0,
Expand Down
6 changes: 3 additions & 3 deletions server/settings/catalog.py
Original file line number Diff line number Diff line change
Expand Up @@ -5551,9 +5551,9 @@ class StorageSettings(BaseModel):
# server/storage/retention_overrides.py: a retention_*_days setting deletes a table's
# rows older than that many days.
# ---- retention ----
# Days `loom.audit_log` rows are kept; 0 = forever. A person's Undo of a
# retirement holds by its record there: one aged out stops holding, and the
# conflict resolver may judge and retire that pair again.
# Days `loom.audit_log` rows are kept; 0 = forever, independent of namespace retention.
# A person's Undo of a retirement holds by its record there: one aged out stops
# holding, and the conflict resolver may judge and retire that pair again.
retention_audit_log_days: int = 0
# Days `loom.agent_events` rows are kept; 0 = forever.
retention_agent_events_days: int = 0
Expand Down
7 changes: 5 additions & 2 deletions server/storage/retention_overrides.py
Original file line number Diff line number Diff line change
Expand Up @@ -12,8 +12,8 @@
means no TTL: a table that still carries one from an earlier pass gets
`ALTER TABLE … REMOVE TTL` (none of the managed tables has a schema TTL).

Per-namespace retention applies uniformly across every managed table;
per-table-per-namespace granularity is deliberately not exposed.
Namespace retention never expires audit rows; their retention comes only from
the audit setting. Namespace tiering may still move them to warm storage.
"""

from __future__ import annotations
Expand Down Expand Up @@ -253,6 +253,9 @@ def compute_alters(
r_days = max(0, target.retention_days(settings_obj) or 0)
t_days = max(0, target.warm_days(settings_obj) or 0)
overrides = ovr_all
if target.table == "loom.audit_log":
# Memory retention must not erase the evidence of its own deletion.
overrides = [{**o, "retention_days": 0} for o in ovr_all]
if target.table in (*_PG_HELD, "loom.chunks") and pg.enabled():
# Postgres holds memory and document heads: a TTL here would delete only
# ClickHouse's copy (or only its vectors, leaving live memories search no
Expand Down
37 changes: 17 additions & 20 deletions tests/integration/test_repositories_live_ch.py
Original file line number Diff line number Diff line change
Expand Up @@ -335,6 +335,13 @@ async def _drain(attempts: int = 120) -> None:
await asyncio.sleep(0.5)

try:
for table in managed:
row = await ch.query_one(
"SELECT engine_full FROM system.tables WHERE database='loom' AND name={name:String}",
{"name": table.removeprefix("loom.")},
)
if " TTL " in str((row or {}).get("engine_full", "")):
await ch.execute(f"ALTER TABLE {table} REMOVE TTL")
# apply() leaves a table alone while it has
# unfinished mutations (an earlier test's DELETE may still be
# running on this shared service) and the reconcile worker retries
Expand All @@ -350,14 +357,18 @@ async def _drain(attempts: int = 120) -> None:
namespace_overrides=overrides,
leader=True,
)
if n >= 8:
if n >= 7:
break
await _drain()
assert n == 8 # one ALTER per managed table
assert n == 7 # Audit retention is configured independently.

row = await ch.query_one(
audit = await ch.query_one(
"SELECT engine_full FROM system.tables WHERE database='loom' AND name='audit_log'",
)
assert "TTL" not in (audit or {}).get("engine_full", "")
row = await ch.query_one(
"SELECT engine_full FROM system.tables WHERE database='loom' AND name='agent_events'",
)
engine_full = (row or {}).get("engine_full", "")
assert "multiIf" in engine_full
assert f"'{test_org}'" in engine_full
Expand All @@ -368,25 +379,11 @@ async def _drain(attempts: int = 120) -> None:
assert "2099" in engine_full

finally:
try:
for t in (
"loom.audit_log",
"loom.agent_events",
"loom.memory_embeddings",
"loom.conversations",
"loom.chunks",
"loom.documents",
):
try:
await ch.execute(f"ALTER TABLE {t} REMOVE TTL")
except Exception: # noqa: BLE001 — teardown: a table may lack a TTL; must not raise
pass
for t in managed:
try:
await ch.execute("ALTER TABLE loom.memory REMOVE TTL")
except Exception: # noqa: BLE001 — teardown: memory may lack a TTL; must not raise
await ch.execute(f"ALTER TABLE {t} REMOVE TTL")
except Exception: # noqa: BLE001 — teardown: a table may lack a TTL; must not raise
pass
except Exception: # noqa: BLE001 — teardown must not raise
pass


def dataclass_compat(cls):
Expand Down
Loading