Struct ProceduralMemory 

pub struct ProceduralMemory { /* private fields */ }

Procedural memory for storing learned action sequences with confidence scoring.

Stores procedures as embedding vectors with associated metadata. Supports confidence-based recall, reinforcement learning, and TTL expiration.

ACT-R activation decay

When built with with_activation_decay, the confidence returned by recall is modulated by the ACT-R base-level power-law formula: c × max(1, t_days)^(-d) where d is the decay exponent (Anderson 1996, default ≈ 0.5). The stored value is unchanged — decay is applied read-only at retrieval time.

Implementations

impl ProceduralMemory

pub fn collection_name(&self) -> &str

Returns the name of the underlying VelesDB collection.

pub fn dimension(&self) -> usize

Returns the embedding dimension for this collection.

pub fn new_from_db( db: Arc<Database>, dimension: usize, ) -> Result<Self, AgentMemoryError>

Creates or opens procedural memory.

Errors

Returns an error when collection creation/opening fails or dimensions mismatch.

pub fn with_reinforcement_strategy( self, strategy: Arc<dyn ReinforcementStrategy>, ) -> Self

Overrides the default reinforcement strategy with a custom implementation.

pub fn with_activation_decay(self, decay_exponent: f32) -> Self

Enables ACT-R base-level activation decay at recall time.

When set, the confidence returned by recall is multiplied by max(1, t_days)^(-decay_exponent) where t_days is the number of days since the procedure was last reinforced.

The stored confidence is not modified — decay is applied read-only. ACT-R recommends decay_exponent ≈ 0.5 (Anderson 1996).

pub fn learn( &self, procedure_id: u64, name: &str, steps: &[String], embedding: Option<&[f32]>, confidence: f32, ) -> Result<(), AgentMemoryError>

Learns a procedure and stores it in memory.

Errors

Returns an error when embedding dimension is invalid, the collection is unavailable, or persistence fails.

pub fn learn_with_ttl( &self, procedure_id: u64, name: &str, steps: &[String], embedding: Option<&[f32]>, confidence: f32, ttl_seconds: u64, ) -> Result<(), AgentMemoryError>

Learns a procedure and assigns a TTL for auto-expiration.

A ttl_seconds of 0 means “expire immediately”: the procedure is eagerly removed (and any pre-existing point for procedure_id deleted), harmonising the behaviour with SemanticMemory::store_with_ttl. The embedding is still dimension-validated so callers get the same error contract as a real learn.

The expiry is persisted as a reserved _veles_expires_at (epoch seconds) payload field, so the TTL survives a process restart: the in-memory map is rebuilt from payloads when the collection is reopened.

Errors

Returns the same errors as Self::learn.

pub fn set_ttl_durable( &self, procedure_id: u64, ttl_seconds: u64, ) -> Result<(), AgentMemoryError>

Durably sets (or refreshes) the TTL of an existing procedure.

Unlike AgentMemory::set_procedural_ttl (in-memory map only, lost on restart), this persists the expiry to the reserved _veles_expires_at payload field, so it survives a restart. A ttl_seconds of 0 expires the procedure immediately.

Errors

Returns NotFound when no procedure with procedure_id exists, or CollectionError when persistence fails.

pub fn relate( &self, from_id: u64, to_id: u64, rel_type: &str, properties: Option<&Map<String, Value>>, ) -> Result<u64, AgentMemoryError>

Relates two live procedures with a typed, durable graph edge (e.g. DEPENDS_ON, REFINES); see SemanticMemory::relate for semantics.

Errors

Returns NotFound when either endpoint is missing or expired, or CollectionError when the edge write fails.

pub fn relations(&self, id: u64) -> Result<Vec<GraphEdge>, AgentMemoryError>

Returns the outgoing relations of a procedure.

Errors

Returns CollectionError when the collection cannot be resolved.

pub fn unrelate(&self, edge_id: u64) -> Result<bool, AgentMemoryError>

Removes a relation edge created by Self::relate.

Errors

Returns CollectionError when the collection cannot be resolved.

pub fn recall( &self, query_embedding: &[f32], k: usize, min_confidence: f32, ) -> Result<Vec<ProcedureMatch>, AgentMemoryError>

Recalls matching procedures by vector similarity.

When ACT-R activation decay is configured via with_activation_decay, the returned confidence reflects power-law decay since last use without modifying the stored value.

Errors

Returns an error when embedding dimension is invalid, collection access fails, or vector search fails.

pub fn reinforce( &self, procedure_id: u64, success: bool, ) -> Result<(), AgentMemoryError>

Reinforces a stored procedure using the configured strategy.

Errors

Returns an error when procedure retrieval or update fails.

pub fn reinforce_with_strategy( &self, procedure_id: u64, success: bool, strategy: &dyn ReinforcementStrategy, ) -> Result<(), AgentMemoryError>

Reinforces a stored procedure using a custom strategy.

Errors

Returns an error when procedure retrieval or update fails.

pub fn list_all(&self) -> Result<Vec<ProcedureMatch>, AgentMemoryError>

Lists all tracked procedures.

Errors

Returns an error when collection access fails.

pub fn delete(&self, id: u64) -> Result<(), AgentMemoryError>

Deletes a procedure by id.

Errors

Returns an error when collection access or deletion fails.

pub fn serialize(&self) -> Result<Vec<u8>, AgentMemoryError>

Serializes all procedures into snapshot bytes.

Errors

Returns an error when collection access or JSON encoding fails.

pub fn deserialize(&self, data: &[u8]) -> Result<(), AgentMemoryError>

Replaces procedural memory state from serialized snapshot bytes.

Errors

Returns an error when JSON decoding fails, collection access fails, or persistence operations fail.