Pi Hindsight S1 Enhanced 1.0 supports a stable Pi-first Hindsight integration. Core and Pi workflow tools are part of the stable 1.0 contract. Capability-gated tools are supported when the connected Hindsight server exposes the required upstream endpoint or field; unsupported servers should return a clear capability error.
Recall raw memories from Hindsight for this project.
Parameter
Type
Required
Description
query
string
yes
Natural language memory query
bank
string
no
Optional bank id. Defaults to project bank.
types
array<world | experience | observation>
no
Optional Hindsight fact types to retrieve.
preferObservations
boolean
no
When recalling raw facts (‘world’/‘experience’) together with ‘observation’, drop raw facts superseded by a returned observation. Defaults to the configured recall.preferObservations.
minScores
object
no
Optional per-stage score floors. Omitted stages impose no floor. No floor by default.
budget
low | mid | high
no
Optional Hindsight recall budget override for this tool call.
maxTokens
integer
no
Optional Hindsight recall token cap override for this tool call. Use 0 for metadata/source-only recall when supported by Hindsight.
queryTimestamp
string
no
Optional ISO timestamp for time-scoped recall.
includeChunks
boolean
no
Ask Hindsight to include source chunks when supported.
recallChunksMaxTokens
integer
no
Optional token cap for included recall chunks.
includeSourceFacts
boolean
no
Ask Hindsight to include source facts when supported.
maxSourceFactsTokens
integer
no
Optional token cap for included source facts.
includeEntities
boolean
no
Ask Hindsight to include entities when supported.
trace
boolean
no
Ask Hindsight to include recall trace/debug data.
tags
array
no
Additional tag filter.
tagsMatch
any | all | any_strict | all_strict | exact
no
How to match tags. Always enforced together with the automatic Pi project/user scope tag filter. ‘exact’ folds the automatic scope tags into the exact-match set (memory tags must equal scope tags plus these tags, no more, no less) instead of AND-ing a separate scope group, since scope tags must still be present. To also include Hindsight shared/untagged observations (exact empty tags), set includeSharedObservations=true or config.scope.includeSharedObservations.
tagGroups
array
no
Compound Hindsight tag_groups filter. AND-ed with the automatic Pi project/user scope filter.
includeSharedObservations
boolean
no
When true, also match exact-empty (shared/untagged) observations inside the bank via tag_groups OR. Defaults to config.scope.includeSharedObservations (false). Not cross-bank.
Retain explicit raw content in Hindsight. Use for durable facts or decisions.
Parameter
Type
Required
Description
content
string
yes
Raw content to retain, not summary if source content is available.
context
string
yes
Source context for this memory.
bank
string
no
Optional bank id. Defaults to project bank.
tags
array
no
entities
array
no
Optional Hindsight entities to associate with this retained content.
documentId
string
no
Optional Hindsight document ID. Defaults to the existing deterministic explicit retain document ID.
timestamp
string
no
Optional Hindsight timestamp string, including ISO-ish strings or literal unset, passed through as provided.
metadata
object/map
no
Optional caller metadata string map. Reserved provenance keys such as cwd, pi_session_file, source, and retainSource are set by pi-hindsight-s1enhanced and cannot be overridden.
updateMode
append | replace
no
Optional Hindsight update mode for this explicit retain call.
Optional Hindsight observation scopes. Use per_tag, combined, all_combinations, shared, or explicit string groups. When provided, overrides configured default observation scopes for this retain call.
documentTags
array
no
Optional Hindsight document_tags for this retained document when supported.
async
boolean
no
Optional Hindsight async extraction flag for this retain call. Defaults to configured retain.async.
Retain explicit durable user memory in the configured user bank. Use for stable user identity, preferences, and cross-project workflows only — for anything tied to this repository use hindsight_retain instead (hindsight_retain with bank=global reaches the same user bank).
Parameter
Type
Required
Description
content
string
yes
Raw memory content to retain.
context
string
yes
Why this memory is durable user context.
tags
array
no
entities
array
no
Optional Hindsight entities to associate with this retained content.
documentId
string
no
Optional Hindsight document ID. Defaults to the existing deterministic explicit retain document ID.
timestamp
string
no
Optional Hindsight timestamp string, including ISO-ish strings or literal unset, passed through as provided.
metadata
object/map
no
Optional caller metadata string map. Reserved provenance keys such as cwd, pi_session_file, source, and retainSource are set by pi-hindsight-s1enhanced and cannot be overridden.
updateMode
append | replace
no
Optional Hindsight update mode for this explicit retain call.
Optional Hindsight observation scopes. Use per_tag, combined, all_combinations, shared, or explicit string groups. When provided, overrides configured default observation scopes for this retain call.
documentTags
array
no
Optional Hindsight document_tags for this retained document when supported.
async
boolean
no
Optional Hindsight async extraction flag for this retain call. Defaults to configured retain.async.
Ask Hindsight to synthesize an answer from memory. Use explicitly, not for default recall.
Parameter
Type
Required
Description
query
string
yes
context
string
no
bank
string
no
budget
low | mid | high
no
Optional Hindsight reflect budget override for this tool call.
maxTokens
integer
no
Optional Hindsight reflect token cap override for this tool call.
responseSchema
object/map
no
includeFacts
boolean
no
Ask Hindsight reflect to include facts when supported.
includeToolCalls
boolean
no
Ask Hindsight reflect to include tool-call trace data when supported.
includeToolCallOutput
boolean
no
When includeToolCalls is set, include tool-call outputs (default true); set false for an inputs-only trace.
factTypes
array<world | experience | observation>
no
Restrict reflection to these Hindsight fact types.
excludeMentalModels
boolean
no
Exclude all mental models from reflection.
excludeMentalModelIds
array
no
Exclude specific mental models by id from reflection.
tags
array
no
Additional tag filter.
tagsMatch
any | all | any_strict | all_strict | exact
no
How to match tags. Always enforced together with the automatic Pi project/user scope tag filter. ‘exact’ folds the automatic scope tags into the exact-match set (memory tags must equal scope tags plus these tags, no more, no less) instead of AND-ing a separate scope group, since scope tags must still be present. To also include Hindsight shared/untagged observations (exact empty tags), set includeSharedObservations=true or config.scope.includeSharedObservations.
tagGroups
array
no
Compound Hindsight tag_groups filter. AND-ed with the automatic Pi project/user scope filter.
includeSharedObservations
boolean
no
When true, also match exact-empty (shared/untagged) observations inside the bank via tag_groups OR. Defaults to config.scope.includeSharedObservations (false). Not cross-bank.
Show active project identity: project: tag, derivation (pin/remote/basename), scope.mode (domain-tagged vs isolated-bank), coding/life bank ids. Read-only.
Read the effective allowlisted Pi Hindsight S1 Enhanced config values plus the allowlist; secrets are never returned. Read-only. Use it before hindsight_config_set to see what a patch would change; hindsight_status covers the setup gate, banks, and sync readiness instead.
Patch allowlisted Pi Hindsight S1 Enhanced config (project or global file) with typed keys only: setupComplete, scopeMode, projectId, projectIdStrategy, includeSharedObservations, userScopeTags, projectBankId, enableGlobalBank, globalBankId, agentUse, mentalModelsInject, memoryProfile, recall/retain knobs, decision instruction text (decisionInstructionsInject/Read/Write, with {bank}/{description}/{access} placeholders) and decisionThreshold, baseUrl, apiKeyEnvVar, timeoutMs. dryRun defaults true (preview) — set false to write. Domain-tagged setupComplete requires projectBankId. Never pass raw API keys — use apiKeyEnvVar. Read current values with hindsight_config_get first.
Parameter
Type
Required
Description
patch
object
yes
Typed allowlisted config fields only (no free-form keys).
scope
project | global
no
Which config file to write (default project .pi/hindsight.json).
dryRun
boolean
no
When true (default), preview only; set false to write.
List the banks Pi is configured with (id, bankId, role, enabled, access, retain mode) without contacting Hindsight. Use it to pick the bank value for the sibling bank, mental-model, and knowledge-page tools; hindsight_status shows live bank health, and hindsight_bank_get returns one bank’s Hindsight-side facts. Read-only.
Read one bank’s Hindsight-side facts: existence (list-banks), stats, and bank config. A retired /profile is not a hard failure. Read-only. Use hindsight_bank_set_mission to change missions, and hindsight_bank_list for the Pi-configured bank list.
Parameter
Type
Required
Description
bank
string
no
Bank id or alias project|user|global. Defaults to the coding/project bank.
Patch a bank’s retain/reflect/observations mission text; at least one of the three is required. dryRun defaults true (preview) — set false to write. Read the current missions with hindsight_bank_get first and propose a change only when extraction has been consistently wrong. Use hindsight_bank_list for the Pi-configured bank list.
Parameter
Type
Required
Description
bank
string
no
Bank id or alias project|user|global. Defaults to the coding/project bank.
retainMission
string
no
Replacement retain mission text.
reflectMission
string
no
Replacement reflect mission text.
observationsMission
string
no
Replacement observations mission text.
dryRun
boolean
no
When true (default), preview only; set false to write.
List the mental models on a bank as metadata only (id, name, tags, max_tokens, last_refreshed_at). Use it to find ids, then hindsight_mm_get for full content/reflect_response. Create or change models with hindsight_mm_create/update/refresh/delete (dry-run first). Read-only.
Parameter
Type
Required
Description
bank
string
no
Bank id or alias project|user|global. Defaults to the coding/project bank.
Read one mental model’s full content and reflect_response by id. Get ids from hindsight_mm_list (metadata-only); regenerate content with hindsight_mm_refresh. Read-only.
Parameter
Type
Required
Description
id
string
yes
Mental model id, from hindsight_mm_list.
bank
string
no
Bank id or alias project|user|global. Defaults to the coding/project bank.
Create one mental model from a name plus the question it answers. dryRun defaults true (preview) — set false to create. Coding-bank models default tags to source:pi + project:; optional tagsMatch sets refresh tag matching on the create trigger. Keep one dimension per model. Use hindsight_mm_update for an existing id, hindsight_mm_refresh to regenerate it.
Parameter
Type
Required
Description
name
string
yes
Mental model name; one dimension per model.
sourceQuery
string
yes
Question the model answers, answerable from retained memory.
id
string
no
Optional caller-chosen model id.
bank
string
no
Bank id or alias project|user|global. Defaults to the coding/project bank.
tags
array
no
Optional tag override; omitted defaults to source:pi (+ project: on the coding bank).
maxTokens
integer
no
Optional model content cap in tokens.
tagsMatch
any | all | any_strict | all_strict | exact
no
How to match tags. Always enforced together with the automatic Pi project/user scope tag filter. ‘exact’ folds the automatic scope tags into the exact-match set (memory tags must equal scope tags plus these tags, no more, no less) instead of AND-ing a separate scope group, since scope tags must still be present. To also include Hindsight shared/untagged observations (exact empty tags), set includeSharedObservations=true or config.scope.includeSharedObservations.
dryRun
boolean
no
When true (default), preview only; set false to create.
Patch one mental model by id: name, sourceQuery, tags, maxTokens, and/or tagsMatch (at least one required). dryRun defaults true (preview) — set false to write. Read the current model with hindsight_mm_get first; use hindsight_mm_refresh when only the content needs regenerating.
Parameter
Type
Required
Description
id
string
yes
Mental model id to update.
bank
string
no
Bank id or alias project|user|global. Defaults to the coding/project bank.
name
string
no
New model name.
sourceQuery
string
no
New model question.
tags
array
no
New tag list for the model.
maxTokens
integer
no
New model content cap in tokens.
tagsMatch
any | all | any_strict | all_strict | exact
no
How to match tags. Always enforced together with the automatic Pi project/user scope tag filter. ‘exact’ folds the automatic scope tags into the exact-match set (memory tags must equal scope tags plus these tags, no more, no less) instead of AND-ing a separate scope group, since scope tags must still be present. To also include Hindsight shared/untagged observations (exact empty tags), set includeSharedObservations=true or config.scope.includeSharedObservations.
dryRun
boolean
no
When true (default), preview only; set false to write.
Regenerate one mental model’s content now from its tags and source query. dryRun defaults true (preview) — set false to refresh. Use after relevant memory lands; the inject cache may lag (mentalModels.cacheTtlMs). Use hindsight_mm_update to change the model’s definition instead.
Parameter
Type
Required
Description
id
string
yes
Mental model id to refresh.
bank
string
no
Bank id or alias project|user|global. Defaults to the coding/project bank.
dryRun
boolean
no
When true (default), preview only; set false to refresh.
Delete one mental model by id. dryRun defaults true (preview) — set false to delete. Confirm the target with hindsight_mm_get first; Pi cannot restore a deleted model. Use hindsight_mm_update when the model should change rather than disappear.
Parameter
Type
Required
Description
id
string
yes
Mental model id to delete.
bank
string
no
Bank id or alias project|user|global. Defaults to the coding/project bank.
dryRun
boolean
no
When true (default), preview only; set false to delete.
Show the knowledge-page tree (folders and pages) of a bank. Read-only. For routine Q&A prefer hindsight_kb_search then hindsight_kb_get — knowledge pages are not auto-injected into context. Requires Hindsight client/server knowledge-base support.
Parameter
Type
Required
Description
bank
string
no
Bank id or alias project|user|global. Defaults to the coding/project bank.
Hybrid-search knowledge pages in a bank and return matching page references. Read-only. Pair it with hindsight_kb_get (search, then get) for routine Q&A; use hindsight_kb_tree to browse structure instead. Requires Hindsight client/server knowledge-base support.
Parameter
Type
Required
Description
query
string
yes
Hybrid page-search query.
limit
integer
no
Search result limit (1–50).
bank
string
no
Bank id or alias project|user|global. Defaults to the coding/project bank.
Read one knowledge page or folder by id, with its full content. Read-only. Get ids from hindsight_kb_search or hindsight_kb_tree; change a page with hindsight_kb_update. Requires Hindsight client/server knowledge-base support.
Parameter
Type
Required
Description
id
string
yes
Page or folder id to read.
bank
string
no
Bank id or alias project|user|global. Defaults to the coding/project bank.
Create one knowledge page from the question it documents. dryRun defaults true (preview) — set false to create. Coding-bank pages default tags to source:pi + project:; optional tagsMatch restates the server page defaults with refresh tag matching. Nest it with parentId, create a folder with hindsight_kb_create_folder, and change an existing page with hindsight_kb_update. Requires Hindsight client/server knowledge-base support.
Parameter
Type
Required
Description
name
string
yes
Page name.
sourceQuery
string
yes
The question this page documents.
parentId
string | null
no
Folder parent. Omit for root create; pass null on update to move to root.
bank
string
no
Bank id or alias project|user|global. Defaults to the coding/project bank.
tags
array
no
Optional tag override; omitted defaults to source:pi (+ project: on the coding bank).
maxTokens
integer
no
Optional page content cap in tokens.
tagsMatch
any | all | any_strict | all_strict | exact
no
How to match tags. Always enforced together with the automatic Pi project/user scope tag filter. ‘exact’ folds the automatic scope tags into the exact-match set (memory tags must equal scope tags plus these tags, no more, no less) instead of AND-ing a separate scope group, since scope tags must still be present. To also include Hindsight shared/untagged observations (exact empty tags), set includeSharedObservations=true or config.scope.includeSharedObservations.
dryRun
boolean
no
When true (default), preview only; set false to create.
Create one knowledge page folder, optionally nested under parentId. dryRun defaults true (preview) — set false to create. Folders group pages; create pages with hindsight_kb_create_page. Requires Hindsight client/server knowledge-base support.
Parameter
Type
Required
Description
name
string
yes
Folder name.
parentId
string | null
no
Folder parent. Omit for root create; pass null on update to move to root.
bank
string
no
Bank id or alias project|user|global. Defaults to the coding/project bank.
dryRun
boolean
no
When true (default), preview only; set false to create.
Patch one knowledge page or folder by id: name, parentId, sourceQuery, tags, and/or maxTokens (at least one required). Pass parentId null to move it back to the root. dryRun defaults true (preview) — set false to write. Read the target with hindsight_kb_get first. Requires Hindsight client/server knowledge-base support.
Parameter
Type
Required
Description
id
string
yes
Page or folder id to update.
bank
string
no
Bank id or alias project|user|global. Defaults to the coding/project bank.
name
string
no
New page or folder name.
parentId
string | null
no
Folder parent. Omit for root create; pass null on update to move to root.
sourceQuery
string
no
New page question.
tags
array
no
New tag list for the page.
maxTokens
integer
no
New page content cap in tokens.
dryRun
boolean
no
When true (default), preview only; set false to write.
Delete one knowledge page or folder by id. dryRun defaults true (preview) — set false to delete; Pi cannot restore it. Confirm the target with hindsight_kb_get or hindsight_kb_tree first. Requires Hindsight client/server knowledge-base support.
Parameter
Type
Required
Description
id
string
yes
Page or folder id to delete.
bank
string
no
Bank id or alias project|user|global. Defaults to the coding/project bank.
dryRun
boolean
no
When true (default), preview only; set false to delete.
Seed the fixed five-page coding knowledge taxonomy (idempotent; tags knowledge:component|concept|convention|decision|feature-work). dryRun defaults true (preview) — set false to apply. Degrades with knowledge_pages_unavailable when the client/server lacks knowledge-base APIs. Use hindsight_kb_create_page for one custom page instead.
Parameter
Type
Required
Description
bank
string
no
Bank id or alias project|user|global. Defaults to the coding/project bank.
dryRun
boolean
no
When true (default), preview only; set false to apply.
Export the whole bank knowledge base as one portable markdown bundle. Heavy and read-only — use it only for a full export/backup, not routine reading (that is hindsight_kb_search + hindsight_kb_get). Requires Hindsight client/server knowledge-base support.
Parameter
Type
Required
Description
bank
string
no
Bank id or alias project|user|global. Defaults to the coding/project bank.
Dry-run only: plan dual-tag / legacy repo: → project: migration. Writes a local receipt under .pi/hindsight/. Never rewrites Hindsight tags or documents. Prefer Hindsight export/import or Pi transcript reimport for actual rebuilds.
Parameter
Type
Required
Description
bankTags
array
no
Optional tag inventory sample from the coding bank (e.g. listTags). Used only for counts in the plan.
Coding (project-only) is recommended: shared coding bank. Coding+Life (project+global) adds a personal bank. Isolated is a hard-wall escape hatch. Life-only / recall-only are special cases.
When models exist on the active bank(s), inject their content into automatic context alongside recall.
projectBankId
Banks
text
auto-derived
no
banks.project.bankId
Shared coding bank for domain-tagged mode (prefer user/global config). Isolated mode may pin a per-repo bank.
globalBankEnabled
Banks
boolean
disabled
no
banks.global.enabled
Allows cross-project recall from a shared bank.
globalBankId
Banks
text
not set
no
banks.global.bankId
Shared user bank used only when user memory is enabled.
recallEnabled
Recall
boolean
enabled
no
recall.enabled
Looks up memory before answer generation and injects it ephemerally.
recallBudget
Recall
select
mid
low, mid, high
no
recall.budget
Low, mid, or high retrieval effort.
recallMaxTokens
Recall
positive-int
800
no
recall.maxTokens
Maximum Project Bank memory tokens injected into context.
recallUserMaxTokens
Recall
positive-int
400
yes
recall.userMaxTokens
Maximum User Bank memory tokens injected into context, independent of the Project Bank limit.
recallStoreLast
Recall
boolean
disabled
yes
recall.storeLastRecall
Advanced. Writes the latest successful recall snapshot to a local sidecar under .pi/hindsight/ for debugging.
recallStoreFailures
Recall
boolean
disabled
yes
recall.storeLastRecallFailures
Advanced. Also records redacted failed recall attempts in the last-recall sidecar. Requires storing last recall snapshots.
recallPreferObservations
Recall
boolean
enabled
yes
recall.preferObservations
Advanced. When recalling raw facts together with observations, drop raw facts superseded by a returned observation.
retainEnabled
Retain
boolean
enabled
no
retain.enabled
Stores raw structured conversation deltas after turns.
retainAsync
Retain
boolean
enabled
yes
retain.async
Writes retain jobs through durable queue instead of blocking UI.
retainDelivery
Retain
select
immediate
immediate, coalesced
yes
retain.delivery
immediate flushes after every turn (default); coalesced merges compatible deltas and defers delivery to session end or periodic flush (retain.flushIntervalMs) to cut database write amplification.
queuePath
Retain
text
.pi/hindsight/retain-queue.jsonl
yes
retain.queuePath
JSONL retry queue used when Hindsight is unavailable.
globalRetainMode
Retain
select
explicit-only
explicit-only
yes
globalRetain.mode
Advanced. explicit-only keeps User Bank writes manual (the only supported mode).
importMode
Import
select
curated
curated, raw, forensic
no
import.mode
Curated drops noisy successful tool results from preview metrics; raw keeps current raw branch import behavior; forensic preserves recall blocks too.
importQualityProfile
Import
select
compatible
compatible, strict
no
import.qualityProfile
Compatible preserves current curated behavior; strict drops process/UI-like, oversized, or repeated successful tool output in curated mode.
importBranches
Import
select
current-only
current-only, all-leaves
no
import.includeBranches
Import current branch only, or every leaf branch explicitly.
importToolResults
Import
select
errors-only
errors-only, summary, content
no
import.toolResults
Curated import defaults to errors-only; summary keeps bounded low-noise successful tool output; content keeps allowed full successful tool content.
importToolSummaryMaxChars
Import
positive-int
500
yes
import.toolResultSummaryMaxChars
Maximum characters kept for successful tool summaries in curated imports.
importManifest
Import
text
.pi/hindsight/import-manifest.json
yes
import.manifestPath
Tracks imported sessions so reimports stay deterministic.
importCheckpoint
Import
text
.pi/hindsight/import-checkpoint.json
yes
import.checkpointPath
Tracks import progress so interrupted imports can resume safely.
importReplaceExisting
Import
boolean
enabled
yes
import.replaceExistingImportedDocs
Uses deterministic replace mode for historical reimports instead of appending duplicates.
importResume
Import
boolean
enabled
yes
import.resume
Skips completed import documents when checkpoint content hashes match.
statusStyle
UI
select
text
off, text, emoji, nerdfont
no
status.style
Off, plain text, emoji, or nerdfont symbols.
statusDetail
UI
select
activity
minimal, project, activity, verbose
no
status.detail
How much Hindsight info appears in Pi footer.
statusMaxLength
UI
positive-int
24
no
status.maxLength
Maximum characters used by Hindsight footer status.
statusActivity
UI
boolean
enabled
no
status.showActivity
Displays recall/retain activity in the status line.
notifyStartup
UI
boolean
enabled
no
notifications.startup
Shows selected Hindsight bank when Pi session starts.
notifyRecall
UI
boolean
disabled
no
notifications.recall
Shows a toast when automatic recall runs.
notifyRetain
UI
boolean
disabled
no
notifications.retain
Shows a toast when automatic retain queues memory.