Skip to content

docs: fix parameter-resolution.mdx memory examples (fixes #203) #218

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
MervinPraison merged 1 commit into from
Apr 28, 2026
Merged

docs: fix parameter-resolution.mdx memory examples (fixes #203) #218

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
40 changes: 28 additions & 12 deletions docs/reference/parameter-resolution.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,8 +18,8 @@ When multiple configuration sources are provided, the system resolves them in th
|----------|------|---------|-------------|
| 1 | **Instance** | `memory=db_instance` | Pre-configured object instance |
| 2 | **Config** | `memory=MemoryConfig(...)` | Explicit configuration object |
| 3 | **Dict** | `memory={"provider": "redis"}` | Config shorthand (strict validation) |
| 4 | **Array** | `memory=["redis", {"port": 6380}]` | Preset with overrides |
| 3 | **Dict** | `memory={"backend": "redis"}` | Config shorthand (strict validation) |
| 4 | **Array** | `knowledge=["docs/", "data.pdf"]` | Multiple sources (feature-specific) |
Comment on lines +21 to +22
Copy link
Copy Markdown

@gemini-code-assist gemini-code-assist Bot Apr 22, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

The resolution order table incorrectly lists Dict (Priority 3) as having higher precedence than Array (Priority 4). According to the implementation in praisonaiagents/config/param_resolver.py (lines 95-110), arrays are resolved before dictionaries. To maintain accuracy, the order of these two rows should be swapped.

| 3 | **Array** | `knowledge=["docs/", "data.pdf"]` | Multiple sources (feature-specific) |
| 4 | **Dict** | `memory={"backend": "redis"}` | Config shorthand (strict validation) |

| 5 | **String** | `memory="redis"` or `memory="postgresql://..."` | Preset name or URL |
| 6 | **Bool** | `memory=True` | Enable with defaults |
| 7 | **Default** | (not specified) | Feature disabled or default config |
Expand All @@ -44,14 +44,14 @@ agent = Agent(instructions="...", memory="redis")
# 3. String - Use a URL
agent = Agent(instructions="...", memory="postgresql://localhost:5432/mydb")

# 4. Array - Preset with overrides
agent = Agent(instructions="...", memory=["redis", {"port": 6380}])
# 4. String URL - Direct connection string
agent = Agent(instructions="...", memory="redis://localhost:6379")
Comment on lines +47 to +48
Copy link
Copy Markdown

@gemini-code-assist gemini-code-assist Bot Apr 22, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

The user-friendly progression defined on line 32 is Bool → String → Array → Dict → Config → Instance. By changing step 4 from an Array example to another String example, the numbered list no longer aligns with the conceptual progression. Since the memory parameter supports single-item arrays (as noted on line 65), it is better to use a single-item array here to maintain the narrative flow of the documentation.

# 4. Array - Single-item list (feature-specific)
agent = Agent(instructions="...", memory=["redis://localhost:6379"])


# 5. Dict - Config shorthand (strict validation)
agent = Agent(instructions="...", memory={"provider": "redis", "port": 6380})
agent = Agent(instructions="...", memory={"backend": "redis", "config": {"port": 6380}})

# 6. Config - Full control
agent = Agent(instructions="...", memory=MemoryConfig(provider="redis", port=6380))
agent = Agent(instructions="...", memory=MemoryConfig(backend="redis", config={"port": 6380}))

# 7. Instance - Pre-configured
db = create_memory_backend("redis", port=6380)
Expand All @@ -62,7 +62,7 @@ agent = Agent(instructions="...", memory=db)

| Param | Surfaces | Bool | String | Array | Config Class |
|-------|----------|------|--------|-------|--------------|
| `memory` | Agent, Agents | ✅ Enable file-based | Preset/URL | `[preset, {overrides}]` | `MemoryConfig` |
| `memory` | Agent, Agents | ✅ Enable file-based | Preset/URL | `["url"]` (single item only) | `MemoryConfig` |
| `knowledge` | Agent, Agents | ✅ Enable | Path/URL | `[path1, path2]` | `KnowledgeConfig` |
| `planning` | Agent, Agents | ✅ Enable | LLM model | `[model, {opts}]` | `PlanningConfig` |
| `reflection` | Agent, Agents | ✅ Enable | Preset | `[preset, {opts}]` | `ReflectionConfig` |
Expand Down Expand Up @@ -220,6 +220,20 @@ agent = Agent(

## Array Parsing Rules

<Note>
**Memory Parameter**: The `memory` parameter uses `ArrayMode.SINGLE_OR_LIST`, which only accepts **single-item arrays**. For multiple values or preset + overrides, use dict or config object instead.

```python
# ❌ This fails for memory parameter
memory=["redis", {"port": 6380}] # Multiple items not allowed

# ✅ Use these instead
memory="redis://localhost:6380" # URL string
memory={"backend": "redis", "config": {"port": 6380}} # Dict
memory=MemoryConfig(backend="redis", config={"port": 6380}) # Config
```
</Note>

### Preset with Overrides

The most common array pattern combines a preset with custom options:
Expand Down Expand Up @@ -273,11 +287,13 @@ from praisonaiagents import MemoryConfig
agent = Agent(
instructions="...",
memory=MemoryConfig(
provider="redis",
host="localhost",
port=6379,
db=0,
ttl=3600,
backend="redis",
config={
"host": "localhost",
"port": 6379,
"db": 0,
"ttl": 3600,
}
)
)
```
Expand Down