MyelinMesh

The reliability evidence mesh for AI systems.

MyelinMesh is an open-source evidence layer that connects software and model changes, agent trajectories, physical tests, runtime incidents, diagnoses, recoveries, and human reviews into reusable reliability knowledge.

The name draws from biological myelin, which insulates and accelerates signals, and a mesh, which links evidence across otherwise isolated systems. MyelinMesh does not certify safety or prove causality. It preserves provenance, exposes uncertainty, and makes reliability claims testable.

Supported v0.1 path: reports → validated MER → local JSON/SQLite → CLI.

Text version of the evidence flow

1. Tool-Semantics, MyelinMesh, and Parallax reports enter through their supported adapters.
2. Pydantic and JSON Schema validate each MyelinMesh Evidence Record (MER).
3. Canonical JSON produces a SHA-256 content hash.
4. MER JSON files and SQLite metadata are written under .myelinmesh/.
5. The CLI retrieves evidence with list, show, search, and stats.

Why this exists

Reliability evidence is usually fragmented:

• Tool-interface changes live in compatibility reports.
• Agent failures live in traces and benchmark outputs.
• Robot regressions live in MCAP bags and simulation artifacts.
• Diagnoses live in incident documents.
• Recoveries live in code, runbooks, or human memory.

MyelinMesh gives these artifacts a shared record format and a local-first store so future tests and decisions can reuse what the system has already learned.

Tool-Semantics ─┐
MyelinMesh ─────┼──► validate + hash ─► MER JSON + SQLite ─► list · show · search · stats
Parallax ────────┘

Initial capabilities

• Versioned MyelinMesh Evidence Record (MER) schema.
• Deterministic validation and content hashing.
• Local evidence store backed by JSON files and SQLite metadata.
• CLI for initialization, validation, ingestion, search, inspection, and statistics.
• Adapters for Tool-Semantics, MyelinMesh, and Parallax-style outputs.
• Example records covering tool drift, physical regression, and runtime recovery.
• JSON Schema export for non-Python producers.

Quick start

python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

myelinmesh init .myelinmesh
myelinmesh validate examples/records/tool-semantic-drift.mer.json
myelinmesh ingest examples/records/tool-semantic-drift.mer.json --store .myelinmesh
myelinmesh list --store .myelinmesh
myelinmesh search "semantic drift" --store .myelinmesh
myelinmesh stats --store .myelinmesh

Run the demo dataset:

make demo

The demo creates an isolated .myelinmesh-demo store, ingests all three included evidence records, lists them, and prints aggregate statistics. It never writes outside the repository.

CLI at a glance

Command	Purpose
myelinmesh init PATH	Create a local evidence store and SQLite index.
myelinmesh validate RECORD	Validate an MER JSON document without ingesting it.
myelinmesh migrate RECORD --to VERSION	Write a deterministic record migration to a new file.
myelinmesh ingest RECORD --store PATH	Validate, hash, and persist evidence.
myelinmesh ingest-batch PATH... --store PATH	Deterministically ingest files or directories and report inserts, duplicates, invalid records, and failures.
myelinmesh list --store PATH	List indexed evidence records.
myelinmesh search QUERY --store PATH	Search evidence using indexed text and metadata.
myelinmesh show ID --store PATH	Inspect one evidence record.
myelinmesh stats --store PATH	Summarize the local evidence collection.
myelinmesh adapt PRODUCER REPORT	Convert supported producer output into an MER record.

Migration paths are explicit and registered in myelinmesh.migrations. Each path must validate its output, preserve evidence identity and provenance, and remain deterministic. Unsupported target versions fail closed; the CLI never silently edits the input unless --in-place is requested.

Example evidence record

{
  "schema_version": "0.1.0",
  "identity": {
    "evidence_id": "mer-demo-tool-drift-001",
    "project": "tool-semantics",
    "captured_at": "2026-08-04T18:20:00Z"
  },
  "provenance": {
    "source_type": "simulation",
    "producer": "tool-semantics",
    "producer_version": "0.1.0",
    "commit_sha": "a71c22"
  },
  "context": {
    "domain": "agent",
    "system": "calendar-agent",
    "task": "schedule a meeting"
  },
  "failure": {
    "detected": true,
    "failure_class": "semantic_tool_drift",
    "severity": "critical",
    "confidence": 0.91
  },
  "validation": {
    "human_reviewed": true,
    "replay_count": 10,
    "reproduced_count": 9
  }
}

Architecture

Producers
  GitHub · Tool-Semantics · MyelinMesh · Parallax · ROS 2 · OTel
                                │
                                ▼
                     Adapter and validation layer
                                │
                                ▼
                  MyelinMesh Evidence Record (MER)
                                │
              ┌─────────────────┴─────────────────┐
              ▼                                   ▼
        JSON artifact store                  SQLite index
              │                                   │
              └─────────────────┬─────────────────┘
                                ▼
                     CLI · SDK · future API

See docs/architecture.md and docs/evidence-model.md.

Relationship to the existing projects

• Tool-Semantics produces evidence about tool schemas, descriptions, selection behavior, side effects, and compatibility risk.
• MyelinMesh produces evidence about change impact, selected physical tests, simulation metrics, and release decisions.
• Parallax produces semantic traces, early warnings, diagnoses, recovery attempts, and post-recovery outcomes.
• MyelinMesh connects those records without replacing the source systems.

Trust boundaries

MyelinMesh records evidence, not proof. Every record carries provenance, uncertainty, validation context, and reproducibility signals so consumers can judge whether it applies to a new situation. Historical similarity must not be treated as causal certainty, safety certification, or an authorization to deploy. See the evidence model, security and privacy guidance, and data governance policy.

Development

./scripts/bootstrap.sh
source .venv/bin/activate
./scripts/check.sh

You can also use the included dev container or Docker image:

docker compose build
docker compose run --rm myelinmesh --help

The repository ships with Ruff, mypy, pytest with branch coverage, pre-commit hooks, schema drift detection, multi-version CI, CodeQL, and Dependabot configuration.

Regenerate the README evidence flow and its reduced-motion fallback with:

pip install -e ".[media]"
python scripts/render_readme_demo.py

Non-goals

MyelinMesh is not:

• A safety certification authority.
• A generic log-management platform.
• An autonomous root-cause oracle.
• A replacement for MCAP, OpenTelemetry, or experiment tracking.
• A system that treats historical similarity as proof.

Project status

The repository is at Milestone 0: foundation. The local schema, validation, storage, and adapter interfaces are usable. Production connectors, vector retrieval, benchmark datasets, and hosted operation remain roadmap work.

Documentation

• Project charter
• Roadmap
• Research agenda
• Architecture
• Evidence model
• Integration contracts
• Dataset strategy
• Benchmark plan
• Security and privacy
• Brand and naming
• Name due diligence
• Data governance
• Start here

Contributing

Read CONTRIBUTING.md, the Code of Conduct, and the governance model. Small schema fixtures, adapters, provenance improvements, validation tests, and benchmark cases are excellent first contributions.

License

Apache License 2.0. See LICENSE.