feat(agentic): Phase 2 — long-term semantic memory + SQLite conversation store (#1544)

Long-term cross-thread memory (the durable counterpart to per-thread IConversationStore):

- IAgentMemoryStore (AddAsync/SearchAsync/GetAllAsync/RemoveAsync) + AgentMemory/ScoredMemory.

- InMemoryAgentMemoryStore: lexical-overlap ranking (zero-config, no model).

- EmbeddingAgentMemoryStore<T>: TRUE semantic recall — embeds memories+query via IEmbeddingModel<T> and ranks by the RAG stack's ISimilarityMetric<T> (cosine by default), reusing existing RAG infrastructure. Drop-in over the lexical default (same interface).

- MemoryAugmentedAgent<T> (IAgent<T>): retrieves memories relevant to the latest user message and injects them as system context before delegating to the inner agent (executor/supervisor/swarm). Read-only by design — what gets remembered stays under app control. Composes with ThreadedAgent (long-term recall + short-term thread memory).

Durable conversation backend:

- SqliteConversationStore (AiDotNet.Storage.Sqlite): DB-backed IConversationStore (auto-incrementing Seq preserves order, schema created on demand), keeping the native SQLite dep out of core. Mirrors the SQLite graph checkpointer.

- 12 tests (9 memory green net10.0+net471; 3 SQLite conversation net10-gated for the e_sqlite3 native-lib reason — pre-existing repo-wide). No null-forgiving.

Part of epic #1544 (Phase 2).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: franklinic

src/Agentic/Memory/AgentMemory.cs

@@ -0,0 +1,42 @@
+namespace AiDotNet.Agentic.Memory;
+
+/// <summary>
+/// A single long-term memory: a piece of text the agent should be able to recall later, with a stable id
+/// and optional metadata. Memories live across conversation threads (unlike <see cref="IConversationStore"/>,
+/// which is per-thread short-term history).
+/// </summary>
+/// <remarks>
+/// <para><b>For Beginners:</b> Think of one sticky note the assistant keeps — e.g. "the user prefers metric
+/// units" or "the project deadline is in June". Each note has a unique id (so it can be updated or removed)
+/// and the note text itself. Later, when something relevant comes up, the assistant can find and re-read the
+/// note even if it's in a completely different conversation.
+/// </para>
+/// </remarks>
+public sealed class AgentMemory
+{
+    /// <summary>
+    /// Initializes a new memory.
+    /// </summary>
+    /// <param name="id">The stable, unique identifier for this memory.</param>
+    /// <param name="content">The remembered text. Must be non-empty.</param>
+    /// <param name="metadata">Optional key/value metadata (e.g., source, category). <c>null</c> means none.</param>
+    /// <exception cref="ArgumentNullException">Thrown when <paramref name="id"/> or <paramref name="content"/> is <c>null</c>.</exception>
+    /// <exception cref="ArgumentException">Thrown when <paramref name="id"/> or <paramref name="content"/> is empty/whitespace.</exception>
+    public AgentMemory(string id, string content, IReadOnlyDictionary<string, string>? metadata = null)
+    {
+        Guard.NotNullOrWhiteSpace(id);
+        Guard.NotNullOrWhiteSpace(content);
+        Id = id;
+        Content = content;
+        Metadata = metadata;
+    }
+
+    /// <summary>Gets the stable, unique identifier for this memory.</summary>
+    public string Id { get; }
+
+    /// <summary>Gets the remembered text.</summary>
+    public string Content { get; }
+
+    /// <summary>Gets optional key/value metadata, or <c>null</c> when none was supplied.</summary>
+    public IReadOnlyDictionary<string, string>? Metadata { get; }
+}

src/Agentic/Memory/EmbeddingAgentMemoryStore.cs

@@ -0,0 +1,137 @@
+using AiDotNet.Interfaces;
+using AiDotNet.LinearAlgebra;
+using AiDotNet.RetrievalAugmentedGeneration.VectorSearch;
+using AiDotNet.RetrievalAugmentedGeneration.VectorSearch.Metrics;
+
+namespace AiDotNet.Agentic.Memory;
+
+/// <summary>
+/// A semantic <see cref="IAgentMemoryStore"/> that ranks memories by meaning, not words. It embeds each
+/// memory with an <see cref="IEmbeddingModel{T}"/> and scores a query by cosine similarity against those
+/// embeddings — reusing AiDotNet's RAG embedding and similarity-metric stack, so a memory about "due date"
+/// is recalled for a query about "deadline".
+/// </summary>
+/// <typeparam name="T">The numeric type of the embedding model and similarity metric.</typeparam>
+/// <remarks>
+/// <para>
+/// Memories and their embedding vectors are held in memory; the vector for each memory is computed once on
+/// <see cref="AddAsync"/>. This keeps the abstraction identical to the lexical
+/// <see cref="InMemoryAgentMemoryStore"/> while delivering true semantic recall — pick whichever fits the
+/// deployment without touching agent code.
+/// </para>
+/// <para><b>For Beginners:</b> Same notebook idea, but instead of matching words it matches <em>meaning</em>.
+/// It turns every note (and your question) into a list of numbers that capture meaning, then finds the notes
+/// whose numbers are closest to your question's — so synonyms and paraphrases still match.
+/// </para>
+/// </remarks>
+public sealed class EmbeddingAgentMemoryStore<T> : IAgentMemoryStore
+{
+    private readonly object _gate = new();
+    private readonly List<Entry> _entries = new();
+    private readonly IEmbeddingModel<T> _embeddingModel;
+    private readonly ISimilarityMetric<T> _similarity;
+
+    /// <summary>
+    /// Initializes a new semantic memory store.
+    /// </summary>
+    /// <param name="embeddingModel">The model used to embed memories and queries.</param>
+    /// <param name="similarity">The similarity metric. <c>null</c> uses cosine similarity.</param>
+    /// <exception cref="ArgumentNullException">Thrown when <paramref name="embeddingModel"/> is <c>null</c>.</exception>
+    public EmbeddingAgentMemoryStore(IEmbeddingModel<T> embeddingModel, ISimilarityMetric<T>? similarity = null)
+    {
+        Guard.NotNull(embeddingModel);
+        _embeddingModel = embeddingModel;
+        _similarity = similarity ?? new CosineSimilarityMetric<T>();
+    }
+
+    /// <inheritdoc/>
+    public async Task<string> AddAsync(
+        string content,
+        IReadOnlyDictionary<string, string>? metadata = null,
+        CancellationToken cancellationToken = default)
+    {
+        Guard.NotNullOrWhiteSpace(content);
+        var id = Guid.NewGuid().ToString("N");
+        var memory = new AgentMemory(id, content, metadata);
+        var vector = await _embeddingModel.EmbedAsync(content).ConfigureAwait(false);
+
+        lock (_gate)
+        {
+            _entries.Add(new Entry(memory, vector));
+        }
+
+        return id;
+    }
+
+    /// <inheritdoc/>
+    public async Task<IReadOnlyList<ScoredMemory>> SearchAsync(
+        string query,
+        int topK = 5,
+        CancellationToken cancellationToken = default)
+    {
+        Guard.NotNullOrWhiteSpace(query);
+        Guard.Positive(topK);
+
+        List<Entry> snapshot;
+        lock (_gate)
+        {
+            snapshot = new List<Entry>(_entries);
+        }
+
+        if (snapshot.Count == 0)
+        {
+            return new List<ScoredMemory>();
+        }
+
+        var queryVector = await _embeddingModel.EmbedAsync(query).ConfigureAwait(false);
+
+        var scored = new List<ScoredMemory>(snapshot.Count);
+        foreach (var entry in snapshot)
+        {
+            var score = Convert.ToDouble(_similarity.Calculate(queryVector, entry.Vector));
+            scored.Add(new ScoredMemory(entry.Memory, score));
+        }
+
+        var ordered = _similarity.HigherIsBetter
+            ? scored.OrderByDescending(s => s.Score)
+            : scored.OrderBy(s => s.Score);
+
+        return ordered.Take(topK).ToList();
+    }
+
+    /// <inheritdoc/>
+    public Task<IReadOnlyList<AgentMemory>> GetAllAsync(CancellationToken cancellationToken = default)
+    {
+        lock (_gate)
+        {
+            IReadOnlyList<AgentMemory> all = _entries.Select(e => e.Memory).ToList();
+            return Task.FromResult(all);
+        }
+    }
+
+    /// <inheritdoc/>
+    public Task RemoveAsync(string id, CancellationToken cancellationToken = default)
+    {
+        Guard.NotNullOrWhiteSpace(id);
+
+        lock (_gate)
+        {
+            _entries.RemoveAll(e => string.Equals(e.Memory.Id, id, StringComparison.Ordinal));
+        }
+
+        return Task.CompletedTask;
+    }
+
+    private readonly struct Entry
+    {
+        public Entry(AgentMemory memory, Vector<T> vector)
+        {
+            Memory = memory;
+            Vector = vector;
+        }
+
+        public AgentMemory Memory { get; }
+
+        public Vector<T> Vector { get; }
+    }
+}

src/Agentic/Memory/IAgentMemoryStore.cs

@@ -0,0 +1,59 @@
+namespace AiDotNet.Agentic.Memory;
+
+/// <summary>
+/// A long-term, cross-thread memory store: it remembers facts and can retrieve the ones most relevant to a
+/// query. This is the durable counterpart to the per-thread <see cref="IConversationStore"/> and the
+/// retrieval source behind <see cref="MemoryAugmentedAgent{T}"/>.
+/// </summary>
+/// <remarks>
+/// <para>
+/// Implementations differ only in <em>how</em> they rank relevance: <see cref="InMemoryAgentMemoryStore"/>
+/// uses lexical overlap (zero-config, no model), while <c>EmbeddingAgentMemoryStore&lt;T&gt;</c> uses an
+/// <see cref="AiDotNet.Interfaces.IEmbeddingModel{T}"/> for true semantic similarity by reusing AiDotNet's
+/// RAG embedding + cosine-metric stack. Callers depend only on this interface, so semantic search is a
+/// drop-in upgrade over the lexical default.
+/// </para>
+/// <para><b>For Beginners:</b> This is the assistant's notebook of long-term facts. You can add notes,
+/// search for the notes most related to a question, list them, or remove one. Whether the search matches by
+/// shared words or by meaning depends on which implementation you plug in — the way you use it is the same.
+/// </para>
+/// </remarks>
+public interface IAgentMemoryStore
+{
+    /// <summary>
+    /// Stores a new memory and returns its generated id.
+    /// </summary>
+    /// <param name="content">The text to remember. Must be non-empty.</param>
+    /// <param name="metadata">Optional key/value metadata. <c>null</c> means none.</param>
+    /// <param name="cancellationToken">Token used to cancel the operation.</param>
+    /// <returns>The new memory's id.</returns>
+    Task<string> AddAsync(
+        string content,
+        IReadOnlyDictionary<string, string>? metadata = null,
+        CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// Returns the memories most relevant to a query, highest score first.
+    /// </summary>
+    /// <param name="query">The query text. Must be non-empty.</param>
+    /// <param name="topK">The maximum number of memories to return. Must be positive.</param>
+    /// <param name="cancellationToken">Token used to cancel the operation.</param>
+    /// <returns>The top matches ordered by descending relevance (empty when nothing matches).</returns>
+    Task<IReadOnlyList<ScoredMemory>> SearchAsync(
+        string query,
+        int topK = 5,
+        CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// Returns all stored memories (order unspecified).
+    /// </summary>
+    /// <param name="cancellationToken">Token used to cancel the operation.</param>
+    Task<IReadOnlyList<AgentMemory>> GetAllAsync(CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// Removes a memory by id. A no-op when the id is unknown.
+    /// </summary>
+    /// <param name="id">The id of the memory to remove. Must be non-empty.</param>
+    /// <param name="cancellationToken">Token used to cancel the operation.</param>
+    Task RemoveAsync(string id, CancellationToken cancellationToken = default);
+}

src/Agentic/Memory/InMemoryAgentMemoryStore.cs

@@ -0,0 +1,138 @@
+using System.Text;
+
+namespace AiDotNet.Agentic.Memory;
+
+/// <summary>
+/// A process-local <see cref="IAgentMemoryStore"/> that ranks memories by lexical overlap with the query —
+/// the fraction of the query's words that appear in the memory. Requires no embedding model, so it is the
+/// zero-config default; for meaning-based recall, use <c>EmbeddingAgentMemoryStore&lt;T&gt;</c>.
+/// </summary>
+/// <remarks>
+/// <para><b>For Beginners:</b> This notebook finds notes by matching words. If you ask about "deadline" it
+/// finds notes containing "deadline", but it won't realize "due date" means the same thing — that needs the
+/// embedding-backed store. It's fast, needs no setup, and is great for tests and simple cases.
+/// </para>
+/// </remarks>
+public sealed class InMemoryAgentMemoryStore : IAgentMemoryStore
+{
+    private readonly object _gate = new();
+    private readonly List<AgentMemory> _memories = new();
+
+    /// <inheritdoc/>
+    public Task<string> AddAsync(
+        string content,
+        IReadOnlyDictionary<string, string>? metadata = null,
+        CancellationToken cancellationToken = default)
+    {
+        Guard.NotNullOrWhiteSpace(content);
+        var id = Guid.NewGuid().ToString("N");
+        var memory = new AgentMemory(id, content, metadata);
+
+        lock (_gate)
+        {
+            _memories.Add(memory);
+        }
+
+        return Task.FromResult(id);
+    }
+
+    /// <inheritdoc/>
+    public Task<IReadOnlyList<ScoredMemory>> SearchAsync(
+        string query,
+        int topK = 5,
+        CancellationToken cancellationToken = default)
+    {
+        Guard.NotNullOrWhiteSpace(query);
+        Guard.Positive(topK);
+
+        var queryTerms = Tokenize(query);
+        if (queryTerms.Count == 0)
+        {
+            return Task.FromResult<IReadOnlyList<ScoredMemory>>(new List<ScoredMemory>());
+        }
+
+        List<AgentMemory> snapshot;
+        lock (_gate)
+        {
+            snapshot = new List<AgentMemory>(_memories);
+        }
+
+        var scored = new List<ScoredMemory>();
+        foreach (var memory in snapshot)
+        {
+            var terms = Tokenize(memory.Content);
+            if (terms.Count == 0)
+            {
+                continue;
+            }
+
+            var matches = 0;
+            foreach (var term in queryTerms)
+            {
+                if (terms.Contains(term))
+                {
+                    matches++;
+                }
+            }
+
+            if (matches > 0)
+            {
+                scored.Add(new ScoredMemory(memory, (double)matches / queryTerms.Count));
+            }
+        }
+
+        IReadOnlyList<ScoredMemory> result = scored
+            .OrderByDescending(s => s.Score)
+            .Take(topK)
+            .ToList();
+        return Task.FromResult(result);
+    }
+
+    /// <inheritdoc/>
+    public Task<IReadOnlyList<AgentMemory>> GetAllAsync(CancellationToken cancellationToken = default)
+    {
+        lock (_gate)
+        {
+            IReadOnlyList<AgentMemory> all = new List<AgentMemory>(_memories);
+            return Task.FromResult(all);
+        }
+    }
+
+    /// <inheritdoc/>
+    public Task RemoveAsync(string id, CancellationToken cancellationToken = default)
+    {
+        Guard.NotNullOrWhiteSpace(id);
+
+        lock (_gate)
+        {
+            _memories.RemoveAll(m => string.Equals(m.Id, id, StringComparison.Ordinal));
+        }
+
+        return Task.CompletedTask;
+    }
+
+    private static HashSet<string> Tokenize(string text)
+    {
+        var terms = new HashSet<string>(StringComparer.OrdinalIgnoreCase);
+        var current = new StringBuilder();
+        foreach (var ch in text)
+        {
+            if (char.IsLetterOrDigit(ch))
+            {
+                current.Append(char.ToLowerInvariant(ch));
+            }
+            else if (current.Length > 0)
+            {
+                terms.Add(current.ToString());
+                current.Clear();
+            }
+        }
+
+        if (current.Length > 0)
+        {
+            terms.Add(current.ToString());
+        }
+
+        return terms;
+    }
+}