7dad9da02d
* feat: allow chunks only in recall * feat: fetch chunks independently of max_tokens filtering Changes: - Chunks now fetched BEFORE max_tokens filtering (Step 5.5) - Implements batching: (max_chunk_tokens / retain_chunk_size) * 2 - Loop-based fetching until budget exhausted or no more chunks - Handles varying chunk sizes across documents - When max_tokens=0: returns 0 facts but still returns chunks - When max_tokens>0: backward compatible (chunks match filtered facts) Tests: - Added test_recall_chunks_independence.py with 5 comprehensive tests - Tests chunk independence, batching, ordering, and backward compat Docs: - Updated recall.mdx to explain new chunk behavior - Updated memory_engine.py docstrings Fixes chunk-related test failures by reordering chunks to match filtered facts when max_tokens > 0 (backward compatibility). * fix: fetch chunks after token filtering when max_tokens>0 Changes: - When max_tokens=0: fetch chunks BEFORE token filtering (new behavior) - When max_tokens>0: fetch chunks AFTER token filtering (backward compat) - This ensures chunk ordering matches filtered facts for max_tokens>0 - Fixes test failures in test_chunks_and_entities_follow_fact_order, test_chunk_fact_mapping, test_chunk_ordering_preservation, etc. The previous approach tried to reorder prefetched chunks, but that caused issues when the chunk budget was exhausted before all facts were processed. The new approach fetches chunks based on the correct fact set for each scenario. * fix: use ConfigResolver for bank-specific retain_chunk_size Fixes error: Field 'retain_chunk_size' is bank-configurable and cannot be accessed from global config. Changed from: - config.retain_chunk_size (global config, not allowed) To: - bank_config.retain_chunk_size (resolved from ConfigResolver) This ensures the correct chunk size is used for each bank, respecting any bank-specific overrides. * fix: correct Budget import in test_recall_chunks_independence Changed from: - from hindsight_api.engine.interface import Budget (incorrect) To: - from hindsight_api.engine.memory_engine import Budget (correct) This fixes the ImportError that was preventing the tests from running. * fix: prevent infinite loop in chunk fetching and improve test content - Add max(1, ...) to estimated_batch_size to prevent division resulting in 0 - Update test content to use more substantial examples that generate facts - Add request_context parameter to all retain_async and recall_async test calls * refactor: simplify chunk fetching to always use pre-filtering approach Remove backward compatibility code that fetched chunks after token filtering. Now chunks are always fetched from top-scored results before max_tokens filtering, regardless of max_tokens value. This simplifies the code by: - Removing duplicate chunk fetching logic - Eliminating conditional behavior based on max_tokens - Making chunk fetching behavior consistent and predictable Chunks are still fetched in batches and respect max_chunk_tokens limit.
168 lines
6.6 KiB
Text
168 lines
6.6 KiB
Text
---
|
|
sidebar_position: 2
|
|
---
|
|
|
|
# Recall Memories
|
|
|
|
Retrieve memories using multi-strategy recall.
|
|
|
|
import Tabs from '@theme/Tabs';
|
|
import TabItem from '@theme/TabItem';
|
|
import CodeSnippet from '@site/src/components/CodeSnippet';
|
|
|
|
{/* Import raw source files */}
|
|
import recallPy from '!!raw-loader!@site/examples/api/recall.py';
|
|
import recallMjs from '!!raw-loader!@site/examples/api/recall.mjs';
|
|
import recallSh from '!!raw-loader!@site/examples/api/recall.sh';
|
|
|
|
:::info How Recall Works
|
|
Learn about the four retrieval strategies (semantic, keyword, graph, temporal) and RRF fusion in the [Recall Architecture](/developer/retrieval) guide.
|
|
:::
|
|
|
|
:::tip Prerequisites
|
|
Make sure you've completed the [Quick Start](./quickstart) to install the client and start the server.
|
|
:::
|
|
|
|
## Basic Recall
|
|
|
|
<Tabs>
|
|
<TabItem value="python" label="Python">
|
|
<CodeSnippet code={recallPy} section="recall-basic" language="python" />
|
|
</TabItem>
|
|
<TabItem value="node" label="Node.js">
|
|
<CodeSnippet code={recallMjs} section="recall-basic" language="javascript" />
|
|
</TabItem>
|
|
<TabItem value="cli" label="CLI">
|
|
<CodeSnippet code={recallSh} section="recall-basic" language="bash" />
|
|
</TabItem>
|
|
</Tabs>
|
|
|
|
## Recall Parameters
|
|
|
|
| Parameter | Type | Default | Description |
|
|
|-----------|------|---------|-------------|
|
|
| `query` | string | required | Natural language query |
|
|
| `types` | list | all | Filter: `world`, `experience`, `observation` |
|
|
| `budget` | string | "mid" | Budget level: `low`, `mid`, `high` |
|
|
| `max_tokens` | int | 4096 | Token budget for memory facts (text only) |
|
|
| `trace` | bool | false | Enable trace output for debugging |
|
|
| `include_chunks` | bool | false | Include raw text chunks that generated the memories |
|
|
| `max_chunk_tokens` | int | 500 | Token budget for chunks (independent of `max_tokens`) |
|
|
| `tags` | list | None | Filter memories by tags (see [Tag Filtering](#filter-by-tags)) |
|
|
| `tags_match` | string | "any" | How to match tags: `any`, `all`, `any_strict`, `all_strict` |
|
|
|
|
<Tabs>
|
|
<TabItem value="python" label="Python">
|
|
<CodeSnippet code={recallPy} section="recall-with-options" language="python" />
|
|
</TabItem>
|
|
<TabItem value="node" label="Node.js">
|
|
<CodeSnippet code={recallMjs} section="recall-with-options" language="javascript" />
|
|
</TabItem>
|
|
</Tabs>
|
|
|
|
## Filter by Fact Type
|
|
|
|
Recall specific memory types:
|
|
|
|
<Tabs>
|
|
<TabItem value="python" label="Python">
|
|
<CodeSnippet code={recallPy} section="recall-world-only" language="python" />
|
|
<CodeSnippet code={recallPy} section="recall-experience-only" language="python" />
|
|
<CodeSnippet code={recallPy} section="recall-observations-only" language="python" />
|
|
</TabItem>
|
|
<TabItem value="cli" label="CLI">
|
|
<CodeSnippet code={recallSh} section="recall-fact-type" language="bash" />
|
|
</TabItem>
|
|
</Tabs>
|
|
|
|
:::tip About Observations
|
|
Observations are consolidated knowledge synthesized from multiple facts. They capture patterns, preferences, and learnings that the memory bank has built up over time. Observations are automatically created in the background after retain operations.
|
|
:::
|
|
|
|
## Token Budget Management
|
|
|
|
Hindsight is built for AI agents, not humans. Traditional retrieval systems return "top-k" results, but agents don't think in terms of result counts—they think in tokens. An agent's context window is measured in tokens, and that's exactly how Hindsight measures results.
|
|
|
|
The `max_tokens` parameter lets you control how much of your agent's context budget to spend on memories:
|
|
|
|
<Tabs>
|
|
<TabItem value="python" label="Python">
|
|
<CodeSnippet code={recallPy} section="recall-token-budget" language="python" />
|
|
</TabItem>
|
|
</Tabs>
|
|
|
|
This design means you never have to guess whether 10 results or 50 results will fit your context. Just specify the token budget and Hindsight returns as many relevant memories as will fit.
|
|
|
|
:::note Chunks are Independent
|
|
When `include_chunks=True`, chunks are fetched **independently** of the `max_tokens` filtering. This means:
|
|
- Setting `max_tokens=0` will return **0 memory facts** but can still return **chunks** (up to `max_chunk_tokens`)
|
|
- Chunks are based on the top-scored (reranked) results **before** token filtering
|
|
- Chunks are fetched in batches (batch size estimated as `(max_chunk_tokens / retain_chunk_size) * 2`) until the token budget is exhausted
|
|
- This batching approach handles varying chunk sizes across documents efficiently
|
|
- This allows you to retrieve raw source text without memory facts when needed
|
|
:::
|
|
|
|
## Budget Levels
|
|
|
|
The `budget` parameter controls graph traversal depth:
|
|
|
|
- **"low"**: Fast, shallow retrieval — good for simple lookups
|
|
- **"mid"**: Balanced — default for most queries
|
|
- **"high"**: Deep exploration — finds indirect connections
|
|
|
|
<Tabs>
|
|
<TabItem value="python" label="Python">
|
|
<CodeSnippet code={recallPy} section="recall-budget-levels" language="python" />
|
|
</TabItem>
|
|
<TabItem value="node" label="Node.js">
|
|
<CodeSnippet code={recallMjs} section="recall-budget-levels" language="javascript" />
|
|
</TabItem>
|
|
</Tabs>
|
|
|
|
## Filter by Tags
|
|
|
|
Tags enable **visibility scoping**—filter memories based on tags assigned during [retain](./retain#tagging-memories). This is essential for multi-user agents where each user should only see their own memories.
|
|
|
|
### Basic Tag Filtering
|
|
|
|
<Tabs>
|
|
<TabItem value="python" label="Python">
|
|
<CodeSnippet code={recallPy} section="recall-with-tags" language="python" />
|
|
</TabItem>
|
|
</Tabs>
|
|
|
|
### Tag Match Modes
|
|
|
|
The `tags_match` parameter controls how tags are matched:
|
|
|
|
| Mode | Behavior | Untagged Memories |
|
|
|------|----------|-------------------|
|
|
| `any` | OR: memory has ANY of the specified tags | **Included** |
|
|
| `all` | AND: memory has ALL of the specified tags | **Included** |
|
|
| `any_strict` | OR: memory has ANY of the specified tags | **Excluded** |
|
|
| `all_strict` | AND: memory has ALL of the specified tags | **Excluded** |
|
|
|
|
**Strict modes** are useful when you want to ensure only tagged memories are returned:
|
|
|
|
<Tabs>
|
|
<TabItem value="python" label="Python">
|
|
<CodeSnippet code={recallPy} section="recall-tags-strict" language="python" />
|
|
</TabItem>
|
|
</Tabs>
|
|
|
|
**AND matching** requires all specified tags to be present:
|
|
|
|
<Tabs>
|
|
<TabItem value="python" label="Python">
|
|
<CodeSnippet code={recallPy} section="recall-tags-all" language="python" />
|
|
</TabItem>
|
|
</Tabs>
|
|
|
|
### Use Cases
|
|
|
|
| Scenario | Tags | Mode | Result |
|
|
|----------|------|------|--------|
|
|
| User A's memories only | `["user:alice"]` | `any_strict` | Only memories tagged `user:alice` |
|
|
| Support + feedback | `["support", "feedback"]` | `any` | Memories with either tag + untagged |
|
|
| Multi-user room | `["user:alice", "room:general"]` | `all_strict` | Only memories with both tags |
|
|
| Global + user-specific | `["user:alice"]` | `any` | Alice's memories + shared (untagged) |
|