Pi Hindsight 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 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.
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 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.
Get or patch allowlisted Pi Hindsight config (project or global file). action=get returns effective values (no secrets) and the allowlist. action=patch updates only typed allowlisted keys (setupComplete, scopeMode, projectId, projectIdStrategy, includeSharedObservations, projectBankId, enableGlobalBank, globalBankId, agentUse, mentalModelsInject, memoryProfile, recall/retain knobs, baseUrl, apiKeyEnvVar, timeoutMs). dryRun defaults true for patch. Domain-tagged setupComplete requires projectBankId. Never pass raw API keys — use apiKeyEnvVar.
Parameter
Type
Required
Description
action
get | patch
yes
patch
object
no
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 for patch), preview only; set false to write.
Agent control plane for mental models on the selected bank. Actions: list|get|create|update|refresh|delete. list returns metadata only (id, name, tags, max_tokens, last_refreshed_at); use get for full content/reflect_response. Project-tier create defaults tags to source:pi + project:. Optional tagsMatch sets refresh tag matching on create/update trigger. Mutating actions default dryRun=true; set dryRun=false to apply.
Parameter
Type
Required
Description
action
list | get | create | update | refresh | delete
yes
bank
string
no
Bank id or alias project|global|user.
id
string
no
Mental model id for get/update/refresh/delete.
name
string
no
sourceQuery
string
no
tags
array
no
maxTokens
integer
no
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
Mutating actions default true (preview). Set false to apply.
Agent control plane for knowledge pages (living docs over bank observations). Actions: tree|search|get|export|seed_taxonomy|create_page|create_folder|update|delete. Prefer search then get for routine Q&A (pages are not auto-injected). seed_taxonomy creates the fixed five-page coding taxonomy (idempotent; degrades when pages unavailable). Use export only for a portable full-bank markdown bundle. Project-tier create_page defaults tags to source:pi + project:. Mutating actions default dryRun=true. Requires Hindsight client/server knowledge-base support.
Parameter
Type
Required
Description
action
tree | search | get | export | seed_taxonomy | create_page | create_folder | update | delete
yes
bank
string
no
Bank id or alias project|global|user.
id
string
no
Page or folder id for get/update/delete.
query
string
no
Search query for action=search (hybrid page search).
limit
integer
no
Search result limit (1–50).
name
string
no
sourceQuery
string
no
Page question for create_page / update.
parentId
string | null
no
Folder parent. Omit for root create; pass null on update to move to root.
tags
array
no
maxTokens
integer
no
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
Mutating actions (seed_taxonomy|create_page|create_folder|update|delete) default true (preview). Set false to apply.
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.