LangEx.Store behaviour (LangEx v0.11.3)

Copy Markdown View Source

Long-term key-value memory that outlives a single thread.

Checkpoints persist one conversation; a store persists knowledge across conversations — user preferences, learned facts, past decisions. Entries live under a hierarchical namespace (a list of strings, e.g. ["memories", user_id]) with a string key.

Attaching a store to a graph

graph = Graph.compile(builder, store: LangEx.Store.ETS)
# or with backend config:
graph = Graph.compile(builder, store: {LangEx.Store.Postgres, repo: MyApp.Repo})

Inside node functions and tools the attached store is reachable through the convenience API, no plumbing required:

Graph.add_node(:remember, fn state ->
  :ok = LangEx.Store.put(["memories", state.user_id], "diet", "vegan")
  %{}
end)

Tool functions receive it as request.store in wrap_tool_call interceptors and via the same convenience API.

Built-in backends

Summary

Callbacks

Fetches a value.

Writes a value (upsert).

Lists {key, value} pairs in a namespace.

Functions

Returns the {module, config} store attached to the running graph, or nil when none is configured.

Deletes a value from the store attached to the running graph.

Fetches a value from the store attached to the running graph.

Writes a value to the store attached to the running graph.

Searches the store attached to the running graph.

Types

config()

@type config() :: keyword()

key()

@type key() :: String.t()

namespace()

@type namespace() :: [String.t()]

Callbacks

delete(config, namespace, key)

@callback delete(config(), namespace(), key()) :: :ok | {:error, term()}

Deletes a value.

get(config, namespace, key)

@callback get(config(), namespace(), key()) :: {:ok, term()} | :none | {:error, term()}

Fetches a value.

put(config, namespace, key, term)

@callback put(config(), namespace(), key(), term()) :: :ok | {:error, term()}

Writes a value (upsert).

search(config, namespace, keyword)

@callback search(config(), namespace(), keyword()) :: [{key(), term()}] | {:error, term()}

Lists {key, value} pairs in a namespace.

Options:

  • :prefix - key prefix filter (default "")
  • :limit - maximum entries returned (default 100)
  • :query - natural-language query for semantic ranking. When the backend has an embedder configured (see LangEx.Store.ETS), results are ordered by cosine similarity (highest first) instead of by key; backends without an embedder ignore it and fall back to prefix order.

Functions

attached()

@spec attached() :: {module(), config()} | nil

Returns the {module, config} store attached to the running graph, or nil when none is configured.

delete(namespace, key)

@spec delete(namespace(), key()) :: :ok | {:error, term()}

Deletes a value from the store attached to the running graph.

get(namespace, key)

@spec get(namespace(), key()) :: {:ok, term()} | :none | {:error, term()}

Fetches a value from the store attached to the running graph.

put(namespace, key, value)

@spec put(namespace(), key(), term()) :: :ok | {:error, term()}

Writes a value to the store attached to the running graph.

search(namespace, opts \\ [])

@spec search(
  namespace(),
  keyword()
) :: [{key(), term()}] | {:error, term()}

Searches the store attached to the running graph.