SQLite-based storage backend. More...

#include <entropic/storage/backend.h>

Public Member Functions
	SqliteStorageBackend (const std::filesystem::path &db_path)
	Construct with database file path.

bool	initialize ()
	Initialize storage (open database, run migrations).

void	close ()
	Close storage and database connection.

std::string	create_conversation (const std::string &title="New Conversation", const std::optional< std::string > &project_path=std::nullopt, const std::optional< std::string > &model_id=std::nullopt)
	Create a new conversation.

bool	save_messages (const std::string &conversation_id, const std::string &messages_json)
	Save messages to a conversation.

bool	load_conversation (const std::string &conversation_id, std::string &result_json)
	Load a conversation with messages.

bool	list_conversations (int limit, int offset, std::string &result_json)
	List conversations with pagination.

bool	delete_conversation (const std::string &conversation_id)
	Delete a conversation and all associated records.

bool	update_title (const std::string &conversation_id, const std::string &title)
	Update a conversation's title.

bool	search_conversations (const std::string &query, int limit, std::string &result_json)
	Full-text search across conversations.

bool	create_delegation (const std::string &parent_conversation_id, const std::string &delegating_tier, const std::string &target_tier, const std::string &task, int max_turns, std::string &delegation_id, std::string &child_conversation_id)
	Create a delegation record with a child conversation.

bool	complete_delegation (const std::string &delegation_id, const std::string &status, const std::optional< std::string > &result_summary=std::nullopt)
	Mark a delegation as completed or failed.

bool	get_delegations (const std::string &conversation_id, std::string &result_json)
	Get delegations for a parent conversation.

