feat(memory): add nullable category column + plumbing

Migration 0006 adds engine.companion_memories.category TEXT, and
MemoryRepo::upsert / MemoryRow are extended to thread the optional
classifier tag end-to-end. The raw-turn writer in post_process passes
None — populating category is the future classifier extraction step.

Schema-first so shipping the classifier later doesn't require a
backfill migration.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: enriquephl

crates/eros-engine-server/src/pipeline/handlers.rs

@@ -608,6 +608,7 @@ mod tests {
             None,
             "profile fact",
             &unit_embedding(11),
+            None,
         )
         .await
         .unwrap();
@@ -618,6 +619,7 @@ mod tests {
             Some(instance_id),
             "relationship fact",
             &unit_embedding(11),
+            None,
         )
         .await
         .unwrap();
@@ -645,6 +647,7 @@ mod tests {
                 None,
                 &format!("profile-{i}"),
                 &unit_embedding(100 + i),
+                None,
             )
             .await
             .unwrap();
@@ -657,6 +660,7 @@ mod tests {
                 Some(instance_id),
                 &format!("relationship-{i}"),
                 &unit_embedding(200 + i),
+                None,
             )
             .await
             .unwrap();
@@ -684,6 +688,7 @@ mod tests {
             None,
             "profile target",
             &unit_embedding(42),
+            None,
         )
         .await
         .unwrap();
@@ -695,6 +700,7 @@ mod tests {
                 None,
                 &format!("profile decoy-{i}"),
                 &unit_embedding(300 + i),
+                None,
             )
             .await
             .unwrap();
@@ -708,6 +714,7 @@ mod tests {
             Some(instance_id),
             "relationship target",
             &unit_embedding(99),
+            None,
         )
         .await
         .unwrap();
@@ -718,6 +725,7 @@ mod tests {
             Some(instance_id),
             "relationship decoy",
             &unit_embedding(400),
+            None,
         )
         .await
         .unwrap();

crates/eros-engine-server/src/pipeline/post_process.rs

@@ -223,9 +223,19 @@ async fn embed_and_upsert(
         .embed_document(content)
         .await
         .map_err(|e| format!("voyage embed failed: {e}"))?;
-    repo.upsert(layer, session_id, user_id, instance_id, content, &embedding)
-        .await
-        .map_err(|e| format!("memory insert failed: {e}"))?;
+    // category=None: this writer dumps raw turns. The classifier extraction
+    // step (future) will write its own rows with category populated.
+    repo.upsert(
+        layer,
+        session_id,
+        user_id,
+        instance_id,
+        content,
+        &embedding,
+        None,
+    )
+    .await
+    .map_err(|e| format!("memory insert failed: {e}"))?;
     Ok(())
 }
 

crates/eros-engine-store/migrations/0006_memory_category.sql

@@ -0,0 +1,11 @@
+-- SPDX-License-Identifier: AGPL-3.0-only
+-- Optional category tag for companion_memories rows.
+--
+-- Currently NULL on every row — the raw-turn writer in
+-- `pipeline::post_process::write_turn` does not classify content.
+-- A future extraction step will populate it with values like
+-- 'fact' | 'preference' | 'event' | 'emotion' so retrieval can
+-- weight or filter by memory type. Schema is added now so that
+-- shipping the classifier later doesn't require a backfill migration.
+ALTER TABLE engine.companion_memories
+    ADD COLUMN category TEXT;

crates/eros-engine-store/src/memory.rs

@@ -40,6 +40,10 @@ pub struct MemoryRow {
     pub user_id: Uuid,
     pub instance_id: Option<Uuid>,
     pub content: String,
+    /// Optional classifier tag (e.g. `"fact"`, `"preference"`, `"event"`).
+    /// `None` for rows written by the raw-turn writer; populated once the
+    /// classifier extraction step lands.
+    pub category: Option<String>,
     pub created_at: DateTime<Utc>,
 }
 
