Struct Engine 

pub struct Engine { /* private fields */ }

Implementations

impl Engine

pub fn distill( &mut self, space: &ScopedSpace, limit: usize, ) -> Result<DistillReport>

Drain up to limit pending episodes of this space through the LLM.

Failures are recorded on the queue row (attempts, last_error) and never delete anything (memory/bugs.md P-2); after 3 attempts the row parks as failed and stops being retried implicitly.

pub fn add_entity_alias(&mut self, alias: &str, canonical: &str) -> Result<()>

Register alias as another name for canonical (both canonicalized).

pub fn apply_facts( &mut self, space: &ScopedSpace, episode_id: i64, facts: &[ExtractedFact], ) -> Result<ApplyReport>

Apply extracted facts from one episode, in one transaction.

impl Engine

pub fn facts_list( &self, space: &ScopedSpace, all: bool, ) -> Result<Vec<FactItem>>

Facts of a space; active only unless all (closed/expired included).

pub fn facts_why( &self, space: &ScopedSpace, fact_id: i64, ) -> Result<Vec<ProvenanceItem>>

The episodes that taught us this fact (invariant I4 guarantees ≥1).

pub fn facts_close( &mut self, space: &ScopedSpace, fact_id: i64, reason: &str, ) -> Result<()>

Close a fact by hand, with a reason (interval close, never delete).

impl Engine

pub fn facts_about( &self, space: &ScopedSpace, entity: &str, ) -> Result<Vec<FactItem>>

Active facts whose subject is entity (canonicalized, aliases honored), scoped to one space.

impl Engine

pub fn decay_facts( &mut self, space: &ScopedSpace, max_idle_days: u32, ) -> Result<usize>

Decay (spec §5): expire active facts that are old, unaccessed, and low-confidence. Expiry is an interval close with a recorded reason (adopted from the predecessor’s forgetReason, rationales.md R-3) — never a delete. Recalled facts are reinforced (access_count, last_accessed) and therefore immune. Returns how many expired.

impl Engine

pub fn pending_episodes( &self, space: &ScopedSpace, limit: usize, ) -> Result<Vec<(i64, String, String)>>

Episodes awaiting distillation, for agent-driven extraction (subscription-native path: the host agent is the model).

pub fn complete_distillation( &mut self, space: &ScopedSpace, episode_id: i64, facts: &[ExtractedFact], ) -> Result<ApplyReport>

Apply agent-extracted facts for one pending episode and mark its queue row done. The engine enforces the invariants; the agent only proposes.

impl Engine

pub fn ingest( &mut self, space: &ScopedSpace, input: IngestInput, ) -> Result<IngestOutcome>

pub fn import_episode( &mut self, space: &ScopedSpace, kind: &str, content: &str, source: Option<&str>, created_at: Option<&str>, ) -> Result<(i64, bool)>

Import-grade ingest: explicit kind/source/created_at, same pipeline. Returns the episode id and whether it was freshly stored. Public for importers and harnesses that must preserve original timestamps — temporal scoring is only as real as created_at.

impl Engine

pub fn ingest_directory( &mut self, space: &ScopedSpace, dir: &Path, max_file_bytes: u64, ) -> Result<ScanReport>

Recursively ingest text files under dir. Hidden entries and dependency/build directories are skipped; binary and oversized files are counted in skipped, never silently dropped (spec §10). Content-hash dedup makes rescans cheap and edits append-only.

pub fn ingest_directory_tagged( &mut self, space: &ScopedSpace, dir: &Path, max_file_bytes: u64, tags: &[&str], ) -> Result<ScanReport>

Directory scan with curation tags: every ingested (or re-seen) file gets the given tags plus its lowercase extension as a source tag.

impl Engine

pub fn export_jsonl(&self, space: &ScopedSpace) -> Result<String>

Export one space as JSONL: episodes, entity aliases, then facts (with full interval history and hash-based provenance).

pub fn import_jsonl( &mut self, space: &ScopedSpace, data: &str, ) -> Result<ImportReport>

Import JSONL produced by Engine::export_jsonl. Idempotent.

impl Engine

pub fn profile(&mut self, space: &ScopedSpace, limit: usize) -> Result<Profile>

impl Engine

pub fn recall( &mut self, space: &ScopedSpace, query: &str, opts: &RecallOpts, ) -> Result<ContextPack>

impl Engine

pub fn tag_episode( &mut self, space: &ScopedSpace, episode_id: i64, names: &[&str], ) -> Result<()>

Attach tags to an episode (idempotent; names normalized lowercase).

pub fn tags_list(&self, space: &ScopedSpace) -> Result<Vec<(String, i64)>>

Tags of a space with episode counts, most-used first.

impl Engine

pub fn open( data_dir: &Path, embedder: Box<dyn EmbeddingProvider>, ) -> Result<Engine>

Open (creating if needed) the engine rooted at data_dir.

Refuses to open when the store was embedded with a different provider (spec §9): switching embedders is an explicit doctor --rebuild, never a silent re-index.

pub fn open_for_repair( data_dir: &Path, embedder: Box<dyn EmbeddingProvider>, ) -> Result<Engine>

Open bypassing the embedder pin, for doctor --rebuild only.

pub fn set_chunk_target(&mut self, bytes: usize)

Set the chunking granularity (bytes) for future ingests.

pub fn is_read_only(&self) -> bool

True when another scone process holds the index write lock: search works from committed state; ingest/distill/doctor are refused with typed errors until the other process exits.

pub fn set_llm(&mut self, llm: Option<Box<dyn LlmProvider>>)

Attach or detach the semantic lane’s LLM. None pauses lane 2 loudly; the episodic engine is unaffected (spec §9).

pub fn has_llm(&self) -> bool

pub fn set_reranker(&mut self, reranker: Option<Box<dyn Reranker>>)

Attach or detach a cross-encoder reranker for recall precision.

pub fn llm_answer(&self, question: &str, context: &str) -> Result<String>

Answer a question from rendered context via the configured LLM.

pub fn llm_answer_with_system( &self, system: &str, question: &str, context: &str, ) -> Result<String>

Answer with an explicit system prompt (for prompt A/B harnesses).

pub fn doctor_rebuild(&mut self) -> Result<DoctorReport>

Rebuild every derived index from SQLite truth, re-embedding chunks whose stored vectors no longer match the active embedder.

pub fn space_revision(&self, space: &ScopedSpace) -> Result<i64>

pub fn status(&self) -> Result<StatusReport>

Administrative overview of the whole store (single-user surface; multi-user servers must scope what they expose of it).

pub fn episode_content(&self, episode_id: i64) -> Result<(String, String)>

Content and kind of one episode, straight from truth.

pub fn data_dir(&self) -> &Path

pub fn schema_version(&self) -> Result<i64>

Trait Implementations

impl Debug for Engine

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Drop for Engine

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.