oceanbase / oceanbase/powercontext
feat(memory): add bounded pagination for Memory changes and history
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 1.1k
- Forks
- 212
- Avg merge
- 1d 11h
- Merged PRs (30d)
- 199
Description
Feature description
Add bounded Memory change/history queries for the history portion of D2 in RFC #1455, as a focused deliverable related to #1321.
Problem and proposed solution
At aa697c5315204249e090acdf1a00d0582e851c5f, POST /v1/memory/changes accepts scope_id and since_revision but no page size or cursor. The backend reads Artifact revisions before filtering the requested range and assembling revision changes.
Define a query with deterministic revision/change ordering, a bounded page, and an opaque continuation cursor. A limit on revision count alone is insufficient if a single revision contains many changes.
Acceptance criteria
- Specify page-size bounds, ordering, lower/upper revision boundaries, end-of-list semantics, and cursor validity/expiry.
- Preserve existing documented semantics:
since_revisionis an exclusive lower bound;0requests history from revision 1; a positive nonexistent revision is an error. Explicitly document the existing omitted/null behavior and any versioned migration. - Define a stable upper boundary or another explicit consistency strategy when new revisions arrive during traversal.
- Bound a page even when one revision has a large change set. Specify continuation within a revision or another explicit bounded representation, preserving precise revision/entry references.
- Do not load all historical revisions and then slice the result. Document and measure remaining per-revision/manifest costs and address anything that violates the declared bound.
- Preserve authorization on every page; reject mismatched, tampered, or expired cursors without leaking another Scope's history.
- Retain change metadata and exact references without expanding all entry bodies; details remain separately retrievable under current authorization.
- Test empty, multi-page, and large-single-revision histories; revision-boundary inputs; invalid cursors; concurrent new revisions; and authorization changes.
- Define an additive/versioned compatibility path. Existing consumers must not silently receive only a first page where they previously received a complete result.
- Update OpenAPI, generate derived code with
make api-generate, and runmake contract-test, focused behavior tests, and required checks.
Alternatives considered
- Loading complete history and paginating in Desktop: unbounded Server and network cost.
- Limiting revision count alone: does not bound a large change set inside one revision.
- Using Candidate history as Memory history: different authoritative data and semantics.
Additional context
- Refs #1321, #1455 (D2), and #1428.
- Current request/response contract.
- Current revision loading and filtering.
- Open for community implementation in a focused PR targeting
master. Coordinate cursor/compatibility choices with the entries-pagination issue, while keeping each deliverable independently reviewable. - This gates the Memory history UI, not the initial Desktop connection/save/search workflow. It does not introduce retention, erasure, compaction, or a general audit/event stream.
Desktop consumer: #1654.
Related entry-pagination deliverable: #1656.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with the current contract in openapi/powercontext.yaml around line 8219 and the revision loading/filtering in src/powercontext/builtin/persistence/memory.py around line 287. Review related issues #1321, #1455, and #1656, then run the focused behavior tests and make api-generate; done means bounded, compatible pagination with the specified authorization, cursor, concurrency, and large-history coverage, followed by make contract-test and required checks.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- openapi, python
- Domain
- backend-api-design, databases
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100