Skip to content

usage.md

Latest commit

 

History

History
151 lines (107 loc) · 4.81 KB

usage.md

File metadata and controls

151 lines (107 loc) · 4.81 KB
Raw

TiMEM CLI 使用说明

面向人类用户的 timem（timem-cli）说明书。
参数级细节请以 timem <command> --help 为准。
Agent 行为见 skills/timem-memory/SKILL.md（含 references/）。
English: usage.en.md

能做什么

  • 在终端读写 TiMEM 云端记忆
  • 可选安装捆绑 Skill，让编程 Agent 通过 shell 调用 timem
  • 经 timem-ai SDK 访问云端（不自建 HTTP 客户端层）

本 MVP 不含：timem kb（知识库 / RAG）、timem rules（经验学习）——仅占位。

安装

pip install timem-cli
# 或从仓库本地安装：
python -m pip install -e ".[dev]"

需要 Python >= 3.9。入口：timem 或 python -m timem_cli。

首次配置

timem init --api-key <你的_API_KEY>
timem doctor
  • API Key 必填（命令行参数，或已有配置 / 环境变量 TIMEM_API_KEY）。
  • user_id 可选。未指定且配置中也没有时，会写入 cli；已有存储值时再次 init 不会覆盖。
  • 可选安装 Agent Skill：
timem init --api-key <你的_API_KEY> --agent cursor
# 支持：cursor、claude、codex、opencode、trae、trae-cn 等
timem uninstall --agent cursor -y

配置文件：~/.timem/config.yaml。

配置优先级

生效值按以下顺序解析：

  1. 命令行参数（如全局 --api-key / --base-url，或命令上的 --user-id）
  2. 环境变量：TIMEM_API_KEY、TIMEM_BASE_URL、TIMEM_USER_ID、TIMEM_CHARACTER_ID、TIMEM_SESSION_ID
  3. ~/.timem/config.yaml
  4. 内置默认：user_id=cli，character_id=default，base_url=https://api.timem.cloud
timem config show
timem config get defaults.user_id
timem config set defaults.character_id coder

config set 只改配置文件（不会把当前环境变量写进磁盘）。
config show 默认遮罩 API Key；需要明文时加 --reveal。

session_id

用于按「当前项目」隔离记忆（建议在仓库根目录附近执行命令）。

优先级：

  1. --session <id>
  2. 否则配置中的 defaults.session_id / TIMEM_SESSION_ID
  3. 否则 git 仓库根目录名
  4. 否则当前目录的 timem-cwd-<8 位哈希>

timem search 默认带上该 session。需要跨项目检索时加 --global。

记忆命令

写入 add

timem add "一条事实或决策"
timem add -m "同样内容，用参数传入"
timem add --messages '[{"role":"user","content":"..."},{"role":"assistant","content":"..."}]'
timem add --no-wait -m "异步备注"    # 很快返回 task_id
timem status <task_id>               # 查询异步生成状态

默认 add 会等待生成完成（走 SDK）。
--character 可覆盖 character_id / expert（默认 default）。

检索 search

timem search "查询内容"
timem search -q "查询内容" --limit 5 --layer L1
timem search "查询内容" --global          # 不按 session 过滤
timem search "查询内容" --format json

使用 SDK 默认 enhanced_semantic（BM25 + 向量混合检索）。
CLI 不会传 domain。

查看 / 删除

timem get <memory_id>
timem delete <memory_id> -y            # 必须加 --yes / -y

自检 doctor

timem doctor

检查配置（或 env/flags）、user_id（缺省回退 cli），以及 /health。

输出格式

多数命令支持 --format text|json。脚本解析请用 json。

给 Agent 用

  1. 安装一次：timem init --api-key <key> --agent <名称>
  2. 让 Agent 在项目目录下执行命令，以便正确解析 session_id
  3. Skill 策略：若已配置 TiMEM MCP，优先用 MCP；否则 shell timem。不要让 MCP 去调 CLI。

环境变量

变量 含义
TIMEM_API_KEY API Key
TIMEM_BASE_URL API 地址（默认 https://api.timem.cloud）
TIMEM_USER_ID 覆盖默认 / 配置中的 user_id
TIMEM_CHARACTER_ID 覆盖 character / expert
TIMEM_SESSION_ID 强制 session（跳过 git/cwd 自动解析）

常见问题

现象 排查
Invalid API key 确认 Console 中的 Key；timem config show；环境变量是否覆盖了过期 Key
user_id 不是预期值 TIMEM_USER_ID 会覆盖文件配置——删掉该环境变量，或 config set defaults.user_id …
搜不到刚写入的内容 user_id、session 是否一致？可试 --global 或相同的 --session
doctor health 正常但写入失败 health 未必完整校验 Key——用一次 add 验证

相关链接