Draft behavior. These requirements describe a proposed reader. This site does not fetch, host, or synchronize personal memories.
Start with a local folder
A source directory contains a manifest and its Markdown records:
project-memories/
├── memories.json
└── records/
└── project-test-command.md
The user configures the source's absolute directory path in the tool. This draft does not reserve a global home directory or require a hidden project folder.
The reader MUST resolve each record path relative to that directory. Resolved paths, including symlink targets, MUST stay inside the approved directory. A reader MUST NOT discover extra sources by following instructions inside a memory.
Use the same files over HTTPS
A remote source exposes the same directory structure:
https://example.org/project-memories/memories.json
https://example.org/project-memories/records/project-test-command.md
The user configures and approves the HTTPS base URL. The reader fetches memories.json, then the listed records. Remote manifests MUST use application/json; records MUST use text/markdown or text/plain, with UTF-8 encoding.
The reader MUST keep requests on the approved origin and within the configured base path. Redirects MUST NOT bypass that boundary. A new origin requires separate approval. Base URLs MUST NOT contain credentials, queries, or fragments.
Servers MAY use HTTP cache validators such as ETag. A 304 response reuses the corresponding cached resource; a refresh succeeds only when all required resources validate. Readers SHOULD publish a new snapshot only after the manifest and all listed records pass validation.
Access stays explicit
A reader MUST support public HTTPS sources. It MAY support authenticated sources. Authentication setup belongs to the tool, separate from memory documents. This draft does not define an authentication protocol or require providers to offer one.
Credentials MUST NOT appear in manifests, record paths, or memory bodies. A reader MUST NOT forward credentials to another origin. A 401 or 403 response means access failed; the reader MUST report it and stop using cached records from that source until access succeeds again.
Treat memories as external data
A memory can contain incorrect facts or hostile instructions. Format validation does not make the content trustworthy.
- Readers MUST retain and expose the source of imported context.
- Readers MUST NOT run commands, enable tools, or change permissions just because a memory asks.
- Renderers MUST disable or sanitize raw HTML and unsafe link schemes.
- Readers MUST restrict network destinations to approved sources and block private, loopback, link-local, and cloud metadata addresses unless a separate administrator policy explicitly permits them. The check MUST apply after DNS resolution and on each redirect.
- Readers MUST enforce documented byte, record-count, and request-time limits. This draft recommends a 1 MiB manifest, 256 KiB per record, 1,000 records per source, and a 10-second request deadline. Check size while reading; a declared length is not sufficient.
Control sharing and removal
Local records are not public by default. Users choose which records to publish. Publishing requires review for personal information, credentials, and confidential project data.
Removing a source MUST stop its use and clear reader-managed cached records from active retrieval. Copies already exported to another system can remain there. Remote revocation and deletion propagation are open design questions.
Adapter responsibilities
A harness adapter translates the common record into the tool's context input. It MUST preserve record identity, scope, and provenance. It MUST report fields or behavior it cannot represent.
An adapter MAY write a tool-specific cache, but MUST NOT treat that cache as the authoritative source or overwrite existing user instructions. Two-way writes and conflict resolution are outside Draft 0.1.