Mental Models

The Mental Models sync type reconciles query recipes between architxt and a Hindsight memory bank. Mental model sync is more involved than document or directive sync because architxt supports three different kinds of models — plain, derived, and contextual — and not all of them can be pushed or pulled.

What is compared

When you run Diff with the Mental Models object type, architxt fetches Hindsight's mental models and compares them against architxt's local models. Templates with Entity Template enabled are expanded into their derived instances before comparison, so the diff shows one row per concrete model that would exist on the bank.

For each row that exists on both sides, architxt checks:

Field	Divergent if...
Name	The model name differs.
Source query	The composed query in architxt differs from Hindsight's stored source_query. This catches changes to the prompt, AQL directives, placeholders, and runtime variables.
Max tokens	The token budgets are not equal.
Refresh mode	The refresh mode strings differ (for example full vs delta).
Refresh after consolidation	One side refreshes after consolidation and the other does not.
Exclude all mental models	The global exclusion flag differs.
Exclude list	The set of excluded mental model ids differs.
Tags match mode	The tag matching rule differs.
Tags	The set of tags applied to the model differs.
Response schema	The JSON response schema differs.

The diff result groups rows into four columns:

• Same — both sides present and all compared fields match.
• Different — both sides present, but at least one field diverged.
• Only in architxt — the model exists in architxt but not in the Hindsight bank. This includes newly created plain models and derived instances that have not been pushed.
• Only in Hindsight — the model exists in the Hindsight bank but not in architxt.

Contextual models never appear in "Only in architxt"

Contextual mental models are auto-generated by the contextual graph from template roles. If a contextual model exists in architxt but not on Hindsight, it is hidden from the sync UI because it is managed by the graph, not by manual push/pull.

Model kinds and what you can do with them

Plain mental models

A plain mental model is a normal model with Entity Template disabled. It is stored as its own row in the architxt database and can be pushed, pulled, created, and updated freely through Hindsight Sync.

Derived mental models

Derived mental models are generated on demand from an architxt template plus attached contextual-graph entities. They do not have their own database row; their effective configuration is the parent template plus per-entity overrides in mental_model_entities.

• Push — derived models can be pushed to Hindsight. Pushing creates or updates the concrete model on the bank using the composed query.
• Pull — when you pull a derived model, architxt updates only the per-entity overrides (refresh_mode, refresh_after_consolidation, exclude_all_mental_models, max_tokens). It does not overwrite the parent template's name, source query, tags, exclude list, or tags-match mode, because those belong to the template. The UI shows derived-model diff badges with a different background for fields that are not pullable.

Contextual mental models

Contextual mental models are role-based templates bound to specific nodes, edges, or seeds in the contextual graph. They are fully auto-managed by the contextual graph service.

• No push — the sync UI does not let you select contextual models for push. They are pushed automatically by the contextual graph when the graph is deployed or updated.
• No pull — the sync UI does not let you select contextual models for pull. Their content is derived from the graph state and template roles, so pulling bank state over them is not allowed.
• Still compared — contextual models still appear in the diff so you can see whether the bank is in sync with the graph. Any divergence is normally resolved by redeploying or refreshing the contextual graph, not through the Hindsight Sync page.

Push a mental model

Pushing sends an architxt mental model to Hindsight.

In the UI:

1. Select one or more rows from Only in architxt or Different. Contextual models cannot be selected.
2. Click Push.
3. If the model already exists on Hindsight, architxt PATCHes it. If it does not exist, architxt POSTs it with the model's ext_id.
4. The payload contains the composed query, name, tags, max tokens, refresh settings, exclusion settings, tags match mode, and response schema.
5. Hindsight may return an operation id. If it does, architxt tracks the operation in pending operations and refreshes the diff when it completes.

Derived models push their composed query

When you push a derived model, architxt composes the final prompt from the parent template and entity placeholders before sending it. The bank stores the composed result, not the template.

Pull a mental model

Pulling copies or updates a mental model from Hindsight into architxt.

In the UI:

1. Select one or more rows from Only in Hindsight or Different. Contextual and derived models can only update their pullable override fields.
2. Click Pull.
3. For a plain model, architxt creates a new local row if the Hindsight id is unknown, or updates the existing row. Tags are synced from Hindsight.
4. For a derived model, architxt updates only the per-entity overrides (refresh_mode, refresh_after_consolidation, exclude_all_mental_models, max_tokens). The parent template is left unchanged.
5. Contextual models are skipped during pull because they are graph-managed.

Field mapping

The values compared and transferred map to Hindsight mental-model fields as follows. See the Hindsight mental models API for field definitions.

architxt field	Hindsight field	Notes
mm_ext_id / derived ext_id	id	Stable identifier on both sides.
mm_name	name	Display name.
composed_query	source_query	Final composed prompt, including AQL blocks and substituted placeholders.
mm_max_tokens	max_tokens	Token budget.
mm_refresh_mode	trigger.mode	full or delta.
mm_refresh_after_consolidation	trigger.refresh_after_consolidation	Boolean.
mm_exclude_all_mental_models	trigger.exclude_mental_models	Boolean.
mm_exclude_mental_model_list	trigger.exclude_mental_model_ids	Comma-separated string locally; array on the bank.
mm_tags_match_mode	trigger.tags_match	Tag matching rule.
tags	tags	Array of tag names.
response_schema	trigger.response_schema	Unified JSON schema used by architxt.

Typical workflows

Situation	Action	Notes
You created a plain mental model in architxt and want it on Hindsight.	Push from Only in architxt.
You changed a model's source query or refresh settings in architxt.	Push from Different.
You want to import a plain model that was created in Hindsight.	Pull from Only in Hindsight.
A derived instance needs different tokens or refresh settings on the bank.	Push or pull from Different for the derived row.	Pull only updates override fields.
You want to change which bank models a derived instance excludes.	Edit the parent template in architxt, then push the derived row.	Exclude list is not pullable for derived rows.
A contextual model is out of sync.	Update or redeploy the contextual graph.	Manual push/pull is disabled.
You want architxt to match Hindsight exactly for a plain model.	Pull from Different.	Overwrites name, query, settings, and tags.

Summary

Mental model sync compares plain models, derived instances, and contextual models against the Hindsight bank. Divergence is checked on name, composed query, tokens, refresh settings, exclusions, tag matching, tags, and response schema. Plain models can be pushed and pulled freely. Derived models can be pushed and can have their override fields pulled. Contextual models are read-only in the sync UI because they are managed by the contextual graph.