Expose gated memory intake API

Author: robertohluna

README.md

@@ -110,7 +110,7 @@ Built and verified now:
 | Derivation Ledger | Source-to-Claim, Claim-to-Fact, and Fact-to-Memory steps write lineage entries. |
 | Governed retrieval | Retrieval returns Context Packages, not loose chunks, writes explicit retrieval-plan metadata, applies structured subject/action/object and asset filters, filters Facts, Memory Objects, and asset extraction projections by partition/security scope before package assembly, marks affected packages stale when returned Facts or Memory Objects are superseded, can refresh a stale package from its original request scope, can batch refresh stale packages, and exposes API, CLI/cron, and supervised scheduler triggers for app/agent/runtime workflows. |
 | Active Memory Pools | Task-scoped working memory can load Context Packages, refresh stale loaded Context Packages, and publish observations as pending Claims. |
-| Smart memory intake | `Memory.remember/2` can gate low-salience writes, skip semantic duplicates, update superseded memories, and attach intake metadata before the governed Source Package and pending Claim bridge runs. |
+| Smart memory intake | `Memory.remember/2` and `POST /api/memory/remember` can gate low-salience writes, skip semantic duplicates, update superseded memories, and attach intake metadata before the governed Source Package and pending Claim bridge runs. |
 | Tool/model governance | Registered tools and model operations can enforce privileges, partitions, required inputs, required outputs, audit links, and the first governed execution path. |
 | Connector governance | Connector sync runs through the governed tool-call surface by default, blocking unauthorized runs before connector execution and recording both connector-run and tool-call audit rows when allowed. Raw sync requires an explicit `governed: false` bypass. |
 | Evaluation runner | Benchmark/evaluation runs can execute against governed retrieval, load JSON/JSONL datasets, assemble Context Packages per question, produce deterministic local answer surfaces, judge expected-answer matches, persist per-case scores, and update aggregate run scores. `mix optimal.eval.run` exposes the flow for CLI/cron use, and external answerer/judge callbacks can be plugged in later without changing the storage contract. |
@@ -136,7 +136,7 @@ mix test test/memory_core/spine_test.exs test/pipeline/multimodal_adapter_runner
 28 tests, 0 failures
 
 mix test test/api/router_test.exs --seed 0
-27 tests, 0 failures
+31 tests, 0 failures
 
 mix test test/connectors/asset_ingest_test.exs --seed 0
 3 tests, 0 failures

lib/optimal_engine/api/router.ex

@@ -1188,6 +1188,53 @@ defmodule OptimalEngine.API.Router do
     end
   end
 
+  # POST /api/memory/remember — gated memory intake for agent/app writes.
+  # Body: {content, workspace?, audience?, metadata?, force?, gate_threshold?,
+  #        salience_floor?, skip_threshold?, update_threshold?}
+  # Returns: 200 + {action, memory?, gate, dedup?}.
+  post "/api/memory/remember" do
+    body = conn.body_params || %{}
+    content = Map.get(body, "content")
+
+    if not (is_binary(content) and content != "") do
+      send_resp(conn, 400, Jason.encode!(%{error: "content is required"}))
+    else
+      attrs =
+        %{
+          content: content,
+          workspace_id: Map.get(body, "workspace", Map.get(body, "workspace_id", "default"))
+        }
+        |> maybe_put(:tenant_id, Map.get(body, "tenant", Map.get(body, "tenant_id")))
+        |> maybe_put(:is_static, Map.get(body, "is_static"))
+        |> maybe_put(:audience, Map.get(body, "audience"))
+        |> maybe_put(:citation_uri, Map.get(body, "citation_uri"))
+        |> maybe_put(:source_chunk_id, Map.get(body, "source_chunk_id"))
+        |> maybe_put(:metadata, Map.get(body, "metadata"))
+        |> maybe_put(:actor_id, Map.get(body, "actor_id"))
+        |> maybe_put(:access_policy_id, Map.get(body, "access_policy_id"))
+        |> maybe_put(:security_labels, string_list_param(body, "security_labels"))
+        |> maybe_put(:partition_ids, string_list_param(body, "partition_ids"))
+
+      opts =
+        [
+          force: parse_bool(Map.get(body, "force"), false),
+          gate_threshold: parse_float(Map.get(body, "gate_threshold")),
+          salience_floor: parse_float(Map.get(body, "salience_floor")),
+          skip_threshold: parse_float(Map.get(body, "skip_threshold")),
+          update_threshold: parse_float(Map.get(body, "update_threshold"))
+        ]
+        |> reject_nil_keyword()
+
+      case OptimalEngine.Memory.remember(attrs, opts) do
+        {:ok, result} ->
+          json(conn, memory_intake_result_to_map(result))
+
+        {:error, reason} ->
+          send_resp(conn, 500, Jason.encode!(%{error: inspect(reason)}))
+      end
+    end
+  end
+
   # POST /api/assets — preserve a multimodal file through the governed asset path.
   #
   # JSON body supports either:
