Runtime and host

retold.facade

Adoption-first API for private, evidence-backed memory sessions.

RetoldSetupError

Bases: RuntimeError

Explain how to install or configure an optional Retold capability.

MemorySearchResult dataclass

A typed search result with stable text rendering for logs and quick starts.

Retold

Open Retold once, then create private sessions for users.

open classmethod

open(
    path: str | Path,
    *,
    config: RetoldConfig | str | Path | None = None,
    profile: Literal["standard", "lite"] = "standard",
) -> Retold

Open a SQLite store and build a runtime with default or supplied configuration.

session

session(
    user_id: str,
    *,
    agent_id: str = "assistant",
    session_id: str | None = None,
    project_id: str | None = None,
) -> MemorySession

Start a session whose default destination is the agent and user's private scope.

close

close() -> None

Close the store when this object opened it.

MemorySession

Private memory operations bound to a trusted agent, user, and session identity.

remember

remember(
    content: str,
    *,
    evidence: str,
    type: MemoryType = "semantic",
    attribute: str | None = None,
    event_at: datetime | None = None,
    tags: list[str] | None = None,
    source_kind: EvidenceSourceKind = "user_statement",
    allow_inference: bool = False,
) -> WriteResult

Record trusted evidence and write one memory through the normal ingestion policy.

A user_statement or tool_result claim the evidence does not support is not stored silently as an expiring inference: remember raises :class:UnsupportedEvidenceError unless allow_inference is true.

search

search(
    query: str,
    *,
    k: int | None = None,
    types: list[MemoryType] | None = None,
    entities: list[str] | None = None,
    since: datetime | None = None,
    until: datetime | None = None,
) -> MemorySearchResult

Search this session's readable memory and retain every retrieval explanation.

finish

finish(*, extract: bool = False) -> Thread | None

End this session and return the background extraction thread when one was started.

retold.runtime

The composition root: one place that wires a store and a configuration into the working components.

The CLI, the adapters, and the benchmarks all need the same graph: embedder, vector index, equivalence judge, session buffer, ingestor, retriever, tool handlers, extraction runner, and session hooks. Building it here keeps the wiring in one place and lets tests substitute fakes for the model-backed pieces.

build_runtime

build_runtime(
    config: RetoldConfig,
    store: Store,
    *,
    embedder: Embedder | None = None,
    judge: EquivalenceJudge | None = None,
    rewriter: QueryRewriter | None = None,
    reranker: Reranker | None = None,
    extractor: Extractor | None = None,
    reviewer: CandidateReviewer | None = None,
    activation: ActivationService | None = None,
    current_time: Callable[[], datetime] = now,
    allow_embedding_mismatch: bool = False,
) -> MemoryRuntime

Wire the components for config over store; any argument given replaces the configured piece.

Hosted pieces are created lazily by their own classes, so building a runtime makes no model call and loads no local model until the first write, search, or extraction.

retold.host

Trusted host operations for provisioning and revoking principal access.

MemoryHost

Provision grants before a host starts work for an agent and user pair.

grant

grant(
    agent_id: str, scope: Scope, *, read: bool, write: bool
) -> None

Create or replace one explicit scope grant and record the administrative action.

provision_user

provision_user(
    user_id: str, aliases: Iterable[str] = ()
) -> str

Create the principal's person entity in its user scope and attach the names people use for it.

Registering display names such as "Aditya" or "Aditya Mishra" makes a later about mention of that name resolve to the same entity a subject-less write uses, so facts about the user cannot split across two person entities when user_id is an opaque identifier.

revoke

revoke(agent_id: str, scope: Scope) -> None

Remove one explicit scope grant and record the administrative action.

retold.store.store.Store

Own SQLite connections and expose persistence without policy or ranking decisions.

__init__

__init__(
    path: str | Path,
    *,
    allow_migration_issues: bool = False,
    busy_timeout_s: float = 30.0,
) -> None

close

close() -> None

Close the current thread's connection, if it was opened.

transaction

transaction(
    *, immediate: bool = True
) -> Iterator[Connection]

Run store operations atomically and nest inner calls with savepoints.

Every transaction begins IMMEDIATE by default: it takes the write lock at the start and waits on the busy timeout if another connection holds it. A deferred transaction that reads first and writes later cannot wait under WAL; when another writer commits in between it fails at once with SQLITE_BUSY, which is exactly the shape of the ingestor beside a background extraction thread. Nested calls inherit the outer lock through savepoints.

snapshot_to

snapshot_to(path: str | Path) -> None

Copy the database through SQLite's consistent backup API.