Configure portable Memory Profiles and local store bindings

[gbaudrit]

Area

Cross-cutting

Feature type

API capability

Problem or need

Governed Memory requires a clear separation between portable Agent policy and the concrete local store selected by an Agentstration installation.

Embedding a local provider name or endpoint directly in an Agent or Pack would make definitions non-portable. Allowing a mutable provider configuration to silently redirect existing data would make ownership and retrieval ambiguous.

Expected outcome

Administrators can configure local Memory store bindings and reusable Memory Profiles. Agents reference portable policy, while concrete provider selection is explicit, scope-aware, version-compatible, and observable.

Pack composition and installation can preserve Memory policy through logical bindings without exporting accumulated Memory records or local credentials.

Proposed solution

Add Management resources following the current provider and binding patterns:

• MemoryProvider represents a configured local store integration and references either the builtin store or an Extension Registration contribution.
• MemoryProfile contains bounded retrieval policy, default expiry behavior, and permitted Agent/shared subjects.
• Agent definitions optionally reference a MemoryProfile.
• Pack manifests express a logical memory-provider requirement that installation resolves to an authorized local provider.
• Provider identity/configuration generation used by stored data remains observable so a later configuration change cannot silently reinterpret existing records.

Use current Resource Scope, Extension Registration, immutable option-contract, ETag, reference, usage, and binding conventions rather than the typed Builtin/AEP union from historical PR #38.

Scope

• Define MemoryProvider and MemoryProfile resource contracts and supported scope kinds.
• Add CRUD, ETag validation, references, usage inspection, and deletion protection.
• Add optional Agent Memory configuration and compile it into immutable Agent revisions.
• Resolve Agent revision -> MemoryProfile -> MemoryProvider deterministically.
• Add dynamic provider configuration based on versioned option contracts where applicable.
• Add Pack binding support for Memory providers and portable Memory Profiles.
• Ensure Packs never include accumulated Memory records, credentials, local scopeRef values, or provider endpoints.
• Define explicit behavior when a profile changes provider; no implicit data migration.
• Add Management, Pack, validation, and architecture tests plus ADR documentation.

Out of scope

• Runtime context injection.
• AEP Memory store protocol implementation.
• Console UI.
• Copying or migrating records between providers.
• Making accumulated records Management resources.
• Semantic retrieval and provider-owned retrieval policy.

Dependencies

• Parent feature: Add governed Memory with explicit cross-Run recall #194.
• Governed Memory domain and local store: Persist governed Memory records with SQLite and PostgreSQL #195.
• Resource Scope foundation: Model Management resource ownership as explicit hierarchical scopes #166.
• Current Extension Registration, option-contract, and Pack binding foundations.

Alternatives considered

• Configure a store directly on each Agent: rejected because it duplicates local configuration and prevents reusable policy.
• Put provider endpoints in Packs: rejected because endpoints and credentials are installation-specific.
• Make Memory records Pack resources: rejected because they are accumulated runtime/user data.
• Allow transparent provider replacement: rejected because existing data provenance and location would become ambiguous.

Deployment impact

None

Acceptance criteria

• MemoryProvider and MemoryProfile have explicit responsibilities and supported Resource Scope rules.
• An Agent can opt in by referencing a MemoryProfile; absence of the reference preserves current behavior.
• Agent revisions retain the resolved portable Memory policy without concrete provider SDK or AEP types.
• Provider selection is deterministic, observable, and validated against current contribution/configuration contracts.
• Provider configuration changes cannot silently reinterpret or relocate existing records.
• Deletion is blocked while a provider or profile has active usages.
• Pack composition converts environment-specific provider selection into a logical binding.
• Pack installation resolves the binding in one target scope and never exports Memory records or credentials.
• Existing Packs and Agents without Memory remain compatible.
• Management, Pack, and architecture tests pass offline.
• ADR documentation covers portability, binding, generation, deletion, and provider-change semantics.

Additional context

Portable policy and local integration must remain separate in the same way Agentstration separates published definitions from installation-specific bindings elsewhere.

Preliminary checks

• I searched for an existing issue covering this request.