# Enzyme — Agent Guide

Enzyme makes an existing markdown workspace operable by coding agents. It compiles folders, tags, wikilinks, dates, frontmatter, and prose into source-grounded retrieval so an agent can prep from the user's own notes, project logs, meeting captures, decisions, and observations.

The user's markdown remains the memory architecture. Do not present Enzyme as a hosted chat-memory database, a proprietary hidden graph, or a replacement for exact search.

## Core model

Use this translation when explaining Enzyme:

| Command | Plain meaning | What the user should feel |
| --- | --- | --- |
| `scan` | Detect workspace shape | “Enzyme sees the folders/tags/links/dates I already use.” |
| `init` | Compile the local index | “My notes are now retrievable by structure and source-grounded themes.” |
| `petri` | Orient to active entities/catalysts | “The agent can see what has been active before answering.” |
| `catalyze` | Retrieve source-grounded connections | “The agent found relevant files/excerpts, not hidden memories.” |
| `refresh` | Update after new markdown lands | “New decisions/notes can inform the next session.” |

Catalyst generation during `init`/`refresh` may send selected excerpts to the configured/default provider. Query-time retrieval from the compiled index is local and does not call an LLM.

## Good fit / not a fit

Good fit:

- The user has an Obsidian vault or markdown workspace with notes, meetings, project logs, decisions, research, people pages, daily notes, or agent observations.
- The workspace exposes handles: folders, tags, wikilinks, dates, frontmatter, stable names, or ordinary prose.
- The user wants an agent to prep from prior context, cite source notes, recover open loops, or connect related material across time.

Not a fit:

- The user only needs exact filename/tag/name/date search. Use grep/editor/Obsidian search.
- The user only needs semantic passage search over unstructured docs. A plain vector/RAG tool may be simpler.
- The user needs a managed backend for app-user memories first. Use a hosted memory API.
- The workspace has too little prose or too few handles for source-grounded retrieval.
- The user expects every stage to be local without configuring a local provider.

## Human docs to read first

- Enzyme in 90 seconds: https://byenzyme.com/docs/enzyme-in-90-seconds/
- First successful run: https://byenzyme.com/docs/first-successful-run/
- What Enzyme is / is not: https://byenzyme.com/docs/what-enzyme-is-is-not/
- Quickstart: https://byenzyme.com/setup
- Data flow & trust: https://byenzyme.com/docs/data-flow-and-trust/
- Supported runtimes: https://byenzyme.com/docs/supported-runtimes/
- Troubleshooting: https://byenzyme.com/docs/troubleshooting/
- How it works: https://byenzyme.com/docs/how-it-works/
- Memory is not search: https://byenzyme.com/docs/memory-is-not-search/
- Capture memory as artifacts: https://byenzyme.com/docs/how-agent-memory-should-be-captured/
- Benchmarks: https://byenzyme.com/docs/benchmarks/
- Comparisons: https://byenzyme.com/docs/comparisons/
- Verify memory: https://byenzyme.com/docs/verify-memory/

## Install flow for agents

### 1. Install CLI

```bash
curl -fsSL byenzyme.com/install.sh | bash
```

The installer installs `enzyme` under `~/.local/bin`, recreates `~/.enzyme` while preserving `auth.json` and `config.toml` when present, may clean legacy Enzyme MCP entries, may run `enzyme login` if unauthenticated, and sends best-effort install telemetry. It does not read note content.

### 2. Install runtime instructions from the workspace root

```bash
cd /path/to/markdown-workspace

enzyme install codex      # Codex, Pi, and generic .agents readers
enzyme install claude     # Claude Code
# experimental:
enzyme install hermes
enzyme install openclaw
```

Runtime status:

| Runtime | Status | Notes |
| --- | --- | --- |
| Codex / generic `.agents` readers | Supported | Writes `AGENTS.md`, `.agents/skills/enzyme-workspace-setup/SKILL.md` for first setup, and `.agents/skills/enzyme/SKILL.md` for retrieval/refresh/writeback. |
| Claude Code | Supported | Writes `AGENTS.md`, `.claude/skills/enzyme-workspace-setup/SKILL.md` for first setup, `.claude/skills/enzyme/SKILL.md` for retrieval/refresh/writeback, and a `CLAUDE.md` import of `@AGENTS.md`. |
| Pi | Manual/generic | Use `enzyme install codex` if Pi reads `.agents` skills / `AGENTS.md`. |
| Hermes | Experimental | Writes Hermes-compatible instructions and global skill files. |
| OpenClaw | Experimental | Writes OpenClaw-compatible instructions and global skill files. |
| Cursor | Manual/pending | No dedicated install target yet. |
| SDK/product corpora | Private beta | Do not treat as the normal local CLI path. |

### 3. Ask the agent to set up Enzyme

