心智模型：预计算的反思

心智模型（Mental Models）是预先计算、被缓存的反思，它们捕获记忆库中所存记忆的当前综合状态。它们通过运行 Reflect 查询生成，并可在记忆库知识变化时自动或手动刷新。

由于心智模型是预先计算的，检索它只是一次快速查找——读取时无需 LLM 调用，这与实时的 Reflect 调用不同。这使得心智模型非常适合需要频繁、快速获取的信息，比如用户偏好。例如，如果你为用户偏好创建一个自动刷新的心智模型，它将始终包含关于该用户偏好的所有记忆和观察的最新综合结果。

备注

心智模型是异步更新的。即使启用了自动刷新，它们也是 最终一致的——在新记忆被添加和模型反映这些记忆之间可能会有短暂延迟。

概述

心智模型提供：

预计算检索 —— 内容提前生成，因此读取即时，无需 LLM 调用
缓存的反思 —— 每个模型都是一次 Reflect 查询的结果，将多条记忆的信息综合为单个最新摘要
自动或手动刷新 —— 可选地在记忆整合后自动刷新，或按需手动刷新
层级优先级 —— Reflect 期间，心智模型最先被检查并作为高优先级上下文注入
基于标签的组织 —— 使用标签对模型进行过滤和分类
最终一致性 —— 更新在后台异步进行

使用场景

场景	来源查询示例
用户资料	"What do we know about this user's preferences and background?"
FAQ 机器人	"What are the most common questions and their answers?"
状态报告	"What is the current status of the project?"
团队目录	"Who works here and what do they do?"
入职指南	"What does a new team member need to know?"
政策摘要	"What are the key policies and guidelines?"

创建心智模型

心智模型的创建是异步的——它在后台运行一次 Reflect 查询，并返回一个 operation_id 用于追踪进度。

Python
TypeScript
cURL

from hindsight_client import Hindsight

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

# Create a mental model
result = client.create_mental_model(
    bank_id="my-assistant",
    name="User Profile",
    source_query="What do we know about this user's preferences and background?"
)

print(f"Creating mental model (operation: {result.operation_id})")

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

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

// Create a mental model
const result = await client.createMentalModel(
  'my-assistant',
  'User Profile',
  'What do we know about this user\'s preferences and background?'
);

console.log(`Creating mental model (operation: ${result.operation_id})`);

curl -X POST https://api.hindsight.vectorize.io/v1/default/banks/my-assistant/mental-models \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "User Profile",
    "source_query": "What do we know about this user'\''s preferences and background?"
  }'

带选项创建

你可以指定标签、Token 限制和自动刷新行为：

Python
TypeScript
cURL

result = client.create_mental_model(
    bank_id="my-assistant",
    name="Team Directory",
    source_query="Who works here and what do they do?",
    tags=["team", "directory"],
    max_tokens=4096,
    trigger={"refresh_after_consolidation": True}
)

const result = await client.createMentalModel(
  'my-assistant',
  'Team Directory',
  'Who works here and what do they do?',
  {
    tags: ['team', 'directory'],
    maxTokens: 4096,
    trigger: { refreshAfterConsolidation: true }
  }
);

curl -X POST https://api.hindsight.vectorize.io/v1/default/banks/my-assistant/mental-models \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Team Directory",
    "source_query": "Who works here and what do they do?",
    "tags": ["team", "directory"],
    "max_tokens": 4096,
    "trigger": {
      "refresh_after_consolidation": true
    }
  }'

创建参数

参数	类型	必填	说明
`name`	string	是	心智模型的人类可读名称
`source_query`	string	是	通过 Reflect 运行以生成内容的查询
`tags`	string[]	否	用于过滤和组织的标签
`max_tokens`	integer	否	生成内容的最大 Token 数（默认：2048，范围：256–8192）
`trigger`	object	否	自动刷新设置
`trigger.refresh_after_consolidation`	boolean	否	记忆整合后重新生成（默认：false）

创建响应

{
  "operation_id": "op_abc123"
}

operation_id 可用于追踪创建进度。后台 Reflect 操作完成后模型即可用。

列出心智模型

Python
TypeScript
cURL

# List all mental models
models = client.list_mental_models(bank_id="my-assistant")

for model in models.items:
    print(f"{model.name}: {model.content[:100]}...")

# Filter by tags
models = client.list_mental_models(bank_id="my-assistant", tags=["team"])

// List all mental models
const models = await client.listMentalModels('my-assistant');

