Recall：检索记忆

Recall 操作从记忆库中搜索并检索相关记忆。它使用 TEMPR 检索策略，通过多种搜索方法找到与你查询相匹配的信息——语义相似性、关键词匹配、实体关系和时间推理。

概述

Recall 实现智能记忆检索：

• TEMPR 多策略搜索（语义、关键词、图、时间）
• 按相关性排序的结果
• 可配置的结果数量限制
• 记忆类型过滤（世界事实、经验、观察）

基本用法

Python

from hindsight_client import Hindsight

client = Hindsight(
    base_url="https://api.hindsight.vectorize.io",
    api_key="your-api-key"
)

# Simple recall
result = client.recall(
    bank_id="your-bank-id",
    query="What are the user's preferences?"
)

for memory in result.results:
    print(f"[{memory.type}] {memory.text}")

TypeScript

import { HindsightClient } from '@vectorize-io/hindsight-client';

const client = new HindsightClient({
  baseUrl: 'https://api.hindsight.vectorize.io',
  apiKey: 'your-api-key'
});

// Simple recall
const result = await client.recall(
  'your-bank-id',
  "What are the user's preferences?"
);

result.results.forEach(memory => {
  console.log(`[${memory.type}] ${memory.text}`);
});

cURL

curl -X POST https://api.hindsight.vectorize.io/v1/default/banks/{bank_id}/memories/recall \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What are the user'\''s preferences?"
  }'

工作原理

调用 Recall 时：

1. 查询处理 - 对查询进行语义、关键词、实体和时间引用方面的分析
2. TEMPR 搜索 - 四种并行搜索方法同时执行：
   • 语义 - 寻找概念上相似的记忆
   • 关键词（BM25） - 匹配精确词项和短语
   • 图 - 遍历实体关系
   • 时间 - 处理基于时间的查询（"上周"、"三月份"）
3. 排序 - 来自所有方法的结果被融合并按相关性排序
4. 过滤 - 应用可选过滤器（类型、日期等）
5. 响应 - 返回最匹配的记忆

请求参数

参数	类型	必填	说明
bank_id	string	是	要搜索的记忆库（在 URL 路径中）
query	string	是	搜索查询（自然语言）
types	array	否	按记忆类型过滤
budget	string	否	搜索深度："low"、"mid"、"high"（默认："mid"）
max_tokens	integer	否	响应的最大 Token 数（默认：4096）
trace	boolean	否	包含调试追踪（默认：false）
query_timestamp	string	否	时间查询的参考时间（ISO 8601）

响应

{
  "results": [
    {
      "id": "mem_abc123",
      "text": "User prefers dark mode interfaces",
      "type": "observation",
      "entities": ["user"],
      "context": "",
      "mentioned_at": "2024-03-15T10:30:00Z"
    },
    {
      "id": "mem_def456",
      "text": "User's timezone is Pacific Standard Time",
      "type": "world",
      "entities": ["user"],
      "context": "",
      "mentioned_at": "2024-03-14T14:20:00Z"
    }
  ],
  "entities": {
    "user": {
      "entity_id": "ent_456",
      "canonical_name": "user",
      "observations": []
    }
  }
}

字段	说明
results	匹配记忆的数组
results[].id	记忆的唯一标识符
results[].text	记忆文本
results[].type	记忆分类（world、experience、observation）
results[].entities	记忆中提到的实体
results[].context	形成该记忆时的上下文
results[].mentioned_at	记忆存储的时间
entities	结果中各实体的详细信息

查询最佳实践

使用自然语言

推荐

memories = client.recall(
    bank_id=bank_id,
    query="What programming languages does the user know?"
)

效果较差

memories = client.recall(
    bank_id=bank_id,
    query="programming languages"
)

保持具体

推荐

memories = client.recall(
    bank_id=bank_id,
    query="What did we discuss about the project timeline in our last meeting?"
)

效果较差

memories = client.recall(
    bank_id=bank_id,
    query="timeline"
)

提问形式

将查询表述为问题通常能获得更好的结果：

# Questions work well
memories = client.recall(query="What are the user's hobbies?")
memories = client.recall(query="When does the client prefer to have meetings?")
memories = client.recall(query="What technology stack is the project using?")

结果过滤

按记忆类型

# Only get world facts and observations
memories = client.recall(
    bank_id=bank_id,
    query="Tell me about the user",
    types=["world_fact", "observation"]
)

按相关性分数

# Only highly relevant results
memories = client.recall(
    bank_id=bank_id,
    query="user preferences",
    min_score=0.8
)

限制结果数量

# Get top 5 results
memories = client.recall(
    bank_id=bank_id,
    query="project requirements",
    limit=5
)

理解分数

相关性分数（0-1）表示记忆与查询的匹配程度：

分数范围	解读
0.9 - 1.0	极佳匹配，直接相关
0.8 - 0.9	强匹配，高度相关
0.7 - 0.8	良好匹配，相关
0.6 - 0.7	中等匹配，有些相关
< 0.6	弱匹配，可能不太有用

高级模式

上下文搜索

将查询与上下文结合以获得更好的结果：

context = "We're discussing the new mobile app feature"
question = "What design preferences have been mentioned?"

memories = client.recall(
    bank_id=bank_id,
    query=f"{context} {question}"
)

迭代细化

先宽泛，再缩小：

# First, broad search
all_prefs = client.recall(query="user preferences")

# Then, specific search based on results
color_prefs = client.recall(query="preferred colors for UI design")

与 Retain 结合

构建对话记忆：

# Store what the user says
client.retain(
    bank_id=bank_id,
    content=f"User said: {user_message}"
)

# Recall relevant context for response
context = client.recall(
    bank_id=bank_id,
    query=user_message,
    limit=5
)

在界面中使用

记忆库中的 Recall 视图提供了一个调试界面：

1. 进入你的记忆库
2. 在侧边栏点击 Recall
3. 输入搜索查询
4. 查看结果，包括：
   • 记忆内容
   • 相关性分数
   • 记忆类型
   • 检索追踪

这对以下场景有用：

• 测试查询效果
• 调试检索问题
• 理解分数分布

Token 使用

Recall 操作的 Token 消耗取决于：

• 查询长度
• 检索结果数量
• 记忆内容大小

在 使用分析 页面监控用量。

错误处理

Python

try:
    result = client.recall(bank_id=bank_id, query=query)
    for memory in result.results:
        print(memory.text)
except Exception as e:
    print(f"Error: {e}")

TypeScript

try {
  const result = await client.recall(bankId, query);
  result.results.forEach(m => console.log(m.text));
} catch (error) {
  console.error('Error:', error.message);
}

常见错误

错误	原因	解决方法
401 Unauthorized	API 密钥无效	检查 API 密钥
402 Payment Required	额度不足	为账户添加额度
404 Not Found	bank_id 无效	确认记忆库存在
400 Bad Request	查询为空	提供搜索查询

性能建议

1. 限制结果数量 - 只请求你需要的记忆数量
2. 按类型过滤 - 当你知道要查找什么时缩小范围
3. 使用 min_score - 过滤掉低相关性的匹配
4. 缓存结果 - 在本地存储经常需要的记忆