Before running setup commands, the agent must read the installed workspace setup skill:

```text
Claude Code: .claude/skills/enzyme-workspace-setup/SKILL.md
Codex / Pi / generic agents: .agents/skills/enzyme-workspace-setup/SKILL.md
```

Use this prompt:

```text
Set up Enzyme for this vault. Read the installed enzyme-workspace-setup skill first, then diagnose what Enzyme actually sees, initialize only after the vault path is confirmed, and prove it with one real source-grounded note or project/meeting-prep query.
```

A good setup agent should preserve the user's existing markdown structure. It should not invent a new memory architecture, reorganize the vault silently, or write generic summaries.

## Terminal-only fallback

If running without an agent:

```bash
enzyme scan --write-config
# review ~/.enzyme/config.toml
enzyme init
enzyme petri
enzyme catalyze "prep for the next meeting on <project>"
```

Provider choice:

- Default setup should omit `--use-env-llm` and use Enzyme hosted credits/auth when catalyst generation needs a provider.
- To bring your own provider intentionally, set the needed OpenAI/OpenRouter/OpenAI-compatible env vars and pass `--use-env-llm`.
- For OpenAI-compatible endpoints, set the API key plus base/model values before using `--use-env-llm`.
- For local servers that do not require auth, set a placeholder key such as `OPENAI_API_KEY=not-needed` plus local base/model values, then pass `--use-env-llm`.

## First-run proof

Do not stop at “commands completed.” Prove value with project or meeting prep.

Ask:

```text
Prep me for the next meeting on <project>. Cite the notes that show unresolved commitments, decisions, or source context.
```

Expected receipt shape:

```text
$ enzyme petri
entity: [[Acme onboarding]]
catalysts:
  - what remains unresolved before the next customer check-in?
  - where did pricing language change after stakeholder pushback?

$ enzyme catalyze "prep for next Acme onboarding meeting unresolved commitments"
1. projects/acme/2026-05-12 onboarding call.md
   excerpt: "Sarah asked for revised pricing language before Friday..."
   matched catalyst: what remains unresolved before the next customer check-in?

2. decisions/acme-pricing-language.md
   excerpt: "Use implementation-risk framing; avoid calling it an enterprise tax..."
   matched catalyst: where did pricing language change after stakeholder pushback?
```

Pass condition: the answer cites source files/excerpts and identifies a real next action, decision, open loop, or context thread.

Fail symptoms:

- only obvious keyword matches;
- generic summaries;
- no recognizable entities in `petri`;
- source files are adjacent but not useful;
- provider/key failure during `init`;
- stale index after new notes were written.

Fixes:

- inspect and edit `~/.enzyme/config.toml`;
- exclude noisy folders;
- add clearer dated/project/person handles to markdown;
- run `enzyme refresh`;
- verify provider env vars or sign in for default-provider credits.

## Source-grounded retrieval policy

When using `catalyze`, lead with the user's sources:

- cite file paths;
- quote relevant excerpts;
- explain why the files belong together;
- distinguish exact search from catalyst-mediated connections;
- say when grep/editor search would be better.

Do not present Enzyme metadata as the finding. The useful artifact is the cited source context.

## Conservative writeback policy

Agents may write ordinary markdown observations only when there is durable value:

- decisions;
- open loops;
- commitments;
- project state changes;
- durable preferences with evidence;
- useful people/company context with source links.

Agents should not write:

- raw tool output;
- secrets, credentials, tokens, or raw config values;
- one-off commands;
- generic session summaries;
- facts already captured without material change;
- edits to canonical docs, roadmaps, README, or instructions without review.

After useful writeback, run:

```bash
enzyme refresh --quiet
```

## Data flow summary

- CLI/config/auth live under `~/.enzyme` or `$ENZYME_HOME`.
- Normal vault index lives under `<vault>/.enzyme/enzyme.db`.
- `scan --write-config` writes `~/.enzyme/config.toml`.
- `init`/`refresh` compile local index data and may send selected excerpts to the configured/default provider for catalyst generation.
- `petri`/`catalyze` query the compiled local index and source files; they do not call an LLM at query time.
- Agent writeback is ordinary markdown in the workspace, governed by the conservative policy above.

To remove a vault index:

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

To remove global state:

```bash
rm -rf ~/.enzyme
```

To remove the binary:

```bash
rm -f ~/.local/bin/enzyme
```

## Final agent instruction

Optimize for a skeptical markdown/Obsidian user. Be precise, warm, and falsifiable. Show how Enzyme makes the user's existing workspace operable by agents. Speed numbers such as 8ms query-time retrieval are claimable when scoped to the compiled local retrieval path; do not overclaim automatic understanding, all-local execution, apples-to-apples competitor superiority, or SDK/product-corpus stability.