Skip to content

feat(memory): define capacity contract for long-lived Memories #1718

Description

@AlexStocks

Context

#1709 removed the projection write amplification reported in #1321 by updating active-head/search projection rows incrementally instead of rewriting every projection row on each append.

That PR intentionally did not define the remaining long-lived Memory capacity contract. #1321 was closed by the merge, but several parts of the original expected behavior still need a separate design and implementation track.

Pagination for list_memory_entries is already tracked separately in #1656. This issue should coordinate with that work but should not duplicate it.

Remaining problem

A long-lived Memory can still grow without an explicit, observable capacity boundary:

  • each Artifact Revision still stores a complete manifest directory;
  • inactive entries remain in the manifest as tombstones;
  • revision/history growth has no retention or compaction contract;
  • there is no entry-count or manifest-byte budget;
  • there is no defined behavior for routing/splitting when a Memory reaches a practical limit;
  • scale regression coverage is still focused on projection writes, not the full capacity envelope.

Scope

Define and implement the remaining Memory capacity contract after #1709.

At minimum, cover:

  • Current-manifest entry-count budget.
  • Current-manifest byte budget.
  • Stable over-limit behavior: explicit error, automatic routing to another Memory, or split.
  • Split/routing semantics, including artifact identity, citation behavior, and search across split Memories.
  • Inactive/tombstone compaction semantics.
  • Revision/history retention or bounding semantics.
  • Interaction with MemoryIndex.delete() / upsert() and projection rebuilds.
  • SQLite and OceanBase behavior documented separately.
  • Scale regression benchmarks beyond projection statement count.

Acceptance criteria

  • The Memory layer has a documented capacity contract for long-lived Memories.
  • Over-limit behavior is deterministic and observable through public APIs.
  • Split/routing or stable failure behavior is covered by tests.
  • Tombstone compaction defines what happens to old citations and stale references.
  • Scale tests record at least:
    • entry count,
    • manifest bytes,
    • database bytes,
    • append latency,
    • final-window append latency,
    • projection row writes,
    • search behavior after split/compaction if applicable.
  • SQLite and OceanBase validation results are reported separately.
  • The implementation does not regress the incremental projection write guarantees added by perf(memory): update search projections incrementally per revision #1709.

Related work

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or requestproduction-readyProduction readiness, operations, portability, and governance

    Type

    No type

    Projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions