Expand memory ingestion and retrieval APIs

README.md

@@ -97,7 +97,7 @@ is deliberately outside `full`: "give me the whole workspace" is not the same
 request as "give me the test doubles".
 
 This table says which crate each feature brings in. For what each *engine*
-feature actually serves — driver class, and how many of the twenty capability
+feature actually serves — driver class, and which capability
 families answer — see the engine table under
 [Using from your project](#using-from-your-project).
 
@@ -176,17 +176,18 @@ use tinymemory::tinycortex::{provider, InMemoryMemoryStore};
 let provider = Arc::new(provider(Arc::new(InMemoryMemoryStore::new())));
 ```
 
-That is a complete embedded setup for the mandatory three families. The full
-twenty-family engine (`TinycortexProvider`) additionally needs the host
+That is a complete embedded setup for the mandatory families plus document
+ingestion. The full
+full engine (`TinycortexProvider`) additionally needs the host
 seams (`EmbeddingHost` et al.) installed — see
 `crates/tinymemory-tinycortex/tests/full_provider_conformance.rs` for the
 minimal working wiring.
 
 | Feature | Engine | Class | Families served |
 | --- | --- | --- | --- |
-| `tinycortex` | TinyCortex, in-process | embedded | 3 (mandatory) via `provider`; all 18 via `TinycortexProvider` |
+| `tinycortex` | TinyCortex, in-process | embedded | mandatory + document ingest via `provider`; every compiled family via `TinycortexProvider` |
 | `supermemory` | Supermemory, hosted | external | 3 (mandatory) |
-| `mem0` | Mem0, hosted (`cloud`) or self-hosted | external | 3 (mandatory) |
+| `mem0` | Mem0, hosted (`cloud`) or self-hosted | external | mandatory + conversation ingest |
 | `cognee` | Cognee, hosted or self-hosted | external | 3 (mandatory) |
 | `agentmemory` | AgentMemory, self-hosted | external | 3 (mandatory) |
 | `memory-git` | add-on: git-backed diff snapshots | — | requires `tinycortex` |
@@ -204,7 +205,7 @@ for assistant-memory workloads; wrong for high-volume keyed storage.
 ## The contract
 
 `MemoryProvider` is an object-safe trait with **three mandatory** capability
-families and **seventeen optional** ones. The mandatory three are supertraits, so
+families and independently negotiated optional ones. The mandatory three are supertraits, so
 a driver missing any of them cannot be constructed; the optional seventeen are
 reached through `as_ingest()` / `as_tree()` / … accessors that default to `None`,
 so a minimal driver implements what it supports and inherits correct absence for
@@ -215,6 +216,25 @@ A driver's advertised set and its reachable accessors must agree.
 implemented" into a detectable, testable mistake rather than a runtime surprise
 on the first call.
 
+The product-facing routes are available through one router:
+
+```rust,ignore
+use tinymemory::{MemoryApi, operations::AnswerRequest};
+
+let memory = MemoryApi::new(provider.as_ref());
+let hits = memory.recall("release date", 10, &Default::default(), None).await?;
+
+if provider.as_answer().is_some() {
+    let response = memory.answer(AnswerRequest::new("When do we release?")).await?;
+    println!("{}", response.answer);
+}
+```
+
+Document, conversation, learning, event, and answer support are independent
+capabilities. Recall remains mandatory. See the
+[operation specification](docs/specs/ingestion-retrieval-api.md) for the adapter
+matrix and payload rules.
+
 Capabilities are asked **once, at bind time, and cached**: a host filters its RPC
 surface and its agent-tool list from the answer, so a set that changed
 afterwards would not be noticed.

crates/tinymemory-api/src/lib.rs

@@ -67,10 +67,10 @@
 //! - [`recall`]: the borrowed [`recall::RecallOpts`] and owned, serde-derived
 //!   [`recall::OwnedRecallOpts`] recall filters (both re-exported from
 //!   [`types`]).
-//! - [`capabilities`]: the twenty [`capabilities::Capability`] families and
+//! - [`capabilities`]: the [`capabilities::Capability`] families and
 //!   the [`capabilities::Capabilities`] set negotiated at bind time.
 //! - [`provider`]: the driver contract — [`provider::MemoryProvider`] plus the
-//!   twenty capability family traits and the value types they need.
+//!   capability family traits and the value types they need.
 //! - [`null`]: [`null::NullMemoryProvider`], the reference driver a
 //!   compiled-out or unconfigured memory subsystem binds to.
 //! - [`health`]: [`health::MemoryHealth`], the liveness state a driver reports.
@@ -118,7 +118,7 @@ pub mod sync_events;
 // nothing type-checks.
 pub use tinymemory_bus::{
     capabilities, chunks, composio, error, evidence, goals, graph, health, learning, namespace,
-    recall, tool_memory, tree, types, version, wire,
+    operations, recall, tool_memory, tree, types, version, wire,
 };
 /// The mandatory-family composition: wrap any [`traits::Memory`] backend as a
 /// complete [`provider::MemoryProvider`].

crates/tinymemory-api/src/null.rs

@@ -55,20 +55,24 @@ use crate::capabilities::{Capabilities, Capability};
 use crate::error::MemoryError;
 use crate::goals::GoalsDoc;
 use crate::health::MemoryHealth;
+use crate::learning::LearningCandidate;
+use crate::operations::{AnswerRequest, AnswerResponse, RawMemoryEvent};
 use crate::provider::types::{
     DiffReport, EntityHit, ExportPage, ExportRecord, FlushOutcome, ImportOutcome, IngestItem,
     IngestOutcome, MaintenanceReport, ResetOutcome, SnapshotRef, SourceItem, SourceScope,
 };
 use crate::provider::{
     AddressBookSeedOutcome, ChunkDetail, ChunkEmbedding, ChunkQuery, CodingSessionIngestReport,
     CodingSessionIngestRequest, CodingSessionSource, CoverWindowQuery, EntityMatch, FacetType,
-    FastRetrieveQuery, MemoryChunks, MemoryCodingSessions, MemoryCore, MemoryDiff, MemoryDocuments,
-    MemoryEntities, MemoryGoals, MemoryGraph, MemoryIngest, MemoryMaintenance, MemoryPeople,
-    MemoryPortability, MemoryProfile, MemoryProvider, MemoryRecall, MemoryRetrieval, MemoryScoring,
-    MemorySourceSink, MemorySourceSync, MemoryToolMemory, MemoryTree, PersonHandle,
-    PersonInteraction, PersonRecord, PersonScore, ProfileFacet, RankedPerson, RawArchiveCoverage,
-    RawRebuildOutcome, ResolvedPerson, RetrievalHit, RetrievalResponse, SourceRetrievalQuery,
-    SourceSyncState, SourceSyncStatus, SyncAuditEntry, SyncRunOutcome, UserState,
+    FastRetrieveQuery, MemoryAnswer, MemoryChunks, MemoryCodingSessions, MemoryConversationIngest,
+    MemoryCore, MemoryDiff, MemoryDocumentIngest, MemoryDocuments, MemoryEntities,
+    MemoryEventIngest, MemoryGoals, MemoryGraph, MemoryIngest, MemoryLearningIngest,
+    MemoryMaintenance, MemoryPeople, MemoryPortability, MemoryProfile, MemoryProvider,
+    MemoryRecall, MemoryRetrieval, MemoryScoring, MemorySourceSink, MemorySourceSync,
+    MemoryToolMemory, MemoryTree, PersonHandle, PersonInteraction, PersonRecord, PersonScore,
+    ProfileFacet, RankedPerson, RawArchiveCoverage, RawRebuildOutcome, ResolvedPerson,
+    RetrievalHit, RetrievalResponse, SourceRetrievalQuery, SourceSyncState, SourceSyncStatus,
+    SyncAuditEntry, SyncRunOutcome, UserState,
 };
 use crate::recall::OwnedRecallOpts;
 use crate::tool_memory::ToolMemoryRule;
@@ -236,6 +240,47 @@ impl MemoryIngest for NullMemoryProvider {
     }
 }
 
+#[async_trait]
+impl MemoryDocumentIngest for NullMemoryProvider {
+    async fn ingest_document(&self, _document: IngestItem) -> Result<IngestOutcome, MemoryError> {
+        unsupported(Capability::DocumentIngest)
+    }
+}
+
+#[async_trait]
+impl MemoryConversationIngest for NullMemoryProvider {
+    async fn ingest_conversation(
+        &self,
+        _messages: Vec<IngestItem>,
+    ) -> Result<IngestOutcome, MemoryError> {
+        unsupported(Capability::ConversationIngest)
+    }
+}
+
+#[async_trait]
+impl MemoryLearningIngest for NullMemoryProvider {
+    async fn ingest_learning(
+        &self,
+        _learning: LearningCandidate,
+    ) -> Result<IngestOutcome, MemoryError> {
+        unsupported(Capability::LearningIngest)
+    }
+}
+
+#[async_trait]
+impl MemoryEventIngest for NullMemoryProvider {
+    async fn ingest_event(&self, _event: RawMemoryEvent) -> Result<IngestOutcome, MemoryError> {
+        unsupported(Capability::EventIngest)
+    }
+}
+
+#[async_trait]
+impl MemoryAnswer for NullMemoryProvider {
+    async fn answer(&self, _request: AnswerRequest) -> Result<AnswerResponse, MemoryError> {
+        unsupported(Capability::Answer)
+    }
+}
+
 #[async_trait]
 impl MemoryDocuments for NullMemoryProvider {
     async fn put_document(&self, _input: NamespaceDocumentInput) -> Result<String, MemoryError> {

crates/tinymemory-api/src/null_tests.rs

@@ -261,7 +261,10 @@ fn every_optional_method_fails_with_its_advertised_family_name() {
         subject: None,
         list_unsubscribe: None,
     };
-    assert_unsupported(block_on(driver.ingest_document(ingest)), Capability::Ingest);
+    assert_unsupported(
+        block_on(MemoryIngest::ingest_document(&driver, ingest)),
+        Capability::Ingest,
+    );
 
     let document = NamespaceDocumentInput {
         namespace: "ns".into(),

crates/tinymemory-api/src/provider/driver.rs

@@ -60,6 +60,10 @@ use crate::provider::content::{MemoryDocuments, MemoryIngest, MemoryTree};
 use crate::provider::episodic::MemoryEpisodic;
 use crate::provider::knowledge::{MemoryDiff, MemoryEntities, MemoryGraph};
 use crate::provider::mandatory::{MemoryCore, MemoryPortability, MemoryRecall};
+use crate::provider::operations::{
+    MemoryAnswer, MemoryConversationIngest, MemoryDocumentIngest, MemoryEventIngest,
+    MemoryLearningIngest,
+};
 use crate::provider::people::MemoryPeople;
 use crate::provider::profile::MemoryProfile;
 use crate::provider::records::{
@@ -220,6 +224,31 @@ pub trait MemoryProvider: MemoryCore + MemoryRecall + MemoryPortability + 'stati
         None
     }
 
+    /// Product-facing document ingestion, when advertised.
+    fn as_document_ingest(&self) -> Option<&dyn MemoryDocumentIngest> {
+        None
+    }
+
+    /// Product-facing conversation ingestion, when advertised.
+    fn as_conversation_ingest(&self) -> Option<&dyn MemoryConversationIngest> {
+        None
+    }
+
+    /// Product-facing learning ingestion, when advertised.
+    fn as_learning_ingest(&self) -> Option<&dyn MemoryLearningIngest> {
+        None
+    }
+
+    /// Product-facing event ingestion, when advertised.
+    fn as_event_ingest(&self) -> Option<&dyn MemoryEventIngest> {
+        None
+    }
+
+    /// Agentic grounded answers, when advertised.
+    fn as_answer(&self) -> Option<&dyn MemoryAnswer> {
+        None
+    }
+
     /// Whether `capability` is actually **reachable** on this driver.
     ///
     /// This is the implementation-side truth, as opposed to
@@ -253,6 +282,11 @@ pub trait MemoryProvider: MemoryCore + MemoryRecall + MemoryPortability + 'stati
             Capability::SourceSync => self.as_source_sync().is_some(),
             Capability::CodingSessions => self.as_coding_sessions().is_some(),
             Capability::Scoring => self.as_scoring().is_some(),
+            Capability::DocumentIngest => self.as_document_ingest().is_some(),
+            Capability::ConversationIngest => self.as_conversation_ingest().is_some(),
+            Capability::LearningIngest => self.as_learning_ingest().is_some(),
+            Capability::EventIngest => self.as_event_ingest().is_some(),
+            Capability::Answer => self.as_answer().is_some(),
         }
     }
 }

crates/tinymemory-api/src/provider/mod.rs

@@ -1,4 +1,4 @@
-//! The memory driver contract: [`MemoryProvider`] plus the twenty capability
+//! The memory driver contract: [`MemoryProvider`] plus its capability
 //! family traits a driver may implement.
 //!
 //! ## Shape
@@ -58,7 +58,8 @@
 //!
 //! ## Reference implementation
 //!
-//! [`crate::null::NullMemoryProvider`] implements all twenty families:
+//! [`crate::null::NullMemoryProvider`] implements every family directly for
+//! conformance testing:
 //! `/dev/null` semantics for the mandatory three, and
 //! [`crate::error::MemoryError::Unsupported`] for the other seventeen, which it
 //! does not advertise. It is what a compiled-out or unconfigured memory subsystem
@@ -72,6 +73,7 @@ pub mod driver;
 pub mod episodic;
 pub mod knowledge;
 pub mod mandatory;
+pub mod operations;
 pub mod people;
 pub mod profile;
 pub mod records;
@@ -104,6 +106,11 @@ pub use driver::MemoryProvider;
 pub use episodic::{ConversationSegment, EpisodicEvent, EpisodicTurn, EventKind, MemoryEpisodic};
 pub use knowledge::{MemoryDiff, MemoryEntities, MemoryGraph, INBOUND_SCAN_LIMIT};
 pub use mandatory::{MemoryCore, MemoryPortability, MemoryRecall};
+pub use operations::{
+    AnswerCitation, AnswerRequest, AnswerResponse, AnswerStep, MemoryAnswer,
+    MemoryConversationIngest, MemoryDocumentIngest, MemoryEventIngest, MemoryLearningIngest,
+    RawMemoryEvent,
+};
 pub use people::{
     AddressBookSeedOutcome, MemoryPeople, PersonHandle, PersonInteraction, PersonRecord, PersonRef,
     PersonScore, RankedPerson, ResolvedPerson,

crates/tinymemory-api/src/provider/operations.rs

@@ -0,0 +1,82 @@
+//! Granular product-facing ingestion and answer operations.
+//!
+//! These traits deliberately split the legacy [`MemoryIngest`](super::MemoryIngest)
+//! family. A connector may be excellent at conversations while having no
+//! document, learning, or event model, and capability negotiation must be able
+//! to express exactly that.
+
+use async_trait::async_trait;
+
+use crate::error::MemoryError;
+use crate::learning::LearningCandidate;
+use crate::provider::types::{IngestItem, IngestOutcome};
+
+pub use crate::operations::{
+    AnswerCitation, AnswerRequest, AnswerResponse, AnswerStep, RawMemoryEvent,
+};
+
+/// Document ingestion with driver-owned chunking and indexing.
+#[async_trait]
+pub trait MemoryDocumentIngest: Send + Sync {
+    /// Ingest one decoded document.
+    ///
+    /// # Errors
+    ///
+    /// Returns [`MemoryError::Invalid`] for rejected input and a backend error
+    /// when persistence or indexing fails.
+    async fn ingest_document(&self, document: IngestItem) -> Result<IngestOutcome, MemoryError>;
+}
+
+/// Ordered conversation ingestion.
+#[async_trait]
+pub trait MemoryConversationIngest: Send + Sync {
+    /// Ingest all messages belonging to one conversation.
+    ///
+    /// # Errors
+    ///
+    /// Returns [`MemoryError::Invalid`] when the batch mixes conversations or
+    /// contains invalid content, otherwise backend failures.
+    async fn ingest_conversation(
+        &self,
+        messages: Vec<IngestItem>,
+    ) -> Result<IngestOutcome, MemoryError>;
+}
+
+/// Ingestion of already-extracted learnings.
+#[async_trait]
+pub trait MemoryLearningIngest: Send + Sync {
+    /// Persist one learning candidate and its evidence pointer.
+    ///
+    /// # Errors
+    ///
+    /// Returns [`MemoryError::Invalid`] for malformed confidence or keys,
+    /// otherwise backend failures.
+    async fn ingest_learning(
+        &self,
+        learning: LearningCandidate,
+    ) -> Result<IngestOutcome, MemoryError>;
+}
+
+/// Ingestion of raw durable events.
+#[async_trait]
+pub trait MemoryEventIngest: Send + Sync {
+    /// Persist one event.
+    ///
+    /// # Errors
+    ///
+    /// Returns [`MemoryError::Invalid`] for malformed event data, otherwise
+    /// backend failures.
+    async fn ingest_event(&self, event: RawMemoryEvent) -> Result<IngestOutcome, MemoryError>;
+}
+
+/// Agentic retrieval that synthesises a grounded answer.
+#[async_trait]
+pub trait MemoryAnswer: Send + Sync {
+    /// Retrieve evidence and synthesize an answer with citations.
+    ///
+    /// # Errors
+    ///
+    /// Returns [`MemoryError::Invalid`] for an empty query and backend or
+    /// inference errors when retrieval or synthesis fails.
+    async fn answer(&self, request: AnswerRequest) -> Result<AnswerResponse, MemoryError>;
+}

crates/tinymemory-bus/README.md

@@ -50,7 +50,7 @@ A host depends on `tinymemory-bus` and gets vocabulary alone.
 
 ## What is deliberately absent
 
-**No traits.** `MemoryProvider` and the twenty capability-family traits
+**No traits.** `MemoryProvider` and its capability-family traits
 describe what an engine must implement, not what a frame carries. They stay in
 `tinymemory-api`. The split is readable off the path: a name here is data, a
 name there is an obligation.