安装与接入：login、enable、hooks / AGENTS.md

你将得到什么

• 本机可用的 memorable CLI（npx 即用，或全局安装短命令）
• 一次成功的 login + enable：本机已签到工作区，且写入同意为 read-write
• 按你用的 harness：Claude Code 装上 prompt hook，或 Cursor / 其它 写入 AGENTS.md 说明

开始前准备

1. 终端可访问外网（拉 npm / Memorable Extraction API）。
2. 本机有 Node.js + npm/npx；若完全没有 Node，官方提供安装脚本（见下）。
3. 准备在浏览器打开 Memorable 登录页并点 Approve；若 Agent 环境无法开浏览器，改从 memorable.sh/dash 取密钥，用 login --paste。
4. 至少一个 coding agent：Claude Code、Codex、Cursor、Devin、Antigravity 等（本课以 Claude Code 与 Cursor 为主路径）。

核心事实（先记住）

步骤 1：拿到 CLI

官方 Docs Quickstart：可先直接用 npx（首次会拉包）：

npx memorable-cli@latest

对照结果：终端出现 Memorable 状态卡（backend / consent / extraction / stored）以及 setup / memory / upkeep / inspect / integrate 命令分组。无交互终端时，它会打印一套可手敲的 setup 命令。

可选：把短命令装到 PATH：

npm install -g memorable-cli
memorable --version

对照结果：能打印版本号（本课核对时为 0.5.x 一类；以你机器当前版为准）。之后命令都可写成 memorable …，也可用 npx memorable-cli@latest <command>。

无 npm 时（官方 CLI 页）：

curl -fsSL https://memorable.sh/install.sh | sh

对照结果：安装到 ~/.memorable 与 ~/.local/bin/memorable（官方称不碰其它路径）。跑前建议先打开 https://memorable.sh/install.sh 阅读脚本。

步骤 2：登录本机（link workspace）

官方两条等价路径：

路径 A — 本机终端 + 浏览器（推荐人机跟做）

npx memorable-cli@latest login

对照结果：打印 verification URL 与短码，浏览器打开后点 Approve；结束后本地保存密钥（官方：~/.memorable/config.json），status 里 extraction api 应变为 configured。

路径 B — Agent 环境无法开浏览器（官方 CLI「Inside an agent」）

1. 人在 memorable.sh/dash → Environments → Connect，或 Account → New key for an agent，复制以 mk_ 开头的密钥。
2. Agent / 你执行（不要把密钥打进聊天记录长期保存）：

echo 'mk_YOUR_KEY_HERE' | memorable login --paste

对照结果：提示 connected / 密钥已保存；再跑：

memorable status

对照结果（成功时大致应有）：

• extraction api → configured
• backend → local（默认；或你已 init gbrain）
• write consent 可能仍是 unset（下一步才 enable）

官方强调：裸 login 会等浏览器；在 Agent shell 工具里会超时。Agent 场景一律 --paste。

步骤 3：显式打开写入同意

官方：consent 是 fail-closed；unset = deny。未 enable 前既不落盘也不送 extraction。

memorable enable

对照结果：出现 write consent 变为 read-write（本机 local store）。再确认：

memorable status

对照结果：应看到类似 capture on · recall on（措辞随版本略有差异），write consent = read-write。

相关命令（本课先记住，第 2 课会用）：

步骤 4：接到你的 harness

A. Claude Code（官方 install-hooks）

memorable install-hooks

对照结果：提示 Claude Code 的 UserPromptSubmit hook 已安装；之后新开的 Claude Code 会话，新 prompt 会自动做 recall 检查，命中则注入短的 guarded pointer（官方：每会话一次注入；失败静默，不打断 prompt）。

若当前会话在装 hook 之前已打开，官方建议：先结束会话再开新会话，再做真实任务。

可选一键（登录后）：官方也提供交互式

memorable start

或

npx memorable-cli

会询问你用的 agent、是否为项目建 Environments 页，并代写 hooks / consent。

B. Cursor / Codex / 其它（官方 agents-md / setup）

官方：Cursor 等走 AGENTS.md 说明，而不是 Claude Code 那套 hook。

一键（登录后）：

memorable setup

对照结果：完成 enable（若尚未）并写入项目侧 agent 说明。

或只追加说明文件：

memorable agents-md >> AGENTS.md

对照结果：AGENTS.md 末尾出现「Using Memorable (procedural memory)」整段指令（含 recall / show / ingest / consent）。之后在 Cursor 里对 Agent 说「use memorable」即可按 CLI 跟做。

Codex 本地仅捕获轨迹（官方 README，可不登录）：

npm install -g memorable-cli
memorable install-hooks codex

对照结果：重启 Codex，在 /hooks 审批新 hook；轨迹写入 ~/.memorable/traces/<session-id>/<turn-id>.json（此时仍未变成 procedure，需后续 ingest / enable + extraction）。禁用捕获可不卸 hook：启动前设 MEMORABLE=0。

步骤 5：本课验收

memorable status
memorable doctor

对照结果：

• status：extraction configured，consent read-write（若你已 enable）
• doctor：api credentials 通过；store 行显示 local / consent / procedure 数。若语义召回未配好，doctor 会如实标出（官方：不只看 HTTP 200，要确认真有向量）

常见问题（官方要点）

1. 没 enable 就 ingest？ 会拒绝写入；consent 错误是设计行为，不要绕过。
2. 密钥进了聊天？ 到 dashboard 轮换/作废旧 key，重新 login --paste。
3. 只要本机库、不要云？ 默认 procedure 在本机；extraction 仍是一次 HTTPS。完全自建库可用 memorable init gbrain / memorable init qm（需另装 gbrain / QM，本课不强制）。
4. 想先只读？ memorable disable：仍可 recall，不再录入。

本课检查清单

• npx memorable-cli@latest 或全局 memorable 可用
• login（或 login --paste）成功，status 显示 extraction configured
• memorable enable 后 consent 为 read-write
• Claude Code：install-hooks 完成；或 Cursor：agents-md / setup 完成
• memorable doctor 已跑过，知道当前缺口

完成后进入第 2 课：写入第一条 procedure，并跑通 recall / show / chain。