MotifVM is a cognitive virtual machine for LLM agents. It converts natural-language or domain tasks into typed, inspectable state transitions, validates those transitions through invariants, commits success or failure states, and exports portable audit packs with source-bound lineage and authority references.
MotifVM is not a LangChain alternative, a RAG system, or a generic agent framework. It is a stateful reasoning runtime: a compiler-style cognitive VM and invariant-checked agent substrate.
CognitiveState + StatePatch
-> validate patch
-> apply transition
-> run invariants
-> commit success/failure
-> export audit pack
No pass, tool, or LLM call mutates CognitiveState directly. Everything emits StatePatch; the runtime validates, applies, verifies, and commits.
flowchart LR
Request["Request / Domain Task"] --> TaskAST["TaskAST"]
TaskAST --> Motif["Motif Diagnosis"]
Motif --> Frame["MotifFrame"]
Frame --> Plan["ReasoningPlan"]
Plan --> Patch["StatePatch"]
Patch --> Invariants["Invariant Check"]
Invariants --> Commit["Commit Success / Failure"]
Commit --> Pack["Audit Pack"]
Run tests:
make testRun the product workbench:
cd product
npm install
npm run devOpen http://127.0.0.1:5173 for the interactive MotifVM workbench with draggable reasoning graphs, domain invariant proposals, run history, and local SQLite persistence.
Run the full demo suite:
make demoDemo outputs are written to .motifvm/demo_outputs/, including audit packs and benchmark.csv.
Run the evaluation harness:
make evalEvaluation outputs are written to .motifvm/eval_outputs/.
Run the adversarial harness:
make adversarialAdversarial outputs are written to .motifvm/adversarial_outputs/, including adversarial_results.csv and failure_taxonomy.json.
Verify an exported audit pack independently:
python3 -m motifvm verify-pack .motifvm/demo_outputs/dccb_mismatch/audit_packRun the larger adversarial suite:
make adversarial-100Run adapter conformance checks:
make adapter-conformanceRun compiler planning evaluation:
make compiler-evalSuccessful DCCB CRAR verification:
python3 -m motifvm run "Verify CRAR using examples/crar_good.csv" --domain dccb_audit
python3 -m motifvm reportCRAR mismatch with reconciliation patch:
python3 -m motifvm run "Verify CRAR using examples/crar_mismatch.csv" --domain dccb_audit
python3 -m motifvm export-audit 001Code review auth-bypass detection:
python3 -m motifvm run-task "Review this code diff for security risk" \
--domain code_review \
--input examples/code_review/unsafe_auth_bypass/diff.patchRepository-scale code review:
python3 -m motifvm run-task \
"Review this repository diff for security risk" \
--domain code_review \
--input examples/code_review/repo_helperStructured LLM call boundary with DeepSeek:
DEEPSEEK_API_KEY=... python3 -m motifvm run-task \
"Review this code diff for security risk" \
--domain code_review \
--input examples/code_review/unsafe_auth_bypass/diff.patch \
--llm deepseekThe API key is read from the environment and is not written to state, logs, commits, or audit packs.
Compare two committed runs:
python3 -m motifvm compare-runs 001 002DCCB:
examples/crar_good.csv: successexamples/crar_mismatch.csv: reported CRAR mismatch with reconciliation patchexamples/crar_below_threshold.csv: regulatory non-complianceexamples/crar_missing_rwa.csv: blocked invalid input
Code review:
examples/code_review/safe/diff.patch: successexamples/code_review/unsafe_auth_bypass/diff.patch: unconditional auth allowexamples/code_review/secret_literal/diff.patch: obvious secret literal
committed_success: all error-severity invariants pass.committed_failed: one or more error-severity invariants fail, but the failed evidence state is preserved.
Failed states are first-class outputs. MotifVM preserves evidence, lineage, graph state, invariant failures, and reconciliation patches.
motifvm export-audit <commit-id> exports:
report.mdstate.jsonmotif_frame.jsonreasoning_plan.jsonreasoning_plans.jsongraph.jsongraph.dotgraph.mmdlineage.jsoninvariants.jsoninputs_manifest.jsonreconciliation_patch.jsonllm_calls.jsonartifacts/*.json
Input manifest entries include SHA-256 hashes so row-level or line-level evidence remains stable even if source files change later.
Audit packs can be checked without rerunning the task:
python3 -m motifvm verify-pack <audit-pack-dir>Audit packs also include patch_timeline.json and patch_timeline.md, which show each authorized or rejected StatePatch transition.
Audit packs include extracted_facts.json, which records adapter-emitted EvidenceRef and ExtractedFact records before domain passes convert facts into claims.
Audit packs also include the compiler surface: motif_frame.json records required/support/gap/risk, while reasoning_plan.json records selected passes, policy rationale, and verification strength.
MotifVM v0.5.4 freezes the core boundary around artifact adapters and extracted facts:
ArtifactAdapter -> EvidenceRef -> ExtractedFact -> StatePatch -> invariants -> terminal state -> audit pack
Contract docs:
MotifVM v0.6.5 adds the cognitive compiler above the frozen kernel:
TaskAST -> MotifFrame -> ReasoningPlan -> verification policy -> StatePatch runtime
The compiler computes consequence-weighted motif risk, selects passes from config/pass_effects.json, chooses light/standard/strict verification, and emits replan events when fatal invariants classify as reconciliation, computation-blocked, invalid-input, missing-authority, missing-lineage, or security-risk failures.
Compiler docs:
Paper:
The public demo package is under demo/:
demo/run_all.sh: runs tests, canonical demos, adversarial cases, and evaluation.demo/expected_results.md: summarizes expected terminal states.demo/graph_explorer/index.html: offline audit-pack graph viewer.
Generated demo audit packs are copied to demo/audit_packs/ and ignored by git.