oceanbase / oceanbase/powercontext
feat: add portable export, backup, and restore
@larry-zy is already working on this.
Since Sep 2, 2026.
- Dominant language
- Python
- Stars
- 1.1k
- Forks
- 212
- Avg merge
- 1d 11h
- Merged PRs (30d)
- 199
Description
Feature description
Add a versioned, portable export, backup, and restore contract for current PowerContext data.
The goal is to support disaster recovery, migration between SQLite and OceanBase deployments, offline transfer, customer-controlled backup, and bounded analysis exports without bypassing immutable Revision, lineage, review, or authorization semantics.
Problem and proposed solution
PowerContext has focused import paths (#1384 and #1300), deterministic Handoff report export, and managed Skill projection. Those surfaces do not provide a complete, restorable PowerContext archive. The legacy PowerMem export/import issue #137 predates the current Source, Artifact Revision, Handoff, Review, and Workstream model and is not a sufficient contract for the current product.
Define two explicit products:
- Logical portable bundle — backend-neutral, versioned records with exact identities, Revisions, lineage, manifests, checksums, and bounded metadata.
- Deployment backup guidance/adapters — provider-specific procedures for crash-consistent backup where logical export is not an operational substitute.
The portable-bundle contract should cover supported Sources, Memory entry versions and manifests, Experience and Skill Revisions, Candidates and decisions, Work/Project/Workstream state, Handoffs and Receipts, and required projections or rebuild instructions. It should explicitly decide whether access bindings, audit records, usage facts, and evaluation receipts are included, optional, or excluded.
Required behavior:
- archive schema and producer version;
- deterministic manifest, per-object digests, total checksum, and optional compression;
- streaming export/import with progress and bounded memory use;
- dry-run validation and compatibility reporting before writes;
- idempotent replay and explicit conflict handling that never overwrites an immutable Revision;
- transactional or resumable restore with a durable receipt;
- scope-selective export only after authorization;
- redaction and exclusion rules for credentials, bearer tokens, provider secrets, absolute host paths, and host-local installation state;
- projection rebuild and verification after restore;
- documented upgrade and downgrade compatibility windows.
Human-readable CSV may be offered for analysis, but it must not be described as an authoritative round-trip format.
Acceptance criteria
- A non-trivial SQLite deployment can be exported, restored into a clean SQLite deployment, and verified by exact IDs, Revisions, lineage, citations, review state, and Handoff receipts.
- At least one backend migration path, such as SQLite to OceanBase, preserves the same logical contract.
- Re-importing the same bundle is idempotent; a conflicting payload under an existing immutable identity fails visibly.
- A failed or interrupted restore cannot leave successful-looking partial state without a resumable or rollback-safe receipt.
- Export authorization is checked before record enumeration and pagination.
- Archives contain no credentials or configured provider secrets, and validation errors do not echo sensitive record bodies.
- Restored indexes/projections are rebuilt or verified before readiness claims search parity.
- Large fixtures prove streaming behavior and bounded resource use.
Alternatives considered
- Copy the SQLite file: useful for one local deployment, but not a portable or cross-backend contract and unsafe without snapshot coordination.
- Dump database tables directly: freezes implementation details and can bypass migrations and domain invariants.
- Export only current heads: loses immutable history, lineage, auditability, and exact citations.
- Reuse Handoff Report or Skill export: those are projections for specific consumers, not complete backup artifacts.
Additional context
Related: #1384, #1300, #1395, #1219, and the cross-Runtime boundary documented by the Handoff Report RFC.
- I am willing to contribute code, docs, or design feedback.
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.
Assessment
This issue has not been assessed yet.