Aller au contenu principal
Version: Future

Troubleshooting

First step: open engram entry and read the Runtime tab. It shows the resolved profile, memory roots, core config, routing, graph, and Git detection.

Memory did not load​

  • Run engram load --dry-run "<task>" to inspect candidate counts and narrowing tags.
  • Check engram config view for enabled, read, and load.limit.
  • Confirm workspace memory exists under .agents/.engram/.
  • Run engram verify to check hashes.

Hooks not injecting​

  • Confirm engram set-read status is not off or manual.
  • Confirm the host is linked: engram link <target>.
  • Restart or reload the host after link/unlink (especially OpenCode).
  • Check engram set-proof status for proof line visibility.

Save failed​

  • Read the approval preview for related-memory hints.
  • If accept-all reported related memories, no file was saved. Rerun with DEPENDS_ON or UPDATE candidates.
  • Check schema, secret, and injection scan errors in the CLI output.

Profile confusion​

  • Run engram profile status.
  • Confirm the workspace default_profile and active user profile.
  • Remember: an explicit profile different from the workspace default disables workspace memory for that command.

Invalid memory files​

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

Stale adapters after package update​

engram upgrade
engram upgrade --latest
engram link all

Use --force only when replacing generated Engram adapter files intentionally.

SQLite config DB unavailable​

Normal read/write commands fall back to JSON config snapshots. DB-specific commands report SQLite as unavailable instead of blocking normal memory use.

Global Git sync issues​

  • Confirm global_git.enabled is true.
  • Check global_git.remote_url is a valid Git remote URL.
  • Review global_git.auto_resolve — auto conflict handling can mask memory diffs.
  • Run engram entry and open the Construct tab, or run engram config view, to inspect resolved Git detection.

Next steps​

Git author identity​

Engram can store a global author and an optional workspace override. Resolution is workspace, global, then read-only Git fallback. Settings affect future memories only; a workspace override never changes global Git configuration. Use explicit plan and confirmation for global Git sync or legacy-memory migration.

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

Read the complete Git author settings guide.

Vector primary-key error during upgrade​

Older vector-sidecar code could surface this sqlite-vec error while engram upgrade --latest rebuilt memory_vectors:

Only integers are allowed for primary key values on memory_vectors

Current Engram binds vec0 row IDs with integer-compatible BigInt values. Vector search is a disposable acceleration layer: if sqlite-vec still fails, Engram removes the incomplete sidecar/WAL/SHM files, reports vector status as degraded, and continues the durable upgrade through lexical/graph retrieval. Use engram upgrade --latest --plan to preview the durable configuration changes. See Configuration upgrades.