Rust .me

Rust ground for the modern .me semantic kernel.

This crate is the Rust port of the TypeScript .me kernel, kept faithful to the same semantic model: append-only memories, hash-chain integrity, path grammar, operators, secret/noise scopes, derivations, inspection, proofs, key wrapping, snapshots, and live runtime events.

The goal is not to invent a second .me. The goal is to carry the same kernel meaning into a smaller, stricter runtime that can eventually live closer to hardware: a daemon, a local gateway, a Raspberry Pi, a vehicle computer, an embedded agent, or a future monad.ai host.

What Exists

The Rust kernel currently includes:

• hash-chained semantic memory,
• public and owner projections,
• canonical path parsing with selectors such as items[], items[0], and items[field >= 10],
• the main .me operators:
  • @ identity,
  • _ secret scope,
  • ~ noise scope,
  • __ pointer,
  • = derivation,
  • ? query/collect,
  • - remove/tombstone,
• operator registry and semantic replay,
• eager and lazy derivation recompute modes,
• inspect() and explain() traces,
• secret value encryption using the v3 blob material model,
• WrappedSecretV1 key wrapping with P-256 ECDH and AES-GCM,
• Ed25519 .prove() identity proofs,
• canonical me:// execute dispatch,
• JSON snapshot storage,
• a reusable KernelRuntime host with write-through persistence,
• live runtime events with path filtering,
• runtime receipts for host integrations,
• a small me CLI,
• Rust contract tests against TypeScript fixtures,
• and release-mode benchmark binaries.

Install And Verify

From this directory:

cargo fmt --check
cargo check
cargo test
cargo clippy --all-targets --all-features -- -D warnings

That is the standard gate for this crate. A green run means formatting, compilation, semantic contracts, CLI contracts, fixture parity, and clippy all pass.

Quick Kernel Example

use this_me::kernel::{Kernel, Value};

let mut me = Kernel::new();

me.postulate("profile.name", "Jabellae")?;
me.postulate("wallet.income", 100_u64)?;
me.postulate("wallet.expenses", 40_u64)?;
me.derive("", "wallet.total", "wallet.income - wallet.expenses")?;

assert_eq!(me.read("wallet.total"), Some(&Value::from(60_u64)));

The memory log remains append-only. Reads are the latest projection of that history.

Runtime Host

Kernel is the semantic core. KernelRuntime<S> is the host wrapper: it loads a kernel from a MemoryStore, performs writes or me:// executions, persists the snapshot, and returns live events.

use this_me::runtime::{runtime_receipt_to_json, KernelRuntime};
use this_me::storage::JsonFileStore;

let store = JsonFileStore::new("/tmp/me-state.json");
let mut runtime = KernelRuntime::load(store)?;

let receipt = runtime.write_with_receipt(
    "apps.fulltrailer.home.count",
    3_u64,
)?;

let json = runtime_receipt_to_json(&receipt);
println!("{json}");

Receipts have a stable host-facing shape:

{
  "result": "... operation result ...",
  "events": [
    {
      "path": ["apps", "fulltrailer", "home", "count"],
      "operator": null,
      "value": 3.0,
      "memoryHash": "..."
    }
  ]
}

That shape is meant for HTTP/WS hosts: execute once, persist once, broadcast the events generated by that operation.

CLI

Use the local CLI against an optional JSON snapshot file:

cargo run -- --state /tmp/me-state.json write profile.name '"Jabellae"'
cargo run -- --state /tmp/me-state.json read profile.name
cargo run -- --state /tmp/me-state.json exec me://self:write/wallet.income 1000
cargo run -- --state /tmp/me-state.json inspect profile
cargo run -- --state /tmp/me-state.json explain wallet.total
cargo run -- --state /tmp/me-state.json snapshot

Without --state, the CLI runs an ephemeral kernel. With --state, it uses the same KernelRuntime host path used by embedders.

Produce a branch-scoped proof:

cargo run -- --who jabellae --secret 'correct horse battery staple' prove local.netget '{"nonce":"n-1"}'

