oceanbase / oceanbase/powercontext

feat(memory): add bounded cursor pagination for Memory entries

Open
#1,656 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 an authorized, bounded Server query for Memory entries, implementing the directory portion of D2 in RFC #1455. Track this as a focused deliverable related to the broader capacity problem in #1321.

Problem and proposed solution

At aa697c5315204249e090acdf1a00d0582e851c5f, POST /v1/memory/entries/list accepts Scope, inactive-entry, and tag-filter inputs but has no page size or cursor. Its response contains the complete selected entries. The persistence implementation loads entry versions referenced by the complete Memory manifest.

Client-side pagination or slicing the fully assembled HTTP response leaves the Server work unbounded. Generic Artifact pagination also does not paginate entries inside one Memory Artifact.

Specify and implement a bounded query with an explicit default/maximum page size, deterministic ordering, an opaque continuation cursor, and clear consistency/error semantics. Agree on whether this is an additive operation or a versioned evolution; do not silently change existing clients from complete results to an undisclosed first page.

Acceptance criteria
  • Publish request/response schemas, ordering, page-size bounds, end-of-list behavior, and cursor invalidation/expiry rules.
  • Apply current authorization and supported inactive/tag filtering before page selection; continuation requests reauthorize access.
  • Bind continuation to the relevant resource/query context. Reject tampered, mismatched, and invalid/expired cursors without revealing other Scopes or private data.
  • Define concurrent append/revise/retire behavior: traverse a pinned revision or explicitly require restart when the consistency boundary changes. Do not silently skip or duplicate entries.
  • Preserve exact Memory and entry/citation identities so a listed item can be inspected correctly.
  • Bound entry-body loading and response assembly, not just the final response slice. State and measure any remaining whole-manifest cost; if it prevents the promised bound, agree the necessary storage/index work before claiming bounded browsing.
  • Cover empty and multi-page results, the final page, inactive/tag filters, unauthorized requests, permission changes, invalid cursors, and concurrent mutations through observable behavior tests.
  • Include a scale fixture or measurement demonstrating the declared bounds without freezing private call counts.
  • Document compatibility/migration for existing clients; keep old full-list semantics explicit while supported. Regenerate OpenAPI-derived code and run contract/relevant behavior checks.

Alternatives considered

  • Fetch everything and page in the UI: does not bound Server work or network payload.
  • Truncate responses without continuation: loses data and misrepresents completeness.
  • Reuse Artifact-directory pagination: addresses a different level of the data model.

Additional context

  • Refs #1321, #1455 (D2/AC-19), #1428, and the Web viewer work in #1454.
  • Current request/response contract.
  • Current entry loading.
  • Scope: entry directory queries. Memory history pagination, full storage-growth remediation, split/compaction policy, and Desktop UI are separate work.
  • Open for community implementation in a focused PR targeting master. Coordinate shared cursor/consistency and compatibility choices with the history work.
  • This gates complete Memory browsing, not Desktop's initial explicit-save/search/exact-detail workflow.

Desktop consumer: #1654.

Related history-pagination deliverable: #1657. Both issues cover focused portions of #1321 and should agree on shared consistency/compatibility decisions.

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 request/response contract in openapi/powercontext.yaml around line 8248 and entry loading in src/powercontext/builtin/persistence/memory.py around line 181. Review related issues #1321, #1455, and #1657 before settling shared cursor, consistency, and compatibility decisions. Done means bounded, authorized pagination with observable behavior and scale tests, documented compatibility, regenerated OpenAPI code, and relevant checks passing.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
api, backend, 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.