跳到主要内容

故障排除

第一步：打开 engram entry 并阅读 Runtime 选项卡。它会显示解析出的配置文件、内存根目录、核心配置、路由、图和 Git 检测状态。

内存未能加载​

  • 运行 engram load --dry-run "<任务>" 来检查候选数量和过滤收窄的标签。
  • 检查 engram config view 中的 enabled、read 和 load.limit 选项。
  • 确认 .agents/.engram/ 目录下存在工作空间内存。
  • 运行 engram verify 来检查哈希值。

钩子未注入​

  • 确认 engram set-read status 不是 off 或 manual。
  • 确认宿主已链接：engram link <目标>。
  • 在 link/unlink 后重启或重新加载宿主（特别是 OpenCode）。
  • 检查 engram set-proof status 以确认证明行的可见性。

保存失败​

  • 阅读审批预览以获取有关关联内存的提示信息。
  • 如果全部接受（accept-all）报告了关联内存，则没有任何文件被保存。请使用 DEPENDS_ON 或 UPDATE 候选方案重新运行。
  • 在 CLI 输出中检查模式、秘密以及提示词注入扫描错误。

配置文件混淆​

  • 运行 engram profile status。
  • 确认工作空间的 default_profile 和当前活跃的用户配置文件。
  • 记住：指定与工作空间默认配置不同的显式配置文件会针对该命令禁用工作空间内存。

无效的内存文件​

engram verify
engram repair
engram rebuild-index
engram graph --rebuild

包更新后适配器失效​

engram upgrade
engram upgrade --latest
engram link all

仅在有意替换生成的 Engram 适配器文件时使用 --force。

SQLite 配置数据库不可用​

普通的读写命令会回退到 JSON 配置快照。针对数据库的特定命令会报告 SQLite 不可用，而不会阻止常规的内存使用。

全局 Git 同步问题​

  • 确认 global_git.enabled 为 true。
  • 检查 global_git.remote_url 是一个有效的 Git 远程仓库 URL。
  • 审查 global_git.auto_resolve — 自动冲突处理可能会掩盖内存的差异。
  • 运行 engram entry 中的 Runtime 选项卡以检查 global_git_detected。

下一步​

Git 作者身份​

Engram 可以存储一个全局作者以及可选的工作区覆盖。解析顺序依次为工作区、全局，然后是只读的 Git 回退。设置仅影响未来的记忆；工作区覆盖绝不会更改全局 Git 配置。全局 Git 同步或旧版记忆迁移需要显式的计划与确认。

engram author show
engram author set --name "Jane Doe" --email "jane@example.com"
engram author unset --scope workspace
engram author sync-git-global --plan
engram author sync-git-global --confirm
engram author migrate-memories --plan
engram author migrate-memories --confirm

请阅读完整的 Git 作者设置指南。