Agentic.Persistence.Knowledge behaviour (agentic v0.2.2)

Copy Markdown

Behaviour for knowledge storage — entries, edges, search, and supersession.

The :local fallback uses file-based storage at <workspace>/.agentic/knowledge.jsonl.

The :recollect backend delegates to the Recollect knowledge graph.

Summary

Types

edge()

@type edge() :: %{
  id: String.t(),
  source_entry_id: String.t(),
  target_entry_id: String.t(),
  relation: String.t(),
  weight: float()
}

entry()

@type entry() :: %{
  id: String.t(),
  content: String.t(),
  entry_type: String.t(),
  source: String.t(),
  scope_id: String.t() | nil,
  owner_id: String.t() | nil,
  metadata: map(),
  confidence: float(),
  inserted_at: DateTime.t()
}

Callbacks

create_edge(from_id, to_id, relation, opts)

@callback create_edge(
  from_id :: String.t(),
  to_id :: String.t(),
  relation :: String.t(),
  opts :: keyword()
) :: {:ok, edge()} | {:error, term()}

create_entry(entry, opts)

@callback create_entry(entry :: entry(), opts :: keyword()) ::
  {:ok, entry()} | {:error, term()}

get_edges(entry_id, direction, opts)

@callback get_edges(entry_id :: String.t(), direction :: :from | :to, opts :: keyword()) ::
  {:ok, [edge()]} | {:error, term()}

get_entry(entry_id, opts)

@callback get_entry(entry_id :: String.t(), opts :: keyword()) ::
  {:ok, entry()} | {:error, :not_found}

recent(scope_id, opts)

@callback recent(scope_id :: String.t(), opts :: keyword()) ::
  {:ok, [entry()]} | {:error, term()}

search(query, opts)

@callback search(query :: String.t(), opts :: keyword()) ::
  {:ok, [entry()]} | {:error, term()}

supersede(scope_id, entity, relation, new_value)

@callback supersede(
  scope_id :: String.t(),
  entity :: String.t(),
  relation :: String.t(),
  new_value :: String.t()
) :: {:ok, [entry()]} | {:error, term()}