You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
The Temporal Gradient outputs **Internal State Telemetry** rather than conventional debug lines. The goal is to show how internal time (τ) and memory retention respond to salience.
3
-
Canonical module references and compatibility shims are listed in [`docs/CANONICAL_SURFACES.md`](docs/CANONICAL_SURFACES.md).
1
+
# Usage
4
2
3
+
Temporal Gradient outputs **internal state telemetry** — packets that show
4
+
how internal time (τ) and memory retention respond to salience. This guide
5
+
covers the packet contract, configuration knobs, and the salience
6
+
components shipped by default.
5
7
6
-
## 0. Telemetry contract (canonical vs extended)
7
-
The telemetry packet is versioned and split into **required** vs **optional** keys.
8
-
For canonical symbol/module ownership (including telemetry validators and compatibility aliases), see [`docs/CANONICAL_SURFACES.md`](docs/CANONICAL_SURFACES.md).
8
+
See [`architecture.md`](architecture.md) for the data-flow diagram and
9
+
public API surface.
9
10
10
-
### Packet API contract
11
-
-`to_packet()` => returns the packet as a `dict` mapping for schema checks and in-memory processing.
12
-
-`to_packet_json()` => returns serialized JSON `str` for transport/logging boundaries.
13
-
- Avoid `json.loads(to_packet())`; parse only the JSON text returned by `to_packet_json()`.
11
+
## Telemetry packet contract
14
12
15
-
**Required keys (canonical schema):**
16
-
-`SCHEMA_VERSION`
17
-
-`WALL_T`
18
-
-`TAU`
19
-
-`SALIENCE`
20
-
-`CLOCK_RATE`
21
-
-`MEMORY_S`
22
-
-`DEPTH`
13
+
-`to_packet()` returns a `dict` for schema checks and in-memory processing.
14
+
-`to_packet_json()` returns a JSON string for transport or logging.
`CLOCK_RATE` and `MEMORY_S` are always present in canonical packets. If unset at construction time, serialization currently emits numeric fallbacks (`0.0`), not `null`.
`SCHEMA_VERSION` policy is strict: canonical serialization must emit exactly `"1.0"`. For migration input only, validators accept legacy `"1"` and normalize it to `"1.0"` on canonical re-serialization.
21
+
`SCHEMA_VERSION` must be exactly `"1.0"`. `CLOCK_RATE` and `MEMORY_S` fall
22
+
back to `0.0` when unset at construction time.
31
23
32
-
CLI tables should print **only canonical columns** by default (`WALL_T`, `TAU`, `SALIENCE`, `CLOCK_RATE`, `MEMORY_S`, `DEPTH`). Extended fields like `H` and `V` are intended for verbose/debug output, not the base schema. Demo scripts may also include an `INPUT` column for readability; it is not part of the canonical packet schema.
24
+
### Example packet
33
25
34
-
### Legacy mode compatibility (`legacy_density`)
35
-
`legacy_density` is a migration-only mode. It is not the canonical telemetry contract.
36
-
37
-
Behavior summary:
38
-
- Salience is derived from entropy density and clamped into `[0,1]`.
39
-
- Canonical telemetry schema strictness is intentionally bypassed.
40
-
41
-
Compatibility entry points referenced in this section are cataloged in [`docs/CANONICAL_SURFACES.md`](docs/CANONICAL_SURFACES.md).
42
-
43
-
Packet-shape examples:
44
-
45
-
Canonical packet (preferred):
46
26
```json
47
27
{
48
28
"SCHEMA_VERSION": "1.0",
@@ -57,19 +37,7 @@ Canonical packet (preferred):
57
37
}
58
38
```
59
39
60
-
Legacy compatibility packet (allowed only in `legacy_density` mode):
61
-
```json
62
-
{
63
-
"WALL_T": 1.0,
64
-
"TAU": 0.15,
65
-
"SALIENCE": 0.9,
66
-
"DEPTH": 0
67
-
}
68
-
```
69
-
70
-
See `docs/CANONICAL_VS_LEGACY.md` for the full migration guidance and deprecation horizon.
-**TAU:** Internal time accumulator after clock-rate reparameterization.
107
-
-**SALIENCE:** Surprise×value score from the valuator.
108
-
-**CLOCK_RATE (dτ/dt):** Internal clock multiplier after salience modulation.
109
-
110
-
Interpretation:
111
-
- A CLOCK RATE below 1.0x means the internal clock slowed to process a high-load event (reduced internal clock rate), not “bullet time.”
112
-
- 1.0x indicates the baseline clock rate.
67
+
-**WALL_T** — external time elapsed (seconds).
68
+
-**TAU** — internal time accumulator after clock-rate reparameterization.
69
+
-**SALIENCE** — Ψ = H × V from the salience pipeline.
70
+
-**CLOCK_RATE** — dτ/dt. Below 1.0 means the internal clock slowed to
71
+
process a high-load event. 1.0 is the baseline.
113
72
114
-
## 2. The entropy sweep (memory audit)
115
-
At the end of the simulation, the decay engine reports which memories stayed above the retention threshold.
73
+
## Memory audit (post-simulation)
116
74
117
75
```
118
-
>>> MEMORY AUDIT (Post-Simulation)
119
-
[ALIVE] Strength: 1.42 | Content: "My name is Sentinel."
120
-
[PRUNED ] Content: "Rain. Water. Liquid."
76
+
[ALIVE] Strength: 1.42 | Content: "My name is Sentinel."
77
+
[PRUNED] Content: "Rain. Water. Liquid."
121
78
```
122
79
123
-
-**ALIVE:**The memory stayed above the pruning threshold because it started with high salience or was reconsolidated.
124
-
-**PRUNED:**The memory decayed below the threshold and was pruned.
80
+
-**ALIVE**— above the pruning threshold.
81
+
-**PRUNED**— decayed below the threshold and removed by the entropy sweep.
125
82
126
-
## 3. Configuration hints
127
-
Adjust these parameters in `simulation_run.py` and the supporting modules to shape the simulation (canonical policy surface: `temporal_gradient.policies.compute_cooldown`):
128
-
-`base_dilation_factor` and `min_clock_rate` in `ClockRateModulator` to control the clock-rate floor and sensitivity to salience load.
129
-
-`half_life` in `DecayEngine` to control decay speed.
130
-
- Reconsolidation cooldowns and diminishing returns in `EntropicMemory.reconsolidate` to avoid runaway reinforcement.
83
+
## Configuration knobs
131
84
132
-
## 4. Salience components (H/V)
133
-
The salience pipeline currently decomposes **H (novelty)** and **V (value)** into two concrete components with constrained inputs and normalized outputs.
-`policies.cooldown_tau` — compute eligibility window on internal time.
90
+
91
+
## Salience components
134
92
135
93
### RollingJaccardNovelty (H)
136
-
-**Operational definition:** Compute tokens from the incoming text, compare against a rolling history window, and take `1 - max_jaccard_similarity` across the window. The history stores the most recent **5** token sets (default `window_size=5`).
137
-
-**Tokenization:** Lowercase and split on the regex pattern `[a-z0-9']+` to form a unique token set.
138
-
-**Allowed inputs:** Current message text **plus** the internal rolling history (no external context).
139
-
-**Normalization:** Jaccard similarity is in `[0,1]`, so novelty output is normalized to `[0,1]`.
140
-
-**Swap-friendly note:** This component can be replaced with an embedding-based novelty scorer, provided the output stays normalized to `[0,1]` and only uses the current text plus an internal memory of prior text.
94
+
95
+
Tokenize the incoming text, compare against a rolling history window of
0 commit comments