Metadata-Version: 2.4
Name: memora-swarm
Version: 0.1.4
Classifier: Programming Language :: Rust
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries
Summary: Bit-exact Byzantine-fault-tolerant state layer for federated learning and edge/defence swarms. Three layers — OR-Set CRDT (L1), an epistemic drift + human-in-the-loop layer (L2), and ACFA Q16.16 multi-Krum + G-Set (L3) — keep heterogeneous nodes byte-identical; one prompt-injected or equivocating node can't fork, poison, or move the agreed state. Every write is signed, attributable, and exactly replayable. Architected for large swarms; bit-exact by construction.
Keywords: ai-agents,multi-agent,crdt,byzantine,langchain,crewai,autogen
Author: mgillr
License: Apache-2.0
Requires-Python: >=3.9
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Documentation, https://memora.optitransfer.ch/docs
Project-URL: Homepage, https://memora.optitransfer.ch
Project-URL: Repository, https://github.com/mgillr/memora-swarm

# Memora

**A Byzantine-fault-tolerant state layer for large-scale federated learning and edge/defence swarms.**
Fixed-point Strong Eventual Consistency replaces non-deterministic IEEE-754 aggregation, so heterogeneous
nodes — ARM, x86, GPU — **never silently diverge**, even under partition, jamming, or adversarial poisoning.
One prompt-injected or rogue node is **mathematically unable to fork or poison** the shared state of the
rest — and every write is **signed, attributable, and exactly replayable**.

```bash
pip install memora-swarm
```

> You aren't paying for message delivery. You're paying for mathematical certainty that a single
> compromised node can't fork the swarm — and for a memory that knows when it can't vouch for itself.

One key is the **whole engine** — all three layers, unlimited agents, **no feature gates**. The
same math runs in the hosted cloud and, byte-for-byte, on-prem.

---

## The three layers

Every key gets all three. They compose: L1 keeps the shared state conflict-free, L2 decides whether
a resolved value is *believable right now*, and L3 makes numeric consensus Byzantine-robust.

### L1 · OR-Set CRDT + delta-state
Conflict-free replicated JSON beliefs. Concurrent writers merge deterministically, no locks, and the
swarm **never forks** — even on a network partition. Every write is Ed25519-signed by a
self-certifying node identity and appended to a replayable log, so any state is attributable and
auditable after the fact. Removes are author-signed tombstones (only the writer of a fact can retract it).

### L2 · Epistemic layer — *is this value believable now?*
Consensus is not the same as truth. The epistemic layer sits on the resolved value and decides
whether it is **current, un-drifted, and un-poisoned** before your agents act on it:

- **Distributional drift detection** — flags when the agreed value shifts beyond a poison-bounded envelope.
- **Derived-fact self-repair (DCER)** — a value derived from premises is re-checked against them; a
  contested premise raises a `DerivationConflict` instead of silently propagating.
- **Primitive grounding** — a leaf fact whose ground truth is external *by design* escalates for
  human/tool re-verification rather than being trusted on convergence alone.
- **Human-in-the-loop escalation** — anything the layer can't self-certify becomes a queryable,
  closeable escalation event (reason + stable id, never the payload). A human grounds it from the
  live dashboard or via `ground_escalation(...)`.
- **L3 semantic + L4 procedural memory, checkpoint/resume** — confirmed facts and situation→strategy
  mappings persist; a clean checkpoint lets a swarm resume without re-inheriting drift.

The rule: **agreement never promotes to authority — only external re-verification does.**

### L3 · ACFA · Q16.16 multi-Krum + G-Set
Byzantine-robust numeric aggregation. Up to *f* malicious agents in a group of ≥ 2f+3 **cannot move
the agreed result**. An agent that says different things to different peers (equivocation) is caught
by a self-certifying G-Set proof and its **key convicted for good** — no coordinator, no human needed. All
arithmetic is exact integer fixed-point (Q16.16), so an agent on ARM and one on x86 resolve to the
**identical byte sequence** — byte-identical roots, no float drift. Based on the ACFA paper:
[arXiv:2607.10305](https://arxiv.org/abs/2607.10305).

---

## Quickstart

```python
import memora_swarm as memora

# One key is the whole engine. Get a free key at https://memora.optitransfer.ch
db = memora.Blackboard("./swarm.memora", node_id="agent_12", api_key="opti_sk_...")
db.connect("research-swarm")          # join a room; every agent in it shares one memory

# ── L1: shared key/value state, CRDT-merged ───────────────────────────────
db.put("best_hypothesis", "H3")
print(db.get("best_hypothesis"))      # -> ['H3']  (get returns the set of current values)

# ── L3: Byzantine-tolerant numeric aggregation ────────────────────────────
db.submit_tensor("reward_estimate", [0.71, 0.68, 0.73], round=1)
vector, acfa_root, convicted = db.resolve(round=1, f=1)
print(vector, "convicted:", convicted)   # poisoners are evicted, not averaged in

# ── L2: the same aggregate, but epistemically checked ─────────────────────
# resolve_checked adds the drift verdict + escalation on top of the Byzantine-clean value.
vector, root, convicted, drift_json, authoritative = db.resolve_checked("reward_estimate", round=1, f=1)
if not authoritative:
    # the swarm could not self-certify this value (drift / unresolved premise / primitive fact)
    for esc in db.pending_escalations():   # reason + stable id, never the payload
        print("needs grounding:", esc)
    # a human (or a trusted tool) confirms it, closing the escalation
    # db.ground_escalation(escalation_id, confirmed=True)
```

No server to run: your key connects you to the hosted relay, which does the CRDT merge,
trust-weighting, epistemic checks and Byzantine aggregation for you.

### Full client surface
`put` / `get` · `submit_tensor` / `resolve` / `resolve_checked` · `pending_escalations` /
`ground_escalation` · `checkpoint` (clean-state snapshot) · `record_evidence` (trust signal) ·
`connect(room, room_f=...)`. Large values (> 15 KB) transparently offload to R2/S3 by content hash.

---

## Watch your swarm live

Every account gets a real-time dashboard — agents, ops/sec, Byzantine evictions, **per-room drift
status**, and the **human-in-the-loop escalation queue** (with a one-click *Ground* button that
resolves an escalation on the owning client). Telemetry is private to your key.
**https://memora.optitransfer.ch/monitor**

## Use it with your stack

Memora is a plain shared-memory backend, so it drops under the agent frameworks you already use —
**LangChain**, **CrewAI**, **AutoGen** — as poison-resistant shared memory / Byzantine-robust
voting. Copy-paste adapters: **https://memora.optitransfer.ch/docs**

## Pricing

**25,000 semantic ops free** on signup — unlimited agents, the full three-layer engine, no feature
gates. An "op" is a semantic state transition (a `put` or a `submit_tensor`); keepalive, sync, gossip
and reads are never billed. At 85% of the free allowance you're prompted to add a card so nothing
stops mid-run; after that it's metered at **$0.35 / 1,000 ops** ($0.20 / 1,000 above 2M/mo). The
same key upgrades in place — your swarm never re-keys.

## Links

- Home & docs — https://memora.optitransfer.ch
- Get a key (dashboard) — https://memora.optitransfer.ch/dashboard
- Live swarm monitor — https://memora.optitransfer.ch/monitor

Made under the [optitransfer.ch](https://optitransfer.ch) umbrella.

