Draft 0.1 · Request for feedback. This is a proposed contract. It is not an adopted standard, and no tool compatibility is claimed.
One memory, one document
A memory record is a UTF-8 Markdown file with YAML front matter. For example, a project can record its test command once and make that record available to different agents.
---
openmemories: '0.1'
id: 'project-test-command'
title: 'Project test command'
kind: 'project'
scope: 'https://example.org/team/project'
created: '2026-11-12T12:00:00Z'
updated: '2026-11-12T12:00:00Z'
provenance:
source: 'https://example.org/team/project/README.md'
---
Run `bun test` before proposing a change.
The test suite needs no network access.
The example records project context. It does not grant permission to run a command.
Required fields
In this draft, MUST, SHOULD, and MAY mean required, recommended, and optional behavior for a conforming reader or writer.
| Field | Type | Requirement |
|---|---|---|
openmemories | String | MUST be "0.1" for this draft. |
id | String | MUST be nonempty and stable within its source. |
title | String | MUST be a short, nonempty description. |
kind | String | MUST be preference, project, fact, or procedure. |
scope | String | MUST be user or an absolute URI identifying the relevant project or subject. |
created | String | MUST be an RFC 3339 UTC timestamp ending in Z. |
updated | String | MUST use the same timestamp format, at or after created. |
The Markdown body MUST contain nonempty text. Readers MUST reject duplicate YAML keys, custom YAML tags, and aliases. Front matter MUST be a mapping. This keeps the metadata small and limits parser differences.
Optional metadata
| Field | Type | Meaning |
|---|---|---|
tags | Array of strings | Search and grouping hints. |
provenance | Object | An optional source URI and author string. Describes origin; it does not prove authenticity. |
expires | String | UTC timestamp after which the record MUST NOT be used. |
supersedes | Array of strings | Record IDs in this source that this record replaces. |
Extension keys MUST start with x-. Readers MUST ignore unknown extension keys. Writers that edit a record SHOULD retain them. Readers MUST reject an unsupported openmemories version rather than assume compatibility.
A source manifest
A source is a collection of records with one memories.json manifest. The following manifest points to the test-command record:
{
"openmemories": "0.1",
"name": "Project knowledge",
"memories": [
{
"id": "project-test-command",
"path": "records/project-test-command.md"
}
]
}
name MUST be a nonempty string. memories MUST be an array of objects with nonempty string id and path values. Each ID and path MUST be unique within the manifest. A record's id MUST match its manifest entry. An empty array is valid.
Paths MUST be relative, slash-separated paths ending in .md. Paths MUST NOT contain a scheme, authority, leading slash, backslash, empty segment, . or .. segment, percent escape, query, or fragment. Readers MUST enforce source boundaries after resolving paths and local symlinks. Cross-source references are outside this draft.
Identity and updates
A record's identity is the pair configured source identity + record ID. Matching IDs from two sources MUST remain separate. A configured source identity is an absolute local directory path or an HTTPS base URL. Moving a source requires an explicit configuration change; automatic identity migration is outside this draft.
Writers MUST retain the ID when updating a memory and MUST advance updated. A record replaces another record only when supersedes names it within the same source. Readers MUST NOT select a winner across sources only because one timestamp is later. Missing targets and replacement cycles MUST be reported; affected replacements MUST NOT apply.
Removing an entry from the manifest removes it from the active collection after a successful refresh. This is not a request to erase previously exported copies. Readers MUST discard expired and superseded records from active context, including cached context.
Reader contract
- Read only sources approved by the user or administrator.
- Validate the manifest, version, paths, metadata, and source boundaries before use.
- Keep the source identity, record ID, and retrieval time with each imported record.
- Apply scope, expiration, and replacement rules before selecting context.
- Keep imported content below system, developer, and explicit user instructions in authority.
- Make source failures and rejected records visible. Never silently write remote content into local instruction files.
A failed refresh MUST NOT appear as an empty successful refresh. Readers MAY retain the last successful snapshot, but MUST mark it stale and reapply expiration rules. A 401 or 403 response MUST disable use of that source's cached records until access succeeds again.
What this draft leaves open
Write APIs, automatic synchronization, merge algorithms, cryptographic signatures, encrypted records, and deletion propagation need separate proposals. Embeddings and ranking are implementation choices. Markdown portability does not guarantee that two models interpret a memory in the same way.