Module trajectory 

Trajectory Memory Module

High-performance algorithms for trajectory-structured memory, implementing concepts from IRCP (Inverse Ring Contextual Propagation) and RCP (Ring Contextual Propagation).

Components

Module	Purpose
graph	DAG traversal, path finding, branch detection
phase	Phase inference from episode patterns
salience	Importance weighting for bounded forgetting
ring	Circular topology for multi-scale context (includes DualRing)
coordinate	5D positioning system (DLM coordinates with complexity)
coordinate_tree	Tree operations with O(log n) LCA via binary lifting
conservation	Conservation metrics for forgetting validation
ircp	Inverse Ring Contextual Propagation attention
chainlink	ChainLink interaction framework with 4-component estimation
branch	Branch state machine for split/merge/recover operations
chain	Multi-chain management for conversation tracking

Conceptual Framework

• Trajectory: A sequence of experiences (episodes) forming a path through time
• Episode: A unit of experience (message turn, interaction, decision point)
• Phase: A qualitative state within a trajectory:
  • Exploration: Initial inquiry, questions, topic discovery
  • Consolidation: Building understanding, code implementation
  • Synthesis: Summarization, decisions, conclusions
  • Debugging: Error resolution, troubleshooting
  • Planning: Roadmaps, structured plans
• Salience: Importance weight [0, 1] for bounded forgetting
• Conservation: Metrics ensuring memory operations preserve invariants

Coordinate System (5D DLM)

Each episode has a 5D position (extending TPO with complexity):

Dimension	Type	Meaning
depth	u32	Distance from root (0 = root)
sibling_order	u32	Position among siblings
homogeneity	f32	Semantic similarity to parent [0, 1]
temporal	f32	Normalized timestamp [0, 1]
complexity	u32	Message complexity (n_parts from DLM)

Dual Ring Structure (IRCP/RCP)

The DualRing provides two simultaneous orderings over the same episodes:

Ring	Direction	Ordering	Use Case
Temporal (RCP)	Forward	Time/causal sequence	“What context led here?”
Influence (IRCP)	Inverse	By influence weight	“What had most impact?”

Temporal Ring (RCP):     [E₀] → [E₁] → [E₂] → [E₃] → [E₄] ─┐
                           ↑                                 │
                           └─────────────────────────────────┘

Influence Ring (IRCP):   [E₂] → [E₄] → [E₀] → [E₃] → [E₁] ─┐
                           ↑     (sorted by influence)      │
                           └────────────────────────────────┘

Conservation Laws

Per RCP, memory operations should preserve:

Law	Formula	Meaning
Magnitude	Σ aᵢ‖eᵢ‖ = const	Context doesn’t disappear
Energy	½Σᵢⱼ aᵢaⱼ cos(eᵢ,eⱼ)	Attention capacity conserved
Information	-Σ aᵢ log(aᵢ)	Shannon entropy of attention

Performance

These algorithms are implemented in Rust for performance because they run repeatedly during retrieval and corpus maintenance. Key optimizations:

• SIMD-accelerated distance computations (via distance module)
• Cache-friendly contiguous storage in Ring topology
• O(1) neighbor access in ring structure
• Efficient hash-based DAG traversal

Example Usage

use rag_plusplus_core::trajectory::{
    TrajectoryGraph, Edge, EdgeType, PathSelectionPolicy,
    PhaseInferencer, TurnFeatures, TrajectoryPhase,
    SalienceScorer, SalienceFactors, Feedback,
    Ring, TrajectoryCoordinate,
    ConservationMetrics,
};

// Build trajectory graph from edges
let edges = vec![
    Edge { parent: 1, child: 2, edge_type: EdgeType::Continuation },
    Edge { parent: 2, child: 3, edge_type: EdgeType::Continuation },
];
let graph = TrajectoryGraph::from_edges(edges.iter().copied());

// Find primary path through DAG
let primary = graph.find_primary_path(PathSelectionPolicy::FeedbackFirst);

// Infer phases from episode features
let inferencer = PhaseInferencer::new();
let features = TurnFeatures::from_content(1, "user", "What is this?");
let (phase, confidence) = inferencer.infer_single(&features).unwrap();

// Compute salience scores
let scorer = SalienceScorer::new();
let factors = SalienceFactors {
    turn_id: 1,
    feedback: Some(Feedback::ThumbsUp),
    ..Default::default()
};
let salience = scorer.score_single(&factors, None);

