[docs] Architectural mismatch: `parameter-resolution.mdx` `memory` progression vs `Agent` resolver

[Dhivya-Bharathy]

Docs: docs/reference/parameter-resolution.mdx
SDK: praisonaiagents.agent.agent.Agent + praisonaiagents.config.param_resolver.resolve
Kind: Documentation / API contract drift (not an SDK defect)

---

1. Executive summary

Field	Content
Symptom	Examples #4–#6 in the memory “progression” code block raise TypeError when pasted against current praisonaiagents.
Root cause	The docs describe generic “array / dict / MemoryConfig” patterns that do not match how memory= is actually resolved on Agent: list form uses ArrayMode.SINGLE_OR_LIST, dict keys are strictly validated against MemoryConfig fields, and MemoryConfig has backend not provider.
Impact	Readers treat this page as the canonical explanation of unified parameters; broken examples undermine resolve() documentation everywhere else.
Fix location	PraisonAIDocs only (unless product intentionally changes resolver — then PraisonAI ADR + docs together).

---

2. Architectural context — unified resolve() pipeline

praisonaiagents centralizes consolidated parameters (memory, knowledge, reflection, …) through resolve() in param_resolver.py.

flowchart TB
  subgraph Input["memory= value"]
    B[bool]
    S[str preset / URL]
    L[list / tuple]
    D[dict]
    C[MemoryConfig instance]
    I[Memory-like instance]
  end
  subgraph Agent["Agent.__init__"]
    FP["Fast path: True / False / MemoryConfig / instance"]
    RV["resolve(..., param_name='memory', ...)"]
  end
  Input --> Agent
  RV --> R["param_resolver.resolve"]
  R --> M["MemoryConfig or backend / config extraction"]

Loading

Design intent (from param_resolver.py header):

• Precedence: Instance → Config dataclass → Array → Dict → String → Bool → Default
• ArrayMode selects list semantics (SINGLE_OR_LIST, PRESET_OVERRIDE, SOURCES, …) per parameter, not one global rule.

---

3. What Agent actually does for memory

File: PraisonAI/src/praisonai-agents/praisonaiagents/agent/agent.py

After fast paths (memory is True → MemoryConfig(), MemoryConfig instance, memory-like instance), the generic branch calls:

            _memory_config = resolve(
                value=memory,
                param_name="memory",
                config_class=MemoryConfig,
                presets=MEMORY_PRESETS,
                url_schemes=MEMORY_URL_SCHEMES,
                instance_check=lambda v: (hasattr(v, 'search') and hasattr(v, 'add')) or hasattr(v, 'database_url'),
                array_mode=ArrayMode.SINGLE_OR_LIST,
                default=None,
            )

Critical design fact: memory lists use ArrayMode.SINGLE_OR_LIST, not PRESET_OVERRIDE.

So memory=["redis", {"port": 6380}] (two list items) hits _resolve_array → SINGLE_OR_LIST branch → TypeError: multiple values not allowed.

flowchart LR
  subgraph DocClaim["parameter-resolution.mdx implies"]
    A1["memory = [preset, overrides_dict]"]
  end
  subgraph Actual["Agent memory resolve"]
    A2["array_mode = SINGLE_OR_LIST"]
  end
  A1 -->|copy-paste| X["TypeError"]
  A2 --> X

Loading

---

4. MemoryConfig contract (dict + dataclass)

File: PraisonAI/src/praisonai-agents/praisonaiagents/config/feature_configs.py

Valid dataclass fields include backend, user_id, session_id, config, learn, history, … — not provider or port as top-level kwargs.

Dict shorthand is validated with _validate_dict_keys against that dataclass → provider / port are unknown keys.

flowchart TB
  subgraph Allowed["Valid MemoryConfig surface"]
    BE["backend: str | MemoryBackend"]
    CF["config: dict (provider-specific)"]
    UID["user_id / session_id / ..."]
  end
  subgraph Rejected["Doc examples #5–#6"]
    P["provider= / port= on MemoryConfig(...)"]
    D2["dict keys provider, port"]
  end
  Rejected --> E["TypeError"]

Loading

---

5. Doc inventory — failing lines

File: docs/reference/parameter-resolution.mdx (approximate line numbers from a recent main checkout)

#	Lines (approx)	Snippet	Failure mode
4	~47–48	memory=["redis", {"port": 6380}]	SINGLE_OR_LIST — multiple list items
5	~50–51	memory={"provider": "redis", "port": 6380}	Unknown dict keys
6	~53–54	MemoryConfig(provider="redis", port=6380)	Invalid dataclass kwargs

Examples #1–#3 in the same block (bool, string preset, URL) align with resolver behavior in spot checks — keep unless versions drift.

---

