oceanbase / oceanbase/powercontext

feat(memory): add bounded pagination for Memory changes and history

Open
#1,657 0 comments 0 reactions 0 assignees View on GitHub

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_revision is an exclusive lower bound; 0 requests 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 run make 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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.