@@ -50,6 +54,9 @@ pub struct MemoryRepo<'a> {
 impl<'a> MemoryRepo<'a> {
     /// Insert a memory row. For `Profile`, `instance_id` is forced to `None`.
     /// For `Relationship`, the caller MUST pass `Some(instance_id)`.
+    /// `category` is an optional classifier tag — pass `None` from
+    /// the raw-turn writer; the future extraction step will populate it.
+    #[allow(clippy::too_many_arguments)] // each arg is a distinct concern
     pub async fn upsert(
         &self,
         layer: MemoryLayer,
@@ -58,6 +65,7 @@ impl<'a> MemoryRepo<'a> {
         instance_id: Option<Uuid>,
         content: &str,
         embedding: &[f32],
+        category: Option<&str>,
     ) -> Result<Uuid, sqlx::Error> {
         let resolved_instance = match layer {
             MemoryLayer::Profile => None,
@@ -67,14 +75,15 @@ impl<'a> MemoryRepo<'a> {
 
         let id: Uuid = sqlx::query_scalar(
             "INSERT INTO engine.companion_memories \
-                 (session_id, user_id, instance_id, content, embedding) \
-             VALUES ($1, $2, $3, $4, $5::vector) RETURNING id",
+                 (session_id, user_id, instance_id, content, embedding, category) \
+             VALUES ($1, $2, $3, $4, $5::vector, $6) RETURNING id",
         )
         .bind(session_id)
         .bind(user_id)
         .bind(resolved_instance)
         .bind(content)
         .bind(vec_text)
+        .bind(category)
         .fetch_one(self.pool)
         .await?;
         Ok(id)
@@ -96,7 +105,7 @@ impl<'a> MemoryRepo<'a> {
         match instance_id {
             Some(pid) => {
                 sqlx::query_as::<_, MemoryRow>(
-                    "SELECT id, session_id, user_id, instance_id, content, created_at \
+                    "SELECT id, session_id, user_id, instance_id, content, category, created_at \
                      FROM engine.companion_memories \
                      WHERE user_id = $1 AND instance_id = $2 \
                      ORDER BY embedding <=> $3::vector \
@@ -111,7 +120,7 @@ impl<'a> MemoryRepo<'a> {
             }
             None => {
                 sqlx::query_as::<_, MemoryRow>(
-                    "SELECT id, session_id, user_id, instance_id, content, created_at \
+                    "SELECT id, session_id, user_id, instance_id, content, category, created_at \
                      FROM engine.companion_memories \
                      WHERE user_id = $1 AND instance_id IS NULL \
                      ORDER BY embedding <=> $2::vector \
@@ -166,6 +175,7 @@ mod tests {
                 Some(instance_id),
                 "user lives in shanghai",
                 &emb,
+                None,
             )
             .await
             .unwrap();
@@ -195,6 +205,7 @@ mod tests {
                 Some(instance_id),
                 "target",
                 &unit_embedding(42),
+                None,
             )
             .await
             .unwrap();
@@ -205,6 +216,7 @@ mod tests {
             Some(instance_id),
             "decoy a",
             &unit_embedding(100),
+            None,
         )
         .await
         .unwrap();
@@ -215,6 +227,7 @@ mod tests {
             Some(instance_id),
             "decoy b",
             &unit_embedding(200),
+            None,
         )
         .await
         .unwrap();
@@ -227,6 +240,48 @@ mod tests {
         assert_eq!(hits[0].id, target_id);
     }
 
+    #[sqlx::test(migrations = "./migrations")]
+    async fn category_roundtrips_through_search(pool: PgPool) {
+        let repo = MemoryRepo { pool: &pool };
+        let user_id = Uuid::new_v4();
+        let instance_id = Uuid::new_v4();
+        let session_id = make_session(&pool, user_id, Some(instance_id)).await;
+
+        repo.upsert(
+            MemoryLayer::Relationship,
+            session_id,
+            user_id,
+            Some(instance_id),
+            "tagged",
+            &unit_embedding(33),
+            Some("preference"),
+        )
+        .await
+        .unwrap();
+        repo.upsert(
+            MemoryLayer::Relationship,
+            session_id,
+            user_id,
+            Some(instance_id),
+            "untagged",
+            &unit_embedding(34),
+            None,
+        )
+        .await
+        .unwrap();
+
+        let mut hits = repo
+            .search(user_id, Some(instance_id), &unit_embedding(33), 10)
+            .await
+            .unwrap();
+        hits.sort_by_key(|r| r.content.clone());
+        assert_eq!(hits.len(), 2);
+        assert_eq!(hits[0].content, "tagged");
+        assert_eq!(hits[0].category.as_deref(), Some("preference"));
+        assert_eq!(hits[1].content, "untagged");
+        assert_eq!(hits[1].category, None);
+    }
+
     #[sqlx::test(migrations = "./migrations")]
     async fn profile_layer_isolates_from_relationship(pool: PgPool) {
         let repo = MemoryRepo { pool: &pool };
@@ -242,6 +297,7 @@ mod tests {
             Some(instance_id), // ignored
             "profile fact",
             &unit_embedding(11),
+            None,
         )
         .await
         .unwrap();
@@ -253,6 +309,7 @@ mod tests {
             Some(instance_id),
             "relationship fact",
             &unit_embedding(11),
+            None,
         )
         .await
         .unwrap();