FAQ

Why not just use CLAUDE.md?

CLAUDE.md is written by hand. It captures conclusions — the final answer to “what did we decide?” What it doesn’t capture is the reasoning: why that decision was made, what was tried first, what broke, what’s intentionally left in a broken state for now. That reasoning is exactly what a new Claude session needs to be useful from the first message.

Wyren is complementary to CLAUDE.md, not a replacement. Think of it this way:

• CLAUDE.md — the project brief. You write it once (or occasionally update it). It covers stable facts: architecture, conventions, how to run the project.
• .wyren/memory.md — the session log. Wyren writes it continuously. It covers the moving parts: what changed today, what was rejected, what’s temporarily broken.

Both get injected. Neither replaces the other.

Why not Claude Projects?

Claude Projects let you upload documents as persistent context. That’s useful for stable reference material. It has two limitations for team work: it doesn’t update automatically as you work, and it’s tied to one person’s project — there’s no shared sync across teammates.

Will this work if we’re not all on the same network?

Yes. Sync is over git, so any git remote (GitHub, self-hosted) works the same over LAN or WAN. Tested in both.

What if git push fails?

Wyren retries up to 3 times. On conflict, it fetches the latest remote, fast-forwards local HEAD if safe (no user commits diverged), creates a fresh wyren-only commit, and retries. If the branches have diverged (user commits not on remote), Wyren restores remote .wyren/ files and leaves HEAD untouched — run git fetch && git rebase origin/<branch> then wyren distill --push to recover. On final failure, the memory update stays local — it will push on the next successful distill.

Will my conversations leak to my teammates?

No. Only the distilled memory is pushed. Verbatim transcripts never leave your machine. The distiller’s prompt explicitly forbids code snippets and conversation quotes.

That said: if you say something secret in a session on a shared repo, the conclusion of it may end up in memory. Treat .wyren/memory.md like any other committed file.

Should I keep my repo private when using Wyren?

Yes, strongly recommended — unless you’re deliberately okay with public memory.

.wyren/memory.md is a regular committed file. If your repo is public, that file is readable by anyone on the internet. The distiller writes things like:

• Technical decisions and the reasoning behind them
• Approaches that were tried and rejected (and why)
• Known workarounds and shortcuts still in the code
• Scope changes and what was deliberately cut

None of this is verbatim transcript — but it’s real project context that you probably don’t want public. If you’re working on an open-source project and want Wyren, audit .wyren/memory.md regularly and remove anything sensitive before pushing, or just keep the repo private while in active development.

To inspect current memory at any time:

cat .wyren/memory.md

To redact an entry: hand-edit the file. Wyren treats your edits as trusted state and will not undo them.

How do I disable Wyren temporarily?

Use the Claude Code slash command:

/plugins disable wyren

Re-enable with /plugins enable wyren. This is the only supported toggle — the WYREN_DISABLE env var mentioned in early drafts is not wired up.

If you want to skip git fetch on a specific session (e.g. offline demo), set WYREN_SKIP_PULL=1 before launching Claude Code. Memory injection still works from whatever is already on disk; only the pre-session pull is skipped.

How do I stop distillation on a specific turn?

You can’t, and you don’t need to. The Tier 0 weighted signal filter already kills ~70% of triggers. For fully private turns, disable the plugin for that session:

/plugins disable wyren

Re-enable with /plugins enable wyren when done.

Memory is wrong / stale / contradictory — what do I do?

Hand-edit .wyren/memory.md. The distiller treats your edits as trusted starting state. On the next distill, it merges new transcript signal against your edits.

If you want something permanent that the distiller should never touch, put it in .wyren/broadcast/CLAUDE.md instead.

A resolved workaround keeps showing up in memory. Why?

Most likely the transcript didn’t mention the resolution explicitly. The distiller can’t detect something it wasn’t told. Two fixes:

1. Say “that workaround is fixed now” in the session — next distill catches it.
2. Hand-edit the memory file to remove it.

Does this work with Cursor or Windsurf?

No. Wyren uses Claude Code’s hook system. Other editors have different (or no) hook surfaces.

In a future release, a generic “transcript watcher” daemon could support Cursor + Windsurf via their respective APIs. See Future.

How does Wyren handle merge conflicts on memory.md?

If two teammates distill within the same second and both push, the second push fails non-fast-forward. Wyren pulls the first person’s version, re-runs the distiller against that new base (idempotent — transcripts are per-session), and pushes on attempt 2.

If branches have diverged (user has local commits not on remote), Wyren leaves HEAD untouched, restores remote .wyren/ files, and returns remote_diverged. Run git fetch && git rebase origin/<branch> then re-run wyren distill --push.

What Claude Code version is supported?

Tested against Claude Code 2.1.x (transcript schema observed during development). Earlier versions may have different JSONL shapes. README will pin the supported range.

What about tmux, multi-tab, multi-process sessions?

Each Claude Code session has its own UUID and transcript. Wyren handles them independently — each spawns its own distiller based on its own Stop hook firings. Watermarks are per-session.

The only coordination point is git pushes, which are serialized by the advisory lock.

Known limitations

1. Distiller needs signal to work. Pure research sessions (read, read, read) produce almost nothing in memory. That’s intentional — noise is worse than nothing.
2. Tier 0 filter may miss purely conversational decisions. The filter uses weighted scoring across decision/rejection/hack/scope/maintenance categories plus structural signals (session length, edit count). Most real work sessions pass automatically. Edge case: pure design discussions with no signal words (“let’s go with dark mode”) may not trigger. Fix: use explicit language (“we decided to use dark mode”) or run wyren distill --force --push manually.
3. Resolved-but-unmentioned workarounds linger. Fix: say it’s fixed, or hand-edit.
4. Mid-session sync has one-prompt lag. The UserPromptSubmit hook pulls A’s latest memory and injects the delta at the start of each of B’s turns. B doesn’t need to restart — the update arrives on B’s next message after A’s distiller pushes. Typical lag: a few seconds to one full turn. UPS pull is capped at 1.5s; visible as a short pause before Claude responds.
5. Distillation requires Claude Code authentication. Wyren calls claude -p using your existing Claude Code login — no separate API key. Run claude auth login if distillation is being skipped silently. Check .wyren/log for the error.

Where do I report bugs?

GitHub issues.