Struct CerememoryEngine 

pub struct CerememoryEngine { /* private fields */ }

The main Cerememory engine — orchestrates all CMP operations.

Implementations

impl CerememoryEngine

pub fn new(config: EngineConfig) -> Result<Self, CerememoryError>

Create a new engine. Uses in-memory stores when paths are None.

pub fn in_memory() -> Result<Self, CerememoryError>

Create an engine with all in-memory stores (for testing).

pub fn start_background_decay(self: &Arc<Self>)

Start the background decay task. Requires the engine to be wrapped in Arc. No-op if already running or if background_decay_interval_secs is None.

pub async fn stop_background_decay(&self)

Stop the background decay task and wait for it to finish.

pub async fn is_background_decay_enabled(&self) -> bool

Check if background decay is running.

pub fn start_background_dream(self: &Arc<Self>)

Start the background dream task. Requires the engine to be wrapped in Arc. No-op if already running or if background_dream_interval_secs is None.

pub async fn stop_background_dream(&self)

Stop the background dream task and wait for it to finish.

pub async fn is_background_dream_enabled(&self) -> bool

Check if background dream processing is running.

pub async fn rebuild_coordinator(&self) -> Result<(), CerememoryError>

Rebuild the hippocampal coordinator and all indexes from persistent stores. Must be called after construction when opening existing stores.

pub async fn append_raw_journal( &self, record: RawJournalRecord, ) -> Result<Uuid, CerememoryError>

Append a verbatim preserved record to the raw journal.

pub async fn get_raw_journal_record( &self, id: &Uuid, ) -> Result<Option<RawJournalRecord>, CerememoryError>

Retrieve a raw journal record by id.

pub async fn query_raw_journal_by_session( &self, session_id: &str, ) -> Result<Vec<RawJournalRecord>, CerememoryError>

Retrieve all raw journal records for a session in chronological order.

pub async fn query_raw_journal_session_range( &self, session_id: &str, start: DateTime<Utc>, end: DateTime<Utc>, ) -> Result<Vec<RawJournalRecord>, CerememoryError>

Retrieve raw journal records for a session within a time range.

pub async fn raw_journal_count(&self) -> Result<usize, CerememoryError>

Return the number of raw journal records.

pub async fn encode_store_raw( &self, req: EncodeStoreRawRequest, ) -> Result<EncodeStoreRawResponse, CerememoryError>

encode.store_raw — append a raw journal record to the preservation plane.

pub async fn encode_batch_store_raw( &self, req: EncodeBatchStoreRawRequest, ) -> Result<EncodeBatchStoreRawResponse, CerememoryError>

encode.batch_raw — append multiple raw journal records.

pub async fn recall_raw_query( &self, req: RecallRawQueryRequest, ) -> Result<RecallRawQueryResponse, CerememoryError>

recall.raw_query — explicit retrieval from the raw journal.

pub async fn encode_store( &self, req: EncodeStoreRequest, ) -> Result<EncodeStoreResponse, CerememoryError>

encode.store — Store a new memory record (CMP Spec §3.1).

pub async fn encode_batch( &self, req: EncodeBatchRequest, ) -> Result<EncodeBatchResponse, CerememoryError>

encode.batch — Store multiple records (CMP Spec §3.2).

pub async fn encode_update( &self, req: EncodeUpdateRequest, ) -> Result<(), CerememoryError>

encode.update — Update an existing record (CMP Spec §3.3).

pub async fn recall_query( &self, req: RecallQueryRequest, ) -> Result<RecallQueryResponse, CerememoryError>

recall.query — Retrieve memories (CMP Spec §4.1).

Phase 2 recall pipeline:

1. Text search via Tantivy (if cue.text present)
2. Vector similarity search (if cue.embedding present)
3. Hybrid score merging
4. Temporal range filter
5. Spreading activation
6. Reconsolidation + human noise rendering

pub async fn recall_associate( &self, req: RecallAssociateRequest, ) -> Result<RecallAssociateResponse, CerememoryError>

recall.associate — Get associated memories (CMP Spec §4.2).

pub async fn recall_timeline( &self, req: RecallTimelineRequest, ) -> Result<RecallTimelineResponse, CerememoryError>

recall.timeline — Temporal bucketed recall (CMP Spec §4.3, OPTIONAL).

pub async fn recall_graph( &self, req: RecallGraphRequest, ) -> Result<RecallGraphResponse, CerememoryError>

recall.graph — Local graph extraction (CMP Spec §4.4, OPTIONAL).

pub async fn lifecycle_dream_tick( &self, req: DreamTickRequest, ) -> Result<DreamTickResponse, CerememoryError>

lifecycle.dream_tick — summarize unprocessed raw journal entries into episodic summaries.

pub async fn lifecycle_consolidate( &self, req: ConsolidateRequest, ) -> Result<ConsolidateResponse, CerememoryError>

lifecycle.consolidate — Smart Consolidation (CMP Spec §5.1).

Phase 4 enhancements:

• Duplicate detection: Vector similarity > 0.92 identifies near-duplicates. Higher-fidelity record is kept; associations are merged.
• LLM summarization: When a provider is configured, related episodic records are summarized into a single semantic node (otherwise, truncation fallback).
• Relation extraction: LLM extracts semantic relations, stored as associations.

pub async fn lifecycle_decay_tick( &self, req: DecayTickRequest, ) -> Result<DecayTickResponse, CerememoryError>

lifecycle.decay_tick — Advance decay (CMP Spec §5.2).

pub async fn lifecycle_set_mode( &self, req: SetModeRequest, ) -> Result<(), CerememoryError>

lifecycle.set_mode (CMP Spec §5.3).

pub async fn lifecycle_forget( &self, req: ForgetRequest, ) -> Result<u32, CerememoryError>

lifecycle.forget — Delete memory records (CMP Spec §5.4).

pub async fn lifecycle_export( &self, req: ExportRequest, ) -> Result<(Vec<u8>, ExportResponse), CerememoryError>

lifecycle.export — Export records to a CMA archive with optional store filtering and encryption.

pub async fn lifecycle_import( &self, req: ImportRequest, ) -> Result<u32, CerememoryError>

lifecycle.import — Import records from a CMA archive with optional decryption and conflict resolution.

pub async fn import_records(&self, data: &[u8]) -> Result<u32, CerememoryError>

Import records from a serialized CMA archive (convenience method).

Uses KeepExisting conflict resolution (skips duplicates).

pub async fn collect_all_records( &self, ) -> Result<Vec<MemoryRecord>, CerememoryError>

Collect all records for export (used by archive module).

pub async fn collect_records_for_stores( &self, stores: Option<&[StoreType]>, ) -> Result<Vec<MemoryRecord>, CerememoryError>

Collect records from specified stores, or all stores if None.

pub async fn introspect_stats(&self) -> Result<StatsResponse, CerememoryError>

introspect.stats (CMP Spec §6.1).

pub async fn introspect_record( &self, req: RecordIntrospectRequest, ) -> Result<MemoryRecord, CerememoryError>

introspect.record (CMP Spec §6.2).

pub async fn introspect_decay_forecast( &self, req: DecayForecastRequest, ) -> Result<DecayForecastResponse, CerememoryError>

introspect.decay_forecast — Forward-calculate fidelity (CMP Spec §6.3, OPTIONAL).

pub async fn introspect_evolution( &self, ) -> Result<EvolutionMetrics, CerememoryError>

introspect.evolution — Return evolution engine metrics (CMP Spec §6.4, OPTIONAL).