4d030707ad
Change DEFAULT_ENABLE_BANK_CONFIG_API from false to true, update all docs, error messages, and client docstrings to reflect the new default. Remove explicit env var overrides in CI and tests that are no longer needed.
274 lines
9.6 KiB
Text
274 lines
9.6 KiB
Text
---
|
||
sidebar_position: 6
|
||
---
|
||
|
||
# Memory Banks
|
||
|
||
Memory banks are isolated containers that store all memory-related data for a specific context or use case.
|
||
|
||
import Tabs from '@theme/Tabs';
|
||
import TabItem from '@theme/TabItem';
|
||
import CodeSnippet from '@site/src/components/CodeSnippet';
|
||
|
||
{/* Import raw source files */}
|
||
import memoryBanksPy from '!!raw-loader!@site/examples/api/memory-banks.py';
|
||
import memoryBanksMjs from '!!raw-loader!@site/examples/api/memory-banks.mjs';
|
||
import directivesPy from '!!raw-loader!@site/examples/api/directives.py';
|
||
import directivesMjs from '!!raw-loader!@site/examples/api/directives.mjs';
|
||
|
||
## What is a Memory Bank?
|
||
|
||
A memory bank is a complete, isolated storage unit containing:
|
||
|
||
- **Memories** — Facts and information retained from conversations
|
||
- **Documents** — Files and content indexed for retrieval
|
||
- **Entities** — People, places, concepts extracted from memories
|
||
- **Relationships** — Connections between entities in the knowledge graph
|
||
- **Directives** — Hard rules the agent must follow during reflect operations
|
||
|
||
Banks are completely isolated from each other — memories stored in one bank are not visible to another.
|
||
|
||
You don't need to pre-create a bank. Hindsight will automatically create it with default settings when you first use it.
|
||
|
||
:::tip Prerequisites
|
||
Make sure you've completed the [Quick Start](./quickstart) to install the client and start the server.
|
||
:::
|
||
|
||
## Creating a Memory Bank
|
||
|
||
<Tabs>
|
||
<TabItem value="python" label="Python">
|
||
<CodeSnippet code={memoryBanksPy} section="create-bank" language="python" />
|
||
</TabItem>
|
||
<TabItem value="node" label="Node.js">
|
||
<CodeSnippet code={memoryBanksMjs} section="create-bank" language="javascript" />
|
||
</TabItem>
|
||
<TabItem value="cli" label="CLI">
|
||
|
||
```bash
|
||
hindsight bank create my-bank
|
||
```
|
||
|
||
</TabItem>
|
||
</Tabs>
|
||
|
||
## Bank Configuration
|
||
|
||
Each memory bank can be configured independently per operation. Configuration can be set via the [bank config API](#updating-configuration), the [Control Plane UI](/developer/index), or [server-wide environment variables](/developer/configuration).
|
||
|
||
### retain_mission
|
||
|
||
A plain-language description of what this bank should pay attention to during extraction. The mission is injected into the extraction prompt alongside the built-in rules — it steers focus without replacing the extraction logic.
|
||
|
||
```
|
||
e.g. Always include technical decisions, API design choices, and architectural trade-offs.
|
||
Ignore meeting logistics, greetings, and social exchanges.
|
||
```
|
||
|
||
Works alongside any extraction mode. Leave blank for general-purpose extraction.
|
||
|
||
### retain_extraction_mode
|
||
|
||
Controls how aggressively facts are extracted:
|
||
|
||
| Mode | Description |
|
||
|------|-------------|
|
||
| `concise` *(default)* | Selective — only facts worth remembering long-term |
|
||
| `verbose` | Captures more detail per fact; slower and uses more tokens |
|
||
| `custom` | Write your own extraction rules via `retain_custom_instructions` |
|
||
|
||
### retain_custom_instructions
|
||
|
||
Only active when `retain_extraction_mode` is `custom`. Replaces the built-in extraction rules entirely with your own instructions.
|
||
|
||
See [Retain configuration](/developer/configuration#retain) for environment variable names and defaults.
|
||
|
||
### enable_observations
|
||
|
||
Toggles automatic observation consolidation on or off. Defaults to `true` when the observations feature is enabled on the server.
|
||
|
||
### observations_mission
|
||
|
||
Defines what this bank should synthesise into durable observations. Replaces the built-in consolidation rules entirely — leave blank to use the server default.
|
||
|
||
```
|
||
e.g. Observations are stable facts about people and projects.
|
||
Always include preferences, skills, and recurring patterns.
|
||
Ignore one-off events and ephemeral state.
|
||
```
|
||
|
||
See [Observations configuration](/developer/configuration#observations) for environment variable names and defaults.
|
||
|
||
### mission
|
||
|
||
A first-person narrative that provides identity and framing context for `reflect`. The agent uses this to ground its reasoning and apply a consistent perspective.
|
||
|
||
```
|
||
e.g. You are a senior engineering assistant.
|
||
Always ground answers in documented decisions and rationale.
|
||
Ignore speculation. Be direct and precise.
|
||
```
|
||
|
||
### disposition_skepticism
|
||
|
||
How skeptical vs trusting the bank is when evaluating claims during `reflect`. Scale 1–5.
|
||
|
||
<Tabs>
|
||
<TabItem value="python" label="Python">
|
||
<CodeSnippet code={memoryBanksPy} section="bank-with-disposition" language="python" />
|
||
</TabItem>
|
||
<TabItem value="node" label="Node.js">
|
||
<CodeSnippet code={memoryBanksMjs} section="bank-with-disposition" language="javascript" />
|
||
</TabItem>
|
||
</Tabs>
|
||
|
||
| Value | Behaviour |
|
||
|-------|-----------|
|
||
| `1` | Trusting — accepts information at face value |
|
||
| `3` *(default)* | Balanced |
|
||
| `5` | Skeptical — questions and doubts claims |
|
||
|
||
### disposition_literalism
|
||
|
||
How literally to interpret information during `reflect`. Scale 1–5.
|
||
|
||
| Value | Behaviour |
|
||
|-------|-----------|
|
||
| `1` | Flexible — reads between the lines, considers context |
|
||
| `3` *(default)* | Balanced |
|
||
| `5` | Literal — takes things exactly as stated |
|
||
|
||
### disposition_empathy
|
||
|
||
How much to weight emotional context when reasoning during `reflect`. Scale 1–5.
|
||
|
||
| Value | Behaviour |
|
||
|-------|-----------|
|
||
| `1` | Detached — focuses on facts and logic |
|
||
| `3` *(default)* | Balanced |
|
||
| `5` | Empathetic — considers emotional context |
|
||
|
||
:::info
|
||
Disposition traits and `mission` only affect the `reflect` operation. `retain_mission` and `observations_mission` are separate per-operation settings.
|
||
:::
|
||
|
||
---
|
||
|
||
## Updating Configuration
|
||
|
||
Bank configuration fields (retain mission, extraction mode, observations mission, etc.) are managed via a **separate config API**, not the `create_bank` call. This lets you change operational settings independently from the bank's identity and disposition.
|
||
|
||
### Setting Configuration Overrides
|
||
|
||
<Tabs>
|
||
<TabItem value="python" label="Python">
|
||
<CodeSnippet code={memoryBanksPy} section="update-bank-config" language="python" />
|
||
</TabItem>
|
||
<TabItem value="node" label="Node.js">
|
||
<CodeSnippet code={memoryBanksMjs} section="update-bank-config" language="javascript" />
|
||
</TabItem>
|
||
</Tabs>
|
||
|
||
You can update any subset of fields — only the keys you provide are changed.
|
||
|
||
### Reading the Current Configuration
|
||
|
||
<Tabs>
|
||
<TabItem value="python" label="Python">
|
||
<CodeSnippet code={memoryBanksPy} section="get-bank-config" language="python" />
|
||
</TabItem>
|
||
<TabItem value="node" label="Node.js">
|
||
<CodeSnippet code={memoryBanksMjs} section="get-bank-config" language="javascript" />
|
||
</TabItem>
|
||
</Tabs>
|
||
|
||
The response distinguishes:
|
||
- **`config`** — the fully resolved configuration (server defaults merged with bank overrides)
|
||
- **`overrides`** — only the fields explicitly overridden for this bank
|
||
|
||
### Resetting to Defaults
|
||
|
||
<Tabs>
|
||
<TabItem value="python" label="Python">
|
||
<CodeSnippet code={memoryBanksPy} section="reset-bank-config" language="python" />
|
||
</TabItem>
|
||
<TabItem value="node" label="Node.js">
|
||
<CodeSnippet code={memoryBanksMjs} section="reset-bank-config" language="javascript" />
|
||
</TabItem>
|
||
</Tabs>
|
||
|
||
This removes all bank-level overrides. The bank reverts to server-wide defaults (set via environment variables).
|
||
|
||
You can also update configuration directly from the [Control Plane UI](/developer/index) — navigate to a bank and open the **Configuration** tab.
|
||
|
||
---
|
||
|
||
## Directives
|
||
|
||
Directives are hard rules that the agent must follow during [reflect](./reflect) operations. Unlike disposition traits which influence *how* the agent reasons, directives are explicit instructions that are *always* enforced.
|
||
|
||
:::info
|
||
Directives only affect the `reflect` operation. They are injected into prompts and the agent is required to comply with them in all responses.
|
||
:::
|
||
|
||
### When to Use Directives
|
||
|
||
Use directives for rules that must never be violated:
|
||
|
||
- **Language/style constraints**: "Always respond in formal English"
|
||
- **Privacy rules**: "Never share personal data with third parties"
|
||
- **Domain constraints**: "Prefer conservative investment recommendations"
|
||
- **Behavioral guardrails**: "Always cite sources when making claims"
|
||
|
||
### Creating Directives
|
||
|
||
<Tabs>
|
||
<TabItem value="python" label="Python">
|
||
<CodeSnippet code={directivesPy} section="create-directive" language="python" />
|
||
</TabItem>
|
||
<TabItem value="node" label="Node.js">
|
||
<CodeSnippet code={directivesMjs} section="create-directive" language="javascript" />
|
||
</TabItem>
|
||
</Tabs>
|
||
|
||
### Listing Directives
|
||
|
||
<Tabs>
|
||
<TabItem value="python" label="Python">
|
||
<CodeSnippet code={directivesPy} section="list-directives" language="python" />
|
||
</TabItem>
|
||
<TabItem value="node" label="Node.js">
|
||
<CodeSnippet code={directivesMjs} section="list-directives" language="javascript" />
|
||
</TabItem>
|
||
</Tabs>
|
||
|
||
### Updating Directives
|
||
|
||
<Tabs>
|
||
<TabItem value="python" label="Python">
|
||
<CodeSnippet code={directivesPy} section="update-directive" language="python" />
|
||
</TabItem>
|
||
<TabItem value="node" label="Node.js">
|
||
<CodeSnippet code={directivesMjs} section="update-directive" language="javascript" />
|
||
</TabItem>
|
||
</Tabs>
|
||
|
||
### Deleting Directives
|
||
|
||
<Tabs>
|
||
<TabItem value="python" label="Python">
|
||
<CodeSnippet code={directivesPy} section="delete-directive" language="python" />
|
||
</TabItem>
|
||
<TabItem value="node" label="Node.js">
|
||
<CodeSnippet code={directivesMjs} section="delete-directive" language="javascript" />
|
||
</TabItem>
|
||
</Tabs>
|
||
|
||
### Directives vs Disposition
|
||
|
||
| Aspect | Directives | Disposition |
|
||
|--------|------------|-------------|
|
||
| **Nature** | Hard rules, must be followed | Soft influence on reasoning style |
|
||
| **Enforcement** | Strict — responses are rejected if violated | Flexible — shapes interpretation |
|
||
| **Use case** | Compliance, guardrails, constraints | Personality, character, tone |
|
||
| **Example** | "Never recommend specific stocks" | High skepticism: questions claims |
|