Memory

Memory is OpenRath’s durable knowledge plane. It mirrors the sandbox/backend architecture, but stays independent from it: sandbox backends run side effects, memory backends store and retrieve knowledge.

flowchart LR
  A["flow.Agent"] --> B["Session"]
  A --> C["MemoryStore"]
  B --> D["BackendSandbox"]
  C --> E["MemoryBackend"]
  D --> F["Backend"]

Symmetry With Sandbox Backends

Sandbox plane	Memory plane	Role
Backend	MemoryBackend	Registry-selected implementation.
BackendSandbox	MemoryStore	Refcounted live handle.
BackendSandboxSpec	MemoryStoreSpec	User-facing open spec.
BackendTool*	MemoryOp*	Typed dispatch payload.
ToolResult	MemoryResult	Typed result or structured failure.

The planes do not cross-import. flow.Agent is the composition point because an agent may need both: a sandbox for tool execution and a memory store for durable recall.

Local Backend

The local backend ships with base openrath and is the default registered memory backend. It stores entries under .openrath/memory/local/ or under an explicit configured path.

Capability	Local behavior
write/read/list/tree	Filesystem-backed Markdown entries.
find/search	BM25 by default; optional embeddings when an embedding provider is configured.
resource ingest	Copies or fetches local/URL resources into the memory tree.
commit	Archives session messages and optionally extracts memories with a chat provider.

OpenViking Adapter

The OpenViking backend is optional and belongs behind openrath[openviking]. The public boundary remains memory://...; internal OpenViking identifiers such as viking://... stay inside the adapter.

This keeps workflows portable:

from rath import flow

agent = flow.Agent("Use project memory.", model="gpt-5.5", memory="local")
hits = agent.recall_memory("deployment notes")

Switching a store from local to OpenViking should change configuration, not workflow code.

Agent Memory Lifecycle

Step	API	Notes
Attach	flow.Agent(memory=...)	Accepts a store, store spec, backend/preset name, or None.
Explicit write	remember_memory(...)	Best for facts the app already knows are durable.
Recall	recall_memory(...)	Usually called before a model turn or by application code.
Commit	commit_memory(session, ...)	Extracts durable knowledge from a transcript.
Automatic commit	commit_on_forward=True	Best-effort; failures should not break the main model response path.

Design Boundaries

Boundary	Rule
Public URI	Use memory://... in user code and docs.
Adapter URI	Keep backend-specific schemes private.
Config	memory.providers selects store presets; llm.embedding_provider and llm.vlm_provider remain LLM config.
Stability	rath.memory is public API; adapter internals are not.

Test Coverage

Behavior	Tests
op/result dataclasses	tests/memory/unit/test_op_types.py, tests/memory/unit/test_results.py
registry/default backend	tests/memory/unit/test_registry.py, tests/memory/unit/test_default_backend.py
local backend operations	tests/memory/local_backend/test_local_memory_fs_ops.py, tests/memory/local_backend/test_local_memory_lifecycle.py
agent memory helpers	tests/flow/test_agent_memory_public_api.py, tests/flow/test_agent_forward_memory.py
OpenViking adapter	tests/memory/backends/test_openviking_io.py, tests/memory/backends/test_openviking_query.py

← Developer Notes