Architecture

How Engram turns captured memory operations into evidence, incidents, replay branches, and regression tests.

Engram is a local-first memory reliability workspace for AI agents. It turns captured memory operations and agent turns into a trace, an immutable checkpoint, a diagnosable incident, and an executable regression without claiming access to hidden model reasoning.

Product boundary

Engram is intentionally specialized. Memory providers own storage and retrieval. General observability platforms own broad application traces. Engram connects those systems around one workflow: explain and repair a memory-dependent answer, then preserve the expected behavior as a test.

The current implementation is a source workspace and advanced prototype, not a hosted multi-tenant telemetry service.

Artifact and deployment boundaries

The repository contains two independent Next.js applications:

Artifact	Purpose	Release boundary
Repository root	Local Engram Studio, API routes, capture storage, replay, and server credentials	Packaged with @engramviz/studio and launched on loopback by @engramviz/cli; do not deploy this root to Vercel
apps/web	Public product site and bounded interactive demo	Deploy from Vercel with Root Directory set to apps/web; its route manifest must contain / and /demo and no /api routes
docs	Developer documentation	Publish with Mintlify at docs.engramviz.com

The public app receives only its allowlisted static assets. It must not import Studio API implementations, local stores, or server environment configuration. The root commands npm run dev and npm run build continue to target local Studio; the public equivalents are npm run dev:public, npm run test:public, and npm run build:public.

Product modes

• Learn runs the guided memory demo and conversational teaching flow.
• Traces plays recorded or live agent traces. Only explicit memory events animate the brain; ordinary model, tool, handoff, and guardrail spans remain visible as execution evidence.
• Incidents is the default engineering workspace. It presents the recorded run, earliest supported divergence, evidence, intervention, replay, and regression in one sequence. The synchronized brain is an optional evidence rail rather than the primary control surface.

The modes share one canonical trace and checkpoint model. They are different views over the same evidence, not separate simulations.

Capture path

1. @engramviz/sdk opens an agent turn and emits Memory Telemetry v2 events.
2. A provider adapter maps recognized external responses while preserving source paths.
3. Turn Envelope v1 records input, output, provider identity, and correlated event IDs.
4. Local authenticated routes append validated evidence to NDJSON stores.
5. Studio reconstructs a normalized trace without inventing unobserved operations.
6. A trace turn can be promoted to an immutable incident checkpoint.

Capture is fail-open by default so telemetry does not break the agent. Strict delivery is an explicit SDK option for integration and CI environments.

Evidence levels

Every user-facing claim must map to one of these levels:

1. Observed: captured directly from an Engram event or instrumented span.
2. Mapped: translated from a recognized memory tool with its source path.
3. Derived: computed deterministically from captured evidence.
4. Replayed: produced by rerunning a frozen turn under a documented state change.
5. Unavailable: not captured by the current integration.

Engram never labels a supplied memory as the hidden cause of an answer. A replay can show that an answer changed when memory changed, but model sampling and other runtime factors remain possible explanations.

Canonical objects

Checkpoint

A checkpoint is an immutable snapshot after a conversation turn, dream action, or imported trace step. It contains the event prefix, visible memories, active context, retrieval evidence, and optional answer evidence.

Branch

A branch references one checkpoint and applies explicit mutations:

• quarantine: omit a memory from retrieval and active context.
• replace: retire one memory and introduce a corrected branch-local memory.
• restore: cancel a previous quarantine or replacement in the same branch.

Branch mutations never modify the original checkpoint.

Replay

A replay starts from a versioned MemoryDecisionRun containing memory state, retrieval candidates, selection, active context, answer evidence, and evidence coverage per stage. The executor must declare whether it regenerates candidates or reuses the recorded set, which policy stages it reruns, whether answer generation runs again, and whether execution is deterministic.

Engram first reruns the untreated baseline. A treatment comparison is considered valid only when that baseline reproduces the recorded behavior. The causal diff then reports the earliest comparable divergence across memory state, retrieval, selection, active context, and answer. A missing or incomparable stage is shown as indeterminate, not silently promoted into a cause.

The local executor protocol is provider-neutral. engram.config.json points Studio and the regression CLI at the same executor module, eliminating a common source of test drift. A manifest declares the framework, replay levels, rerun stages, determinism, intervention support, and side-effect modes. engram dev --executor ./engram.executor.mjs serves that executor on an authenticated loopback endpoint. Studio proxies replay requests server-side so executor code and credentials never enter the browser.

The LangGraph capture helper attaches an explicit replay checkpoint to the active turn. The executor restores that state with updateState(..., asNode), then calls the downstream graph for separate baseline and treatment runs. Each runtime must declare isolated checkpoint and Store state. Tool, network, and other side-effect isolation remains application-owned because Engram cannot safely infer what arbitrary graph nodes do.

Regression

A verified incident can export an engram.memory-regression v2 artifact. It uses semantic memory selectors instead of provider-generated IDs, declares replay fidelity from the executor capabilities, and bundles a matrix of controlled perturbations. Assertions cover selected memories, loaded memories, excluded memory states, and affirmed or forbidden answer phrases. engram test executes each variant through project-owned code or checks supplied observations. Version 1 artifacts remain supported for existing fixtures.

Persistence and security

Local mode stores validated telemetry and turn envelopes as append-only NDJSON under .engram/data. Access uses a generated bearer token bound to the local project. Trace reads additionally require local mode and a loopback Host, with a same-authority loopback Origin when an Origin is present. This is sufficient for local development and CI fixtures, not a production tenant, retention, or compliance system.

Delivery order

1. Canonical checkpoints, branches, and replay evidence.
2. Learn / Traces / Incidents workspace hierarchy.
3. Retrieval MRI from real retrieval traces.
4. Branching Memory Time Machine.
5. Live trace processor and shareable .engram files.
6. Memory Integrity and Dream benchmark reports.
7. Multi-agent private/shared memory topology.