> ## Documentation Index
> Fetch the complete documentation index at: https://obversa.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Memory Port

> One command contract for reading and writing memory files, whatever stores them.

Read and write memory files through one small contract, and switch the
store without touching the step that uses it. Use the `Memory` port from
`@obversa/api` when a job needs files it can open again in a later run; the
runtime accepts any adapter that implements it. For what memory is for,
read [Memory](/docs/concepts/memory); for the adapters that ship,
[Memory adapters](/docs/memory/adapters).

The port has a `scope` and one `execute` method that takes a command. The
smallest use creates a file and reads it back:

```ts examples/memory-simple.ts (excerpt) {2-3,7} theme={null}
const memory = createSimpleMemory({ scope: 'memory-simple-example' });
await memory.execute({
  command: 'create',
  path: '/memories/notes.md',
  text: 'Keep the result small.\n',
});
const result = await memory.execute({
  command: 'view',
  path: '/memories/notes.md',
});
```

Every path starts with `/memories`. A result has `ok: true` and a typed
value, or `ok: false` and a typed error with the command, the error code and
a message; some errors also carry the path and structured details. Every
adapter uses the same error codes, and a conformance kit checks the
contract without a network service. A command needs:

* **`command`**, one of the six below.
* **`path`**, under `/memories`, or `oldPath` and `newPath` for `rename`.
* **The command's own fields**: `text`, `viewRange`, `oldText` and
  `newText`, or `insertLine`.

## Run a command

| Command | Result |
| - | - |
| `view` | Reads a file, a line range, or a directory. `viewRange: [start, end]` reads selected lines; line numbers start at 1, and `-1` as the end reads the rest of the file. |
| `create` | Creates a file, or replaces it if the path exists. |
| `str_replace` | Replaces one unique text value. It fails on zero matches or more than one non-overlapping match. |
| `insert` | Inserts text at a zero-based line slot. `insertLine: 0` inserts before the first line, `1` after it. An insert rewrites the file with `\n` line endings; a full view and a text replacement preserve the stored line endings. |
| `delete` | Deletes a file, or a directory and every file below it. |
| `rename` | Moves a file or a complete directory. It doesn't replace an existing destination. |

## Set storage limits

`@obversa/memory-simple` and `@obversa/memory-git` use these defaults:

* **One file** can contain 65,536 bytes.
* **One scope** can contain 1,048,576 bytes and 256 files.
* **File types**: `.txt`, `.md`, `.json`, `.py`, `.yaml` and `.yml`.

When a write takes a scope past a limit, the adapter removes files in order
of earliest write time until the write fits. A read doesn't change a file's
write time, and the adapter never removes the file being written.

## Name a path

A path can contain letters, numbers, periods, underscores and hyphens. Each
segment can contain 128 characters, and a complete path 1,024 bytes. A scope
and all written text must be complete Unicode: the adapters reject
malformed Unicode instead of replacing incomplete characters. The memory
root can't be a file, and you can't delete or rename it.

## Failure

| Area | Error codes |
| - | - |
| Command input | `INVALID_COMMAND`, `INVALID_ARGUMENT` |
| Paths and files | `INVALID_PATH`, `ROOT_PROTECTED`, `INVALID_EXTENSION`, `PATH_CONFLICT` |
| Missing or existing data | `NOT_FOUND`, `ALREADY_EXISTS` |
| Text and line selection | `INVALID_RANGE`, `MATCH_NOT_FOUND`, `MATCH_NOT_UNIQUE` |
| Limits and concurrent writes | `LIMIT_EXCEEDED`, `CONFLICT` |
| Adapter storage | `UNSAFE_STORAGE`, `STORAGE_ERROR` |

## Next steps

* [Memory adapters](/docs/memory/adapters): the in-process store, the Git
  store, and how to pass one to `run()`.
* [Memory mechanics](/docs/memory/mechanics): `ground`, `curate` and
  `consolidate` over the port.
* [API](/docs/packages/api): the `Memory` contract and the conformance kit.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.