Struct SqliteAgentMemoryStore 

pub struct SqliteAgentMemoryStore { /* private fields */ }

Bundled SQLite store. Cheap to clone; connections are cached per realm and shared across clones.

Implementations

impl SqliteAgentMemoryStore

pub fn open(root: impl Into<PathBuf>) -> Result<Self, AgentMemoryError>

pub fn set_llm_write_gate(&self, gate: Arc<dyn LlmWriteGate>)

Install the §10.1 LLM write gate. Wiring installs it at startup, before any member can dispatch a write.

pub fn set_llm_write_gate_if_absent(&self, gate: Arc<dyn LlmWriteGate>) -> bool

Install the §10.1 gate only when none is present. The classic-mob builder path uses this so it never clobbers a taint-tracking gate an embedder (or the gateway) installed before handing the store over. Returns whether this call installed the gate.

pub fn set_evidence_resolver(&self, resolver: Arc<dyn EvidenceRefResolver>)

Install the §10.2 evidence-ref resolver. The steward wiring installs it at startup; from then on every staged retier to agent_verified must cite evidence that resolves against the session store.

pub fn set_event_sink(&self, sink: Arc<dyn MemoryEventSink>)

Wire the §9.3 timeline sink for quarantined-write events.

pub fn set_event_sink_if_absent(&self, sink: Arc<dyn MemoryEventSink>) -> bool

Wire the §9.3 sink only when none is present — the classic-mob builder path uses this so an embedder-installed sink survives. Returns whether this call installed the sink.

pub fn path_for_realm(&self, realm: &str) -> PathBuf

Same directory + percent-encoding scheme as MarkdownAgentMemoryStore::path_for, one database per realm.

pub async fn injection_log( &self, realm: &str, limit: usize, ) -> Result<Vec<InjectionLogEntry>, AgentMemoryError>

Newest-first injection-ledger rows for a realm (§9.2). Read surface for the steward’s usage audit and the console Memory panel.

impl SqliteAgentMemoryStore

pub fn scope_floors(&self) -> (usize, usize)

The per-scope retention floors this store warns against (§7.3); rendered into the dream’s orient overview as floor pressure.

pub async fn scope_overview( &self, realm: &str, ) -> Result<Vec<ScopeOverview>, AgentMemoryError>

Per-scope counts and byte totals for a realm — the orient phase’s one cheap aggregate.

pub async fn pending_proposals( &self, realm: &str, limit: usize, ) -> Result<Vec<PendingProposal>, AgentMemoryError>

Pending/held proposals, oldest first (§8.5 promotion queue).

pub async fn set_proposal_status( &self, realm: &str, proposal_id: &str, status: &str, ) -> Result<(), AgentMemoryError>

Record a dream verdict on a proposal: accepted, rejected, or held (held stays in the pending queue for the next dream).

pub async fn quarantined_records( &self, realm: &str, limit: usize, ) -> Result<Vec<MemoryRecord>, AgentMemoryError>

Quarantined records, newest first — the dream’s review queue (§8.5). The steward is the one stage that reads these bodies wholesale; the caller renders them defanged.

pub async fn records_by_ids( &self, realm: &str, ids: &[String], ) -> Result<Vec<MemoryRecord>, AgentMemoryError>

Records by id, any status — the gather phase’s bounded body fetch. Missing ids are skipped (the model may cite stale ids).

pub async fn recent_records( &self, realm: &str, limit: usize, ) -> Result<Vec<MemoryRecord>, AgentMemoryError>

Most recently updated records in a realm, any scope, active or quarantined — the gather phase filters (e.g. recent distillates by author) host-side.

pub async fn record_pending_harvest( &self, realm: &str, identity: &str, session_key: Option<&str>, cause: &str, ) -> Result<(), AgentMemoryError>

Record a retired identity for the next dream’s exit-interview harvest (§8.5). Idempotent per (identity, retired_at_ms).

pub async fn pending_harvests( &self, realm: &str, limit: usize, ) -> Result<Vec<PendingHarvest>, AgentMemoryError>

Pending exit-interview harvests, oldest first.

pub async fn mark_harvest_complete( &self, realm: &str, identity: &str, retired_at_ms: u64, ) -> Result<(), AgentMemoryError>

Mark one exit-interview harvest done.

pub async fn record_pending_promotion( &self, realm: &str, promotion: PendingPromotion, ) -> Result<(), AgentMemoryError>

Record a gated quarantine-promotion: gating pending_id → staged batch token (§10.2). Only a gating approval commits the token.

pub async fn pending_promotion_by_id( &self, realm: &str, pending_id: &str, ) -> Result<Option<PendingPromotion>, AgentMemoryError>