@@ -1873,6 +1920,40 @@ defmodule OptimalEngine.API.Router do
     }
   end
 
+  defp memory_intake_result_to_map(result) do
+    %{
+      action: Atom.to_string(result.action),
+      memory: result.memory && memory_to_map(result.memory),
+      gate: memory_intake_gate_to_map(result.gate),
+      dedup: memory_intake_dedup_to_map(result.dedup)
+    }
+  end
+
+  defp memory_intake_gate_to_map(nil), do: nil
+
+  defp memory_intake_gate_to_map(gate) do
+    %{
+      should_encode: gate.should_encode,
+      score: gate.score,
+      novelty: gate.novelty,
+      salience: gate.salience,
+      prediction_error: gate.prediction_error,
+      reason: gate.reason,
+      similar_memory_id: gate.similar_memory_id
+    }
+  end
+
+  defp memory_intake_dedup_to_map(nil), do: nil
+
+  defp memory_intake_dedup_to_map(dedup) do
+    %{
+      action: Atom.to_string(dedup.action),
+      reason: dedup.reason,
+      similarity: dedup.similarity,
+      existing_memory_id: dedup.existing && dedup.existing.id
+    }
+  end
+
   defp claim_to_map(claim) when is_map(claim) do
     if Map.has_key?(claim, :__struct__) do
       claim
@@ -2144,6 +2225,20 @@ defmodule OptimalEngine.API.Router do
   defp parse_bool(false, _default), do: false
   defp parse_bool(_, default), do: default
 
+  defp parse_float(nil), do: nil
+  defp parse_float(""), do: nil
+  defp parse_float(value) when is_float(value), do: value
+  defp parse_float(value) when is_integer(value), do: value / 1
+
+  defp parse_float(value) when is_binary(value) do
+    case Float.parse(value) do
+      {float, ""} -> float
+      _ -> nil
+    end
+  end
+
+  defp parse_float(_value), do: nil
+
   # Resolve a workspace id (e.g. "default" or "default:engineering") to a
   # Workspace struct. Returns `{:error, :not_found}` for unknown ids.
   defp resolve_workspace(id) do

lib/optimal_engine/memory_core/asset_store.ex

@@ -709,12 +709,10 @@ defmodule OptimalEngine.MemoryCore.AssetStore do
   defp normalize_adapter_id(id) when is_atom(id), do: id
 
   defp normalize_adapter_id(id) when is_binary(id) do
-    id
-    |> String.downcase()
-    |> String.replace("-", "_")
-    |> String.to_existing_atom()
-  rescue
-    ArgumentError -> :unknown
+    case MultimodalToolRegistry.get(id) do
+      %{id: tool_id} -> tool_id
+      nil -> :unknown
+    end
   end
 
   defp build_adapter_run(asset, tool, opts) do

lib/optimal_engine/pipeline/multimodal_adapter_runner.ex

@@ -170,13 +170,10 @@ defmodule OptimalEngine.Pipeline.MultimodalAdapterRunner do
   end
 
   defp get_tool(adapter_id) when is_binary(adapter_id) do
-    adapter_id
-    |> String.downcase()
-    |> String.replace("-", "_")
-    |> String.to_existing_atom()
-    |> get_tool()
-  rescue
-    ArgumentError -> {:error, {:unknown_adapter, adapter_id}}
+    case MultimodalToolRegistry.get(adapter_id) do
+      nil -> {:error, {:unknown_adapter, adapter_id}}
+      tool -> {:ok, tool}
+    end
   end
 
   defp scope_opts(opts) do

