Append-only Event Log + /v1/events

[valiantone]

Summary

Introduce an append-only event log — an immutable stream of memory lifecycle events enabling replay, recovery, synchronization, and deterministic reconstruction.

Scope

• Event vocabulary: MemoryAdded, MemoryUpdated, MemoryMerged, MemoryArchived, SnapshotCreated, PromotionRequested.
• Each event: id, type, timestamp, target memory id(s), before/after payloads as needed, sequence number.
• Storage: append-only (SQLite table or JSONL log file under the mount) with monotonically increasing sequence; no in-place updates/deletes.
• Replay API: reconstruct memory state from the event stream (deterministic; used for recovery/sync, not the hot read path).
• GET /v1/events with cursor + limit (tail-style), for consumers/sync.
• Emit events from existing write paths (add/update) without changing their external behavior.

Out of scope: distributed sync protocol, cross-instance replication (EMOS-side).

Acceptance Criteria

• Every add/update/merge/archive/snapshot/promotion-request emits exactly one event
• Events are append-only; sequence numbers are monotonic and gap-free per emitter
• Replay from an empty state reconstructs current memory state deterministically
• GET /v1/events supports cursor + limit pagination
• Event emission does not alter existing /v1/add//v1/search behavior or latency materially
• Event log survives restart (durable under the mount)

Migration

Additive. Event log starts empty; existing memories are unaffected (a baseline snapshot can seed the log on first vNext boot, documented in the RFC).

Testing

• Unit: each lifecycle path emits the correct event type + payload.
• Unit: replay reconstruction matches direct DB state for a fixture workload.
• Unit: append-only guarantee (no update/delete of log rows); monotonic sequence.
• Unit: /v1/events pagination returns contiguous, ordered results.

Depends on

• Memory Record v2 schema + provenance + migration #36 (event payloads reference the v2 record shape)
• RFC: File-Aware Memory Sidecar architecture + roadmap #35 (event vocabulary + replay semantics ratified)

[valiantone]

Design addendum from recent OKF planning:

Compatibility constraints:

• Event logging must be additive and must not alter /v1/add, /v1/search, JSONL hydrate, or snapshot defaults.
• Existing stores can start with an empty event log. No forced replay migration should be required.

Scope constraints:

• The event log is for local audit, replay, recovery, and future sync hooks.
• It is not a distributed sync protocol and not an EMOS memory hierarchy.
• EMOS owns cross-instance replication, durable hierarchy movement, and lineage reconstruction beyond local provenance.

Implementation constraints:

• Events should be append-only with monotonic sequence numbers.
• Replay should deterministically reconstruct local memory state for supported events.
• Event log growth should produce future local hygiene hints, not write-blocking behavior.
• A baseline snapshot can seed event history later, but that should be documented and optional.

[valiantone]

Planning sync: this ticket remains the append-only local event-log work. The expanded OKF epic adds related tickets for compatibility tests, bundle support, inspectors, optional indexing, local hygiene hints, and native-helper exploration. Those will be created separately and linked back here so #41 stays focused on durable local events and deterministic replay.

[valiantone]

Expanded filesystem-first implementation set:

Core existing vNext spine:

• File-backed memories (URI + range + checksum hydration) #38 File-backed memories
• Snapshot v2 directory format (manifest + jsonl + attachments) #39 Snapshot directory format
• Hydration Profiles (agent/compact/audit/full) #40 Hydration Profiles
• Append-only Event Log + /v1/events #41 Append-only Event Log
• Promotion lifecycle (HOT→READY→PROMOTED→ARCHIVED, signal only) #42 Promotion lifecycle
• API extensions (/v1/files, /v1/export, hydrate params) #43 API extensions

New supporting tickets:

• Compatibility golden tests for file-native evolution #54 Compatibility golden tests for file-native evolution
• Bundle Store: loose local markdown bundle reader #52 Bundle Store: loose local markdown bundle reader
• Bundle indexing and discovery #50 Bundle indexing and discovery
• Lightweight file inspectors for CSV, JSONL, and Parquet metadata #53 Lightweight file inspectors for CSV, JSONL, and Parquet metadata
• Optional derived vector index #49 Optional derived vector index
• Local hygiene and store growth warnings #51 Local hygiene and store growth warnings
• Native helper spike: Rust, C, or WebAssembly fast-path primitives #48 Native helper spike: Rust, C, or WebAssembly fast-path primitives

Planning sources:

• OKF architecture: docs/okf/file-aware-architecture.md
• OKF epic: docs/okf/file-native-epic.md
• OKF practices: docs/okf/file-native-memory-practices.md
• OKF migration PR: [codex] Adopt OKF docs for file-native memory planning #47

Implementation rule: GitHub issues own scope and acceptance criteria; OKF docs own rationale, boundaries, and heuristics.