Generated surface reference

This reference is generated from the operation catalog and config editing registry.

1.0 support scope

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.

Tool	Scope
hindsight_recall	core 1.0
hindsight_retain	core 1.0
hindsight_retain_global	core 1.0
hindsight_reflect	core 1.0

Deferred or non-goal upstream surfaces

Surface	1.0 status	Rationale
Cross-bank list/create	Deferred	No public list_banks or arbitrary cross-bank create_bank tool in 1.0.
Full-bank deletion	Deferred	No public delete_bank tool in 1.0; selected-bank reset/delete-like repair remains scoped.
Platform bank stats	Deferred	No global get_bank_stats dashboard/tool in 1.0.
Audit logs and webhooks	Non-goal	Platform administration is outside the Pi-first 1.0 memory lifecycle.

Tools

hindsight_recall

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.
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	no
tagGroups	array	no	Compound Hindsight tag_groups filter. AND-ed with the automatic Pi project/user scope filter.

hindsight_retain

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.
observationScopes	per_tag | combined | all_combinations | array<array>	no	Optional Hindsight observation scopes. Use per_tag, combined, all_combinations, 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.

hindsight_retain_global

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.
observationScopes	per_tag | combined | all_combinations | array<array>	no	Optional Hindsight observation scopes. Use per_tag, combined, all_combinations, 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.

hindsight_reflect

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	no
tagGroups	array	no	Compound Hindsight tag_groups filter. AND-ed with the automatic Pi project/user scope filter.

Commands

Command	Description
/hindsight	Open Hindsight memory TUI.
/hindsight:init	Write .pi/hindsight.json with the currently selected project bank.
/hindsight:import	Import the current Pi session JSONL into Hindsight.
/hindsight:import-current	Import the current Pi session JSONL into Hindsight.
/hindsight:import-file	Import an explicit Pi session JSONL file into Hindsight.
/hindsight:import-project-sessions	Import Pi session JSONL files scoped to the current repo/cwd.
/hindsight:session	Show current Hindsight session memory mode and tags.
/hindsight:mode	Set session memory mode: normal, read-only, or ignored.
/hindsight:next-opt-out	Skip automatic retain for the next agent run in this session.
/hindsight:retain	Enable or disable retain for this session.
/hindsight:tag	Add or remove a Hindsight tag for this session.
/hindsight:last-recall	Show the last opt-in persisted recall snapshot.
/hindsight:recall-cleanup	Scan or prune accidentally persisted Hindsight recall blocks from the current session transcript.
/hindsight:queue	Inspect local retain queue and dead-letter metadata without printing payloads.
/hindsight:flush	Flush queued retain jobs.

Config fields

Field	Tab	Kind	Default	Choices	Advanced	Reset key	Description
enabled	Connection	boolean	enabled		no	enabled	Master switch. When off, automatic recall and retain are skipped.
baseUrl	Connection	text	http://localhost:8888		no	hindsight.baseUrl	Server endpoint used for recall, retain, reflect, and bank setup.
apiKeyEnv	Connection	text	not set		no	hindsight.apiKey	Recommended: environment variable name that contains the API key. Editing writes a safe env SecretRef, not the raw secret.
apiKeyDirect	Connection	text	not set		yes	hindsight.apiKey	Advanced. Writes raw API key only to user/global config. Prefer API key source/env var whenever possible.
timeoutMs	Connection	positive-int	30000 ms		no	hindsight.timeoutMs	Maximum time to wait for Hindsight network calls.
memoryProfile	Banks	select	project-only	project-only, project+global, global-only, recall-only	no	banks.profile	Choose Project Only for strict isolation, Project + User for personal coding, User Only for cross-repo preference memory, or Recall Only to disable automatic retain.
projectBankId	Banks	text	auto-derived		no	banks.project.bankId	Bank used for this repository. Default derives a stable ID from repo identity.
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 memory tokens injected into context.
recallStoreLast	Recall	boolean	disabled		yes	recall.storeLastRecall	Advanced. Writes the latest successful recall snapshot to a local sidecar for /hindsight:last-recall.
recallStoreFailures	Recall	boolean	disabled		yes	recall.storeLastRecallFailures	Advanced. Also records redacted failed recall attempts in the last-recall sidecar. Requires storing last recall snapshots.
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.
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, router	yes	globalRetain.mode	Advanced. explicit-only keeps global writes manual; router enables future high-confidence routing.
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.