LemonCore.RunHistoryStore (lemon_core v0.1.0)

View Source

Dedicated store for run history, isolated from the main Store GenServer.

Uses its own SQLite database (run_history.sqlite3) so that large conversation payloads never block secrets lookups, chat-state reads, or other latency-sensitive operations in the main store.

Includes built-in retention: entries older than the configured TTL are swept periodically.

Configuration

config :lemon_core, LemonCore.RunHistoryStore,
  path: "~/.lemon/store",            # directory — run_history.sqlite3 created inside
  retention_ms: 7 * 24 * 3600_000,   # 7 days (default)
  max_per_session: 50                 # keep at most N entries per session_key

Instances

The store is named (default LemonCore.RunHistoryStore) and every public function takes an optional leading server argument, so additional instances can run alongside the default one:

{LemonCore.RunHistoryStore, name: :scratch_history, path: "/tmp/scratch"}

start_link/1 opts win over the application env, which is read under the instance's name (config :lemon_core, LemonCore.RunHistoryStore for the default).

Summary

Types

server()

A running run-history store: its registered name or its pid.

Functions

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

delete_session(server \\ __MODULE__, session_key)

Delete all history for a session.

get(session_key, opts \\ [])

Fetch the most recent limit history entries for a session.

get(server, session_key, opts)

Fetch history for a session from a specific store instance.

handle_finalize_run(event)

LemonCore.Store finalize-run hook: persist the finalized run's history.

handle_finalize_run(server, map)
list_all(server \\ __MODULE__)

List all entries (for migration/debug). Expensive — avoid in production hot paths.

put(server \\ __MODULE__, session_key, started_at_ms, run_id, data)

Store a run history entry.

start_link(opts \\ [])

Types

server()

@type server() :: atom() | pid()

A running run-history store: its registered name or its pid.

Functions

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

See Supervisor.

delete_session(server \\ __MODULE__, session_key)

@spec delete_session(server(), String.t()) :: :ok

Delete all history for a session.

get(session_key, opts \\ [])

@spec get(
  String.t(),
  keyword()
) :: [{term(), map()}]

Fetch the most recent limit history entries for a session.

Returns [{run_id, data}, ...] sorted by recency (newest first).

get(server, session_key, opts)

@spec get(server(), String.t(), keyword()) :: [{term(), map()}]

Fetch history for a session from a specific store instance.

handle_finalize_run(event)

@spec handle_finalize_run(map()) :: :ok

LemonCore.Store finalize-run hook: persist the finalized run's history.

Wired by the runtime, not by the store:

config :lemon_core, LemonCore.Store,
  finalize_run_hooks: [{LemonCore.RunHistoryStore, :handle_finalize_run}]

Pass a store instance name as a leading argument to target a non-default history store: {LemonCore.RunHistoryStore, :handle_finalize_run, [:my_history]}.

handle_finalize_run(server, map)

@spec handle_finalize_run(server(), map()) :: :ok

list_all(server \\ __MODULE__)

@spec list_all(server()) :: [{term(), map()}]

List all entries (for migration/debug). Expensive — avoid in production hot paths.

put(server \\ __MODULE__, session_key, started_at_ms, run_id, data)

@spec put(server(), String.t(), integer(), String.t() | reference(), map()) :: :ok

Store a run history entry.

start_link(opts \\ [])