a56cd044e5
* feat: independent versioning for integrations
- Add per-integration changelog pages at /changelog/integrations/<name>
- Move main changelog to changelog/index.md (URL unchanged)
- Add --integration flag to generate-changelog for LLM-based per-integration changelog generation
- Add scripts/release-integration.sh <name> <version> for cutting integration releases
- Add .github/workflows/release-integration.yml to publish on integrations/** tags
- Remove integrations from main release.sh and release.yml cycle
* fix: add agno and hermes integration docs to version-0.4 for production build
* chore: apply ruff formatting to generate_changelog.py
* feat: add 4-tab code parity across all documentation examples
Every code snippet Tabs block now has Python, Node.js, CLI, and Go variants.
Raw HTTP/curl tabs replaced with proper SDK calls.
New example files:
- Go: retain.go, recall.go, reflect.go, memory-banks.go, directives.go,
mental-models.go, documents.go, main-methods.go
- Shell: memory-banks.sh, directives.sh, mental-models.sh
- Node.js: mental-models.mjs
Extended example files with missing sections:
- recall.mjs/sh: world/experience/observation types, token-budget, all tag modes
- reflect.sh: reflect-with-params, reflect-disposition, reflect-sources, reflect-with-tags
- reflect.mjs: reflect-with-tags, fixed reflect-sources API usage
- retain.mjs/sh: retain-conversation, retain-batch, retain-files-batch
SDK/CLI additions:
- TypeScript: getMentalModelHistory method
- CLI recall: --tags, --tags-match flags
- CLI reflect: --tags, --tags-match, --include-facts flags
- CLI directive update: --is-active flag
- CLI bank set-config: --retain-mission, --retain-extraction-mode,
--observations-mission, --reflect-mission, --disposition-* flags
Build validation:
- scripts/check-code-parity.mjs validates 4-tab parity across all MDX files
- Integrated into npm run build — fails if any Tabs block is missing a variant
* fix: fix doc examples for Go, Node.js, CLI + add mental model with-id examples
- Fix Go Budget constants: BUDGET_HIGH/LOW/MID → HIGH/LOW/MID
- Fix Go documents.go: ListDocuments returns []map[string]interface{}, use map access
- Fix Go retain.go: use correct relative path for sample.pdf
- Fix Node.js createMentalModel: use positional args (name, sourceQuery) not object
- Add CLI 'history' subcommand for mental models (api.rs, main.rs, mental_model.rs)
- Rebuild TypeScript/Python clients to support id param in createMentalModel
- Add create-mental-model-with-id examples across all 4 languages and docs
* fix: move id param to end of create_mental_model signature for backwards compat
171 lines
7.5 KiB
Text
171 lines
7.5 KiB
Text
---
|
|
sidebar_position: 3
|
|
---
|
|
|
|
# Reflect
|
|
|
|
Generate a grounded, disposition-aware response using an agentic reasoning loop.
|
|
|
|
When you call **reflect**, Hindsight runs an agentic loop that autonomously searches the memory bank using multiple retrieval tools, applies the bank's disposition traits to shape the reasoning style, and produces a final answer grounded in what it found. Unlike recall — which returns raw facts — reflect returns a synthesized response written by the LLM.
|
|
|
|
import Tabs from '@theme/Tabs';
|
|
import TabItem from '@theme/TabItem';
|
|
import CodeSnippet from '@site/src/components/CodeSnippet';
|
|
|
|
{/* Import raw source files */}
|
|
import reflectPy from '!!raw-loader!@site/examples/api/reflect.py';
|
|
import reflectMjs from '!!raw-loader!@site/examples/api/reflect.mjs';
|
|
import reflectSh from '!!raw-loader!@site/examples/api/reflect.sh';
|
|
import reflectGo from '!!raw-loader!@site/examples/api/reflect.go';
|
|
|
|
:::info How Reflect Works
|
|
Learn about disposition-driven reasoning in the [Reflect Architecture](/developer/reflect) guide.
|
|
:::
|
|
|
|
:::tip Prerequisites
|
|
Make sure you've completed the [Quick Start](./quickstart) to install the client and start the server.
|
|
:::
|
|
|
|
## Basic Usage
|
|
|
|
<Tabs>
|
|
<TabItem value="python" label="Python">
|
|
<CodeSnippet code={reflectPy} section="reflect-basic" language="python" />
|
|
</TabItem>
|
|
<TabItem value="node" label="Node.js">
|
|
<CodeSnippet code={reflectMjs} section="reflect-basic" language="javascript" />
|
|
</TabItem>
|
|
<TabItem value="cli" label="CLI">
|
|
<CodeSnippet code={reflectSh} section="reflect-basic" language="bash" />
|
|
</TabItem>
|
|
<TabItem value="go" label="Go">
|
|
<CodeSnippet code={reflectGo} section="reflect-basic" language="go" />
|
|
</TabItem>
|
|
</Tabs>
|
|
|
|
---
|
|
|
|
## Parameters
|
|
|
|
### query
|
|
|
|
The question or prompt to reflect on. This is the only required field. If you have situational context that should influence the answer, include it directly in the query rather than as a separate field.
|
|
|
|
### budget
|
|
|
|
Controls how thoroughly the agent explores the memory bank before answering. Accepted values are `low` (default), `mid`, and `high`. At `low`, the agent does a shallow search optimized for speed. At `mid`, it checks multiple sources when the question warrants it. At `high`, it performs deep exploration across all knowledge levels and may use multiple query variations to find indirect connections. Use `high` for complex questions that require synthesizing information from many sources.
|
|
|
|
<Tabs>
|
|
<TabItem value="python" label="Python">
|
|
<CodeSnippet code={reflectPy} section="reflect-with-params" language="python" />
|
|
</TabItem>
|
|
<TabItem value="node" label="Node.js">
|
|
<CodeSnippet code={reflectMjs} section="reflect-with-params" language="javascript" />
|
|
</TabItem>
|
|
<TabItem value="cli" label="CLI">
|
|
<CodeSnippet code={reflectSh} section="reflect-with-params" language="bash" />
|
|
</TabItem>
|
|
<TabItem value="go" label="Go">
|
|
<CodeSnippet code={reflectGo} section="reflect-with-params" language="go" />
|
|
</TabItem>
|
|
</Tabs>
|
|
|
|
### max_tokens
|
|
|
|
Limits the length of the final generated response. Defaults to `4096`. This does not affect how much the agent can retrieve during the agentic loop — only the final answer length.
|
|
|
|
### response_schema
|
|
|
|
An optional JSON Schema object. When provided, the LLM generates a response that conforms to the schema and the response includes a `structured_output` field with the result parsed accordingly. The `text` field will be empty since only a single structured LLM call is made. Use this when you need to process the response programmatically rather than display it as prose.
|
|
|
|
<Tabs>
|
|
<TabItem value="python" label="Python">
|
|
<CodeSnippet code={reflectPy} section="reflect-structured-output" language="python" />
|
|
</TabItem>
|
|
<TabItem value="node" label="Node.js">
|
|
<CodeSnippet code={reflectMjs} section="reflect-structured-output" language="javascript" />
|
|
</TabItem>
|
|
<TabItem value="cli" label="CLI">
|
|
<CodeSnippet code={reflectSh} section="reflect-structured-output" language="bash" />
|
|
</TabItem>
|
|
<TabItem value="go" label="Go">
|
|
<CodeSnippet code={reflectGo} section="reflect-structured-output" language="go" />
|
|
</TabItem>
|
|
</Tabs>
|
|
|
|
### tags
|
|
|
|
Filters which memories the agent can access during reflection. Works identically to [recall tags](./recall#tags) — only memories matching the specified tags are considered. The `tags_match` parameter controls the matching logic (`any`, `all`, `any_strict`, `all_strict`) with the same semantics as recall.
|
|
|
|
<Tabs>
|
|
<TabItem value="python" label="Python">
|
|
<CodeSnippet code={reflectPy} section="reflect-with-tags" language="python" />
|
|
</TabItem>
|
|
<TabItem value="node" label="Node.js">
|
|
<CodeSnippet code={reflectMjs} section="reflect-with-tags" language="javascript" />
|
|
</TabItem>
|
|
<TabItem value="cli" label="CLI">
|
|
<CodeSnippet code={reflectSh} section="reflect-with-tags" language="bash" />
|
|
</TabItem>
|
|
<TabItem value="go" label="Go">
|
|
<CodeSnippet code={reflectGo} section="reflect-with-tags" language="go" />
|
|
</TabItem>
|
|
</Tabs>
|
|
|
|
### include
|
|
|
|
Controls optional supplementary data returned alongside the main response.
|
|
|
|
#### include.facts
|
|
|
|
When enabled, the response includes a `based_on` object listing the memories, mental models, and directives the agent actually used to construct the answer. Only sources retrieved during the agent loop can appear here — citations are validated to prevent hallucinated references. Useful for transparency and verification.
|
|
|
|
<Tabs>
|
|
<TabItem value="python" label="Python">
|
|
<CodeSnippet code={reflectPy} section="reflect-sources" language="python" />
|
|
</TabItem>
|
|
<TabItem value="node" label="Node.js">
|
|
<CodeSnippet code={reflectMjs} section="reflect-sources" language="javascript" />
|
|
</TabItem>
|
|
<TabItem value="cli" label="CLI">
|
|
<CodeSnippet code={reflectSh} section="reflect-sources" language="bash" />
|
|
</TabItem>
|
|
<TabItem value="go" label="Go">
|
|
<CodeSnippet code={reflectGo} section="reflect-sources" language="go" />
|
|
</TabItem>
|
|
</Tabs>
|
|
|
|
#### include.tool_calls
|
|
|
|
When enabled, the response includes a `trace` object with the full execution log of every tool call and LLM call made during the agentic loop, including inputs, outputs, and durations. Set `output: false` to include only tool inputs for a smaller payload. Useful for debugging why the agent reached a particular conclusion.
|
|
|
|
---
|
|
|
|
## Response
|
|
|
|
### text
|
|
|
|
The synthesized answer as a well-formatted markdown string. This is the primary output of reflect. Empty when `response_schema` is provided (use `structured_output` instead in that case).
|
|
|
|
### structured_output
|
|
|
|
The LLM's response parsed according to the `response_schema` provided in the request. Only present when `response_schema` was set. `null` otherwise.
|
|
|
|
### based_on
|
|
|
|
The sources the agent used to construct the answer. Only present when `include.facts` was enabled. Contains three fields:
|
|
|
|
- `memories` — a list of memory facts (world, experience, observation) that were retrieved and cited. Each item has `id`, `text`, `type`, `context`, `occurred_start`, and `occurred_end`.
|
|
- `mental_models` — a list of mental models that were used. Each item has `id`, `text`, and `context`.
|
|
- `directives` — a list of directives that were enforced during reasoning. Each item has `id`, `name`, and `content`.
|
|
|
|
### usage
|
|
|
|
Token usage for all LLM calls made during the agentic loop: `input_tokens`, `output_tokens`, and `total_tokens`. Useful for cost tracking.
|
|
|
|
### trace
|
|
|
|
The full execution log of the agentic loop. Only present when `include.tool_calls` was enabled. Contains:
|
|
|
|
- `tool_calls` — each tool invocation with `tool` name (`lookup`, `recall`, `learn`, `expand`), `input`, `output` (if `output: true`), `duration_ms`, and `iteration` number.
|
|
- `llm_calls` — each LLM call with `scope` (e.g., `"agent_1"`, `"final"`) and `duration_ms`.
|