fix(api): correct capability version handling for provider drivers

The provider driver was incorrectly using the provider's own version instead of the capability version when registering capabilities, causing mismatches during capability negotiation. This change ensures that the capability version is properly extracted and passed through the registration flow, aligning with the protocol specification.

Auto-committed-on: macbook
Co-authored-by: Medulla <medulla@tinyhumans.ai>

Author: senamakel

Cargo.lock

@@ -94,6 +94,8 @@ pub enum Capability {
     Retrieval,
     /// Learned facets about the user.
     Profile,
+    /// The turn-by-turn conversation record and its segment lifecycle.
+    Episodic,
 }
 
 impl Capability {
@@ -102,7 +104,7 @@ impl Capability {
     /// Declaration order is also bit order in [`Capabilities`] and iteration
     /// order in its serialized form, so this slice is the single ordering
     /// authority for the whole module.
-    pub const ALL: [Capability; 17] = [
+    pub const ALL: [Capability; 18] = [
         Capability::Core,
         Capability::Recall,
         Capability::Ingest,
@@ -123,6 +125,7 @@ impl Capability {
         Capability::Chunks,
         Capability::Retrieval,
         Capability::Profile,
+        Capability::Episodic,
     ];
 
     /// The families a driver must advertise to be bindable at all.
@@ -165,6 +168,7 @@ impl Capability {
             Self::Chunks => "chunks",
             Self::Retrieval => "retrieval",
             Self::Profile => "profile",
+            Self::Episodic => "episodic",
         }
     }
 
@@ -211,6 +215,7 @@ impl Capability {
             Self::Chunks => 14,
             Self::Retrieval => 15,
             Self::Profile => 16,
+            Self::Episodic => 17,
         }
     }
 

api/src/capabilities.rs

@@ -60,6 +60,7 @@ use crate::provider::content::{MemoryDocuments, MemoryIngest, MemoryTree};
 use crate::provider::knowledge::{MemoryDiff, MemoryEntities, MemoryGraph};
 use crate::provider::mandatory::{MemoryCore, MemoryPortability, MemoryRecall};
 use crate::provider::people::MemoryPeople;
+use crate::provider::episodic::MemoryEpisodic;
 use crate::provider::profile::MemoryProfile;
 use crate::provider::records::{
     MemoryGoals, MemoryMaintenance, MemorySourceSink, MemoryToolMemory,
@@ -191,6 +192,11 @@ pub trait MemoryProvider: MemoryCore + MemoryRecall + MemoryPortability + 'stati
         None
     }
 
+    /// The turn-by-turn conversation record, when advertised.
+    fn as_episodic(&self) -> Option<&dyn MemoryEpisodic> {
+        None
+    }
+
     /// Whether `capability` is actually **reachable** on this driver.
     ///
     /// This is the implementation-side truth, as opposed to
@@ -220,6 +226,7 @@ pub trait MemoryProvider: MemoryCore + MemoryRecall + MemoryPortability + 'stati
             Capability::Chunks => self.as_chunks().is_some(),
             Capability::Retrieval => self.as_retrieval().is_some(),
             Capability::Profile => self.as_profile().is_some(),
+            Capability::Episodic => self.as_episodic().is_some(),
         }
     }
 }

api/src/provider/driver.rs

