Skip to content

README.md

Latest commit

 

History

History
135 lines (88 loc) · 5.89 KB

README.md

File metadata and controls

135 lines (88 loc) · 5.89 KB

Trajectory-Based Drift Detection in Stratified Agent Memory

This repository contains a minimal deterministic research demo for the short paper Trajectory-Based Drift Detection in Stratified Agent Memory. It shows how coherence decay can be detected as deviation in the trajectory of updates across three stratified memory tiers.

The demo is intentionally small and inspectable:

  • no machine learning
  • no randomness
  • no web app
  • fixed scripted sequence only
  • plain Python with one matplotlib plot

What this repo shows

A system can remain locally valid at each step while still losing coherence over time. This demo uses a deterministic three-tier memory model to show that contradiction produces a staged pattern rather than a single failure event:

  • an immediate break in update direction
  • delayed cross-tier misalignment
  • a later reversal during recovery

These effects are measurable using simple metrics computed from existing tier states and update relations. No new subsystem is introduced.

Why this matters

Most systems evaluate behavior one timestep at a time: is a given update valid or not?

This demo shows why that is not enough. A system can remain locally admissible at every step while still drifting away from its prior internal trajectory. That drift may not appear as a single error or violation. Instead, it emerges as a pattern across time:

  • directional instability appears first
  • structural misalignment follows
  • reversal occurs later during recovery

Detecting this requires evaluating the path of updates, not just isolated steps.

Repository contents

  • drift_demo.py: runs the scripted sequence, computes metrics, writes the CSV, and saves the plot
  • model.py: deterministic update rules for the three memory tiers
  • metrics.py: helper functions for the three drift metrics
  • outputs/trace.csv: replayable per-timestep trace
  • outputs/drift_plot.png: one figure showing the three metrics across time
  • LICENSE: license for this repository

How to run

This workspace includes a local virtual environment with matplotlib installed. Run:

.venv/bin/python drift_demo.py

If you prefer to use another Python environment, install matplotlib there first, then run:

python3 drift_demo.py

The script writes outputs into outputs/.

Model structure

Tiers

  • m(t): short-term state, updates fastest toward the current scripted input
  • u(t): intermediate state, follows m(t) at a moderate rate
  • a(t): structural state, follows u(t) slowly and therefore lags behind sudden changes

Phases

The scripted sequence has four phases:

  1. stable: repeated aligned input; directional continuity stays high
  2. gradual_shift: the input direction bends gradually; the path changes without a sharp break
  3. contradiction: the input flips to an opposing direction; u(t) changes course quickly while a(t) lags, creating visible divergence and a directional break
  4. recovery: the input moves back toward the earlier direction; coherence is partially restored and divergence begins to contract

Metrics

  • update_magnitude: the norm of the intermediate update, ||Δu(t)||
  • cross_tier_divergence: the distance between intermediate and structural state, ||u(t) - a(t)||
  • directional_break: cosine similarity between consecutive intermediate updates, cos(Δu(t), Δu(t-1))

Values near 1 indicate directional continuity. Values near 0 indicate a sharp redirection. Negative values indicate reversal.

Relation to paper claim

This demo illustrates that coherence decay can be detected as deviation in the trajectory of stratified memory updates across time, using simple deterministic metrics rather than stochastic interpretation.

Interpreting the figure

  • update strength = how strong the intermediate-state change is at a timestep
  • tier misalignment = how far intermediate and structural memory differ
  • trajectory break = whether the direction of intermediate updates remained consistent or reversed

In the current run:

  • stable phase: low drift, high directional continuity
  • gradual shift: path bends without a hard break
  • contradiction begins at t=10, where update strength jumps and trajectory break drops sharply
  • tier misalignment peaks at t=12
  • strongest directional break appears at t=13, where the trajectory reverses
  • later steps show recovery and re-alignment

Minimal takeaways

  • Drift is not a single anomaly; it is a time-extended pattern.
  • Directional break is the earliest clear signal.
  • Cross-tier divergence lags directional disturbance.
  • Recovery has its own signature rather than being only the absence of error.
  • All three signals are computed from existing state.

Figure

Deterministic trajectory drift plot

Deterministic trajectory-drift micro-run. The contradiction phase begins at t=10, producing an immediate rise in update strength and a sharp drop in trajectory continuity. Misalignment between intermediate and structural memory peaks at t=12, followed by the strongest directional break at t=13, where the update path reverses. Later steps show re-alignment and partial recovery.

Reading the output

outputs/trace.csv records each timestep with the scripted input, tier states, intermediate update vector, and the three metrics. outputs/drift_plot.png shows all three metrics on one shared timeline so the contradiction phase is easy to inspect and cite.

License

This project is licensed under the Creative Commons Attribution-NonCommercial 4.0 International license. See LICENSE and the official Creative Commons legal code:

Contact