278 lines
9.7 KiB
Text
278 lines
9.7 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.
|
||
|
||
:::note
|
||
The bank config API must be enabled on the server with `HINDSIGHT_API_ENABLE_BANK_CONFIG_API=true`.
|
||
:::
|
||
|
||
### 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 |
|