Module brain 

Brain (oxibrain) memory backend.

BrainMemoryBackend is the only durable-memory authority under the Oxi Foundation v1 host. The legacy local memory backends (memory_sqlite, memory_summary, memory_mnemopi, memory_workers, mnemopi) stay compilable during the migration window but are no longer durable: they are read-only mirrors, never write targets.

Wire protocol

oxibrain exposes its MCP tool surface over a Unix-domain socket via the JSON-RPC client in oxibrain-client. The daemon’s fifteen tools are search, recall, brief, navigate, ingest, declare, why, contradictions, stats, traverse, review_merges, remember, retract, merge_entities, redact. The backend maps every MemoryBackend method onto that real surface:

MemoryBackend method	oxibrain tool	args
put	remember	{"content": ..., "space": ..., "source_path": "oxicode/<kind>/<subject>"}
search	search	{"query": ..., "space": ..., "limit": N}
list	search	{"query": <subject>, "space": ..., "limit": 50}
delete	retract	{"statement_id": ...} (auditable retraction)

remember = ingest_note + synchronous extraction on the daemon side, so every put becomes a provenance-bearing episode. search returns entity hits (entity_id, entity_surface, entity_type, score, snippet), mapped into MemoryItem. Deletion is a statement-scoped retraction; ids that are not statement ids surface a typed error steering toward redact — never a silent local removal.

oxibrain-client uses Unix-domain sockets. On non-Unix targets this module compiles to a stub that returns BackendUnavailable for every call. The same memory_info constant is used in both targets so the TUI’s health banner reads “degraded” identically.

Structs

BrainMemoryBackend

Brain memory backend. The Arc<Mutex<Option<…>>> wrapper yields interior mutability on the optional client while keeping the MemoryBackend trait object signature (Arc<…>, no &mut).

Enums

BrainHealth

Health of the Brain connection. Surfaced via memory_info so the TUI health banner reports the state without leaking the underlying transport.

MigrationError

Migration-specific error type. Distinguishes the cases the migration core cares about: backend offline, write failure, runtime failure.

Constants

DEFAULT_BRAIN_SCOPE

Default space passed to oxibrain when one is not provided. personal is the daemon’s conventional default space; override with BrainMemoryBackend::with_scope (e.g. to route a project to its own bucket).

Functions

default_socket_path

Resolves the default socket path for the oxibrain daemon. Canonical per the Foundation discovery contract (mirror of oxibrain-client’s default_socket_path, which ships in 0.3.x; we pin 0.2 so the resolution lives here): $OXIBRAIN_SOCKET if set, else $HOME/.oxi/brain/oxibrain.sock. Never creates directories.