6. Reproduction (minimal)

from praisonaiagents import Agent, MemoryConfig

Agent(name="a", instructions="x", memory=["redis", {"port": 6380}])
# TypeError: Multiple values not allowed for memory...

Agent(name="a", instructions="x", memory={"provider": "redis", "port": 6380})
# TypeError: Unknown keys for memory: ['provider', 'port']...

Agent(name="a", instructions="x", memory=MemoryConfig(provider="redis", port=6380))
# TypeError: MemoryConfig.__init__() got an unexpected keyword argument 'provider'

---

7. Gap analysis

ID	Gap	Severity	Notes
G1	Doc implies preset + override array for memory on Agent	High	Contradicts SINGLE_OR_LIST for this param
G2	Doc uses provider/port dict keys	High	Must use backend + optional config
G3	MemoryConfig(provider=...)	High	API is backend=
G4	Unified table row for memory lists “[preset, {overrides}]”	Medium	Table may describe other params’ array modes, not memory

---

8. Suggested resolutions (pick one strategy)

Option A — Doc-only alignment (recommended)

1. Replace handoff #4 with a single supported pattern (e.g. URL string, memory="redis", or MemoryConfig with valid fields) or explicitly state: “Agent does not support [preset, overrides] for memory; use MemoryConfig + valid keys.”
2. Replace create all these missing modules #5 with dict using only MemoryConfig field names; put connection details under config if needed (confirm with resolver + tests).
3. Replace create all these missing modules #6 with MemoryConfig(backend=..., user_id=..., config={...}) as appropriate.
4. Update Unified Parameter Table so the memory / Array column matches SINGLE_OR_LIST reality.

Option B — Product change (out of scope for this issue)

If PRESET_OVERRIDE for memory lists is desired, that requires PraisonAI change (array_mode for this resolve() call), release notes, migration guide — separate epic.

---

9. Boundary — what this issue is not

• Not claiming memory="redis" or URL strings are broken.
• Not requesting changes to MEMORY_PRESETS without an ADR.
• Not about knowledge= or reflection= (tracked in separate doc issues if needed).

---

10. Acceptance criteria

• Examples handoff #4–create all these missing modules #6 either run on the documented praisonaiagents version or are explicitly labeled unsupported with pointer to supported patterns.
• MemoryConfig examples use only real constructor fields.
• Unified Parameter Table memory row matches Agent array_mode + dict validation.
• Optional: link from this page to MemoryConfig reference / memory concept doc.

---

11. References

• praisonaiagents/agent/agent.py — memory → resolve(..., array_mode=ArrayMode.SINGLE_OR_LIST)
• praisonaiagents/config/param_resolver.py — resolve, _resolve_array, ArrayMode
• praisonaiagents/config/feature_configs.py — MemoryConfig
• docs/reference/parameter-resolution.mdx — edit target

---

12. Suggested labels

documentation, bug, sdk, memory, api-parity, reference

[MervinPraison]

👋 Thanks for opening this issue, @Dhivya-Bharathy!

A maintainer will review this shortly. In the meantime:

• Make sure you've included steps to reproduce (for bugs)
• Check existing issues for duplicates
• Review the documentation for related guides

[MervinPraison]

@claude validate and fix it

[MervinPraison]

Claude finished @MervinPraison's task —— View job • claude/issue-203-20260422-0445 • [Create PR ➔](https://github.com/MervinPraison/PraisonAIDocs/compare/main...claude/issue-203-20260422-0445?quick_pull=1&title=Issue%20%23203%3A%20Changes%20from%20Claude&body=This%20PR%20addresses%20issue%20%23203%0A%0AGenerated%20with%20%5BClaude%20Code%5D(https%3A%2F%2Fclaude.ai%2Fcode)

---

✅ Fixed parameter-resolution.mdx memory examples

Todo List:

• Setup git identity and auth
• Read AGENTS.md for documentation standards
• Read SDK source code to validate the issue
• Examine current parameter-resolution.mdx file
• Fix the broken examples in parameter-resolution.mdx
• Commit and push changes
• Create pull request

Issue Validation ✅

Confirmed the exact problems described in issue #203:

1. Line 48: Array with multiple items fails ArrayMode.SINGLE_OR_LIST
2. Lines 51 & 54: Using provider instead of backend field
3. Lines 51 & 54: Connection params not in config sub-dict

Documentation Fixed ✅

• Replaced broken array example with correct single-item pattern
• Fixed dict example to use backend and config fields properly
• Updated MemoryConfig constructor with correct field names
• Updated precedence table to show accurate array behavior
• Added explanatory note about memory parameter limitations

Pull Request Created: #218

All examples now align with the actual SDK implementation in agent.py and feature_configs.py.

---