用途
Engram 是 Weaviate 提供的托管记忆服务器（managed memory server），用于为 LLM 智能体和聊天机器人添加持久化的长期记忆。当应用需要跨会话记住信息时，可使用本技能。资料明确指出：当 Engram 适用时，不要自行手写记忆系统（例如使用原始 Weaviate 集合并手动插入），因为 Engram 开箱即用地处理提取、去重和整合。
主要能力
- 自动从原始文本或对话中提取、整合并存储记忆。
- 通过向量（vector）、关键词（BM25）、混合（hybrid）以及无排序抓取（unranked fetch）等方式检索记忆。
- 支持主题（topics）、分组（groups）、作用域（scopes）、管道/运行（pipelines/runs）等概念。
- 支持字符串、对话和预提取输入三种存储方式；提供异步运行状态和 committed_operations。
- 支持按 id 获取和删除记忆，进行确定性清理。
- 提供记忆驱动的聊天机器人和将 Engram 作为工具供 RouterAgent 使用的集成模式。
- 提供 Claude Code 插件，无需应用代码即可使用。
- 为非 Python 技术栈提供等价的 REST API 端点。
使用方式
Engram 通过 Weaviate Cloud 访问。若用户没有 Engram 项目，需引导其前往云控制台创建项目并生成 Engram API 密钥。
环境变量：
- 必需：ENGRAM_API_KEY —— 来自 Weaviate Cloud 的 Engram API 密钥（格式为 eng_...）。它携带项目身份；Engram 本身不需要 WEAVIATE_URL / WEAVIATE_API_KEY。
- 可选（仅在将 Engram 与智能体或聊天机器人结合用于生成时）：LLM 提供商的 API 密钥（如 OPENAI_API_KEY、ANTHROPIC_API_KEY、GEMINI_API_KEY）。
安装：Engram 作为独立的 Python SDK 发布，名为 weaviate-engram，不随 weaviate-client 提供。安装命令：
uv add weaviate-engram # 或：pip install weaviate-engram
导入时使用 engram。本技能面向 weaviate-engram 1.0.x（当前版本 1.0.1；要求 Python 3.11–3.14）。1.0 是首个稳定 API，若项目使用 0.x 版本应升级。
Engram 还提供 Claude Code 插件，无需应用代码：/plugin marketplace add weaviate/engram-plugins 然后 /plugin install engram@weaviate-engram。在构建自定义集成前，请先查看参考文档中的 Off-the-shelf Integrations 部分。
快速开始（指南默认使用异步客户端，最小化的存储与搜索示例）：
import os from engram import AsyncEngramClient, HybridRetrieval
client = AsyncEngramClient(api_key=os.environ["ENGRAM_API_KEY"])
存储 —— 即发即忘，异步处理
run = await client.memories.add( "The user prefers dark mode and works primarily in Python.", user_id="alice", )
搜索
results = await client.memories.search( query="What language does the user prefer?", user_id="alice", retrieval_config=HybridRetrieval(limit=5), )
await client.aclose() # 或使用 async with AsyncEngramClient(...) as client:
在构建前，请遵循参考指南了解完整生命周期、错误处理和集成模式。
适用场景
- 需要跨会话记住用户信息的聊天机器人和 LLM 智能体。
- 需要自动提取、去重和整合记忆，而非手动维护记忆存储的应用。
- 需要向量、关键词或混合检索记忆的 Python 应用；非 Python 技术栈可通过 REST API 使用。
- 希望以最少代码接入记忆能力的 Claude Code 用户（通过插件）。
限制与注意事项
- Engram 是托管服务，必须通过 Weaviate Cloud 创建项目并获取 API 密钥。
- 存储是异步的：add 之后立即搜索可能返回空结果，需先 await client.runs.wait(run.run_id)，或检查运行状态是否为 failed。用户首次写入时，即使运行报告已完成，租户可能仍在初始化，需短暂重试搜索。
- 常见错误：ENGRAM_API_KEY 未设置时需设置环境变量，并确保是 Engram 密钥（eng_...）而非 Weaviate 集群密钥。
- 搜索时出现 APIError（422，user "..." not found）表示该 user_id 从未添加过任何内容；应捕获并视为“无记忆”（每个聊天机器人新用户的第一条消息都会遇到）。
- AuthenticationError 是 APIError 的子类；在搜索周围使用裸 except APIError 会静默地把错误的 API 密钥变成“无记忆”。应先捕获 AuthenticationError 并重新抛出。
- 本技能面向 weaviate-engram 1.0.x，要求 Python 3.11–3.14。
- 关于收费、价格、平台支持范围等具体信息，资料中暂未提供。