Struct MemoryRepository 

pub struct MemoryRepository { /* private fields */ }

Repository for memory operations

Implementations

impl MemoryRepository

pub fn new(pool: SqlitePool) -> Self

pub fn pool(&self) -> &SqlitePool

pub async fn store(&self, params: StoreMemoryParams<'_>) -> Result<Memory>

Store a new memory

pub async fn store_with_lineage( &self, params: StoreMemoryWithLineageParams<'_>, ) -> Result<Memory>

Store a memory and write evidence lineage rows atomically.

pub async fn enqueue_job(&self, params: EnqueueJobParams<'_>) -> Result<i64>

Enqueue a new cognitive job.

pub async fn claim_jobs( &self, namespace_id: i64, job_type: &str, lease_owner: &str, lease_ttl_secs: u64, limit: i64, ) -> Result<Vec<ClaimedMemoryJob>>

Claim up to limit pending (or stale running) jobs for a given type and namespace.

Stale running jobs are those whose lease has expired (lease_expires_at < now). Claimed jobs are transitioned to running with a lease owner and TTL.

pub async fn complete_job(&self, job: &ClaimedMemoryJob) -> Result<()>

Mark a job as completed.

pub async fn fail_job(&self, job: &ClaimedMemoryJob, error: &str) -> Result<()>

Mark a job as failed. If attempts < MAX_JOB_ATTEMPTS, requeue it as pending. Otherwise, mark it permanently failed.

pub async fn get_most_reinforced_by_namespace( &self, namespace_id: i64, limit: i64, include_raw: bool, ) -> Result<Vec<Memory>>

pub async fn get_contradictions_by_namespace( &self, namespace_id: i64, limit: i64, include_raw: bool, ) -> Result<Vec<Memory>>

pub async fn list_by_session_key( &self, namespace_id: i64, session_key: &str, limit: i64, include_raw: bool, ) -> Result<Vec<Memory>>

pub async fn store_digest(&self, params: StoreDigestParams<'_>) -> Result<i64>

Register a session digest for a memory.

Returns the digest row ID. Uses the unique index on (namespace_id, session_key, digest_kind, end_memory_id) to prevent duplicate registrations.

pub async fn latest_digest_for_session( &self, namespace_id: i64, session_key: &str, digest_kind: &str, ) -> Result<Option<Memory>>

Get the latest digest memory for a session and digest kind. Returns the Memory row that the digest points to, or None.

pub async fn latest_digest_for_namespace( &self, namespace_id: i64, digest_kind: &str, ) -> Result<Option<Memory>>

Get the latest digest memory for a namespace and digest kind, regardless of session key. Returns the Memory row that the digest points to, or None if no digest exists.

pub async fn session_digest_rollover( &self, namespace_id: i64, session_key: &str, ) -> Result<SessionDigestRollover>

Return how much fresh non-raw, non-digest session content has accumulated since the latest covered digest window.

pub async fn get_recent_by_perspective( &self, namespace_id: i64, perspective: &PerspectiveKey, limit: i64, ) -> Result<Vec<Memory>>

Get recent memories scoped to a perspective, optionally narrowed to a session.

By default, raw-activity noise is excluded. Set include_raw to true to include operational hook event payloads.

pub async fn get_recent_by_perspective_opts( &self, namespace_id: i64, perspective: &PerspectiveKey, limit: i64, include_raw: bool, ) -> Result<Vec<Memory>>

Like Self::get_recent_by_perspective but allows opting into raw-activity noise inclusion.

pub async fn get_by_cognitive_level( &self, namespace_id: i64, level: CognitiveLevel, limit: i64, ) -> Result<Vec<Memory>>

Get active memories by cognitive level ordered from newest to oldest.

pub async fn get_by_cognitive_level_with_perspective( &self, namespace_id: i64, level: CognitiveLevel, perspective: &PerspectiveKey, limit: i64, ) -> Result<Vec<Memory>>

Get active memories by cognitive level and perspective, ordered from newest to oldest.

Unlike Self::get_by_cognitive_level, this method applies perspective filtering (observer, subject, session_key, and session_keys arrays) in the SQL query BEFORE the LIMIT is applied, ensuring the caller receives up to limit matching results.

pub async fn get_most_reinforced_by_perspective( &self, namespace_id: i64, perspective: &PerspectiveKey, limit: i64, ) -> Result<Vec<Memory>>

Get the most reinforced perspective-aligned memories first.

By default, raw-activity noise and contradiction memories are excluded.

pub async fn get_most_reinforced_by_perspective_opts( &self, namespace_id: i64, perspective: &PerspectiveKey, limit: i64, include_raw: bool, ) -> Result<Vec<Memory>>

Like Self::get_most_reinforced_by_perspective but allows opting into raw-activity noise inclusion.

pub async fn get_contradictions_by_perspective( &self, namespace_id: i64, perspective: &PerspectiveKey, limit: i64, ) -> Result<Vec<Memory>>

Get contradiction memories for the requested perspective.

By default, raw-activity noise is excluded.

pub async fn get_contradictions_by_perspective_opts( &self, namespace_id: i64, perspective: &PerspectiveKey, limit: i64, include_raw: bool, ) -> Result<Vec<Memory>>

Like Self::get_contradictions_by_perspective but allows opting into raw-activity noise inclusion.

pub async fn search_working_set( &self, params: WorkingSetParams<'_>, ) -> Result<Vec<Memory>>

Assemble a bounded working set from multiple retrieval buckets.

This is the low-level repository primitive used by higher-level services (e.g. RepresentationService) to build a [WorkingRepresentation].

The method queries four buckets in sequence:

1. Digests — latest short + long session digests
2. Reinforced — highest reinforcement-scored memories
3. Recent — newest perspective-aligned memories
4. Contradictions — highest-confidence contradiction records

Results are deduplicated by memory ID (first-seen-wins in bucket order) and truncated to max_items.

pub async fn load_lineage( &self, memory_id: i64, ) -> Result<Vec<MemoryLineageEntry>>

Load all evidence lineage entries for a given memory (as derived or source).

pub async fn load_lineage_batch( &self, memory_ids: &[i64], ) -> Result<HashMap<i64, Vec<MemoryLineageEntry>>>

Load lineage rows for many source/derived memory IDs in one query.

pub async fn get_by_id(&self, id: i64) -> Result<Option<Memory>>

Get a memory by ID

pub async fn get_by_content( &self, namespace_id: i64, content: &str, ) -> Result<Memory>

Get a memory by namespace and content (fallback for id 0 edge case)

pub async fn search_by_namespace( &self, namespace_id: i64, limit: usize, offset: usize, ) -> Result<Vec<Memory>>

Search memories by namespace

pub async fn count_by_namespace(&self, namespace_id: i64) -> Result<i64>

Count memories in namespace

pub async fn count_all_by_namespace(&self, namespace_id: i64) -> Result<i64>

Count all memories in namespace (including inactive/archived)

pub async fn count_archived_by_namespace( &self, namespace_id: i64, ) -> Result<i64>

Count archived memories in namespace

pub async fn delete(&self, id: i64) -> Result<bool>

Delete a memory

pub async fn touch(&self, id: i64) -> Result<()>

Update access count

pub async fn get_unconsolidated( &self, namespace_id: i64, limit: i32, ) -> Result<Vec<MemoryRow>>

Get unconsolidated memories

pub async fn mark_consolidated(&self, id: i64) -> Result<()>

Mark a memory as consolidated

pub async fn mark_consolidated_batch(&self, ids: &[i64]) -> Result<()>

Mark multiple memories as consolidated in a single query

pub async fn search_by_text( &self, namespace_id: i64, query: &str, limit: i32, include_raw: bool, ) -> Result<Vec<MemoryRow>>

Search memories by text content (LIKE search)

pub async fn search_by_text_memories( &self, namespace_id: i64, query: &str, limit: i32, include_raw: bool, ) -> Result<Vec<Memory>>

Search memories by text content and return domain memories.

pub async fn get_semantic_candidates( &self, params: SemanticCandidateParams<'_>, ) -> Result<Vec<Memory>>

Fetch recent, embedding-bearing cognition memories for vector-first semantic recall.

pub async fn list_filtered( &self, namespace_id: i64, filters: ListMemoryFilters<'_>, ) -> Result<Vec<Memory>>

List memories with optional filters

pub async fn list_missing_cognitive_metadata( &self, namespace_id: i64, limit: i64, offset: i64, ) -> Result<Vec<Memory>>

List memories that still need cognition metadata backfilled.

pub async fn count_missing_cognitive_metadata( &self, namespace_id: i64, ) -> Result<i64>

Count memories that still need cognition metadata backfilled.

pub async fn update_memory_metadata( &self, memory_id: i64, metadata: &Value, ) -> Result<()>

Replace the metadata blob for a single memory.

pub async fn list_session_keys_without_digests( &self, namespace_id: i64, limit: i64, ) -> Result<Vec<String>>

List distinct session keys that have cognitive metadata but no digest coverage yet.

pub async fn count_distinct_session_keys_with_cognition( &self, namespace_id: i64, ) -> Result<i64>

Count distinct non-empty cognitive session keys present in active memories.

pub async fn list_archived_raw_cleanup_candidates( &self, namespace_id: i64, older_than: DateTime<Utc>, limit: i64, ) -> Result<Vec<Memory>>

List lineage-backed archived raw-activity memories that are safe to prune.

pub async fn count_archived_raw_cleanup_candidates( &self, namespace_id: i64, older_than: DateTime<Utc>, ) -> Result<i64>

Count lineage-backed archived raw-activity memories that are safe to prune.

pub async fn delete_batch(&self, ids: &[i64]) -> Result<u64>

Delete a batch of memories by id.

pub async fn delete_by_content_pattern( &self, namespace_id: i64, pattern: &str, ) -> Result<u64>

Delete memories matching a content pattern (for cleaning noise)

pub async fn count_filtered( &self, namespace_id: i64, category: Option<&str>, since: Option<DateTime<Utc>>, until: Option<DateTime<Utc>>, include_raw: bool, ) -> Result<i64>

Count memories matching filters (for stats with time ranges)

pub async fn store_distilled_summary( &self, params: StoreMemoryParams<'_>, source_ids: &[i64], ) -> Result<Memory>

Store a distilled summary and archive its source memories atomically.

pub async fn list_jobs( &self, namespace_id: i64, job_type: Option<&str>, status: Option<&str>, limit: i64, offset: i64, ) -> Result<Vec<MemoryJobRow>>

List memory jobs with optional filters.

pub async fn count_jobs( &self, namespace_id: i64, job_type: Option<&str>, status: Option<&str>, ) -> Result<i64>

Count memory jobs with optional filters.

pub async fn count_jobs_by_status( &self, namespace_id: i64, job_type: Option<&str>, ) -> Result<Vec<(String, i64)>>

Count memory jobs grouped by status for a namespace.

pub async fn purge_completed_jobs( &self, older_than: DateTime<Utc>, ) -> Result<u64>

Delete completed jobs that were last updated before the given timestamp.

Returns the number of rows removed.

pub async fn purge_permanently_failed_jobs( &self, older_than: DateTime<Utc>, ) -> Result<u64>

Delete permanently failed jobs (attempts >= 5) that were last updated before the given timestamp.

Returns the number of rows removed.

pub async fn list_digests( &self, namespace_id: i64, session_key: Option<&str>, limit: i64, offset: i64, ) -> Result<Vec<SessionDigestRow>>

List session digests with optional session_key filter.

pub async fn count_digests( &self, namespace_id: i64, session_key: Option<&str>, ) -> Result<i64>

Count session digests for a namespace, optionally filtered by session_key.

pub async fn count_evidence(&self, namespace_id: i64) -> Result<i64>

Count evidence edges for a namespace.

pub async fn record_metric( &self, metric_name: &str, metric_value: f64, labels: &Value, ) -> Result<i64>

Record a system metric sample.

pub async fn record_metrics_batch(&self, samples: &[MetricSample]) -> Result<()>

Persist multiple metric samples in a single transaction.

pub async fn latest_metrics_for_namespace( &self, namespace_id: i64, metric_prefix: Option<&str>, limit: i64, ) -> Result<Vec<SystemMetricRow>>

Fetch the newest metric samples for a namespace and optional prefix.

pub async fn count_by_cognitive_level( &self, namespace_id: i64, level: CognitiveLevel, ) -> Result<i64>

Count active memories for a namespace at one cognitive level.