Memory banks API — create and configure banks

Memory banks are isolated containers that store all memory-related data for a specific context or use case. Each bank holds memories, documents, entities, relationships, and directives. Banks are completely isolated — memories in one bank are never visible to another. You do not need to pre-create a bank; Hindsight creates it automatically with default settings when you first use it.

Create or update a bank

PUT /v1/{tenant}/banks/{bank_id}

Creates a bank if it does not exist, or updates it if it does. All fields are optional — only the keys you provide are changed.

Request parameters

path.tenant

string

required

Your tenant identifier. Use default for single-tenant deployments.

path.bank_id

string

required

Unique identifier for the bank. Alphanumeric and hyphens.

reflect_mission

string

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. Example: "You are a senior engineering assistant. Always ground answers in documented decisions. Be direct and precise."

disposition_skepticism

integer

How skeptical vs. trusting the bank is when evaluating claims during reflect. Scale 1–5. 1 = trusting (accepts information at face value), 3 = balanced (default), 5 = skeptical (questions and doubts claims).

disposition_literalism

integer

How literally to interpret information during reflect. Scale 1–5. 1 = flexible (reads between the lines), 3 = balanced (default), 5 = literal (takes things exactly as stated).

disposition_empathy

integer

How much to weight emotional context when reasoning during reflect. Scale 1–5. 1 = detached (focuses on facts and logic), 3 = balanced (default), 5 = empathetic (considers emotional context).

Response fields

bank_id

string

required

The bank identifier.

created_at

string

required

ISO 8601 timestamp of when the bank was created.

updated_at

string

required

ISO 8601 timestamp of the most recent update.

Example

curl -X PUT "https://your-hindsight-host/v1/default/banks/my-bank" \
  -H "Authorization: Bearer $HINDSIGHT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "reflect_mission": "You are a senior engineering assistant. Ground answers in documented decisions.",
    "disposition_skepticism": 4
  }'

Get a bank

GET /v1/{tenant}/banks/{bank_id}

Returns the bank profile including identity, disposition, and configuration.

Response fields

bank_id

string

required

The bank identifier.

reflect_mission

string

The bank’s reflect mission, if set.

disposition_skepticism

integer

Current skepticism setting (1–5).

disposition_literalism

integer

Current literalism setting (1–5).

disposition_empathy

integer

Current empathy setting (1–5).

created_at

string

required

ISO 8601 creation timestamp.

updated_at

string

required

ISO 8601 last-updated timestamp.

Example

curl "https://your-hindsight-host/v1/default/banks/my-bank" \
  -H "Authorization: Bearer $HINDSIGHT_API_KEY"

List banks

GET /v1/{tenant}/banks

Returns all banks for the tenant.

Example

curl "https://your-hindsight-host/v1/default/banks" \
  -H "Authorization: Bearer $HINDSIGHT_API_KEY"

Delete a bank

DELETE /v1/{tenant}/banks/{bank_id}

Permanently deletes the bank and all its contents: memories, documents, entities, directives, mental models, and operations.

This action cannot be undone. All data associated with the bank is permanently destroyed.

Example

curl -X DELETE "https://your-hindsight-host/v1/default/banks/my-bank" \
  -H "Authorization: Bearer $HINDSIGHT_API_KEY"

Bank configuration

Bank configuration fields (extraction mode, missions, observations, disposition, recall budgets, entity labels) are managed via a separate config API endpoint, not the PUT /banks/{bank_id} call. This lets you change operational settings independently from the bank’s identity.

Update configuration

POST /v1/{tenant}/banks/{bank_id}/config

retain_mission

string

A plain-language description of what this bank should pay attention to during extraction. Injected into the extraction prompt alongside built-in rules. Example: "Always include technical decisions and API design choices. Ignore meeting logistics and greetings."

retain_extraction_mode

string

default:"concise"

Controls how aggressively facts are extracted. "concise" — selective, only facts worth remembering long-term. "verbose" — captures more detail per fact, slower and uses more tokens. "custom" — use your own extraction rules via retain_custom_instructions.

retain_custom_instructions

string

Custom extraction prompt. Only active when retain_extraction_mode is "custom". Replaces the built-in extraction rules entirely.

retain_chunk_size

integer

default:"3000"

Maximum number of characters per chunk when splitting content for fact extraction.

enable_observations

boolean

Toggles automatic observation consolidation on or off.

observations_mission

string

Defines what this bank should synthesize into durable observations. Replaces the built-in consolidation rules. Example: "Observations are stable facts about people and projects. Always include preferences, skills, and recurring patterns."

