Mnemosyne.GraphBackend behaviour (mnemosyne v0.1.6)

Copy Markdown View Source

Behaviour for unified graph persistence and querying backends.

Implementations handle storing, retrieving, and querying knowledge graph nodes through a single interface, replacing the separate Storage and in-memory Graph modules with a database-agnostic contract.

Callbacks

  • init/1 - Initialize the backend with configuration options.
  • apply_changeset/2 - Persist a batch of node additions and links.
  • delete_nodes/2 - Remove nodes by their IDs.
  • find_candidates/6 - Query for nodes matching type/embedding/tag criteria.
  • get_node/2 - Fetch a single node by ID.
  • get_linked_nodes/3 - Fetch linked nodes, optionally filtered by edge type.

Read callbacks (find_candidates, get_node, get_linked_nodes) return state for interface uniformity but must not rely on state mutation — callers may discard the returned state in read-only contexts.

Summary

Types

scored_node()
state()

Callbacks

apply_changeset(t, state)
delete_metadata(list, state)
delete_nodes(list, state)
find_candidates(node_types, query_embedding, tag_embeddings, value_fn_config, opts, state)
get_linked_nodes(list, arg2, state)
get_metadata(list, state)
get_node(t, state)
get_nodes_by_type(node_types, state)
init(opts)
update_metadata(map, state)

Types

scored_node()

@type scored_node() :: {struct(), float()}

state()

@type state() :: term()

Callbacks

apply_changeset(t, state)

@callback apply_changeset(Mnemosyne.Graph.Changeset.t(), state()) ::
  {:ok, state()} | {:error, Mnemosyne.Errors.error()}

delete_metadata(list, state)

@callback delete_metadata([String.t()], state()) :: {:ok, state()}

delete_nodes(list, state)

@callback delete_nodes([String.t()], state()) ::
  {:ok, state()} | {:error, Mnemosyne.Errors.error()}

find_candidates(node_types, query_embedding, tag_embeddings, value_fn_config, opts, state)

@callback find_candidates(
  node_types :: [atom()],
  query_embedding :: [float()],
  tag_embeddings :: [[float()]],
  value_fn_config :: %{module: module(), params: %{required(atom()) => map()}},
  opts :: keyword(),
  state()
) :: {:ok, [scored_node()], state()} | {:error, Mnemosyne.Errors.error()}

get_linked_nodes(list, arg2, state)

@callback get_linked_nodes([String.t()], Mnemosyne.Graph.Edge.edge_type() | nil, state()) ::
  {:ok, [struct()], state()}

get_metadata(list, state)

@callback get_metadata([String.t()], state()) ::
  {:ok, %{required(String.t()) => struct()}, state()}

get_node(t, state)

@callback get_node(String.t(), state()) :: {:ok, struct() | nil, state()}

get_nodes_by_type(node_types, state)

@callback get_nodes_by_type(node_types :: [atom()], state()) ::
  {:ok, [struct()], state()} | {:error, Mnemosyne.Errors.error()}

init(opts)

@callback init(opts :: keyword()) :: {:ok, state()} | {:error, Mnemosyne.Errors.error()}

update_metadata(map, state)

@callback update_metadata(%{required(String.t()) => struct()}, state()) :: {:ok, state()}