Struct MemorySubstrate 

pub struct MemorySubstrate { /* private fields */ }

The core persistence handle for Punch.

Wraps a SQLite Connection behind a tokio::sync::Mutex so it can be shared across async tasks without blocking the executor. Optionally includes an EmbeddingStore for semantic search over stored memories.

Implementations

impl MemorySubstrate

pub async fn create_bout(&self, fighter_id: &FighterId) -> PunchResult<BoutId>

Create a new bout for the given fighter and return its ID.

pub async fn save_message( &self, bout_id: &BoutId, message: &Message, ) -> PunchResult<()>

Append a message to an existing bout.

pub async fn load_messages(&self, bout_id: &BoutId) -> PunchResult<Vec<Message>>

Load all messages for a bout in chronological order.

pub async fn list_bouts( &self, fighter_id: &FighterId, ) -> PunchResult<Vec<BoutSummary>>

List all bouts for a fighter, most recent first.

pub async fn delete_bout(&self, bout_id: &BoutId) -> PunchResult<()>

Delete a bout and all its messages (cascading).

impl MemorySubstrate

pub async fn save_creed(&self, creed: &Creed) -> PunchResult<()>

Save or update a creed. Uses fighter_name as the natural key.

pub async fn load_creed_by_name( &self, fighter_name: &str, ) -> PunchResult<Option<Creed>>

Load a creed by fighter name. Returns None if no creed exists.

pub async fn load_creed_by_fighter( &self, fighter_id: &FighterId, ) -> PunchResult<Option<Creed>>

Load a creed by fighter ID. Returns None if no creed exists.

pub async fn list_creeds(&self) -> PunchResult<Vec<Creed>>

List all creeds.

pub async fn delete_creed(&self, fighter_name: &str) -> PunchResult<()>

Delete a creed by fighter name.

pub async fn bind_creed_to_fighter( &self, fighter_name: &str, fighter_id: &FighterId, ) -> PunchResult<()>

Bind a creed to a specific fighter instance (after spawn/respawn).

impl MemorySubstrate

pub async fn save_fighter( &self, id: &FighterId, manifest: &FighterManifest, status: FighterStatus, ) -> PunchResult<()>

Persist a fighter’s manifest and status.

pub async fn load_fighter( &self, id: &FighterId, ) -> PunchResult<Option<FighterManifest>>

Load a fighter manifest by ID.

pub async fn list_fighters( &self, ) -> PunchResult<Vec<(FighterId, String, FighterStatus)>>

List all stored fighters as (FighterId, name, FighterStatus) tuples.

pub async fn update_fighter_status( &self, id: &FighterId, status: FighterStatus, ) -> PunchResult<()>

Update a fighter’s operational status.

pub async fn delete_fighter(&self, id: &FighterId) -> PunchResult<()>

Delete a fighter and all related data (cascading).

impl MemorySubstrate

pub async fn add_entity( &self, fighter_id: &FighterId, name: &str, entity_type: &str, properties: &Value, ) -> PunchResult<()>

Add (or upsert) an entity to a fighter’s knowledge graph.

pub async fn add_relation( &self, fighter_id: &FighterId, from: &str, relation: &str, to: &str, properties: &Value, ) -> PunchResult<()>

Add (or upsert) a relation between two entities.

pub async fn query_entities( &self, fighter_id: &FighterId, query: &str, ) -> PunchResult<Vec<KnowledgeEntity>>

Query entities matching a name or type substring.

pub async fn query_relations( &self, fighter_id: &FighterId, entity: &str, ) -> PunchResult<Vec<KnowledgeRelation>>

Query all relations involving a given entity (as source or target).

impl MemorySubstrate

pub async fn cleanup_old_messages( &self, cutoff: DateTime<Utc>, ) -> PunchResult<usize>

Delete bout messages older than the given cutoff date.

Returns the number of messages deleted.

pub async fn compact_memories( &self, max_per_fighter: usize, ) -> PunchResult<usize>

Compact memory entries by removing low-confidence entries when a fighter exceeds the maximum number of memories.

Returns the number of entries removed.

pub async fn vacuum(&self) -> PunchResult<()>

Run SQLite VACUUM to reclaim disk space.

pub async fn count_bouts_in_period( &self, start: DateTime<Utc>, end: DateTime<Utc>, ) -> PunchResult<usize>

Count bouts created within a time period.

pub async fn count_messages_in_period( &self, start: DateTime<Utc>, end: DateTime<Utc>, ) -> PunchResult<usize>

Count messages created within a time period.

impl MemorySubstrate

pub async fn store_memory( &self, fighter_id: &FighterId, key: &str, value: &str, confidence: f64, ) -> PunchResult<()>

Store (or overwrite) a key-value memory for a fighter.

pub async fn recall_memories( &self, fighter_id: &FighterId, query: &str, limit: u32, ) -> PunchResult<Vec<MemoryEntry>>

Recall memories matching a query substring, ordered by confidence descending.

pub async fn decay_memories( &self, fighter_id: &FighterId, rate: f64, ) -> PunchResult<()>

Decay all memory confidences for a fighter by a multiplicative rate.

Each memory’s confidence becomes confidence * (1.0 - rate). Memories that decay below a threshold (0.01) are automatically deleted.

pub async fn delete_memory( &self, fighter_id: &FighterId, key: &str, ) -> PunchResult<()>

Delete a specific memory by key.

impl MemorySubstrate

pub fn new(path: &Path) -> PunchResult<Self>

Open (or create) a SQLite database at path and run pending migrations.

pub async fn conn(&self) -> MutexGuard<'_, Connection>

Get a lock on the underlying database connection.

This is intended for advanced queries that don’t have a dedicated method. Prefer using the higher-level methods on MemorySubstrate when possible.

pub fn in_memory() -> PunchResult<Self>

Create an in-memory substrate (useful for testing).

pub fn with_embedding_store( self, conn: Arc<StdMutex<Connection>>, embedder: Box<dyn Embedder>, ) -> PunchResult<Self>

Attach an embedding store with the given embedder for semantic recall.

The embedding store shares a separate SQLite connection (via std::sync::Mutex) since it operates synchronously.

pub fn with_builtin_embeddings(self) -> PunchResult<Self>

Attach a default built-in (TF-IDF) embedding store using an in-memory SQLite connection. Useful for testing and offline operation.

pub fn has_embedding_store(&self) -> bool

Returns whether an embedding store is attached.

pub fn embed_and_store( &self, text: &str, metadata: HashMap<String, String>, ) -> PunchResult<Option<String>>

Store a text embedding (if the embedding store is attached).

pub fn semantic_search( &self, query: &str, k: usize, ) -> PunchResult<Option<Vec<(f32, Embedding)>>>

Perform semantic search over stored embeddings. Falls back to None if no embedding store is attached.

impl MemorySubstrate

pub async fn record_usage( &self, fighter_id: &FighterId, model: &str, input_tokens: u64, output_tokens: u64, cost_usd: f64, ) -> PunchResult<()>

Record a usage event for a fighter.

pub async fn get_usage_summary( &self, fighter_id: &FighterId, since: DateTime<Utc>, ) -> PunchResult<UsageSummary>

Get an aggregated usage summary for a fighter since the given timestamp.

pub async fn get_total_usage_summary( &self, since: DateTime<Utc>, ) -> PunchResult<UsageSummary>

Get an aggregated usage summary across ALL fighters since the given timestamp.