recall_budget_function

string

default:"fixed"

Selects how the recall budget parameter maps to the internal retrieval limit. "fixed" — uses recall_budget_fixed_<level> independent of max_tokens. "adaptive" — scales retrieval breadth with the requested output size.

entity_labels

object[]

Defines a controlled vocabulary of key:value classification labels extracted at retain time. Each entry is a label group with key, description, type ("value", "multi-values", "text", or "map"), values (allowed enum values), optional, and tag (when true, extracted labels are also written as tags).

mcp_enabled_tools

string[]

Allowlist of MCP tool names enabled for this bank. Set to null to allow all tools.

Example

curl -X POST "https://your-hindsight-host/v1/default/banks/my-bank/config" \
  -H "Authorization: Bearer $HINDSIGHT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "retain_mission": "Focus on technical decisions and API design choices.",
    "retain_extraction_mode": "verbose",
    "enable_observations": true
  }'

Get configuration

GET /v1/{tenant}/banks/{bank_id}/config

Returns the fully resolved configuration (server defaults merged with bank overrides) and the bank-level overrides separately.

Reset configuration

DELETE /v1/{tenant}/banks/{bank_id}/config

Removes all bank-level overrides. The bank reverts to server-wide defaults set via environment variables.

Bank profile

GET /v1/{tenant}/banks/{bank_id}/profile

Returns aggregated statistics about the bank’s memory content.

Response fields

bank_id

string

required

The bank identifier.

memory_unit_count

integer

required

Total number of memory facts stored in the bank.

document_count

integer

required

Total number of documents.

entity_count

integer

required

Total number of entities in the knowledge graph.

observation_count

integer

required

Total number of consolidated observations.

Example

curl "https://your-hindsight-host/v1/default/banks/my-bank/profile" \
  -H "Authorization: Bearer $HINDSIGHT_API_KEY"

Directives

Directives are hard rules that the agent must follow during reflect operations. Unlike disposition traits which influence how the agent reasons, directives are explicit instructions that are always enforced.

Directives only affect the reflect operation. They are injected into prompts and the agent is required to comply in all responses.

Create a directive

POST /v1/{tenant}/banks/{bank_id}/directives

name

string

required

Human-readable name for the directive.

content

string

required

The directive content or rules. Example: "Never share personal data with third parties." or "Always respond in formal English."

priority

integer

default:"0"

Priority level. Higher values are injected first into the prompt.

is_active

boolean

default:"true"

Whether the directive is currently active.

Example

curl -X POST "https://your-hindsight-host/v1/default/banks/my-bank/directives" \
  -H "Authorization: Bearer $HINDSIGHT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Privacy rule",
    "content": "Never share personal data with third parties.",
    "priority": 10
  }'

List, update, and delete directives

GET    /v1/{tenant}/banks/{bank_id}/directives
PUT    /v1/{tenant}/banks/{bank_id}/directives/{directive_id}
DELETE /v1/{tenant}/banks/{bank_id}/directives/{directive_id}

# List
directives = client.list_directives(bank_id="my-bank")

# Update
client.update_directive(
    bank_id="my-bank",
    directive_id="dir-123",
    content="Updated rule content.",
    is_active=False,
)

# Delete
await client.directives.delete_directive("my-bank", "dir-123")

Core Methods

Resources

Memory banks API — create and configure banks

Create or update a bank

Request parameters

Response fields

Example

Get a bank

Response fields

Example

List banks

Example

Delete a bank

Example

Bank configuration

Update configuration

Example

Get configuration

Reset configuration

Bank profile

Response fields

Example

Directives

Create a directive

Example

List, update, and delete directives

Build docs developers (and LLMs) love

Core Methods

Resources

Documentation Index

​Create or update a bank

​Request parameters

​Response fields

​Example

​Get a bank

​Response fields

​Example

​List banks

​Example

​Delete a bank

​Example

​Bank configuration

​Update configuration

​Example

​Get configuration

​Reset configuration

​Bank profile

​Response fields

​Example

​Directives

​Create a directive

​Example

​List, update, and delete directives

Build docs developers (and LLMs) love

Create or update a bank

Request parameters

Response fields

Example

Get a bank

Response fields

Example

List banks

Example

Delete a bank

Example

Bank configuration

Update configuration

Example

Get configuration

Reset configuration

Bank profile

Response fields

Example

Directives

Create a directive

Example

List, update, and delete directives