lib/optimal_engine/pipeline/multimodal_tool_registry.ex

@@ -298,9 +298,14 @@ defmodule OptimalEngine.Pipeline.MultimodalToolRegistry do
   @spec tools() :: [tool()]
   def tools, do: @tools
 
-  @spec get(tool_id()) :: tool() | nil
+  @spec get(tool_id() | String.t()) :: tool() | nil
   def get(id) when is_atom(id), do: Enum.find(@tools, &(&1.id == id))
 
+  def get(id) when is_binary(id) do
+    normalized = normalize_id_string(id)
+    Enum.find(@tools, &(normalize_id_string(Atom.to_string(&1.id)) == normalized))
+  end
+
   @spec profile(tool_id()) :: adapter_profile() | nil
   def profile(id) when is_atom(id) do
     case get(id) do
@@ -367,4 +372,11 @@ defmodule OptimalEngine.Pipeline.MultimodalToolRegistry do
         false
     end
   end
+
+  defp normalize_id_string(id) do
+    id
+    |> String.downcase()
+    |> String.replace(~r/[^a-z0-9]+/, "_")
+    |> String.trim("_")
+  end
 end

test/api/router_test.exs

@@ -117,6 +117,45 @@ defmodule OptimalEngine.API.RouterTest do
   end
 
   describe "Memory Core claim governance API" do
+    test "gated memory intake adds salient memory and skips duplicates" do
+      workspace_id = "api-memory-remember-#{System.unique_integer([:positive])}"
+
+      first_conn =
+        request(:post, "/api/memory/remember", %{
+          "workspace" => workspace_id,
+          "content" => "Decision: Revenue lead owns renewal pricing for Q4 at $2000.",
+          "metadata" => %{"source" => "api-remember-test"}
+        })
+
+      assert first_conn.status == 200
+      assert {:ok, first_body} = Jason.decode(first_conn.resp_body)
+      assert first_body["action"] == "add"
+      assert first_body["memory"]["content"] =~ "Revenue lead"
+      assert first_body["gate"]["should_encode"] == true
+      assert first_body["dedup"]["action"] == "add"
+
+      list_conn = request(:get, "/api/memory-core/claims?workspace=#{workspace_id}")
+      assert {:ok, list_body} = Jason.decode(list_conn.resp_body)
+      assert list_body["count"] == 1
+
+      duplicate_conn =
+        request(:post, "/api/memory/remember", %{
+          "workspace" => workspace_id,
+          "content" => "Decision: Revenue lead owns renewal pricing for Q4 at $2000."
+        })
+
+      assert duplicate_conn.status == 200
+      assert {:ok, duplicate_body} = Jason.decode(duplicate_conn.resp_body)
+      assert duplicate_body["action"] == "skip"
+      assert duplicate_body["memory"]["id"] == first_body["memory"]["id"]
+      assert duplicate_body["memory"]["was_existing"] == true
+      assert duplicate_body["dedup"]["action"] == "skip"
+
+      after_conn = request(:get, "/api/memory-core/claims?workspace=#{workspace_id}")
+      assert {:ok, after_body} = Jason.decode(after_conn.resp_body)
+      assert after_body["count"] == 1
+    end
+
     test "lists pending claims and promotes one into fact and memory object" do
       workspace_id = "api-claim-review-#{System.unique_integer([:positive])}"
       content = "API claim promotion #{System.unique_integer([:positive])}"

test/pipeline/multimodal_tool_registry_test.exs

@@ -29,6 +29,13 @@ defmodule OptimalEngine.Pipeline.MultimodalToolRegistryTest do
     assert Enum.any?(image_tools, &(&1.id == :open_clip))
   end
 
+  test "resolves adapter ids from JSON-safe strings" do
+    assert %{id: :openai_whisper} = MultimodalToolRegistry.get("openai_whisper")
+    assert %{id: :openai_whisper} = MultimodalToolRegistry.get("openai-whisper")
+    assert %{id: :openai_whisper} = MultimodalToolRegistry.get("OpenAI Whisper")
+    assert is_nil(MultimodalToolRegistry.get("not-a-real-adapter"))
+  end
+
   test "returns recommended pipelines by modality" do
     assert MultimodalToolRegistry.recommended_tool_ids(:document) == [
              :docling,