@@ -0,0 +1,223 @@
+//! The episodic family: the turn-by-turn record of conversations.
+//!
+//! A driver advertising [`Capability::Episodic`](crate::capabilities::Capability::Episodic)
+//! stores every chat turn in a full-text index and groups consecutive turns
+//! into *conversation segments* — a segment being a stretch of turns about one
+//! thing, closed when the subject changes and then summarised and embedded.
+//!
+//! # Why this is a family rather than a raw connection
+//!
+//! It is the last thing in the host that held a live `rusqlite::Connection`.
+//! The archivist hook was handed one straight out of the session factory and
+//! called free functions on it, which worked only because the engine was
+//! compiled into this process. A connection cannot cross a bus, so either the
+//! archivist's operations become a contract family or episodic capture stays
+//! behind and the engine can never leave.
+//!
+//! What crosses is small and already typed: insert a turn, read a session's
+//! turns back, and six segment-lifecycle operations. That was the whole surface
+//! the raw connection was used for — no ad-hoc SQL, no schema knowledge.
+//!
+//! # The host keeps the policy, and it is not a small share
+//!
+//! Two of the archivist's eight engine calls took no connection at all —
+//! deciding *whether* a new turn starts a new segment, and composing a summary
+//! when no model is available. Neither touches storage, so both stay host-side
+//! in `agent::harness::archivist`, next to the recap logic and the boundary
+//! thresholds they read. This family persists what the host decided; it does
+//! not decide.
+//!
+//! # `insert_turn` returns the id, and that is load-bearing
+//!
+//! The old code inserted a row and then issued `SELECT last_insert_rowid()` on
+//! the same connection to learn its id. That is two operations relying on a
+//! *connection-local* side effect, and it is wrong the moment anything else
+//! shares the connection or the two hops cross a bus — `last_insert_rowid` is
+//! per-connection state, so an interleaved insert from another task yields the
+//! wrong id and the turn is filed under the wrong segment.
+//!
+//! Returning the id from the insert removes both problems at once: one round
+//! trip instead of two, and no reliance on connection-local state. The engine
+//! knows the id it just wrote; nothing else has to guess.
+
+use async_trait::async_trait;
+use serde::{Deserialize, Serialize};
+
+use crate::error::MemoryError;
+
+/// One recorded turn.
+#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
+pub struct EpisodicTurn {
+    /// Row id, assigned by the driver on insert.
+    ///
+    /// `None` when the host is describing a turn to be written; always `Some`
+    /// on a turn read back.
+    #[serde(default)]
+    pub id: Option<i64>,
+    /// Session this turn belongs to.
+    pub session_id: String,
+    /// When it happened, epoch seconds with sub-second resolution.
+    ///
+    /// The archivist offsets an assistant turn by 1 ms from the user turn it
+    /// answers so the pair sorts in order within one exchange; that convention
+    /// is the host's and the driver must preserve the value it is given rather
+    /// than re-stamping it.
+    pub timestamp: f64,
+    /// `"user"` or `"assistant"`. Open vocabulary — a driver must not reject an
+    /// unfamiliar role.
+    pub role: String,
+    /// The turn's text.
+    pub content: String,
+    /// A short lesson extracted from tool failures, when there was one.
+    #[serde(default)]
+    pub lesson: Option<String>,
+    /// Serialized tool-call summary, when the turn made any.
+    #[serde(default)]
+    pub tool_calls_json: Option<String>,
+    /// Cost attributed to this turn, in microdollars.
+    #[serde(default)]
+    pub cost_microdollars: i64,
+}
+
+/// A stretch of consecutive turns about one subject.
+#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
+pub struct ConversationSegment {
+    /// Stable id, chosen by the host.
+    pub segment_id: String,
+    /// Session the segment belongs to.
+    pub session_id: String,
+    /// Owning namespace.
+    pub namespace: String,
+    /// Row id of the first turn in the segment.
+    pub start_episodic_id: i64,
+    /// Row id of the last turn, once one has been appended.
+    #[serde(default)]
+    pub end_episodic_id: Option<i64>,
+    /// Timestamp of the first turn.
+    pub start_timestamp: f64,
+    /// Timestamp of the last turn, once one has been appended.
+    #[serde(default)]
+    pub end_timestamp: Option<f64>,
+    /// How many turns the segment holds.
+    pub turn_count: i32,
+    /// Summary, once the segment has been closed and summarised.
+    #[serde(default)]
+    pub summary: Option<String>,
+    /// The segment's running embedding centroid, when it has one.
+    ///
+    /// Carried on the read so the host can run boundary detection against it
+    /// without a second call: deciding whether the next turn still belongs to
+    /// this segment is host policy, but it needs the centroid the driver
+    /// holds.
+    #[serde(default)]
+    pub embedding: Option<Vec<f32>>,
+    /// Whether the segment is still open.
+    pub open: bool,
+}
+
+/// The turn-by-turn conversation record.
+///
+/// Reached through [`MemoryProvider::as_episodic`](super::MemoryProvider::as_episodic).
+#[async_trait]
+pub trait MemoryEpisodic: Send + Sync {
+    /// Record one turn, returning the id the driver assigned it.
+    ///
+    /// See the module docs for why the id comes back from the insert rather
+    /// than from a follow-up `last_insert_rowid` call.
+    ///
+    /// # Errors
+    ///
+    /// Backend failures. A driver that refuses a turn on safety grounds (a
+    /// secret-shaped session id, say) reports [`MemoryError::Invalid`] rather
+    /// than silently dropping it — the host cannot notice a missing turn.
+    async fn insert_turn(&self, turn: &EpisodicTurn) -> Result<i64, MemoryError>;
+
+    /// Every recorded turn for one session, oldest first.
+    ///
+    /// # Errors
+    ///
+    /// Backend failures; an unknown session yields an empty vector.
+    async fn session_turns(&self, session_id: &str) -> Result<Vec<EpisodicTurn>, MemoryError>;
+
+    /// The open segment for a session, when there is one.
+    ///
+    /// # Errors
+    ///
+    /// Backend failures only; no open segment yields `Ok(None)`.
+    async fn open_segment(
+        &self,
+        session_id: &str,
+    ) -> Result<Option<ConversationSegment>, MemoryError>;
+
+    /// Start a new segment at `start_episodic_id`.
+    ///
+    /// # Errors
+    ///
+    /// Backend failures only.
+    async fn create_segment(
+        &self,
+        segment_id: &str,
+        session_id: &str,
+        namespace: &str,
+        start_episodic_id: i64,
+        start_timestamp: f64,
+        now: f64,
+    ) -> Result<(), MemoryError>;
+
+    /// Extend a segment to include one more turn.
+    ///
+    /// # Errors
+    ///
+    /// Backend failures only.
+    async fn append_turn(
+        &self,
+        segment_id: &str,
+        episodic_id: i64,
+        timestamp: f64,
+        now: f64,
+    ) -> Result<(), MemoryError>;
+
+    /// Mark a segment closed. Idempotent.
+    ///
+    /// # Errors
+    ///
+    /// Backend failures only.
+    async fn close_segment(&self, segment_id: &str, now: f64) -> Result<(), MemoryError>;
+
+    /// Attach a summary to a segment.
+    ///
+    /// Separate from [`Self::close_segment`] because the two happen at
+    /// different times: a segment closes the moment the subject changes, and is
+    /// summarised afterwards by a model call that may be slow, may fail, or may
+    /// fall back to a composed summary. Folding them together would mean either
+    /// holding the segment open across an inference call or losing the summary
+    /// when one fails.
+    ///
+    /// # Errors
+    ///
+    /// Backend failures only.
+    async fn set_segment_summary(
+        &self,
+        segment_id: &str,
+        summary: &str,
+        now: f64,
+    ) -> Result<(), MemoryError>;
+
+    /// Store a segment's embedding under `model_signature`, replacing any
+    /// vector already held for that signature.
+    ///
+    /// The signature must be produced the same way the rest of the store
+    /// produces it — see `docs/specs/2026-08-13-memory-module-port.md` §3 for
+    /// why a mismatch here is silent.
+    ///
+    /// # Errors
+    ///
+    /// Backend failures only.
+    async fn upsert_segment_embedding(
+        &self,
+        segment_id: &str,
+        model_signature: &str,
+        embedding: &[f32],
+        created_at: f64,
+    ) -> Result<(), MemoryError>;
+}

