# Mnemosyne
A source-to-source TypeScript transpiler that instruments regular code to record a linear tape of every operation at runtime, reconstructing the full value-provenance path — including internal variable names — across one or more "black box" functions. An MCP server runs the instrumented program once and serves the resulting DAG to an AI agent as queryable tools, so debugging a value's origin doesn't require re-reading and mentally simulating the source on every question.
## How It Works
At compile time, a Babel plugin rewrites native operators, bindings, and returns into calls against a runtime tape, reading variable names straight from the AST (something a runtime wrapper alone could never see, since names are erased after compilation). Values pass through untouched — only a side-channel record of what produced them is captured. The MCP server calls run_trace once, then answers find_variable_origin / query_causality against the cached DAG — a low-token, run-once workflow instead of re-tokenizing thousands of lines of source per question.
AI Agent ──MCP (stdio)──▶ mcp-server.ts
└── run_trace (once)
└── Babel plugin (transform.ts) ──▶ instrumented code
└── runtime tape (__t) ──▶ value-provenance DAG
└── find_variable_origin / query_causality / get_diagram
└── served from the cached DAG## Screenshots
❯ run_trace ✓ Instrumented 3 files · 1 shared tape ✓ 54 nodes recorded ✓ Output identical to uninstrumented run
❯ find_variable_origin name=priceBox.total priceBox.total = 64.7676 ← total (local) = subtotal + tax @price-box.ts:12 ← subtotal (local) = price * qty @price-box.ts:10 ← price (param), qty (param) ← tax (local) = subtotal * TAX_RATE @price-box.ts:11 ← TAX_RATE (const) = 0.08 ← process.env.TAX_RATE
❯ get_diagram name=priceBox.total
## Features
- +Side-channel tracing — the real value flows through unchanged, identical program output
- +Reconstructs full ancestry across black-box function calls, including internal var names
- +Cross-file import/export tracing sharing one tape across a whole local module graph
- +MCP tools: run_trace, find_variable_origin, query_causality, get_diagram, get_execution_summary
- +Publishable as a library — use the Babel plugin directly, or bundle via the esbuild plugin
## vs. The Field
| Feature | Mnemosyne | console.log / debugger | OpenTelemetry tracing |
|---|---|---|---|
| MCP-native, agent-queryable | ✓ | ✗ | ✗ |
| Internal variable names preserved | ✓ | n/a | ✗ |
| Ancestry across black-box functions | ✓ | manual | partial |
| Low-token: run once, query many times | ✓ | ✗ | partial |
| Behavior-preserving (side-channel) | ✓ | ✓ | ✓ |
## Installation
Install
No cloning or build step needed.
npm install @web4w3/mnemosyne
Register the Babel plugin
Add the plugin to your own Babel config to instrument your code.
const { mnemosynePlugin } = require("@web4w3/mnemosyne");
module.exports = {
presets: [["@babel/preset-typescript", {}]],
plugins: [mnemosynePlugin],
};Register the MCP server
The MCP server itself runs from a local clone (not the npm package) — clone the repo, then point your client at it.
{
"mcpServers": {
"mnemosyne": {
"command": "npx",
"args": ["ts-node", "--transpile-only", "src/mcp-server.ts"],
"cwd": "/absolute/path/to/mnemosyne"
}
}
}