MemoryIndex Migration

Overview

MemoryIndexModule is a retired compatibility module. Version 2.0 is hidden from Workflow Studio and never reads chat messages, contacts an LLM endpoint, or writes a UserPreference.

The former version accepted a caller-selected username and API base URL. It could fall back from an owner-scoped chat lookup to findAll(), send chat content to a configurable endpoint, suppress failures, and store the result outside the canonical GrayMatter durable-memory boundary. Version 2.0 removes those unsafe behaviors. The class remains loadable so saved workflows can be inspected and migrated, but every execution fails closed with MODULE_RETIRED.

Usage

Do not add MemoryIndexModule to a new workflow. For each saved task that references it:

1. Identify whether the workflow intended to write a durable fact, query memory, retrieve evidence, or consolidate duplicates.
2. Use GrayMatterModule for principal-bound memory query/write operations.
3. Use OmegaRetrievalModule when the workflow needs receipt-backed evidence retrieval.
4. Use SkillConsolidateMemoryModule only for an approved duplicate-consolidation workflow.
5. Remove caller-selected usernames, owner IDs, API base URLs, and raw chat-history inputs.
6. Test the replacement under the exact authenticated principal and required approval policy.

Inputs

The compatibility shell recognizes four legacy migration hints. It does not parse, resolve, store, log, or transmit them.

Name	Type	Required	Version 2.0 behavior
principalUsername	string	No	Ignored. Principal authority comes from server authentication in replacements.
llmServiceId	string	No	Ignored. No LLM service is loaded.
maxMessages	integer	No	Ignored. No chat query runs.
basePath	string	No	Ignored. No URL is parsed or contacted.

Outputs

Name	Type	Description
status	string	Always error.
error.code	string	Always MODULE_RETIRED.
error.message	string	Safe GrayMatter migration guidance.
error.retryable	boolean	Always false; repeating the task cannot index or persist data.
error.migrationTargets	array	Canonical GrayMatter module class names to evaluate.

No chat content, username, owner ID, LLM response, memory summary, endpoint, credential, or provider exception is returned.

IntegrationAccount Requirements

MemoryIndexModule accepts, loads, and decrypts no IntegrationAccount. There is no account configuration that re-enables its former HTTP path.

The replacement GrayMatter modules derive the principal from server authentication and use the platform's RBAC/ACL-scoped durable-memory client. Do not pass a principal, owner, username, raw token, or arbitrary GrayMatter endpoint through workflow input.

Configuration

Direct metadata lookup exposes four advanced legacy hints so old configurations can be recognized:

Field	Legacy purpose	Version 2.0 behavior
principalUsername	Selected whose chat to read.	Never resolved.
llmServiceId	Selected a summarization service.	Never loaded.
maxMessages	Bounded the requested history.	No messages are queried.
basePath	Selected an HTTP API origin.	No network request is made.

The module is discoverable=false; Workflow Studio does not offer it for new tasks.

Operations

Version 2.0 implements one deterministic compatibility operation: reject execution and return migration targets.

Replacement	Intended operation
GrayMatterModule	Principal-bound durable memory query and idempotent write.
OmegaRetrievalModule	Receipt-backed retrieval with bounded evidence references.
SkillConsolidateMemoryModule	Conservative, approved duplicate-memory consolidation.

Prefer structured GrayMatter MemoryEntry fields, stable source scope, tags, provenance, and explicit relationships. Do not rebuild the former “summarize arbitrary chat into UserPreference” path.

Errors and Failure Modes

Failure	Meaning	Recovery
MODULE_RETIRED	A workflow still references the legacy indexer. No read, LLM request, or write occurred.	Replace the task with the appropriate GrayMatter module.
Replacement authentication failure	No server-derived principal is available.	Restore the authenticated workflow context; do not pass a principal ID manually.
Replacement ACL denial	The authenticated principal cannot read or write the requested memory scope.	Request the exact required grant or narrow the operation.
Replacement retrieval uncertainty	A receipt reports partial, stale, conflicting, or low-confidence context.	Follow the receipt policy; retry, clarify, or stop rather than claiming confidence.

The compatibility response never includes legacy input, chat content, credentials, endpoint data, or exception text.

Example

Legacy migration hints:

{
  "principalUsername": "alice",
  "llmServiceId": "7a7b7c7d-0000-4000-8000-000000000000",
  "maxMessages": 50,
  "basePath": "<legacy-api-origin>"
}

Expected result:

{
  "status": "error",
  "error": {
    "code": "MODULE_RETIRED",
    "message": "MemoryIndexModule is retired; migrate to principal-bound GrayMatter modules",
    "retryable": false,
    "migrationTargets": [
      "GrayMatterModule",
      "OmegaRetrievalModule",
      "SkillConsolidateMemoryModule"
    ]
  }
}

For a durable write, replace the task with GrayMatterModule, use its write operation, provide the bounded durable fact and stable source, and let server authentication supply the principal.

Notes

• Pagination: not applicable; the compatibility shell performs no chat or memory query.
• Limits: legacy hints are ignored. Replacement modules enforce their documented query, text, timeout, and result bounds.
• Idempotency: repeated execution returns the same failure shape and has no external or durable side effect.
• API constraints: no HTTP or LLM endpoint is called. GrayMatter replacements use the canonical authenticated client and live schema.
• Destructive behavior: none. The compatibility shell cannot read, summarize, write, update, or delete memory.
• Observability: one bounded warning records that execution was blocked; legacy inputs are not logged.
• Runtime boundary: source metadata changes appear in the deployed Workflow Studio catalog only after a separate ValkyrAI runtime deployment. Until then, live /v1/modules/metadata remains authoritative.