api/src/provider/episodic.rs

@@ -21,7 +21,8 @@
 //!   ├─ as_people()       -> Option<&dyn MemoryPeople>
 //!   ├─ as_chunks()       -> Option<&dyn MemoryChunks>
 //!   ├─ as_retrieval()    -> Option<&dyn MemoryRetrieval>
-//!   └─ as_profile()      -> Option<&dyn MemoryProfile>
+//!   ├─ as_profile()      -> Option<&dyn MemoryProfile>
+//!   └─ as_episodic()     -> Option<&dyn MemoryEpisodic>
 //! ```
 //!
 //! The mandatory three are supertraits, so "mandatory" is enforced by the type
@@ -63,6 +64,7 @@ pub mod driver;
 pub mod knowledge;
 pub mod mandatory;
 pub mod people;
+pub mod episodic;
 pub mod profile;
 pub mod records;
 pub mod retrieval;
@@ -78,6 +80,7 @@ pub use people::{
     AddressBookSeedOutcome, MemoryPeople, PersonHandle, PersonInteraction, PersonRecord, PersonRef,
     PersonScore, RankedPerson, ResolvedPerson,
 };
+pub use episodic::{ConversationSegment, EpisodicTurn, MemoryEpisodic};
 pub use profile::{FacetState, FacetType, MemoryProfile, ProfileFacet, UserState};
 pub use records::{MemoryGoals, MemoryMaintenance, MemorySourceSink, MemoryToolMemory};
 pub use retrieval::{