models.items.forEach(model => {
  console.log(`${model.name}: ${model.content?.substring(0, 100)}...`);
});

// Filter by tags
const filtered = await client.listMentalModels('my-assistant', {
  tags: ['team']
});

# List all mental models
curl -X GET https://api.hindsight.vectorize.io/v1/default/banks/my-assistant/mental-models \
  -H "Authorization: Bearer your-api-key"

# Filter by tags
curl -X GET "https://api.hindsight.vectorize.io/v1/default/banks/my-assistant/mental-models?tags=team" \
  -H "Authorization: Bearer your-api-key"

列表响应

{
  "items": [
    {
      "id": "mm_abc123",
      "bank_id": "my-assistant",
      "name": "User Profile",
      "source_query": "What do we know about this user?",
      "content": "The user is a software engineer who prefers dark mode...",
      "tags": [],
      "max_tokens": 2048,
      "trigger": {
        "refresh_after_consolidation": false
      },
      "last_refreshed_at": "2024-03-15T10:30:00Z",
      "created_at": "2024-03-15T10:30:00Z"
    }
  ]
}

获取心智模型

Python
TypeScript
cURL

model = client.get_mental_model(
    bank_id="my-assistant",
    mental_model_id="mm_abc123"
)

print(f"Name: {model.name}")
print(f"Content: {model.content}")
print(f"Last refreshed: {model.last_refreshed_at}")

const model = await client.getMentalModel('my-assistant', 'mm_abc123');

console.log(`Name: ${model.name}`);
console.log(`Content: ${model.content}`);
console.log(`Last refreshed: ${model.last_refreshed_at}`);

curl -X GET https://api.hindsight.vectorize.io/v1/default/banks/my-assistant/mental-models/mm_abc123 \
  -H "Authorization: Bearer your-api-key"

心智模型响应

字段	说明
`id`	心智模型的唯一标识
`bank_id`	此模型所属的记忆库
`name`	人类可读名称
`source_query`	用于生成内容的 Reflect 查询
`content`	生成的内容（从记忆中综合而来）
`tags`	用于过滤的标签
`max_tokens`	内容的最大 Token 限制
`trigger`	自动刷新设置
`last_refreshed_at`	模型最近一次刷新时间
`created_at`	模型创建时间
`reflect_response`	包含 `based_on` 来源的完整 Reflect 响应

刷新心智模型

刷新会通过 Reflect 重新运行来源查询，以最新记忆更新内容。这是异步操作。

Python
TypeScript
cURL

# Manually refresh a mental model
result = client.refresh_mental_model(
    bank_id="my-assistant",
    mental_model_id="mm_abc123"
)

print(f"Refresh operation: {result.operation_id}")

// Manually refresh a mental model
const result = await client.refreshMentalModel('my-assistant', 'mm_abc123');

console.log(`Refresh operation: ${result.operation_id}`);

curl -X POST https://api.hindsight.vectorize.io/v1/default/banks/my-assistant/mental-models/mm_abc123/refresh \
  -H "Authorization: Bearer your-api-key"

自动刷新

启用 trigger.refresh_after_consolidation 后，心智模型会在 Retain 操作将新记忆整合为观察之后自动刷新。这无需人工干预即可让模型的缓存反思保持最新。

由于刷新是异步进行的，自动刷新的心智模型是 最终一致的——在新记忆整合和模型内容更新之间可能会有短暂延迟。

何时启用自动刷新：

需要随频繁变化的数据保持同步的模型（例如用户偏好、状态报告）
经常接收记忆更新的记忆库

何时保留手动刷新：

用于汇总稳定信息的模型（例如政策文档、入职指南）
当你希望精确控制更新时机
为不需要频繁更新的模型最小化 Token 使用

手动刷新

无论是否启用自动刷新，你都可以按需通过调用刷新端点来刷新任意心智模型。当你知道记忆库内容发生变化且希望立即更新模型，而不是等待下次整合周期时，这非常有用。

更新心智模型

更新模型的名称、来源查询、标签、Token 限制或触发设置：

Python
TypeScript
cURL

model = client.update_mental_model(
    bank_id="my-assistant",
    mental_model_id="mm_abc123",
    name="Updated Profile",
    source_query="What are the user's key preferences?",
    trigger={"refresh_after_consolidation": True}
)

const model = await client.updateMentalModel('my-assistant', 'mm_abc123', {
  name: 'Updated Profile',
  sourceQuery: 'What are the user\'s key preferences?',
  trigger: { refreshAfterConsolidation: true }
});

