Module memory_handler 

memory:// URL protocol handler.

Resolves the documented artifact paths from the autonomous memory pipeline against the Oxi Foundation v1 host’s durable-memory authority (the oxibrain daemon):

• memory://root → short listing of MEMORY.md, memory_summary.md, learned.md, and any skills/<name>/ directories.
• memory://root/MEMORY.md, memory://root/memory_summary.md, memory://root/learned.md → the corresponding artifact.
• memory://root/skills/<name>/SKILL.md → the skill playbook.

The router is resolved through the wired Oxicode InternalUrlRouter port. When the foundation daemon is unreachable (BrainHealth::Unavailable / Degraded), memory://root resolves to a listing whose first line is (degraded — durable memory is the oxibrain daemon; see \memory_info`)and per-file reads resolve to an empty marker. The handler never falls back to the legacy local file store: under the Foundation host, the daemon is the only authority, and silently reading from a disused file would duplicate memory across two systems (seedocs/superpowers/specs/2026-08-17-oxi-foundation-contract.md`).

Why read-only

memory:// URLs are observation paths, not write paths. The write path runs through the agent tools (memory_retain, memory_recall, memory_edit); they call BrainMemoryBackend directly. The handler cannot satisfy arbitrary write requests without violating the Foundation contract — it documents reads only and refuses writes.

Legacy disk-rooted resolver

The legacy resolver that read from <home>/memory/ is preserved as a free function — resolve_memory_url_legacy(url, memory_root) — so callers that haven’t migrated (unit tests, pre-Foundation hosts) keep compiling. Production code under the Foundation v1 host MUST use MemoryProtocolHandler.

Structs

MemoryProtocolHandler

The brain-backed protocol handler is read-only and degraded-friendly.

Functions

resolve_memory_url_legacy

Legacy disk-rooted resolver. Returns None on URL parse failure or when the candidate file is not within memory_root.