Equivalent seed mode:

cargo run -- --seed '<seed>' --expression jabellae prove local.netget '{"nonce":"n-1"}'

Events

Runtime events are live process state. They are intentionally not persisted in snapshots. Snapshots persist semantic memory, not transient notification queues.

Drain all events:

cargo run -- --state /tmp/me-state.json exec me://kernel:drain/events

Read or drain events matching a path:

cargo run -- --state /tmp/me-state.json exec me://kernel:read/events/apps.fulltrailer
cargo run -- --state /tmp/me-state.json exec me://kernel:drain/events/apps.fulltrailer

Filters use the same ancestor/descendant rule as monad's NRP path stream: subscribing to apps.fulltrailer receives changes at that path, below it, or replacing one of its ancestors.

Storage

JsonFileStore persists owner snapshots as JSON:

use this_me::storage::{JsonFileStore, MemoryStore};

let store = JsonFileStore::new("/tmp/me-state.json");
let kernel = store.load_kernel()?;
store.save_kernel(&kernel)?;

Hydration verifies the memory hash chain. Tampered snapshots fail closed.

Cryptography

The Rust port includes two cryptographic surfaces:

• Ed25519 proofs for .prove() identity signatures.
• WrappedSecretV1 using P-256 ECDH key agreement and AES-GCM wrapping.

Secret branches use the same v3 material model as the TypeScript kernel fixtures covered by the test suite.

Contracts

The test suite is contract-first. Important files:

• tests/axioms_contract.rs - algebraic invariants.
• tests/kernel_contract.rs - core kernel behavior.
• tests/path_contract.rs - path and selector grammar.
• tests/execute_contract.rs - canonical me:// dispatch.
• tests/event_contract.rs - live event queue and filters.
• tests/runtime_contract.rs - host persistence, receipts, event behavior.
• tests/storage_contract.rs - JSON snapshot storage.
• tests/proof_contract.rs - Ed25519 proofs.
• tests/keyspace_contract.rs - keyspace manifest and wrapped keys.
• tests/wrapped_secret_contract.rs - WrappedSecretV1 crypto.
• tests/typescript_fixture_contract.rs - parity with TypeScript memory fixtures.

Benchmarks

See BENCHMARKS.md for the benchmark map.

Run benchmarks in release mode:

cargo run --release --bin bench-ok
cargo run --release --bin bench-sustained
cargo run --release --bin bench-fanout
cargo run --release --bin bench-cold-warm
cargo run --release --bin bench-explain-overhead
cargo run --release --bin bench-secret-scope
cargo run --release --bin bench-push-pull
cargo run --release --bin bench-secret-push-pull

Benchmarks are not hard pass/fail thresholds yet. They are there to keep the shape honest: O(k) recompute behavior, sustained mutation, fan-out, cold/warm hydration, explain overhead, secret cost, and eager/lazy tradeoffs.

Module Map

src/kernel/mod.rs             core memory, operators, projections
src/kernel/path.rs            path and selector grammar
src/kernel/evaluator.rs       derivation expression evaluator
src/kernel/execute.rs         me:// dispatch
src/kernel/json.rs            JSON codecs
src/kernel/proof.rs           Ed25519 proof support
src/kernel/secret_material.rs secret/noise material derivation
src/kernel/wrapped_secret.rs  WrappedSecretV1
src/storage.rs                MemoryStore + JsonFileStore
src/runtime.rs                KernelRuntime host + receipts
src/me_uri.rs                 canonical me:// URI parser/projection
src/main.rs                   me CLI

Current Status

This is now a real Rust kernel, not boilerplate.

It is ready for deeper parity testing and host integration work. It is not yet a drop-in replacement for the TypeScript kernel inside monad.ai; that next phase needs an explicit integration layer, packaging decision, and HTTP/WS host surface.

The rule remains simple: Rust can improve mechanics, memory safety, and runtime shape, but it must not change .me meaning to chase a number.