Mental models API — curated memory summaries

Mental models are saved reflect responses that you curate for your memory bank. When you create a mental model, Hindsight runs a reflect operation with your source query and stores the result. During future reflect calls, these pre-computed summaries are checked first — before observations and raw facts — providing faster, more consistent answers for common queries. During reflect, the agent checks sources in this priority order:

Mental models — user-curated summaries (highest priority)
Observations — consolidated knowledge synthesized over time
Raw facts — ground truth memories

Mental models are checked first because they represent your explicitly curated knowledge.

Create a mental model

POST /v1/{tenant}/banks/{bank_id}/mental-models

Creating a mental model triggers a reflect operation in the background and saves the result. Returns an operation ID for tracking.

Request parameters

path.tenant

string

required

Your tenant identifier. Use default for single-tenant deployments.

path.bank_id

string

required

The memory bank to create the mental model in.

name

string

required

Human-readable name for the mental model (e.g. "Team communication norms" or "Q4 project status").

source_query

string

required

The query to run to generate the mental model’s content. This same query is used again on refresh.

string

Custom ID for the mental model. Must be lowercase alphanumeric with optional hyphens (e.g. "team-policies", "q4-status"). Auto-generated UUID if omitted. If a mental model with that ID already exists, the request is rejected.

tags

string[]

Tags that scope the model during reflect and filter source memories during refresh. During refresh, uses all_strict matching — only memories carrying every listed tag are read. During reflect, the model is visible only if the reflect request’s tags overlap with these tags.

max_tokens

integer

Maximum tokens for the mental model’s generated content.

trigger

object

Settings that control automatic refresh behavior.

Show trigger fields

mode

string

default:"full"

Refresh strategy. "full" — every refresh regenerates the entire content from scratch. "delta" — emits typed operations against the existing structure (add a section, append a bullet, replace a block) and renders the result. Only genuinely changed parts move; unchanged sections are copied byte-identical. Falls back to full if the mental model has no existing content or the source_query has changed.

refresh_after_consolidation

boolean

default:"false"

When true, the mental model is automatically re-generated every time the bank’s observations are consolidated.

Response fields

operation_id

string

required

ID of the background reflect operation generating the mental model’s content. Poll GET /operations/{operation_id} to check completion status.

string

required

The mental model’s ID (auto-generated or the custom ID you provided).

Example

curl -X POST "https://your-hindsight-host/v1/default/banks/my-bank/mental-models" \
  -H "Authorization: Bearer $HINDSIGHT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Team communication norms",
    "source_query": "What are this team'\''s communication preferences and norms?",
    "trigger": {"refresh_after_consolidation": true}
  }'

Create with custom ID and tags

client.create_mental_model(
    bank_id="my-bank",
    id="alice-profile",
    name="Alice's profile",
    source_query="What are Alice's skills, preferences, and working style?",
    tags=["user:alice"],
    trigger={"mode": "delta", "refresh_after_consolidation": True},
)

Adding tags to a mental model narrows the pool of source memories its refresh can read from. If no memories carry those tags yet, refresh will return empty content. Backfill tags on the relevant memories before creating a tagged mental model.

List mental models

GET /v1/{tenant}/banks/{bank_id}/mental-models

Query parameters

detail

string

default:"full"

Controls how much data is returned. "metadata" — only id, bank_id, name, tags, last_refreshed_at, created_at. "content" — all metadata fields plus source_query, content, max_tokens, trigger. "full" — all fields including reflect_response.

tags

string[]

Filter mental models by tag.

Example

# List with content (recommended for agent boot flows)
curl "https://your-hindsight-host/v1/default/banks/my-bank/mental-models?detail=content" \
  -H "Authorization: Bearer $HINDSIGHT_API_KEY"

Use detail=content for agent orientation flows. It includes the generated content without the heavyweight reflect_response provenance chains, which can exceed 200 KB for banks with many models.

Get a mental model

GET /v1/{tenant}/banks/{bank_id}/mental-models/{mental_model_id}

Response fields

string

required

Unique mental model ID.