// Build ring structure
let ring = Ring::new(vec![1, 2, 3, 4, 5]);
let distance = ring.ring_distance(0, 3); // Shortest path: 2

// Validate conservation
let embeddings = vec![vec![1.0, 0.0, 0.0], vec![0.0, 1.0, 0.0]];
let refs: Vec<&[f32]> = embeddings.iter().map(|e| e.as_slice()).collect();
let attention = vec![0.5, 0.5];
let metrics = ConservationMetrics::compute(&refs, &attention);

Re-exports

pub use conservation::ConservationMetrics;

pub use conservation::ConservationViolation;

pub use conservation::ConservationConfig;

pub use conservation::ConservationTracker;

pub use conservation::weighted_centroid;

pub use conservation::weighted_covariance;

pub use coordinate::TrajectoryCoordinate;

pub use coordinate::NormalizedCoordinate;

pub use coordinate::TrajectoryCoordinate5D;

pub use coordinate::NormalizedCoordinate5D;

pub use coordinate::DLMWeights;

pub use coordinate::compute_trajectory_coordinates;

pub use graph::TrajectoryGraph;

pub use graph::Episode;

pub use graph::Edge;

pub use graph::EdgeType;

pub use graph::NodeId;

pub use graph::PathSelectionPolicy;

pub use graph::TraversalOrder;

pub use graph::BranchInfo;

pub use graph::PathResult;

pub use phase::TrajectoryPhase;

pub use phase::PhaseInferencer;

pub use phase::PhaseConfig;

pub use phase::TurnFeatures;

pub use phase::PhaseTransition;

pub use phase::ConversationPhase;Deprecated

pub use ring::Ring;

pub use ring::RingNode;

pub use ring::EpisodeRing;

pub use ring::build_weighted_ring;

pub use ring::DualRing;

pub use ring::DualRingNode;

pub use ring::build_dual_ring;

pub use ring::build_dual_ring_with_attention;

pub use path_quality::PathQuality;

pub use path_quality::PathQualityWeights;

pub use path_quality::PathQualityFactors;

pub use salience::SalienceScorer;

pub use salience::SalienceConfig;

pub use salience::SalienceFactors;

pub use salience::TurnSalience;

pub use salience::CorpusSalienceStats;

pub use salience::Feedback;

pub use ircp::IRCPPropagator;

pub use ircp::IRCPConfig;

pub use ircp::AttentionWeights;

pub use ircp::batch_compute_attention;

pub use ircp::compute_attention_matrix;

pub use chainlink::ChainLink;

pub use chainlink::ChainLinkEstimator;

pub use chainlink::ChainLinkEstimatorConfig;

pub use chainlink::ChainLinkEstimate;

pub use chainlink::LinkType;

pub use chainlink::compute_chain_matrix;

pub use chainlink::find_strongest_links;

pub use coordinate_tree::CoordinateTree;

pub use coordinate_tree::TreeNode;

pub use coordinate_tree::build_coordinate_tree;

pub use branch::BranchStateMachine;

pub use branch::BranchContext;

pub use branch::SplitResult;

pub use branch::MergeResult;

pub use branch::Branch;

pub use branch::BranchId;

pub use branch::BranchOperation;

pub use branch::BranchStatus;

pub use branch::ForkPoint;

pub use branch::BranchError;

pub use branch::BranchResolver;

pub use branch::RecoverableBranch;

pub use branch::RecoveryStrategy;

pub use branch::LostReason;

pub use chain::ChainManager;

pub use chain::ChainId;

pub use chain::ChainMetadata;

pub use chain::ChainManagerConfig;

pub use chain::ChainManagerError;

pub use chain::ChainManagerStats;

pub use chain::CrossChainLink;

pub use chain::CrossChainLinkType;

pub use chain::LinkStrength;

pub use chain::find_cross_chain_links;

pub use chain::detect_knowledge_transfer;

pub use chain::KNOWLEDGE_TRANSFER_PATTERNS;

Modules

branch

Branch Management Module

chain

Chain Management Module

chainlink

ChainLink Interaction Framework

conservation

Conservation Metrics for Bounded Forgetting

coordinate

Trajectory Coordinate System

coordinate_tree

Coordinate Tree with LCA (Lowest Common Ancestor) Algorithm

graph

DAG Traversal Algorithms for Trajectory Structure

ircp

I-RCP (Inverse Ring Contextual Propagation) Module

path_quality

Path Quality Computation

phase

Phase Inference Rules Engine

ring

Ring Topology for Trajectory Memory

salience

Salience Scoring System