🦀 crates.io  ·  docs.rs API  ·  Rust implementation docs  ·  changelog

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.

Documentation Layout

Rust documentation intentionally mirrors the broader .me repo structure:

../docs/
  Global .me docs. Language-agnostic.

../Typescript/typedocs/
  TypeScript-specific docs generated with the TypeScript/VitePress stack.

docs/
  Rust-specific manual docs: quickstart, runtime host, CLI, benchmarks, parity,
  and integration notes.

https://docs.rs/this-me
  Rust API reference generated by rustdoc from the Rust source.

Start with docs/. Release notes live in CHANGELOG.md.

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.

Runnable Examples

The crate ships with small, tested examples under examples/:

cargo run --example quickstart
cargo run --example plural_selectors
cargo run --example operators
cargo run --example runtime_persistence
cargo run --example proof
cargo run --example wrapped_audience

Keep them honest with:

cargo test --examples

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"}'

Use about as a readable expression-binding prefix. It keeps --who and --secret as the identity/seed, then binds the active .me expression for the command that follows:

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

Quote expressions containing shell operators such as > so the terminal passes them to me instead of treating them as redirection.

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. The current crate release is this-me v0.3.3. The current recorded standalone benchmark run is this-me v0.3.0 Run #001 from Aug 26, 2026. See BENCHMARK_COMPARISON.md for the Rust-vs-TypeScript mirror suite. Run #002 records the this-me v0.3.1 source-versioned lazy invalidation fix.

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
cargo run --release --bin bench-mirror

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 write/read 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.