bank_id

string

required

Memory bank ID.

name

string

required

Human-readable name.

source_query

string

required

The query used to generate content.

content

string

required

The generated mental model text.

tags

string[]

Tags for filtering.

max_tokens

integer

Maximum tokens for the content.

trigger

object

Trigger settings for automatic refresh.

reflect_response

object

Full reflect response including based_on provenance facts. Only present at detail=full.

last_refreshed_at

string

ISO 8601 timestamp of the last refresh.

created_at

string

required

ISO 8601 creation timestamp.

Example

curl "https://your-hindsight-host/v1/default/banks/my-bank/mental-models/alice-profile" \
  -H "Authorization: Bearer $HINDSIGHT_API_KEY"

Refresh a mental model

POST /v1/{tenant}/banks/{bank_id}/mental-models/{mental_model_id}/refresh

Re-runs the source query to update the mental model with current knowledge. Useful after new memories have been retained that affect the topic, or when observations have been updated.

Example

curl -X POST "https://your-hindsight-host/v1/default/banks/my-bank/mental-models/alice-profile/refresh" \
  -H "Authorization: Bearer $HINDSIGHT_API_KEY"

Update a mental model

PUT /v1/{tenant}/banks/{bank_id}/mental-models/{mental_model_id}

Updates the mental model’s metadata. All fields are optional — only the keys you provide are changed.

name

string

New human-readable name.

source_query

string

New source query. A source_query change causes the next refresh to fall back to full mode (delta mode requires an existing structure to anchor edits on).

tags

string[]

New tag list. Replaces the existing tags entirely.

max_tokens

integer

New maximum token limit for content.

trigger

object

New trigger settings.

Example

client.update_mental_model(
    bank_id="my-bank",
    mental_model_id="alice-profile",
    name="Alice's updated profile",
    trigger={"mode": "delta", "refresh_after_consolidation": True},
)

Delete a mental model

DELETE /v1/{tenant}/banks/{bank_id}/mental-models/{mental_model_id}

Permanently removes the mental model. Does not affect the underlying memories it was derived from.

Example

curl -X DELETE "https://your-hindsight-host/v1/default/banks/my-bank/mental-models/alice-profile" \
  -H "Authorization: Bearer $HINDSIGHT_API_KEY"

Mental model history

GET /v1/{tenant}/banks/{bank_id}/mental-models/{mental_model_id}/history

Every time a mental model’s content changes (via refresh or manual update), the previous version is saved. Returns the full change log, most recent first.

Response fields

items

object[]

required

List of history entries.

Show history entry fields

previous_content

string

The content before this change. null if not available.

changed_at

string

required

ISO 8601 timestamp of when the change occurred.

Example

history = client.get_mental_model_history(bank_id="my-bank", mental_model_id="alice-profile")
for entry in history.items:
    print(entry.changed_at, entry.previous_content[:100])

History tracking is enabled by default. Set HINDSIGHT_API_ENABLE_MENTAL_MODEL_HISTORY=false to disable it.

Core Methods

Resources

Mental models API — curated memory summaries

Create a mental model

Request parameters

Response fields

Example

Create with custom ID and tags

List mental models

Query parameters

Example

Get a mental model

Response fields

Example

Refresh a mental model

Example

Update a mental model

Example

Delete a mental model

Example

Mental model history

Response fields

Example

Build docs developers (and LLMs) love

Core Methods

Resources

Documentation Index

​Create a mental model

​Request parameters

​Response fields

​Example

​Create with custom ID and tags

​List mental models

​Query parameters

​Example

​Get a mental model

​Response fields

​Example

​Refresh a mental model

​Example

​Update a mental model

​Example

​Delete a mental model

​Example

​Mental model history

​Response fields

​Example

Build docs developers (and LLMs) love

Create a mental model

Request parameters

Response fields

Example

Create with custom ID and tags

List mental models

Query parameters

Example

Get a mental model

Response fields

Example

Refresh a mental model

Example

Update a mental model

Example

Delete a mental model

Example

Mental model history

Response fields

Example