@spec apply_changeset(GenServer.server(), Mnemosyne.Graph.Changeset.t()) :: :ok

Applies a changeset to the graph via the backend.

Returns a specification to start this module under a supervisor.

See Supervisor.

@spec consolidate_semantics(
  GenServer.server(),
  keyword()
) :: :ok

Consolidates near-duplicate semantic nodes.

@spec decay_nodes(
  GenServer.server(),
  keyword()
) :: :ok

Prunes low-utility nodes via decay scoring.

@spec delete_nodes(GenServer.server(), [String.t()]) :: :ok

Removes nodes from the graph via the backend.

@spec get_graph(GenServer.server()) :: Mnemosyne.Graph.t()

Returns the current in-memory graph.

Only works with backends that expose a :graph field in their state (e.g. InMemory). Returns an empty graph for other backends.

@spec get_linked_nodes(GenServer.server(), [String.t()]) ::
  {:ok, [struct()]} | {:error, term()}

Fetches nodes by their IDs from the backend.

@spec get_metadata(GenServer.server(), [String.t()]) ::
  {:ok, %{required(String.t()) => Mnemosyne.NodeMetadata.t()}}
  | {:error, term()}

Fetches metadata for the given node IDs.

@spec get_node(GenServer.server(), String.t()) ::
  {:ok, struct() | nil} | {:error, term()}

Fetches a single node by ID from the backend.

@spec get_nodes_by_type(GenServer.server(), [atom()]) ::
  {:ok, [struct()]} | {:error, term()}

Fetches all nodes of the given types from the backend.

@spec get_session_defaults(GenServer.server()) :: %{
  config: term(),
  llm: module(),
  embedding: module(),
  notifier: module(),
  repo_id: String.t() | nil
}

Returns the config, llm, embedding, notifier, and repo_id for session creation.

@spec latest(GenServer.server(), pos_integer(), keyword()) ::
  {:ok, [{struct(), Mnemosyne.NodeMetadata.t()}]} | {:error, term()}

Fetches the most recently created nodes of the given types, sorted by creation time.

Returns up to top_k nodes paired with their metadata, newest first. Defaults to semantic and procedural node types.

@spec recall(GenServer.server(), String.t(), keyword()) ::
  {:ok, Mnemosyne.Pipeline.RecallResult.t()}
  | {:error, Mnemosyne.Errors.error()}

Runs async retrieval + reasoning and returns the result.

@spec recall_in_context(GenServer.server(), term(), String.t(), keyword()) ::
  {:ok, Mnemosyne.Pipeline.RecallResult.t()}
  | {:error, Mnemosyne.Errors.error()}

Fetches session context, augments the query, then runs recall.

@spec repair_graph(
  GenServer.server(),
  keyword()
) :: :ok

Strips dangling link references and deletes orphaned routing nodes.

@spec validate_episodic(
  GenServer.server(),
  keyword()
) :: :ok

Validates episodic grounding and penalizes weakly grounded nodes.