Korely Memory

Korely Memory

为了解哪些信息仍然有效的 AI Agent 提供记忆。

Korely 会将 Agent 学到的内容存储为带有效期的类型化事实。当信息发生变化时，旧事实会被取代，而不是被覆盖。Agent 可以读取当前事实，你也可以查询过去任意日期的事实。

import time
from korely_memory import Korely

korely = Korely()  # reads KORELY_API_KEY from the environment

korely.add("Maria is on the Pro plan, billed yearly.", user_id="maria")
korely.add("Maria downgraded to Free.", user_id="maria")

time.sleep(10)  # facts are extracted server-side; see "Writes settle asynchronously"

ctx = korely.get_context(query="what plan is Maria on?", user_id="maria")
print(ctx.context)
# ## Known facts
# - Maria downgraded_to Free (since 2026-09-08)
# - Maria billing_frequency yearly (since 2026-09-08)
#
# Pro is gone from the current facts. It was superseded, not deleted.

具体谓词由提取器选择，因此这里的 downgraded_to 在你的运行中可能是 subscribes_to 或 plan。可以确定的是其行为：旧值会从当前集合中移除， 并保留为可检索状态，同时带有 invalid_at。

没有任何内容被删除。Pro 事实仍然存在，带有 invalid_at 以及指向取代它的事实的指针：

korely.get_facts(user_id="maria", include_invalidated=True)
# Maria downgraded_to Free    valid_from=... invalid_at=None
# Maria plan Pro              valid_from=... invalid_at=2026-09-08T08:31:09Z

穿越真实日期的时间

如果事件发生在过去，请传入 timestamp，事实会将其继承为 valid_from。这样，as_of 查询的是世界的时间线，而不是你的写入 顺序：

korely.add("Franco signed up on the Pro plan.", user_id="franco", timestamp="2026-01-15")
korely.add("Franco downgraded to Free.",        user_id="franco", timestamp="2026-06-20")

korely.get_facts(user_id="franco", as_of="2026-03-01")   # subscribes_to -> Pro plan
korely.get_facts(user_id="franco", as_of="2026-08-01")   # subscribes_to -> Free
korely.get_facts(user_id="franco")                       # subscribes_to -> Free

如果没有 timestamp，每条事实都会从写入时起生效，因此对更早日期使用 as_of 会返回空结果。这是正确的行为，但在导入历史记录时通常不是你 想要的结果。

as_of 会根据存储库当前掌握的信息，回答某个日期哪些事实为真。 known_as_of（Korely Agent 0.1.26）回答的是另一个问题：存储库在该日期 知道什么。如果变更信息延迟告知，两者就会不同。Agent 在 10 月 5 日得知 客户于 9 月 1 日搬家：

korely.get_facts(user_id="maria", as_of="2026-09-20")        # lives_in -> Turin
korely.get_facts(user_id="maria", known_as_of="2026-09-20")  # lives_in -> Milan

到 9 月 20 日时，搬家已经发生，但存储库当时还不知道。 known_as_of 可用于 get_facts、get_profile 和 get_context，后者会 重建存储库当时能够构建的区块：也就是 Agent 做出决策时可能知道的信息。 每条事实都会携带 closed_known_at，表示存储库得知该事实已失效的时间。

写入后异步处理

add() 会在记忆存储完成后立即返回，随后由服务端运行提取。因此：

调用	可用时间
对原始记忆调用 search()	立即
get_facts() 和 get_context() 返回类型化事实	几秒后

上面的 time.sleep(10) 只是为了让你粘贴代码片段后能够正常运行。生产环境中不需要它：Agent 在一轮结束时写入，并在下一轮开始时读取；到那时，事实就已经就绪。

如果确实需要准确知道何时处理完成，请查询，而不要猜测。每条记忆都有一个值为 processing、ready 或 error 的 status，而 events() 会报告仍在处理中 的内容：

page = korely.events()
page.processing  # 0
page.events[0]   # MemoryEvent(memory_id='mem_...', status='ready', ...)

processing == 0 表示项目中没有仍在提取的写入（如果传入 user_id，则仅限该范围内），无论写入数量多少；因此脚本只需等待这一个数字，无须遍历每个 ID。执行 batch() 导入后，请先等待 batch_status() 完成：作业尚未存储的记忆不会被计入。

轮询是唯一的信号：提取完成时不会触发 webhook。Webhook 事件包括 memory.created、fact.invalidated 和 quota.warning。

安装

pip install korely-memory      # Python, plus the `korely` CLI
npm install korely-memory      # Node / TypeScript

两个客户端都没有运行时依赖。

对于 LangGraph，可选的 pip install 'korely-memory[langgraph]' 会添加一个存储、一组记忆工具和一个上下文辅助函数：请参阅 python/README.md。

获取密钥

业余版免费使用，无需填写注册表单：

curl -X POST https://api.korely.ai/v1/agents/init \
  -H 'Content-Type: application/json' \
  -d '{"agent_caller": "your-name-here"}'

