Andrey Karasev

Posted on Nov 10

Mnemosyne: Making Code Explain Itself

#ai #typescript #architecture #opensource

From runtime tracing to explainable software

Traditional AI reconstructs what happened from source code, logs, and traces. Mnemosyne records what actually happened during execution.

When a calculation produces the wrong answer, the hardest part is often not finding the final value. It’s reconstructing how the program got there.

A log might tell us that a premium was $863.45. Source code might show the formula that was intended to calculate it. But neither necessarily tells us which values actually flowed through that formula during the run.

Mnemosyne is a TypeScript source-to-source transpiler that records runtime value provenance. It instruments code, lets the real values continue through the program, and builds a directed acyclic graph of the values and operations observed during that execution.

The goal is simple:

Rather than reconstructing behavior from source code, logs, and assumptions, Mnemosyne captures the execution evidence that produced a specific result.

The project is open source:

👉 https://github.com/andrey-karasev-gmail/mnemosyne

Making Code Explain Itself.

A concrete incident

Imagine an insurance application with these inputs:

const application = {
  age: 47,
  vehicleValue: 45_000,
  accidentsLast5Years: 2,
  annualMileage: 18_000,
  state: "NJ",
};

The expected premium is $715.20. Production returns $863.45.

A source review can find the formula. Logs can show the final quote. But to explain this particular result, we need the actual values used by the running program.

In an instrumented trace, we might see:

base premium                     $715.20
AI risk score                      0.63
AI_RISK_WEIGHT                    0.3290124
risk adjustment                 1.2072778
premium before rounding          $863.445
lodash.round(..., 2)              $863.45

The cause is now visible in the value flow: a runtime risk-weight setting amplified the base premium.

The graph is not showing what could have happened. It is showing what actually happened during this execution.

The trace also tells us that the model returned a score of 0.63 and that the rounding package received 863.445 and returned 863.45.

The package and model participated in the calculation, but neither alone explains the discrepancy. The unexpected configuration value does.

What Mnemosyne records

Mnemosyne transforms TypeScript source before it runs. The transform can see details that are lost after compilation, including variable names and source locations. At runtime, the instrumented program writes provenance nodes to a side-channel tape while returning the ordinary program values.

A simplified view of the trace looks like this:

Each edge answers a practical question: which earlier value contributed to this one?

The graph includes ordinary inputs and operations alongside opaque package and AI nodes. Mnemosyne records a package call at its boundary; it does not expand the package’s internals. An AI call is recorded with provider, model, input provenance, and available usage metadata.

Why source review and logs aren’t enough

Source review describes what code could do. It is essential, but it cannot by itself confirm which configuration value entered a specific production execution.

Logs describe what developers chose to log. They may include the final premium while omitting the intermediate multiplier, package arguments, or model output.

Mnemosyne adds a different view: the concrete dataflow observed during an instrumented run. Starting from the premium, an investigator can walk backward through the rounding call, the adjustment calculation, the AI score, and the runtime configuration input.

This doesn’t replace source review or logging. It gives them execution evidence to work from.

Querying Runtime Knowledge Through MCP

Mnemosyne exposes trace queries through the Model Context Protocol (MCP), so a person or AI assistant can inspect the run without reading the entire program.

For the insurance incident, useful questions include:

find_variable_origin("premium")
get_package_usage("lodash")
get_ai_nodes(provider="openai", model="gpt-5")
query_causality("premium", direction="backward")

Together, these queries can show the premium’s ancestry, package calls in the trace, AI calls that influenced it, and upstream dependencies.

Starting from the final premium, the provenance query reconstructs the full ancestry chain, including configuration inputs, AI outputs, package calls, and intermediate calculations.

A removal-impact query should be interpreted carefully. If a package or model appears in the ancestry, the trace can show which observed outputs depended on it. That is evidence about this execution, not proof that the dependency is unused on every possible program path.

One execution, not every possible execution

Mnemosyne records the path that actually ran. It does not speculate about branches that were not taken, and it does not claim to explain every behavior of a program from one trace.

That limitation is also what makes the graph useful for debugging a particular result. It describes the values and operations observed in that run, rather than presenting a large set of hypothetical paths.

The trace’s coverage also depends on what the transpiler supports and what source is instrumented. External package calls remain opaque boundaries. AI calls need to be explicitly instrumented because different providers expose different APIs and usage fields.

A tool for investigating calculations and decisions

The insurance example is not really about insurance. It illustrates a broader problem: business logic often spans application inputs, calculations, dependencies, configuration, and model calls. When an output looks wrong, investigators need a way to follow those contributions through execution.

Observability helped us understand where software executes.

AI helps us understand what code means.

Mnemosyne explores a different question:

Why did this specific result happen?

By capturing value provenance during execution and exposing it through a queryable graph, it gives both humans and AI access to runtime ground truth instead of runtime speculation.