Troubleshooting

Most Enzyme problems show up as a weak first result: generic themes, obvious files, or lack of citations. Treat that as useful feedback. It means setup has not found the right workspace handles yet.

Quick checks

enzyme petri
enzyme catalyze "prep for next meeting on <project>"

If the runtime skill seems missing, check the runtime install:

enzyme install codex    # Codex, Pi, generic .agents
enzyme install claude   # Claude Code

Hermes and OpenClaw are experimental:

enzyme install hermes
enzyme install openclaw

Weak or generic enzyme petri

Symptoms:

  • entities are generic;
  • no project/person/client appears;
  • catalysts feel like bland summaries;
  • noisy generated folders dominate.

Likely causes:

  • config selected weak entities;
  • important folders are excluded or not selected;
  • the workspace lacks visible handles;
  • generated files/logs drown out durable notes.

Fix:

Tell your agent to clear and set up Enzyme again in your vault, especially if coming from a earlier version. More recent releases assist diagnostics with a setup skill.

If you wish to customize the config, prefer handles that reflect real use: projects/, meetings/, people/, clients/, decisions/, daily/, meaningful tags, and recurring wikilinks.

Provider or credits error during init

Catalyst generation needs a provider path. By default, enzyme init and enzyme refresh use Enzyme hosted credits/auth and ignore inherited LLM env keys.

For the default hosted path:

enzyme login
enzyme init

Bring your own provider only when you intend to bill through your own key:

export OPENAI_API_KEY="sk-..."
enzyme init --use-env-llm

For custom or local endpoints:

export OPENAI_API_KEY="not-needed"
export OPENAI_BASE_URL="http://localhost:1234/v1"
export OPENAI_MODEL="qwen/qwen3-8b"
enzyme init --use-env-llm

For refreshes that should use your env provider, run enzyme refresh --use-env-llm. If --use-env-llm reports missing env config, set the key/base/model correctly or omit the flag to use hosted credits/auth. No shell-variable cleanup is needed.

New notes do not appear

Run:

enzyme refresh --quiet

If the note still does not appear:

  • confirm it is inside the workspace being indexed;
  • confirm the folder/tag is not excluded;
  • confirm the note is markdown/text, not only a binary attachment;
  • check whether the note has enough source text or handles to retrieve from.

Agent ignored Enzyme

If the agent does not use Enzyme:

  1. Confirm you ran the right runtime install from the workspace root.
  2. Restart the agent from that same workspace root.
  3. Ask explicitly: Read the Enzyme skill and use it to prep for this project from source files.
  4. Check Supported runtimes for file paths and status.

Writeback got noisy

If the agent writes too much:

  • tell it not to “remember everything”;
  • restrict writeback to durable decisions, open loops, commitments, project state, and source-linked observations;
  • keep generic summaries out of durable memory;
  • ask before changing canonical docs, roadmaps, README, AGENTS.md, or skills.

See Capture memory as artifacts.

Reset

Remove a vault index:

rm -rf /path/to/vault/.enzyme

Remove global Enzyme state:

rm -rf ~/.enzyme

Remove the binary:

rm -f ~/.local/bin/enzyme

Then reinstall or rerun setup from the workspace root.