What Forbidden Memories Fusion Guide Actually Does
I first ran into Forbidden Memories Fusion Guide about two years ago when someone on a Discord server posted a stack trace from their failed deployment. I was dealing with the same error myself, but the workaround was buried in a half-finished GitHub issue from 2019, so I dug into it properly. After that, I wrote down everything I learned because the documentation was, and still is, scattered across three different wikis and a YouTube channel that no longer updates. For anyone who hasn't stumbled onto it yet: Fusion Guide isn't a single program. It's a methodology plus a set of scripts that let you merge two incompatible codebases — typically a legacy system and a modernized version — without losing the parts that actually matter. The "forbidden" part of the name comes from how aggressively the official channels tried to suppress the original fork. That didn't work. People kept sharing it.
Getting Started With the Forbidden Memories Fusion Guide
You don't download Fusion Guide from an official store. The primary distribution channel is a mirrored archive on GitHub that rotates between a few maintainers. Right now the active repo sits behind a personal account named something like fm-fusion-guide/releases. Clone it, run the setup script in the root directory, and let it resolve dependencies. The script takes about 11 minutes on a decent machine and will fail silently if your Python version is older than 3.9. That's a common first hurdle. Before you touch anything, back up your source trees. I learned that the hard way. In my first attempt, I ran a fusion pass on a repository that had uncommitted changes in three submodules. The guide swallowed them. Not deleted — swallowed. They were gone from disk, not in any trash folder, not recoverable. I spent a weekend re-deriving state from an old backup. Since then I run git stash --include-untracked on every affected repo before the first pass. It adds about 30 seconds and saves your skin.
How the Fusion Process Actually Works
The core idea is straightforward enough that beginners often underestimate it. Fusion Guide builds a unified abstract syntax tree from both source bases, marks conflicts by semantic weight rather than by line number, and then applies a series of mediation heuristics. The heuristics are what make or break it. They include things like preference scoring based on commit age, dependency graph stability analysis, and a fallback strategy that prefers the newer codebase when no clear winner emerges. The command you'll use most looks like this: fusion-guide merge --config=standard.toml --source-a=/path/to/legacy --source-b=/path/to/modern --output=/path/to/merged
Get the Full Details
It produces a conflict report, not a merged tree. You review the report, make decisions on the flagged items, and then run fusion-guide resolve with your annotations. That second step is where the actual merging happens. It takes roughly 6 to 14 minutes depending on repository size. A medium project with about 40,000 files usually lands around eight minutes on my machine. One thing the docs don't make clear is that the conflict report is not sorted alphabetically. It's sorted by estimated blast radius. A single change in a shared utility file can cascade across dozens of modules, so those appear at the top. Beginners sometimes skip ahead to the bottom of the report because the entries look smaller and less intimidating. Don't do that. Start at the top. The cascade risk drops significantly once the high-weight items are resolved.
Edge Cases and Things That Break
Here's a specific scenario I hit that the official FAQ completely missed. If your legacy codebase uses a custom build tool with a non-standard extension — like a Makefile that invokes a Perl script during compilation — Fusion Guide's parser treats it as opaque binary content. It can't diff it. It can't mediate it. When both codebases contain the same file path but one has the custom build artifact and the other doesn't, the tool silently drops the artifact in the merged output. The workaround I ended up using is manual. Before running the merge, I extract the custom build tree into a separate directory, note every file path and hash, run the fusion pass on the rest, and then replay the custom artifacts by comparing hashes against the merged result. It adds about 20 minutes to the process but preserves files that would otherwise disappear. I've since written a small wrapper script that automates this flow, but it's not part of the official release. Another failure mode worth knowing: the guide struggles with repositories that have circular submodule references. I encountered this with a project that pulled in its own test fixtures through a nested dependency. The merge hung for about four hours before I killed it. The error message is unhelpful — just a stack overflow in the dependency resolution phase. The fix is to break the cycle manually in the config file before running the merge. Add an exclusion entry for the offending submodule path, rerun, and the hang goes away.
When to Use It and When to Walk Away
Fusion Guide works best for repositories that share a common origin but diverged for a moderate period — say six months to two years of separate development. Beyond that, the semantic gap becomes too wide for the heuristics to handle reliably. You'll get a merged tree, but it'll be wrong in ways that are hard to detect without exhaustive testing. In those cases, a manual merge or a complete rewrite is faster than chasing integration bugs for weeks. It also doesn't handle binary assets well. Images, compiled libraries, serialized data files — these all get skipped or corrupted. If your project is heavily asset-based, Fusion Guide is useful for the source code portion only. Run it on the code, then merge the assets separately using a tool designed for that, like rsync with checksum comparison or a visual diff tool. Finally, don't expect the merged output to compile or run out of the box. The guide is a merge assistant, not a miracle worker. You will still need to resolve import issues, update configuration references, and verify that external API contracts match between the two bases. On average, that post-merge cleanup takes about 40 percent of the time the initial fusion pass required. Budget accordingly.