bool	get_delegation_by_id (const std::string &delegation_id, std::string &result_json)
	Look up a single delegation record by id (gh#32, v2.1.6).

bool	search_delegations (const std::string &query, int max_results, std::string &result_json)
	Search delegations across all conversations (gh#32, v2.1.6).

bool	save_snapshot (const std::string &conversation_id, const std::string &messages_json)
	Save a pre-compaction snapshot of full conversation history.

bool	get_stats (std::string &result_json)
	Get storage statistics.

Detailed Description

SQLite-based storage backend.

Provides conversation persistence, message storage, delegation record management, full-text search, and compaction snapshots. Thread-safe via SqliteDatabase's internal mutex.

Lifecycle:: SqliteStorageBackend storage("/path/to/entropic.db");

storage.initialize();

auto id = storage.create_conversation("Title");

storage.save_messages(id, messages_json);

storage.close();

entropic::SqliteStorageBackend
SQLite-based storage backend.
Definition backend.h:43

Version: 1.8.8

Definition at line 43 of file backend.h.

Constructor & Destructor Documentation

◆ SqliteStorageBackend()

entropic::SqliteStorageBackend::SqliteStorageBackend ( const std::filesystem::path & db_path )

explicit

Construct with database file path.

Parameters

db_path Path to SQLite database file.

Version: 1.8.8

Parameters

db_path Path to SQLite file.

Definition at line 97 of file backend.cpp.

Member Function Documentation

◆ close()

void entropic::SqliteStorageBackend::close ( )

Close storage and database connection.

Close storage.

Version: 1.8.8

Definition at line 116 of file backend.cpp.

◆ complete_delegation()

bool entropic::SqliteStorageBackend::complete_delegation	(	const std::string &	delegation_id,
		const std::string &	status,
		const std::optional< std::string > &	result_summary = `std::nullopt`
	)

Mark a delegation as completed or failed.

Parameters

delegation_id	Delegation ID.
status	"completed" or "failed".
result_summary	Summary text (optional).

Returns: true on success.

Version: 1.8.8

Parameters

delegation_id	Delegation ID.
status	"completed" or "failed".
result_summary	Optional summary text.

Returns: true on success.

Definition at line 602 of file backend.cpp.

◆ create_conversation()

std::string entropic::SqliteStorageBackend::create_conversation	(	const std::string &	title = `"New Conversation"`,
		const std::optional< std::string > &	project_path = `std::nullopt`,
		const std::optional< std::string > &	model_id = `std::nullopt`
	)

Create a new conversation.

Parameters

title	Conversation title.
project_path	Project path (optional).
model_id	Model identifier (optional).

Returns: Conversation ID (UUID string).

Version: 1.8.8

Parameters

title	Conversation title.
project_path	Optional project path.
model_id	Optional model identifier.

Returns: Conversation ID.

Definition at line 131 of file backend.cpp.

◆ create_delegation()

bool entropic::SqliteStorageBackend::create_delegation	(	const std::string &	parent_conversation_id,
		const std::string &	delegating_tier,
		const std::string &	target_tier,
		const std::string &	task,
		int	max_turns,
		std::string &	delegation_id,
		std::string &	child_conversation_id
	)

Create a delegation record with a child conversation.

Create a delegation with a child conversation.

Parameters

	parent_conversation_id	Parent conversation ID.
	delegating_tier	Tier initiating delegation.
	target_tier	Target tier for child loop.
	task	Task description.
	max_turns	Max turns for child (0 = unlimited).
[out]	delegation_id	Created delegation ID.
[out]	child_conversation_id	Created child conversation ID.

Returns: true on success.

Version: 1.8.8

Parameters

	parent_conversation_id	Parent conversation.
	delegating_tier	Source tier.
	target_tier	Target tier.
	task	Task description.
	max_turns	Turn limit (0 = unlimited).
[out]	delegation_id	Created delegation ID.
[out]	child_conversation_id	Created child conversation ID.

Returns: true on success.

Definition at line 540 of file backend.cpp.

◆ delete_conversation()

bool entropic::SqliteStorageBackend::delete_conversation ( const std::string & conversation_id )

Delete a conversation and all associated records.

Delete a conversation and all cascading records.

Parameters

conversation_id Conversation ID.

Returns: true on success.

Version: 1.8.8

Parameters

conversation_id Conversation ID.

Returns: true on success.

Definition at line 385 of file backend.cpp.

◆ get_delegation_by_id()

bool entropic::SqliteStorageBackend::get_delegation_by_id	(	const std::string &	delegation_id,
		std::string &	result_json
	)

Look up a single delegation record by id (gh#32, v2.1.6).

Used by entropic.followup and entropic.resume_delegation to resolve a delegation's target_tier and child_conversation_id without scanning all parents.

Parameters

	delegation_id	Delegation id.
[out]	result_json	Single-object JSON with the delegation row.

Returns: true on success and a row was found; false on absence/error.

Version: 2.1.6

Parameters

	delegation_id	Delegation id.
[out]	result_json	Object JSON of the delegation row.

Returns: true if found and parsed.

Definition at line 708 of file backend.cpp.

◆ get_delegations()

bool entropic::SqliteStorageBackend::get_delegations	(	const std::string &	conversation_id,
		std::string &	result_json
	)

Get delegations for a parent conversation.

Parameters

	conversation_id	Parent conversation ID.
[out]	result_json	JSON array of delegation records.

Returns: true on success.

Version: 1.8.8

Parameters

	conversation_id	Parent conversation ID.
[out]	result_json	JSON array of delegation records.

Returns: true on success.

Definition at line 681 of file backend.cpp.

◆ get_stats()

bool entropic::SqliteStorageBackend::get_stats ( std::string & result_json )

Get storage statistics.

Parameters

[out] result_json JSON with total_conversations, total_messages, total_tokens.

Returns: true on success.

Version: 1.8.8

Parameters

[out] result_json JSON with counts.

Returns: true on success.

Definition at line 807 of file backend.cpp.

◆ initialize()

bool entropic::SqliteStorageBackend::initialize ( )

Initialize storage (open database, run migrations).

Initialize storage.

Returns: true on success.

Version: 1.8.8

Returns: true on success.

Definition at line 107 of file backend.cpp.

◆ list_conversations()

bool entropic::SqliteStorageBackend::list_conversations	(	int	limit,
		int	offset,
		std::string &	result_json
	)

List conversations with pagination.

Parameters

	limit	Maximum results.
	offset	Pagination offset.
[out]	result_json	JSON array of conversation summaries.

Returns: true on success.

Version: 1.8.8

Parameters

	limit	Max results.
	offset	Pagination offset.
[out]	result_json	JSON array of summaries.

Returns: true on success.

Definition at line 349 of file backend.cpp.

◆ load_conversation()

bool entropic::SqliteStorageBackend::load_conversation	(	const std::string &	conversation_id,
		std::string &	result_json
	)

Load a conversation with messages.

Load a conversation with its messages.

Parameters

	conversation_id	Conversation ID.
[out]	result_json	JSON with "conversation" and "messages".

Returns: true if found.

Version: 1.8.8

Parameters

	conversation_id	Conversation ID.
[out]	result_json	JSON result.

Returns: true if found.

Definition at line 309 of file backend.cpp.

◆ save_messages()

bool entropic::SqliteStorageBackend::save_messages	(	const std::string &	conversation_id,
		const std::string &	messages_json
	)

Save messages to a conversation.

Parameters

conversation_id	Conversation ID.
messages_json	JSON array of message objects.

Returns: true on success.

Version: 1.8.8

Parameters

conversation_id	Conversation ID.
messages_json	JSON array of message objects.

Returns: true on success.

Definition at line 225 of file backend.cpp.

◆ save_snapshot()

bool entropic::SqliteStorageBackend::save_snapshot	(	const std::string &	conversation_id,
		const std::string &	messages_json
	)

Save a pre-compaction snapshot of full conversation history.

Save a pre-compaction snapshot.

Parameters

conversation_id	Conversation ID.
messages_json	JSON array of all messages before compaction.

Returns: true on success.

Version: 1.8.8

Parameters

conversation_id	Conversation ID.
messages_json	JSON array of all messages.

Returns: true on success.

Definition at line 774 of file backend.cpp.

◆ search_conversations()

bool entropic::SqliteStorageBackend::search_conversations	(	const std::string &	query,
		int	limit,
		std::string &	result_json
	)

Full-text search across conversations.

Full-text search across conversations via FTS5.

Parameters

	query	FTS5 query string.
	limit	Maximum results.
[out]	result_json	JSON array of search results with snippets.

Returns: true on success.

Version: 1.8.8

Parameters

	query	FTS5 query string.
	limit	Max results.
[out]	result_json	JSON array of search results.

Returns: true on success.

Definition at line 426 of file backend.cpp.

◆ search_delegations()

bool entropic::SqliteStorageBackend::search_delegations	(	const std::string &	query,
		int	max_results,
		std::string &	result_json
	)

Search delegations across all conversations (gh#32, v2.1.6).

Substring-match delegations across all conversations.

Substring match against result_summary (case-insensitive). Returns the top-N most recently completed delegations whose summary contains query.

Parameters

	query	Keyword/phrase to match.
	max_results	Maximum records to return.
[out]	result_json	JSON array of matching delegation rows.

Returns: true on success.

Version: 2.1.6

Bound to top-N most recently completed records. Uses sqlite's LIKE for portability — FTS5 is wired for messages, not delegation summaries.

Parameters

	query	Substring to match (LIKE query%).
	max_results	Cap on returned rows.
[out]	result_json	JSON array of delegation rows.

Returns: true on success.

Definition at line 744 of file backend.cpp.

◆ update_title()

bool entropic::SqliteStorageBackend::update_title	(	const std::string &	conversation_id,
		const std::string &	title
	)

Update a conversation's title.

Parameters

conversation_id	Conversation ID.
title	New title.

Returns: true on success.

Version: 1.8.8

Parameters

conversation_id	Conversation ID.
title	New title.

Returns: true on success.

Definition at line 404 of file backend.cpp.

The documentation for this class was generated from the following files:

entropic/storage/backend.h
storage/backend.cpp

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ SqliteStorageBackend()

Member Function Documentation

◆ close()

◆ complete_delegation()

◆ create_conversation()

◆ create_delegation()

◆ delete_conversation()

◆ get_delegation_by_id()

◆ get_delegations()

◆ get_stats()

◆ initialize()

◆ list_conversations()

◆ load_conversation()

◆ save_messages()

◆ save_snapshot()

◆ search_conversations()

◆ search_delegations()

◆ update_title()