Look up a still-pending gated promotion by its gating pending id.

pub async fn pending_promotions( &self, realm: &str, ) -> Result<Vec<PendingPromotion>, AgentMemoryError>

All still-pending gated promotions (dream-start reconciliation).

pub async fn resolve_pending_promotion( &self, realm: &str, pending_id: &str, status: &str, ) -> Result<(), AgentMemoryError>

Resolve a gated promotion: committed, denied, or expired.

pub async fn rekey_pending_promotion( &self, realm: &str, old_pending_id: &str, new_pending_id: &str, ) -> Result<(), AgentMemoryError>

Re-key a gated promotion after a gating escalation minted a successor pending entry.

pub async fn discard_stage( &self, token: StageToken, ) -> Result<(), AgentMemoryError>

Discard a staged-but-uncommitted batch (denied/expired gated promotions; §8.5 crash semantics keep this safe — an unapplied stage row is never visible).

impl SqliteAgentMemoryStore

pub async fn panel_realms(&self) -> Result<Vec<String>, AgentMemoryError>

Realms with a store file on disk (panel realm picker).

pub async fn record_by_id( &self, realm: &str, memory_id: &str, ) -> Result<Option<MemoryRecord>, AgentMemoryError>

One record by id, any status.

pub async fn records_page( &self, realm: &str, scope_kind: Option<&str>, scope_key: Option<&str>, status_kind: Option<&str>, limit: usize, cursor: Option<(u64, String)>, ) -> Result<PanelRecordsPage, AgentMemoryError>

Panel record listing: optional scope/status filters, newest-updated first, keyset cursor. Any status is visible here — the panel is an inspection surface and renders status explicitly.

pub async fn supersede_chain( &self, realm: &str, memory_id: &str, max_len: usize, ) -> Result<Vec<MemoryRecord>, AgentMemoryError>

Supersede lineage around one record, oldest first: ancestors via the supersedes pointer, the record itself, then committed successors via the Superseded { by } status link. When the tip has no committed successor, records claiming to supersede it (e.g. a quarantined supersede that left the prior active, §10.1) are appended without recursing — claims are visible but never extend the walk. Bounded by max_len, cycle-safe.

pub async fn injection_log_for_record( &self, realm: &str, record_id: &str, limit: usize, ) -> Result<Vec<InjectionLogEntry>, AgentMemoryError>

Newest-first injection-ledger rows for one record (panel usage view).

pub async fn dream_history( &self, realm: &str, max_runs: usize, ) -> Result<Vec<DreamRunAudit>, AgentMemoryError>

Dream-run summaries reconstructed from steward audit rows, newest run first. Bounded scan ([DREAM_HISTORY_SCAN_ROWS]); runs older than the scan window fall off the panel, which is acceptable for a history summary surface.

Trait Implementations

impl AgentMemoryProvider for SqliteAgentMemoryStore

fn recall<'life0, 'async_trait>( &'life0 self, request: AgentMemoryRecallRequest, ) -> Pin<Box<dyn Future<Output = Result<Vec<AgentMemoryRecord>, AgentMemoryError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

fn supports_remember(&self) -> bool

fn remember<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, realm: &'life1 str, identity: &'life2 AgentIdentity, memory: NewAgentMemory, ) -> Pin<Box<dyn Future<Output = Result<AgentMemoryRecord, AgentMemoryError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

fn supports_forget(&self) -> bool

fn forget<'life0, 'life1, 'life2, 'life3, 'async_trait>( &'life0 self, realm: &'life1 str, identity: &'life2 AgentIdentity, memory_id: &'life3 str, ) -> Pin<Box<dyn Future<Output = Result<AgentMemoryForgetResult, AgentMemoryError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, 'life3: 'async_trait,

fn manifest<'life0, 'life1, 'async_trait>( &'life0 self, scopes: &'life1 [MemoryScope], tier: ManifestTier, ) -> Pin<Box<dyn Future<Output = Result<Vec<RecordMeta>, AgentMemoryError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Metadata manifest over the composed scopes (§8.3). WorkingSet(k) is the union of the top-K ranked records and the recent/unranked slice; Full is every active record’s metadata.

fn supports_manifest(&self) -> bool

fn supersede<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, scope: &'life1 MemoryScope, prior: &'life2 str, record: NewMemoryRecord, ) -> Pin<Box<dyn Future<Output = Result<MemoryId, AgentMemoryError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

Update-in-place with history (fixes D4): the new record supersedes prior within its lineage and inherits its working-set rank.

fn supports_supersede(&self) -> bool

