Quickstart
五分钟,给你的 Agent 装上长期记忆
无需手写 HTTP 请求,也不需要手工配置环境变量。按下面几步装好 world CLI 与 Agent Skill,就能直接在终端和 AI 助手里体验完整记忆闭环。
准备工作
开始前,你需要一个 World Machine 开发者控制台 账号(目前支持受邀注册;如需邀请码请联系我们开通)。
cli-guide.md 并一步步带你装好:帮我安装 World CLI:https://worldmachine.dev/cli-guide.md
如果你想自己动手在终端走一遍,请继续往下看。
STEP 1安装 CLI 与 Agent Skill
在终端安装官方 world 命令行与配套 world-machine Skill:
# 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
STEP 2浏览器一键授权
运行登录命令,终端会自动打开浏览器前往控制台授权页。点击「授权并连接 CLI」,控制台会自动为你签发一把 CLI 专用密钥并回传到本机配置(~/.config/world/config.json),无需手动复制粘贴:
# 打开浏览器前往控制台一键完成授权 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 会自动附带本机时区与幂等保护:
world remember "我上个月刚从北京搬到上海,现在在 Acme 当架构师。" --source quickstart 命令返回事件 ID 时,原文已经同步落盘并立即可查;后台会在几秒内自动识别其中的人、公司、居住地与各自生效时间。
STEP 4召回结构化状态与原话
稍等几秒,用自然语言向 World Machine 提问:
world recall "我现在在哪工作?" 终端会同时输出结构化实体(Entities)和逐字留档的原话(Memories):
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 当架构师。 观察输出里的三个亮点:
- 不同属性各自独立起算时间:居住地从「上个月」对应的月初开始生效,任职状态则从声明时刻起算。
- 自动附带可信度标记:通过日常陈述写入的属性默认标注为
[stated_claim](口述声明)。 - 原话一字不改:结论和原话在同一次查询中一起返回,随时可以核对。
STEP 5按历史日期回溯
想知道「过去某一天是什么状态」,只需在召回命令上加 --as-of(直接支持 YYYY-MM-DD 等常见日期格式):
# 回到 2025-10-01 查看当时的状态与记录 world recall "我在哪工作?" --as-of "2025-10-01" # 供脚本或 Agent 解析时,加上 --json 获取完整结构化输出 world recall "我现在在哪工作?" --json
回看历史不会改动任何当前状态,晚于该日期发生的事件也不会提前漏出。
STEP 6精查单个实体
如果你已经知道某个对象的 entityId(从上面的召回结果里拿到),可以用 world entity get 直接查看它的完整属性与历史快照:
# 拿到上方输出的 entityId 后,精确查看该实体的全部属性 world entity get ce7b7b0c-4dbd-5524-9392-13067cf6415c # 同样支持按历史日期查看该实体当时的快照 world entity get ce7b7b0c-4dbd-5524-9392-13067cf6415c --as-of "2026-10-15"