curl -X PATCH https://api.hindsight.vectorize.io/v1/default/banks/my-assistant/mental-models/mm_abc123 \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Profile",
    "source_query": "What are the user'\''s key preferences?",
    "trigger": {
      "refresh_after_consolidation": true
    }
  }'

备注

更新 source_query 不会自动重新生成内容。在更新来源查询之后，请调用 refresh 来用新查询重新生成内容。

删除心智模型

Python
TypeScript
cURL

client.delete_mental_model(
    bank_id="my-assistant",
    mental_model_id="mm_abc123"
)

await client.deleteMentalModel('my-assistant', 'mm_abc123');

curl -X DELETE https://api.hindsight.vectorize.io/v1/default/banks/my-assistant/mental-models/mm_abc123 \
  -H "Authorization: Bearer your-api-key"

心智模型如何与 Reflect 协作

当你调用 Reflect 时，系统会自动：

根据查询检索相关心智模型
将其作为高优先级上下文注入，与检索到的记忆并列
综合答案，同时从心智模型和原始记忆中提取信息

这意味着心智模型作为一层预先计算的知识，提升 Reflect 的质量和一致性。Reflect 响应包含一个 mental_models 字段，显示使用了哪些模型：

{
  "text": "Based on the stored memories...",
  "based_on": [],
  "mental_models": [
    {
      "id": "mm_abc123",
      "text": "The user is a software engineer who prefers..."
    }
  ]
}

最佳实践

来源查询设计

撰写清晰、具体的来源查询，针对你想要综合的信息：

推荐
效果较差

"What are the user's communication preferences, including preferred channels, response times, and meeting styles?"

"Tell me about the user"

命名约定

使用能清楚表明模型内容的描述性名称：

"Customer Support FAQ" 代替 "FAQ"
"Q2 Project Status" 代替 "Status"
"Engineering Team Directory" 代替 "Team"

使用标签组织

使用标签对模型分类以便检索：

# Create related models with shared tags
client.create_mental_model(
    bank_id="my-assistant",
    name="Team Skills Matrix",
    source_query="What skills does each team member have?",
    tags=["team", "skills"]
)

client.create_mental_model(
    bank_id="my-assistant",
    name="Team Availability",
    source_query="What are the team members' schedules and availability?",
    tags=["team", "scheduling"]
)

# Retrieve all team-related models
team_models = client.list_mental_models(bank_id="my-assistant", tags=["team"])

在界面中使用

记忆库中的 Mental Models 视图提供了一个可视化界面：

进入你的记忆库
在侧边栏点击 Mental Models
点击 Create 添加新的心智模型
查看、编辑、刷新或删除已有模型
按模型切换自动刷新

强制 RBAC：组织成员仅具有只读访问权限，而管理员可以创建、编辑和删除。

错误处理

Python
TypeScript

try:
    model = client.get_mental_model(
        bank_id="my-assistant",
        mental_model_id="mm_abc123"
    )
    print(model.content)
except Exception as e:
    print(f"Error: {e}")

try {
  const model = await client.getMentalModel('my-assistant', 'mm_abc123');
  console.log(model.content);
} catch (error) {
  console.error('Error:', error.message);
}

常见错误

错误	原因	解决方法
401 Unauthorized	API 密钥无效	检查 API 密钥
402 Payment Required	额度不足	为账户添加额度
404 Not Found	bank_id 或 mental_model_id 无效	确认记忆库和模型存在
400 Bad Request	缺少必填字段	提供 `name` 和 `source_query`

Token 使用

心智模型操作会消耗 Token 并相应计费：

操作	说明
获取模型	返回缓存内容的轻量查找
刷新模型	运行 Reflect 重新生成内容

创建心智模型与刷新使用相同的 Token 成本，因为创建会在内部运行一次 Reflect 查询。

每项操作的当前定价可在应用内查看。在使用分析页面监控心智模型的 Token 使用情况。

概述​

使用场景​

创建心智模型​

带选项创建​

创建参数​

创建响应​

列出心智模型​

列表响应​

获取心智模型​

心智模型响应​

刷新心智模型​

自动刷新​

手动刷新​

更新心智模型​

删除心智模型​

心智模型如何与 Reflect 协作​

最佳实践​

来源查询设计​

命名约定​

使用标签组织​

在界面中使用​

错误处理​

常见错误​

Token 使用​

概述