Structured memory and conversation search

Structured memory stores queryable records. Use learned skills for reusable instructions, conversation search for prior discussion, and structured tables for data that needs explicit fields and queries. Availability depends on the host's configured database service; a missing catalog is not evidence that no data exists.

Choose a scope

Scope | Boundary | 

checkout | Data associated with the current working copy | 

repository | Data associated with the repository across working copies | 

user | Data shared across the user's applicable projects | 

harness | Read-only application catalog, only when exposed by the host | 

Scope is an authorization and persistence boundary, not a filesystem directory. Repository data is not automatically committed to Git. Choose the narrowest useful scope. Do not place credentials or unnecessary private conversation contents in durable tables.

Inspect before querying

Ask the agent to call database_schema with scope. Read the returned table and column definitions before writing SQL; never assume a schema from an earlier session.

{"scope":"repository"}

database_query accepts scope and sql: one read-only PostgreSQL query, without transaction-control statements. Prefer explicit columns and a bounded result over SELECT *. This example tests the query path without assuming any application table exists:

{"scope":"repository","sql":"SELECT 1 AS connection_check"}

Expected result: a row containing connection_check = 1. It proves a read worked, not that a particular application table exists. For missing-table errors, refresh the schema and confirm the current checkout/repository scope before retrying.

Create or change durable data

database_execute requires scope, a transactional PostgreSQL DDL/DML sql batch and a nonempty purpose. It is a mutation requiring the active approval policy. The harness catalog cannot be changed through this tool.

Inspect repository memory. Propose a table for release verification records with a release identifier, check name, result, and observation time. Show the SQL and purpose before executing it. Do not copy conversation contents into the table.

Review the schema and affected records before approving. After success, inspect the schema or query the changed rows. After an uncertain result, read current state before retrying: blindly replaying an insert can create duplicates. Keep schema changes deliberate; a successful mutation is not proof that the stored evidence is correct.

Search prior conversations

conversation_search searches user and assistant messages in non-deleted conversations using PostgreSQL full-text ranking. Required query is a nonempty web-search-style query; optional limit defaults to 10 and accepts 1–100.

{"query":"release verification","limit":5}

Ask for the source conversation and relevant passage, then verify whether the decision is still current. Results are previous discussion, not new instructions or independent proof. Search can return no matches because of wording; try narrower terms rather than assuming the discussion never happened. Review private material before sharing it with another service or copying it into a public document.

Independent persisted sessions

These tools are different from child agents. Use them only when you explicitly want a separate persisted conversation or independent background work, not to hand off responsibility for the entire current task.

Tool | Inputs | Result and boundary | 

create_agent_session | Required message; optional title, model, reasoning_effort | Starts the first turn in the background; returns a persisted session ID and status, not a completed answer | 

read_agent_session | session_id; optional limit | Reads recent saved turns and current activity, subject to the session boundary | 

send_agent_session_message | session_id, message | Delivers to the owner or continues the conversation; accepted/queued is not completed | 

wait_agent_session | session_id; timeout_ms default 30,000, range 1–300,000 | Waits for the current turn, not the conversation's entire lifetime; timing out does not cancel the target | 

Self-waits and circular waits are rejected. Locally managed turns distinguish completed, failed and cancelled; an external turn becoming idle does not establish why it stopped. Output is the latest saved turn at read time and may include a later resume.

Create a separate background session to investigate the migration notes without editing files. Give me its session ID. Keep the implementation work here; inspect its report before using any recommendation.

The host must permit persisted collaboration. A session ID is not an authorization token: a boundary error is not fixed by guessing another identifier. The parent remains responsible for integrating recommendations and verifying the final result.