mirror of
https://github.com/PR0M3TH3AN/TORCH.git
synced 2026-10-27 07:51:52 +00:00
84 lines
2.3 KiB
Markdown
84 lines
2.3 KiB
Markdown
# Memory Events Contract
|
|
|
|
This contract defines the merge-safe memory pipeline used by `torch-lock memory`.
|
|
|
|
## Source of Truth
|
|
|
|
- Append-only event files:
|
|
- `memory/events/YYYY/MM/DD/<timestamp>_<id>.json`
|
|
- Event schema:
|
|
- `memory/schema/memory-event.schema.json`
|
|
- Generated artifact:
|
|
- `memory_update.md`
|
|
|
|
## Commands
|
|
|
|
### `torch-lock memory add`
|
|
|
|
Writes exactly one new event file.
|
|
|
|
Required flags:
|
|
- `--agent`
|
|
- `--topic`
|
|
- one of `--message` or `--message-file`
|
|
|
|
Optional flags:
|
|
- `--created-at` (RFC3339 UTC, default: now)
|
|
- `--id` (UUIDv7, default: generated)
|
|
- `--run-id`
|
|
- `--tags` (comma-separated)
|
|
- `--source`
|
|
- `--project` (defaults to `TORCH`; non-`TORCH` is rejected by schema)
|
|
- `--events-dir` (default: `memory/events`)
|
|
- `--schema-path` (default: `memory/schema/memory-event.schema.json`)
|
|
|
|
Behavior:
|
|
- Validates event against schema contract before writing.
|
|
- Enforces append-only naming: `<timestamp>_<id>.json`.
|
|
- Fails if target file already exists.
|
|
|
|
### `torch-lock memory build`
|
|
|
|
Builds deterministic markdown from all events.
|
|
|
|
Optional flags:
|
|
- `--events-dir` (default: `memory/events`)
|
|
- `--schema-path` (default: `memory/schema/memory-event.schema.json`)
|
|
- `--output` (default: `memory_update.md`)
|
|
|
|
Behavior:
|
|
- Loads and validates all event JSON files.
|
|
- Enforces filename/date/id contract.
|
|
- Fails on duplicate ids.
|
|
- Sorts by `(created_at ASC, id ASC, relative_path ASC)`.
|
|
- Emits auto-generated header:
|
|
- `<!-- AUTO-GENERATED: DO NOT EDIT. Source: memory/events -->`
|
|
- Normalizes output to LF newlines and one trailing newline.
|
|
|
|
### `torch-lock memory verify`
|
|
|
|
Verification gate for CI and branch safety.
|
|
|
|
Optional flags:
|
|
- `--events-dir` (default: `memory/events`)
|
|
- `--schema-path` (default: `memory/schema/memory-event.schema.json`)
|
|
- `--output` (default: `memory_update.md`)
|
|
|
|
Behavior:
|
|
- Re-validates all events + path contract.
|
|
- Re-renders twice (determinism guard).
|
|
- Fails if output file is missing header.
|
|
- Fails if output file bytes differ from deterministic render (no-diff gate).
|
|
|
|
## Exit Codes
|
|
|
|
- `0`: success
|
|
- `1`: usage error (missing/invalid CLI arguments)
|
|
- `4`: memory contract violation
|
|
- schema invalid
|
|
- filename/date mismatch
|
|
- duplicate event id
|
|
- deterministic render mismatch
|
|
- generated file missing header
|
|
- generated file out of date
|