Get a specific directive.

Get fully-qualified table name with current schema. Example: fq_table("memory_units") -> "public.memory_units" fq_table("mem

Async context manager to acquire a connection with retry logic. Usage: async with acquire_with_retry(pool) as conn: awai

Get the connection pool (must call initialize() first).

Get fully-qualified table name with optional schema prefix.

Create RequestContext with auth details from resolvers. This enables tenant auth and usage metering to work with MCP tools by propagating the

Authenticate tenant and set schema in context variable. The schema is stored in a contextvar for async-safe, per-task isolation.

Run validation if an operation validator is configured. Args: validation_coro: Coroutine that returns a ValidationResult

No-op.

Get fully-qualified table name with optional schema prefix.

Get global configuration with ONLY static (non-configurable) fields accessible. This returns a proxy that prevents access to bank-configurab

Generate embeddings for a list of texts. Args: texts: List of text strings to encode Returns: List

Get fully-qualified table name with optional schema prefix.

Record stats for a single LLM call.

Ensure daemon is running (thread-safe).

Validate a bank write operation before execution. Override to implement custom validation logic for bank writes (delete_bank

Acquire a connection within the budget. Note: Caller must release the connection when done. Prefer using as context manager

Validate a bank read operation before execution. Override to implement custom validation logic for bank reads (get_bank_prof

Helper to log to buffer if available, otherwise use logger. Args: log_buffer: Buffer to append messages to (for main output) mess

Get the global metrics collector instance. Returns a no-op collector if metrics are not initialized.

Update a directive.

Main polling loop with fire-and-forget task execution. Continuously polls for pending tasks, spawns them as background tasks,

Get bank profile (name, disposition + mission). Auto-creates agent with default values if not exists. Args: bank

Check if file exists. Args: key: Storage key Returns: True if file exists, False otherwise

Field wrapper that ensures default_factory values appear in OpenAPI schema. Pydantic doesn't include default_factory in OpenAPI schemas, cau

Create from a database row (asyncpg Record converted to dict).

Close the connection pool and shutdown background workers.

Create a new bank.

Get the global span recorder (NoOp if tracing disabled).

Parse raw entity labels config into EntityLabelsConfig. Accepts: - None → returns None - list → list of attribute dicts (each may us

Explicitly close the client. Args: stop_daemon: If True, stops the daemon. Otherwise, daemon continues running

Color text using gradient position (0.0 = start, 1.0 = end).

Build a SQL WHERE clause for compound tag group filtering. Top-level groups are AND-ed together. Each group is a recursive boolean expre

Build a simple SQL WHERE clause for tags filtering. This is a convenience version that returns just the clause string, assuming the call

Make a mock LLM API call. Records the call for test verification and returns the configured mock response. Args:

No-op.

Load an extension from environment variable configuration. The extension class is specified via {env_prefix}_{prefix}_EXTENSION environment

Add a log line.

Delete all data for a specific agent (multi-tenant cleanup). This is much more efficient than dropping all tables and allows

Dim/gray text.

Get a single pinned mental model by ID. Args: bank_id: Bank identifier mental_model_id: Pinned mental model UUID

Recall memories using N*4-way parallel retrieval (N fact types × 4 retrieval methods). This implements the core RECALL operation:

Record a timing measurement.

Record a timing measurement.

Resolve full HindsightConfig for a bank with hierarchical overrides applied. This is for INTERNAL USE ONLY. Returns the complete con

Submit an async mental model refresh operation. This schedules a background task to re-run the source query and update the content.

Get raw config (internal use only). INTERNAL USE ONLY. Do not use this directly in application code. Use get_config() for static fields

Get cached tiktoken encoding (cl100k_base for GPT-4/3.5).

Get the global tracer instance. Returns a no-op tracer if tracing is disabled, so callers don't need to check for None. This improves co

Sanitize text by removing characters that break downstream systems. Removes: - ASCII control characters (0x00-0x08, 0x0B-0x0C, 0x0E-0x1F

Submit a consolidation operation to run asynchronously. Deduplicates by bank_id - if there's already a pending consolidation for this bank,

Update a pinned mental model. Args: bank_id: Bank identifier mental_model_id: Pinned mental model UUID na

Generate structured output from an answer using the provided JSON schema. Args: answer: The text answer to extract structured data from

Normalize datetime to be timezone-aware (UTC) for consistent comparison.

Create an accepted validation result.

Record metrics for a search phase. Args: phase_name: Name of the phase duration_seconds: Time taken

Count tokens in text using tiktoken (cl100k_base encoding for GPT-4/3.5).

Create configuration from environment variables.

Initialize the connection pool, models, and background workers. Loads models (embeddings, cross-encoder) in parallel with pg0 startup

List directives for a bank. Args: bank_id: Bank identifier tags: Optional tags to filter by tags_match: H

Load the query analyzer model. This should be called during initialization to load the model and avoid cold start latency on

Add a log line.

Parse a database URL and check if it's a pg0:// embedded database URL. Supports: - "pg0" -> default instance "hindsight" - "pg0://in

Copy a patched file from patches/ to the installed package.

Return a no-op span.

Clean up answer text by removing any done() tool call syntax. Some LLMs output the done() call as text instead of a proper tool call. This st

Parse TagsMatch into operator and include_untagged flag. Returns: Tuple of (operator, include_untagged) - operator: "&&" for

Create a new directive. Args: bank_id: Bank identifier name: Human-readable name for the directive conten

Create a new pinned mental model. Args: bank_id: Bank identifier name: Human-readable name for the mental model

Delete a directive. Args: bank_id: Bank identifier directive_id: Directive UUID request_context: Request

Delete a pinned mental model. Args: bank_id: Bank identifier mental_model_id: Pinned mental model UUID re

Filter retrieval results by compound tag groups in Python (for post-processing). Used when SQL filtering isn't possible (e.g., graph travers

Filter retrieval results by tags in Python (for post-processing). Used when SQL filtering isn't possible (e.g., graph traversal results).

Get fully resolved config for a bank (filtered by permissions). Resolution order: 1. Global config (from environment variabl

List pinned mental models for a bank. Args: bank_id: Bank identifier tags: Optional tags to filter by tag

Parse a datetime value that could be either a datetime object or an ISO string. This handles datetime values from both direct Python calls a

Parse a datetime value that could be either a datetime object or an ISO string. This handles datetime values from both direct Python calls a

Reflect and formulate an answer using an agentic loop with tools. The reflect agent iteratively uses tools to: 1. lookup: Ge

No-op.

Start the server in a background thread. Args: timeout: Maximum time to wait for server to start (seconds) Retu

Return a no-op context manager that yields a NoOpSpan.