World Machine

Quickstart

五分钟,给你的 Agent 装上长期记忆

无需手写 HTTP 请求,也不需要手工配置环境变量。按下面几步装好 world CLI 与 Agent Skill,就能直接在终端和 AI 助手里体验完整记忆闭环。

前置条件:控制台账号 · Go 1.27+预计耗时:5 分钟
本页目录(7 节)

准备工作

开始前,你需要一个 World Machine 开发者控制台 账号(目前支持受邀注册;如需邀请码请联系我们开通)。

最快方法:直接让你的 AI 编程助手帮你装。如果你正在使用 Claude Code、Cursor、Trae 或 Antigravity,直接把下面这句话发给它,它会自动读取 cli-guide.md 并一步步带你装好:
发给 AI 助手
帮我安装 World CLI:https://worldmachine.dev/cli-guide.md

如果你想自己动手在终端走一遍,请继续往下看。

STEP 1安装 CLI 与 Agent Skill

在终端安装官方 world 命令行与配套 world-machine Skill:

Shell
# 1. 安装 world 命令行工具(需要 Go 1.27+)
go install github.com/bootun/world-cli/cmd/world@latest
world --version

# 2. 安装配套 Agent Skill(推荐,需要 Node.js 提供 npx)
npx -y skills add bootun/world-cli --skill world-machine -y
装好 Skill 之后,你的 AI 编程助手会自动知道:什么时候该记住用户说过的偏好或事实,什么时候该在回答前先召回上下文,以及如何避免把密钥泄漏到对话或代码库里。

STEP 2浏览器一键授权

运行登录命令,终端会自动打开浏览器前往控制台授权页。点击「授权并连接 CLI」,控制台会自动为你签发一把 CLI 专用密钥并回传到本机配置(~/.config/world/config.json),无需手动复制粘贴:

Shell
# 打开浏览器前往控制台一键完成授权
world auth login

# 若在远程 SSH / 无浏览器环境,使用 --no-browser 复制链接在本地打开
world auth login --no-browser

# 检查服务连通性与密钥有效性
world auth status

确认 world auth status 输出中的 Reachable: true 且 Valid Key: true,就说明连接成功了。之后你也可以随时在控制台的 API 密钥 页面查看用量或撤销这把密钥。

STEP 3记下第一条记忆

直接用日常自然语言记录一条变化,保留「上个月」「昨天」这类原始时间表达即可——world 会自动附带本机时区与幂等保护:

Shell
world remember "我上个月刚从北京搬到上海,现在在 Acme 当架构师。" --source quickstart

命令返回事件 ID 时,原文已经同步落盘并立即可查;后台会在几秒内自动识别其中的人、公司、居住地与各自生效时间。

STEP 4召回结构化状态与原话

稍等几秒,用自然语言向 World Machine 提问:

Shell
world recall "我现在在哪工作?"

终端会同时输出结构化实体(Entities)和逐字留档的原话(Memories):

Terminal Output
Entities (2):
Entity: self (ce7b7b0c-4dbd-5524-9392-13067cf6415c)
Type:   Person
Components:
  - Employment [stated_claim] (conf=1.00): {"organization":"Acme","title":"架构师"} (valid 2026-11-18 12:00:00 CST .. -)
  - Location [stated_claim] (conf=1.00): {"category":"home","city":"上海"} (valid 2026-10-01 00:00:00 CST .. -)

Entity: Acme (ecf5ec2f-ddbe-5453-98ff-5d5635a7911a)
Type:   Organization

Memories (1):
  - [2026-11-18 12:00:00 CST] (0136159b-eb97-54b5-a05d-e37619881c70) 我上个月刚从北京搬到上海,现在在 Acme 当架构师。

观察输出里的三个亮点:

  1. 不同属性各自独立起算时间:居住地从「上个月」对应的月初开始生效,任职状态则从声明时刻起算。
  2. 自动附带可信度标记:通过日常陈述写入的属性默认标注为 [stated_claim](口述声明)。
  3. 原话一字不改:结论和原话在同一次查询中一起返回,随时可以核对。

STEP 5按历史日期回溯

想知道「过去某一天是什么状态」,只需在召回命令上加 --as-of(直接支持 YYYY-MM-DD 等常见日期格式):

Shell
# 回到 2025-10-01 查看当时的状态与记录
world recall "我在哪工作?" --as-of "2025-10-01"

# 供脚本或 Agent 解析时,加上 --json 获取完整结构化输出
world recall "我现在在哪工作?" --json

回看历史不会改动任何当前状态,晚于该日期发生的事件也不会提前漏出。

STEP 6精查单个实体

如果你已经知道某个对象的 entityId(从上面的召回结果里拿到),可以用 world entity get 直接查看它的完整属性与历史快照:

Shell
# 拿到上方输出的 entityId 后,精确查看该实体的全部属性
world entity get ce7b7b0c-4dbd-5524-9392-13067cf6415c

# 同样支持按历史日期查看该实体当时的快照
world entity get ce7b7b0c-4dbd-5524-9392-13067cf6415c --as-of "2026-10-15"