响应中包含一个 kor_live_ 密钥。将其设为 KORELY_API_KEY，SDK、CLI 和 REST API 都会使用它进行身份验证。在代码中，Korely.init_agent()（Python）和 Korely.initAgent()（JS）会执行相同的调用。

该密钥对应的账户没有登录功能：密钥就是账户。请妥善保管，因为它也是删除账户的唯一方式（korely delete-account --yes，或 SDK 中的 delete_account(confirm=True)）。

也可以让 CLI 为你完成这些操作。korely init 会将密钥保存到 ~/.korely/config.json；如果未设置 KORELY_API_KEY，SDK 会从该文件读取密钥，因此只需执行以下操作即可开始使用：

pip install korely-memory
korely init --agent --agent-caller your-name
python -c "from korely_memory import Korely; print(Korely().get_context(query='hi').tokens)"

TypeScript

import { Korely } from "korely-memory";

const korely = new Korely();

await korely.add("Maria downgraded to Free.", { user_id: "maria" });
const ctx = await korely.getContext({ query: "what plan is Maria on?", user_id: "maria" });

使用 Vercel AI SDK 时，只需一行代码：withKorelyMemory(model, { userId })（来自 korely-memory/ai-sdk）即可为任意模型添加此记忆：请参阅 js/README.md。

CLI

korely add "Maria downgraded to Free." --user-id maria
korely context "what plan is Maria on?" --user-id maria
korely facts --as-of 2026-03-01 --user-id maria
korely audit --user-id maria --all --json > maria.json   # everything that touched Maria

所有命令均列于 python/README.md。

Korely 的功能

• 类型化事实。 主语、谓语、宾语均由服务端提取。你无需进行提示词工程。
• 双时态有效性。 每条事实都带有 valid_from 和 invalid_at，因此存储会区分某件事的实际发生时间与记录时间。
• 矛盾处理。 与旧事实冲突的新事实会取代旧事实，并记录被替代的是哪条事实。不会悄无声息地丢弃任何内容。
• 时间点查询。 as_of 可查询过去任意日期哪些内容为真，而 known_as_of 可查询存储在该日期已知的内容。
• 实体图谱。 实体和关系会自动提取，并在所有套餐（包括免费套餐）中提供。
• 语义检索。 记忆和事实按含义（向量相似度）排序；事实也会根据记忆最近一次确认它们的时间排序。
• 可直接用于提示词的上下文。 get_context() 会返回一段可直接粘贴到系统提示词中的内容，并附带令牌数量。
• 由欧盟托管。 服务运行在赫尔辛基。最终用户可以查看、更正和删除 Agent 对他们的记忆。

Async

生产环境中的 Agent 不会一次只发起一个调用。AsyncKorely 与 Korely 的每个方法一一对应，因此你学到的用法都能直接沿用：

import asyncio
from korely_memory import AsyncKorely

async def main():
    korely = AsyncKorely()
    contexts = await asyncio.gather(
        korely.get_context(query="what plan?", user_id="a"),
        korely.get_context(query="what plan?", user_id="b"),
        korely.get_context(query="what plan?", user_id="c"),
    )

asyncio.run(main())

对在线 API 发起 6 次调用：顺序执行需 5.6 秒，并发执行需 1.7 秒。

调用通过线程池运行，而非异步 HTTP 库，因为保持此软件包零运行时依赖比榨取最后一点效率更重要。事件循环不会被阻塞，请求也确实会重叠执行。

示例

examples/audit_trail.py 回答了这个存储存在的意义：你的 Agent 在作答当天知道什么？

客服 Agent 在 3 月告诉客户，他们享有优先支持。6 月，客户转为更便宜的套餐。9 月，他们引用你的机器人说过的话向你投诉。机器人当时是错的，还是当时是对的？

  What the store believed in March, when the agent answered:
      customer-4821 · subscribes_to · Business plan
      Business plan · includes · priority support

  What is true today:
      customer-4821 · subscribes_to · Standard plan
      customer-4821 · lacks · priority support

它在 3 月是对的，如今也是对的，而且两者都有据可证。大约 20 秒即可亲自运行：

pip install korely-memory
korely init --agent --agent-caller audit-example
python examples/audit_trail.py

它会核查自己的说法，而不是只作出断言，也包括数据删除。

仓库结构

路径	软件包
python/	PyPI 上的 korely-memory，包含 korely CLI 和 MCP stdio 服务
js/	npm 上的 korely-memory
n8n/	n8n-nodes-korely，适用于可自托管 n8n 的社区节点（请参阅其 README）

编码助手

在仓库中运行 korely init --tool claude-code（或 codex、cursor），即可将该助手连接到每个仓库独有的记忆：会话开始时，助手会获取记忆；会话内容也会保存到记忆中。你连接的所有助手共享这份记忆。请参阅 Python README。

MCP

Korely 运行托管式 MCP 服务，因此编码 Agent 无需任何软件包即可读取和写入记忆：

claude mcp add --transport http korely https://api.korely.ai/agent/mcp \
  --header "Authorization: Bearer kor_live_..."

文档

完整的 REST 契约、概念和集成指南：korely.ai/agents/docs

许可证

MIT。这些客户端是开源的；它们连接的托管服务则不是。