(pkg-memory)=
# `rath.memory`

Memory backends, store handles, memory operations, typed results, registry helpers, and local/OpenViking adapter boundaries.

```{figure} ../_static/memory-plane.svg
:alt: OpenRath memory plane

Memory is a runtime plane beside sandbox execution: agents can read and write durable knowledge without coupling memory backends to tool backends.
```

## Source
| Module | Source |
| --- | --- |
| `rath.memory.abc` | `src/rath/memory/abc.py` |
| `rath.memory.op_types` | `src/rath/memory/op_types.py` |
| `rath.memory.results` | `src/rath/memory/results.py` |
| `rath.memory.registry` | `src/rath/memory/registry.py` |
| `rath.memory.adapters.local` | `src/rath/memory/adapters/local.py` |
| `rath.memory.adapters.openviking` | `src/rath/memory/adapters/openviking.py` |
| `rath.memory.persistence` | `src/rath/memory/persistence/` |

## Public contract
### Store lifecycle
| API | Behavior |
| --- | --- |
| `MemoryBackend.open(spec=None)` | Opens a store handle with `refcount == 0`. Bind it to an agent or enter `with store:` before holding it. |
| `MemoryStore.acquire()` / `release()` | Adds or drops one reference; final release calls `backend.close(store)`. |
| `MemoryStore.dispatch(op)` | Applies a `MemoryOp*` payload and returns a typed `MemoryResult`. |
| `MemoryStoreSpec.from_config(name=None)` | Reads `memory.providers` from `~/.openrath/config.json`; currently models local store presets. |

### Operations and results
| Operation | Purpose | Typical result |
| --- | --- | --- |
| `MemoryOpWrite` | Write or replace text at a `memory://...` URI. | `MemoryWriteResult` |
| `MemoryOpRead` | Read one entry at abstract/overview/detail level. | `MemoryReadResult` |
| `MemoryOpList` / `MemoryOpTree` | List entries under a URI. | `MemoryListResult` |
| `MemoryOpFind` | Semantic or lexical search. | `MemoryFindResult` with `MemoryHit` rows |
| `MemoryOpSearch` | Intent-aware search when a backend supports it. | `MemoryFindResult` |
| `MemoryOpResource` | Ingest a file, directory, or URL resource. | Backend-specific result or `MemoryExecutionFailure` |
| `MemoryOpCommit` | Archive a session and extract durable memory. | `MemoryCommitResult` |

### Registry
| Function | Behavior |
| --- | --- |
| `register(name)` | Decorator that registers a `MemoryBackend` class. |
| `list_names()` | Returns registered memory backend names. |
| `get(name)` / `get_class(name)` | Returns a backend instance or registered class. |
| `is_available(name)` | Checks registration plus backend availability. |
| `preferred(names)` | Returns the first available backend instance. |
| `set_default(name)` / `current()` | Sets and gets the default backend. The base install defaults to `local`. |

### Built-in adapters
| Backend | Availability | Notes |
| --- | --- | --- |
| `local` | Ships with base `openrath`. | Persists under `.openrath/memory/local/`, supports read/write/list/tree, BM25 search, optional embedding search, resources, and session commit. |
| `openviking` | Optional `openrath[openviking]`. | Connects to OpenViking and maps public `memory://` operations to the backend's internal URI and extraction APIs. |

## Agent integration
`flow.Agent(memory=...)` accepts a `MemoryStore`, `MemoryStoreSpec`, a configured backend/preset string such as `"local"`, or `None`.

| Agent API | Behavior |
| --- | --- |
| `remember_memory(...)` | Writes explicit memory content. |
| `recall_memory(...)` | Searches attached memory and returns hits. |
| `commit_memory(session, ...)` | Commits a session transcript for archive and extraction. |
| `memory_inject=True` | Injects recalled memory into the prompt path. |
| `commit_on_forward=True` | Best-effort commit after each agent forward call. |

## URI boundary
OpenRath exposes `memory://...` as the public user-facing URI scheme. Adapter-specific schemes such as OpenViking's internal `viking://...` stay inside the adapter and should not appear in portable OpenRath workflows.

## Autodoc
```{eval-rst}
.. autoclass:: rath.memory.MemoryBackend
   :members:

.. autoclass:: rath.memory.MemoryStore
   :members:

.. autoclass:: rath.memory.MemoryStoreSpec
   :members:

.. autoclass:: rath.memory.MemoryCapabilities
   :members:

.. autoclass:: rath.memory.ScopeModel
   :members:

.. autoclass:: rath.memory.MemoryOp
   :members:

.. autoclass:: rath.memory.MemoryOpWrite
   :members:

.. autoclass:: rath.memory.MemoryOpRead
   :members:

.. autoclass:: rath.memory.MemoryOpList
   :members:

.. autoclass:: rath.memory.MemoryOpTree
   :members:

.. autoclass:: rath.memory.MemoryOpFind
   :members:

.. autoclass:: rath.memory.MemoryOpSearch
   :members:

.. autoclass:: rath.memory.MemoryOpResource
   :members:

.. autoclass:: rath.memory.MemoryOpCommit
   :members:

.. autoclass:: rath.memory.MemoryHit
   :members:

.. autoclass:: rath.memory.MemoryEntry
   :members:

.. autoclass:: rath.memory.MemoryFindResult
   :members:

.. autoclass:: rath.memory.MemoryReadResult
   :members:

.. autoclass:: rath.memory.MemoryListResult
   :members:

.. autoclass:: rath.memory.MemoryWriteResult
   :members:

.. autoclass:: rath.memory.MemoryCommitResult
   :members:

.. autoclass:: rath.memory.MemoryExecutionFailure
   :members:

.. autofunction:: rath.memory.register

.. autofunction:: rath.memory.list_names

.. autofunction:: rath.memory.get

.. autofunction:: rath.memory.get_class

.. autofunction:: rath.memory.is_available

.. autofunction:: rath.memory.preferred

.. autofunction:: rath.memory.set_default

.. autofunction:: rath.memory.current

.. autoexception:: rath.memory.MemoryBackendError

.. autoexception:: rath.memory.MemoryBackendNotFound

.. autoexception:: rath.memory.MemoryStoreClosed

.. autoexception:: rath.memory.UnsupportedMemoryOp

.. autoexception:: rath.memory.MemoryNotFound

.. autoexception:: rath.memory.MemoryConflict
```

[← API Reference](index.md)