Memory Port

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; for the adapters that ship, 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:

examples/memory-simple.ts (excerpt)

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: the in-process store, the Git store, and how to pass one to run().
Memory mechanics: ground, curate and consolidate over the port.
API: the Memory contract and the conformance kit.

Start

Concepts

Patterns

Examples

Evals and Gates

Recording Runs

Driving Runs

Surfaces and Hosts

Writing Workflow Shapes

Memory

Workspace

Compare

FAQ

API Reference

Run a command

Set storage limits

Name a path

Failure

Next steps

​Run a command

​Set storage limits

​Name a path

​Failure

​Next steps

Run a command

Set storage limits

Name a path

Failure

Next steps