跳到主要内容

Retain：存储记忆

Retain 操作将新信息存储到记忆库中。Hindsight 会处理内容、提取结构化记忆，并为高效检索建立索引。

概述​

Retain 是向 Hindsight 添加信息的主要方式：

  • 处理自然语言内容
  • 自动提取并归类记忆
  • 存储世界事实、经验和观察
  • 构建一个为 TEMPR 检索而索引的可搜索知识库

基本用法​

from hindsight_client import Hindsight

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

# Simple retain
client.retain(
    bank_id="your-bank-id",
    content="The user's favorite color is blue and they work as a software engineer."
)

工作原理​

调用 Retain 时：

  1. 内容分析 - Hindsight 使用 AI 处理你的文本
  2. 记忆提取 - 识别出独立的记忆
  3. 分类 - 每条记忆按类型归类：
    • 世界事实（来自外部来源的客观事实）
    • 经验（事件和交互）
    • 观察（基于事实整合的自动综合知识）
  4. 建立索引 - 为 TEMPR 检索建立索引（语义、关键词、图、时间）
  5. 持久化 - 数据被存储到记忆库中

请求参数​

参数类型必填说明
bank_idstring是目标记忆库 ID（在 URL 路径中）
itemsarray是要存储的记忆项数组
items[].contentstring是要处理的文本内容
items[].contextstring否关于内容的上下文
items[].timestampstring否记忆的 ISO 8601 时间戳
asyncboolean否异步处理（默认：false）

响应​

{
  "success": true,
  "bank_id": "my-assistant",
  "items_count": 1,
  "async": false,
  "operation_id": null,
  "usage": {
    "input_tokens": 2684,
    "output_tokens": 511,
    "total_tokens": 3195
  }
}
字段说明
success操作是否成功
bank_id记忆库 ID
items_count处理的项数
async是否异步处理
operation_id用于追踪异步操作的 ID
usageToken 消耗明细

内容最佳实践​

保持具体​

client.retain(
    bank_id=bank_id,
    content="Alice prefers Python over JavaScript for backend development. She has 5 years of experience with FastAPI."
)

包含上下文​

client.retain(
    bank_id=bank_id,
    content="During our March 15 meeting, the client mentioned they need the report by April 1st and prefer PDF format."
)

使用自然语言​

client.retain(
    bank_id=bank_id,
    content="The customer is based in Tokyo, Japan and operates in the financial services sector. They typically respond faster to emails than phone calls."
)

批量操作​

contents = [
    "User completed onboarding on January 10th.",
    "User's team has 5 members.",
    "User prefers weekly check-ins over daily standups."
]

for content in contents:
    client.retain(bank_id=bank_id, content=content)

带元数据​

client.retain(
    bank_id=bank_id,
    content="Meeting notes from Q1 review...",
    source="meeting_transcript",
    metadata={
        "meeting_date": "2024-03-15",
        "attendees": ["alice", "bob", "charlie"]
    }
)

记忆类型解释​

Hindsight 会自动将记忆归类为四种类型：

世界事实​

来自外部来源的客观事实：

  • "Paris is the capital of France"
  • "The project uses PostgreSQL for the database"
  • "The company was founded in 2020"
  • "The user's email is alice@example.com"

经验​

已经发生的事件和交互：

  • "User signed up for the premium plan last week"
  • "We had a productive call with the design team"
  • "The deployment completed successfully at 2 PM"
  • "I sent a welcome email on January 10th"

观察​

自动综合的知识——新事实经分析后整合为带证据追踪的观察。观察会在每次 retain 调用之后在后台自动创建和精炼：

  • "User is growing comfortable with async Python"
  • "Traffic peaks on Tuesday mornings"
  • "Support tickets decrease after documentation updates"

心智模型自动刷新​

通过 Retain 存储记忆时，Hindsight 会将新事实整合到观察中。启用了 trigger.refresh_after_consolidation 的心智模型会在该整合完成后自动刷新，使其与最新知识保持同步。更多详情请参见 心智模型。

Token 使用​

Retain 操作的 Token 消耗取决于：

  • 输入内容长度
  • 处理复杂度
  • 提取的记忆数量

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

错误处理​

try:
    client.retain(bank_id=bank_id, content=content)
    print("Memory stored successfully")
except Exception as e:
    print(f"Error: {e}")

常见错误​

错误原因解决方法
401 UnauthorizedAPI 密钥无效检查 API 密钥
402 Payment Required额度不足为账户添加额度
404 Not Foundbank_id 无效确认记忆库存在
400 Bad Request内容为空提供非空内容