fn mark_usage<'life0, 'life1, 'async_trait>( &'life0 self, ids: &'life1 [MemoryId], event: UsageEvent, ) -> Pin<Box<dyn Future<Output = Result<(), AgentMemoryError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Mechanical usage-ledger updates (§9.2). Deliberately flag-less: it is an internal coordinator surface, not an advertised RPC capability.

fn log_injections<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, realm: &'life1 str, entries: &'life2 [InjectionLogEntry], ) -> Pin<Box<dyn Future<Output = Result<(), AgentMemoryError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

Injection-ledger append (§9.2): which records entered whose context, through which surface, when. Internal coordinator telemetry — default no-op (not an error) so simple providers like the markdown store need no capability flag and the coordinator never has to care.

fn propose<'life0, 'life1, 'async_trait>( &'life0 self, scope: &'life1 MemoryScope, record: NewMemoryRecord, author: MemoryAuthor, ) -> Pin<Box<dyn Future<Output = Result<ProposalId, AgentMemoryError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Queue a record for steward-committed scopes (mob/operator — §7.2 write authority). author is the proposing principal — the Recorder proposes with real MemoryAuthor::Agent authorship (§8.2), the RPC path with Application.

fn supports_propose(&self) -> bool

fn remember_authored<'life0, 'life1, 'async_trait>( &'life0 self, scope: &'life1 MemoryScope, record: NewMemoryRecord, author: MemoryAuthor, ) -> Pin<Box<dyn Future<Output = Result<AuthoredWriteReceipt, AgentMemoryError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Agent-authored create in scope. Default-unsupported: the Recorder only registers against providers that implement this.

fn supersede_authored<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, scope: &'life1 MemoryScope, prior: &'life2 str, record: NewMemoryRecord, author: MemoryAuthor, ) -> Pin<Box<dyn Future<Output = Result<AuthoredWriteReceipt, AgentMemoryError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

Agent-authored supersede within a single record’s lineage in the author’s own writable scope (§8.2). Cross-scope updates are a validator reject, not a policy the caller can waive.

fn forget_authored<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, scope: &'life1 MemoryScope, memory_id: &'life2 str, author: MemoryAuthor, ) -> Pin<Box<dyn Future<Output = Result<AgentMemoryForgetResult, AgentMemoryError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

Agent-authored tombstone in the author’s own scope.

fn supports_authored_writes(&self) -> bool

fn as_sqlite_store(&self) -> Option<&SqliteAgentMemoryStore>

Bundled-store downcast seam: the builder wires the console Memory panel (§9.3) when — and only when — the configured provider is the bundled SQLite store. External providers keep the default None.

impl Clone for SqliteAgentMemoryStore

fn clone(&self) -> SqliteAgentMemoryStore

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl SelectedRecordFetch for SqliteAgentMemoryStore

Body fetch for selector-chosen ids (§8.3): a plain by-id read over the composed scopes, wire-compat projected, returned in ids order. Only active records in the requested scopes qualify — the selector judged a manifest of exactly those.

fn fetch_records<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, scopes: &'life1 [MemoryScope], ids: &'life2 [String], ) -> Pin<Box<dyn Future<Output = Result<Vec<AgentMemoryRecord>, AgentMemoryError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

fn fetch_records_annotated<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, scopes: &'life1 [MemoryScope], ids: &'life2 [String], ) -> Pin<Box<dyn Future<Output = Result<Vec<AnnotatedRecord>, AgentMemoryError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

Bodies plus §7.2 provenance labels. The default delegates to Self::fetch_records with no provenance so existing stores keep compiling; stores that know each record’s scope and trust tier should override so injected bodies carry their labels.

impl StagedMemoryStore for SqliteAgentMemoryStore

fn stage<'life0, 'async_trait>( &'life0 self, batch: StagedMutationBatch, ) -> Pin<Box<dyn Future<Output = Result<StageToken, AgentMemoryError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Validate the batch against current store state and persist it, unapplied, under a token. Stale tokens are garbage-collected.

fn commit<'life0, 'async_trait>( &'life0 self, token: StageToken, ) -> Pin<Box<dyn Future<Output = Result<CommitReceipt, AgentMemoryError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Re-validate and apply the staged batch in a single transaction, writing one audit entry per op and burning the token.

impl TombstoneSource for SqliteAgentMemoryStore

fn recent_tombstones<'life0, 'life1, 'async_trait>( &'life0 self, scope: &'life1 MemoryScope, since_ms: u64, limit: usize, ) -> Pin<Box<dyn Future<Output = Result<Vec<TombstoneMeta>, AgentMemoryError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Recent tombstones for the Distiller’s pre-injected “never re-create these” list (§8.4). The mechanical backstop for exact recreation is the staged validator’s content-hash check; this list closes the paraphrase gap at the prompt level.