跳到主要内容

cURL 示例

直接使用 cURL 命令访问 Hindsight API 的参考指南。

认证​

所有 API 请求都需要在 Authorization 标头中携带 API 密钥：

-H "Authorization: Bearer your-api-key"

基础 URL​

所有示例均使用以下基础 URL：

https://api.hindsight.vectorize.io

记忆库​

列出记忆库​

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

响应：

{
  "banks": [
    {
      "bank_id": "my-assistant",
      "name": "my-assistant",
      "disposition": {
        "skepticism": 3,
        "literalism": 3,
        "empathy": 3
      },
      "background": "",
      "created_at": "2024-03-15T10:30:00Z",
      "updated_at": "2024-03-15T10:30:00Z"
    }
  ]
}

获取记忆库​

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

Retain（存储记忆）​

基本 Retain​

curl -X POST https://api.hindsight.vectorize.io/v1/default/banks/my-assistant/memories \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "content": "The user prefers dark mode and concise responses."
      }
    ]
  }'

响应：

{
  "success": true,
  "bank_id": "my-assistant",
  "items_count": 1,
  "async": false,
  "operation_id": null,
  "usage": {
    "input_tokens": 2684,
    "output_tokens": 511,
    "total_tokens": 3195
  }
}

多个项​

curl -X POST https://api.hindsight.vectorize.io/v1/default/banks/my-assistant/memories \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "content": "User works in the tech industry"
      },
      {
        "content": "User prefers morning meetings"
      },
      {
        "content": "User is based in San Francisco"
      }
    ]
  }'

携带上下文和时间戳​

curl -X POST https://api.hindsight.vectorize.io/v1/default/banks/my-assistant/memories \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "content": "Customer reported a checkout issue with error code E-1234.",
        "context": "support_ticket",
        "timestamp": "2024-03-15T10:00:00Z"
      }
    ]
  }'

异步处理​

对于较大批次，使用异步模式在后台处理：

curl -X POST https://api.hindsight.vectorize.io/v1/default/banks/my-assistant/memories \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {"content": "First memory"},
      {"content": "Second memory"},
      {"content": "Third memory"}
    ],
    "async": true
  }'

响应中包含用于追踪的操作 ID：

{
  "success": true,
  "bank_id": "my-assistant",
  "items_count": 3,
  "async": true,
  "operation_id": "op_abc123"
}

Recall（搜索记忆）​

基础搜索​

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

响应：

{
  "results": [
    {
      "id": "mem_123abc",
      "text": "User prefers dark mode and concise responses",
      "type": "world",
      "entities": ["user"],
      "context": "",
      "mentioned_at": "2024-03-15T10:30:00Z"
    }
  ],
  "entities": {
    "user": {
      "entity_id": "ent_456",
      "canonical_name": "user",
      "observations": []
    }
  }
}

按类型过滤​

curl -X POST https://api.hindsight.vectorize.io/v1/default/banks/my-assistant/memories/recall \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "user preferences",
    "types": ["observation"]
  }'

携带追踪（调试模式）​

curl -X POST https://api.hindsight.vectorize.io/v1/default/banks/my-assistant/memories/recall \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "project deadlines",
    "trace": true
  }'

携带查询时间戳​

用于诸如 "上周" 或 "三月份" 之类的时间查询：

curl -X POST https://api.hindsight.vectorize.io/v1/default/banks/my-assistant/memories/recall \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What happened last week?",
    "query_timestamp": "2024-03-15T10:00:00"
  }'

Reflect（在记忆之上推理）​

基本提问​

curl -X POST https://api.hindsight.vectorize.io/v1/default/banks/my-assistant/reflect \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What should I know about this customer before our call?"
  }'

响应：

{
  "text": "Based on the stored memories, this customer prefers concise communication and dark mode interfaces...",
  "based_on": [],
  "structured_output": null,
  "usage": {
    "input_tokens": 3352,
    "output_tokens": 806,
    "total_tokens": 4158
  }
}

携带上下文​

curl -X POST https://api.hindsight.vectorize.io/v1/default/banks/my-assistant/reflect \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What are the main concerns?",
    "context": "We are preparing for a quarterly business review meeting"
  }'

携带结构化输出​

在响应中请求特定的 JSON 结构：

curl -X POST https://api.hindsight.vectorize.io/v1/default/banks/my-assistant/reflect \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Summarize the key points about this user",
    "response_schema": {
      "type": "object",
      "properties": {
        "summary": {"type": "string"},
        "key_points": {
          "type": "array",
          "items": {"type": "string"}
        }
      },
      "required": ["summary", "key_points"]
    }
  }'

心智模型​

心智模型是用户精心整理的、基于一次 reflect 查询预计算的反思，会随着记忆变化保持最新。

创建心智模型​

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?"
  }'

响应：

{
  "operation_id": "op_abc123"
}

带选项创建​

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
    }
  }'

列出心智模型​

curl -X GET https://api.hindsight.vectorize.io/v1/default/banks/my-assistant/mental-models \
  -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"
    }
  ]
}

获取心智模型​

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

更新心智模型​

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?"
  }'

刷新心智模型​

重新运行来源查询，用当前的记忆更新内容：

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

响应：

{
  "operation_id": "op_def456"
}

删除心智模型​

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

错误响应​

401 Unauthorized​

{
  "detail": "Invalid or expired API key"
}

404 Not Found​

{
  "detail": "Bank with ID 'invalid-bank' not found"
}

400 Bad Request​

{
  "detail": "Validation error: items is required"
}

402 Payment Required​

{
  "detail": "Insufficient credits to complete this operation"
}

小贴士​

调试模式​

添加 -v 获取详细输出以调试连接问题：

curl -v -X GET https://api.hindsight.vectorize.io/v1/default/banks \
  -H "Authorization: Bearer your-api-key"

使用 jq 美化输出​

curl -s -X POST https://api.hindsight.vectorize.io/v1/default/banks/my-assistant/memories/recall \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"query": "test"}' | jq '.'

将响应保存到文件​

curl -s -X POST https://api.hindsight.vectorize.io/v1/default/banks/my-assistant/memories/recall \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"query": "test"}' > response.json

从文件读取内容​

curl -X POST https://api.hindsight.vectorize.io/v1/default/banks/my-assistant/memories \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d @request.json

其中 request.json 包含：

{
  "items": [
    {"content": "Your content here..."}
  ]
}