Apeireth/Apeireth

What Apeireth is

Apeireth is a privacy‑first, desktop‑based AI companion written in safe Rust. It runs entirely on the user’s machine (Windows, Linux and macOS) and is designed to remember facts about you, act only when you allow it, and never perform irreversible actions without explicit approval. The project is split into a collection of crates (foundation, engine, capabilities, adapters) that together implement a rule‑engine‑driven “care” system, a five‑layer hybrid memory store, and a strict governance layer that enforces “one approval → one side‑effect”.

---

Core capabilities (as documented)

Capability	How it works (high‑level)	Current status
Memory	Append‑only, hash‑chained fact stream with two timestamps (event time + record time). Retrieval combines lexical, semantic, and recency activation layers; older facts decay on a “memory curve” unless marked protected.	Implemented – on by default
Emotion & care	A “care potential field” that can be enabled via APEIRETH_ENABLE_CARE. When active, a rule engine decides when to speak, how long to stay silent, and which gestures to offer. Voice output is tone‑modulated only if emotion readings exist.	Implemented – off by default
Work & trust	Five‑stage execution pipeline with read‑before‑write guards, sandbox escalation ladder, and a two‑tier atomic‑write model. Actions are classified into risk tiers; any tier‑1 (irreversible) operation requires a human‑approved “approval card”.	Implemented
Multi‑household clustering	Each household gets its own users/<id>/ domain with isolated data planes (memory, quota, ledger). Cross‑domain reads/writes are rejected. A partner instance runs a separate runtime, so personalities never migrate between households.	Implemented
Provider adapters	Supports three live LLM back‑ends (OpenAI‑compatible, MiniMax, Anthropic). Gemini and OpenAI‑Responses are only protocol normalizers and are not wired as providers yet.	Implemented
SDK / CLI / Tauri UI	CLI (apeireth‑cli), a Tauri‑based desktop companion, and a terminal UI (apeireth‑tui). The SDK’s WebSocket transport is currently a stub; the HTTP server does not expose the WS endpoint.	UI and CLI functional; SDK WS stub

---

Architecture at a glance

+--------------------------------------------------------------+
|  Faces:  companion‑desktop (Tauri) • apeireth‑tui • CLI      |
+--------------------------------------------------------------+
|  Adapters: gateway (HTTP/SSE, token gate) • SDK • CLI • TUI |
+--------------------------------------------------------------+
|  Assembly: runtime‑assembly (production.rs defaults, quota, |
|            approvals)                                        |
+--------------------------------------------------------------+
|  Engine: memory • provider • organ • runtime                |
+--------------------------------------------------------------+
|  Foundation: core (onion/user_domain) • protocol •          |
|            credentials • governance                         |
+--------------------------------------------------------------+

• Foundation – pure‑Safe‑Rust core crates, no unsafe code. Handles user‑domain isolation, credential storage (OS keyring when available, plaintext fallback), and the double‑onion permission model.
• Engine – implements the memory stream, LLM provider integration, and the “organ” modules that perform side‑effects (file write, git write, etc.) under strict approval checks.
• Adapters – expose HTTP/SSE gateways and the (currently stubbed) WebSocket SDK for external clients.
• Faces – the user‑facing applications: a Tauri desktop window with animated UI, a terminal UI, and a command‑line client.

---

Getting started (user view)

1. Install – download the Windows installer from the Releases page (SHA‑256 verified) or build from source (cargo build --release -p apeireth-cli plus pnpm build for the Tauri UI).
2. Run – launch the desktop icon, pick an LLM provider, and enter your API key. The key is stored in the OS keyring when possible; otherwise it falls back to an environment variable or an in‑memory store.
3. Interact – speak or type; Apeireth will answer using your own words drawn from its memory. Adjust personality sliders in Settings; each change is persisted in the memory ledger.
4. Verify – the README points to a “five‑minute independent verification” consisting of three CLI commands that check the hash‑chain integrity, the approval‑state machine, and the budget‑gate enforcement.

---

Safety & trust mechanisms (the “trust, but verify” section)

• Zero‑unsafe Rust – the whole workspace forbids unsafe; this eliminates undefined behaviour.
• Hash‑chained append‑only memory – every fact is linked to the previous one, making tampering detectable.
• Budget gate – three dimensions (tokens, tool steps, micro‑cost) are tracked per session; exceeding any limit aborts the operation rather than silently throttling.
• Approval cards – irreversible actions (file deletion, money transfer, rule changes) require a one‑time human approval; the system records the approval and guarantees exactly one side‑effect.
• Honest boundaries – the README lists every feature that is defined but not wired (e.g., WebSocket server, P2P mesh, onion DSL layer). These are deliberately disabled and clearly marked, so users know what is unavailable.
• Exportable data – memories, ledgers, and skills can be packed, verified, and moved to another machine; credentials never travel with the export.

---

What is not yet wired (honest gaps)

Gap	Description
WebSocket 8‑frame full‑duplex	Protocol defined, but no /v1/ws HTTP route.
P2P mesh	Plaintext mesh only; no Noise handshake, no onion routing.
SDK transport	Stub implementation (unimplemented!()).
Third‑layer DSL onion	Code exists but is disabled unless APEIRETH_ENABLE_ONION_LAYER=1.
Backup export	Feature exists but is off by default (APEIRETH_ENABLE_BACKUP_EXPORT=1).

---

Who might find this useful?

• Privacy‑conscious users who want an AI assistant that never sends personal data off‑device.
• Developers interested in a Rust‑first, formally‑checked AI‑agent framework with explicit governance.
• Researchers exploring rule‑engine‑driven care models, hybrid memory retrieval, or safe‑by‑design AI execution pipelines.

---

Where to learn more

• Documentation map – docs/ contains a test baseline, capabilities matrix, core‑mechanism guides, and internal delivery records.
• Roadmap & status – badges show the project is in an internal release‑candidate stage (rc internal test).
• License – dual‑licensed under Apache‑2.0 OR MIT, allowing both permissive and copyleft use.

---

Bottom line: Apeireth is a fully‑functional, on‑device AI companion that emphasizes data sovereignty, auditable memory, and strict human‑in‑the‑loop control. Its codebase is organized as a 31‑crate Rust workspace, all written without unsafe, and it openly documents every capability that is still missing.