[docs] Architectural drift: `home.mdx` memory + RAG snippets vs `Agent` constructor surface

[Dhivya-Bharathy]

Docs: docs/home.mdx — “Persistent Memory” + “Knowledge Bases (RAG)” accordions
SDK: praisonaiagents.agent.agent.Agent + MemoryConfig + knowledge resolution
Kind: Documentation — invalid kwargs / duplicate source parameters

---

1. Executive summary

Field	Content
Symptom A	Memory snippet passes user_id= on Agent — constructor has no such kwarg; user_id is modeled on MemoryConfig.
Symptom B	RAG snippet passes knowledge= and knowledge_sources= together — knowledge_sources is not an Agent kwarg.
Root cause	Marketing examples flatten nested config into top-level Agent kwargs that never existed on the consolidated Agent API.
Impact	Same homepage surface as reflection issue — high-trust, high-failure copy-paste path.
Fix	PraisonAIDocs — nest user_id under memory=MemoryConfig(...) or supported dict; collapse multi-source knowledge into a single knowledge= value (list, KnowledgeConfig, paths).

---

2. Architecture — where user_id lives

2.1 Agent constructor (excerpt)

Agent.__init__ exposes memory= but not user_id= as a top-level parameter (see full signature in agent.py).

2.2 MemoryConfig carries identity

File: praisonaiagents/config/feature_configs.py

    # Session identification
    user_id: Optional[str] = None
    session_id: Optional[str] = None

After resolution, Agent extracts user_id / session_id from the resolved MemoryConfig into internal fields — users must supply them via memory=, not alongside memory=True as a sibling kwarg.

flowchart TB
  subgraph Wrong["home.mdx memory snippet"]
    W["Agent(..., memory=True, user_id='...')"]
  end
  subgraph Right["Supported shapes"]
    R1["Agent(..., memory=MemoryConfig(backend='file', user_id='...'))"]
    R2["Agent(..., memory={'backend':'file','user_id':'...'})  # if resolver accepts"]
  end
  Wrong --> TE["TypeError: unexpected keyword argument 'user_id'"]
  R1 --> OK["Construct OK"]

Loading

---

3. Architecture — knowledge= surface

Agent accepts knowledge= as a consolidated parameter (bool, str, list, KnowledgeConfig, … — see Agent signature and resolve() call sites for knowledge).

There is no separate knowledge_sources= keyword on Agent.

Design principle: one consolidated param → one argument tree; multiple sources should be expressed inside that tree (e.g. list of paths, KnowledgeConfig(sources=[...]), documented shorthand).

flowchart LR
  subgraph Wrong2["home.mdx RAG snippet"]
    K1["knowledge='./docs/'"]
    K2["knowledge_sources=[...]"]
  end
  subgraph Right2["Target model"]
    U1["knowledge=['./docs/', 'https://...', './pdfs/']"]
    U2["knowledge=KnowledgeConfig(sources=[...])"]
  end
  Wrong2 --> TE2["TypeError: knowledge_sources"]
  U1 --> OK2["Single param"]
  U2 --> OK2

Loading

---

4. Doc inventory — failing blocks

4.1 Persistent Memory (~L96–102)

agent = Agent(
    name="assistant",
    memory=True,
    user_id="user_123"
)

4.2 Knowledge Bases (~L108–116)

agent = Agent(
    name="researcher",
    knowledge="./docs/",
    knowledge_sources=[
        "https://example.com/api",
        "./pdfs/"
    ]
)

---

5. Reproduction

from praisonaiagents import Agent
Agent(name="a", instructions="x", memory=True, user_id="u")
# TypeError: Agent.__init__() got an unexpected keyword argument 'user_id'

Agent(name="a", instructions="x", knowledge="./d/", knowledge_sources=["x"])
# TypeError: Agent.__init__() got an unexpected keyword argument 'knowledge_sources'

---

6. Suggested replacements (verify against KnowledgeConfig docs)

Memory (illustrative):

from praisonaiagents import Agent, MemoryConfig

agent = Agent(
    name="assistant",
    instructions="You are a helpful assistant.",
    memory=MemoryConfig(backend="file", user_id="user_123"),
)

Knowledge (illustrative):

from praisonaiagents import Agent

agent = Agent(
    name="researcher",
    instructions="You research using provided documents.",
    knowledge=["./docs/", "https://example.com/api", "./pdfs/"],
)

Adjust KnowledgeConfig usage if the site standard is to always show explicit config objects for RAG-heavy examples.

---

7. Gap analysis

ID	Gap	Severity
G1	user_id on Agent	High
G2	knowledge_sources on Agent	High
G3	Implies two parallel params for sources	Medium — teach single consolidated param

---

8. Acceptance criteria

• Memory accordion does not use user_id= on Agent; identity is under memory=.
• RAG accordion does not use knowledge_sources=; all sources appear under knowledge= only.
• Snippets run without TypeError on documented praisonaiagents.
• Optional cross-links: docs/concepts/memory.mdx, docs/concepts/knowledge.mdx (or equivalents).

---

9. Boundary

• Not requesting new Agent(user_id=...) kwargs in PraisonAI (would be separate product decision + ADR).
• Not about browser accordion agent.run (separate review).

---

10. References

• praisonaiagents/agent/agent.py — memory extraction from MemoryConfig
• praisonaiagents/config/feature_configs.py — MemoryConfig, KnowledgeConfig
• docs/home.mdx — edit target

---

11. Suggested labels

documentation, bug, homepage, memory, knowledge, rag, dx

[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-205-20260422-0445 • [Create PR ➔](https://github.com/MervinPraison/PraisonAIDocs/compare/main...claude/issue-205-20260422-0445?quick_pull=1&title=Issue%20%23205%3A%20Changes%20from%20Claude&body=This%20PR%20addresses%20issue%20%23205%0A%0AGenerated%20with%20%5BClaude%20Code%5D(https%3A%2F%2Fclaude.ai%2Fcode)

---

✅ Architectural Drift Fixed in docs/home.mdx

Successfully validated and fixed the documentation issues where home.mdx examples didn't match the actual PraisonAI Agent API.

Todo List:

• Set up git identity and auth
• Read AGENTS.md to understand documentation standards
• Examine current docs/home.mdx to identify problematic examples
• Read SDK source code to understand correct Agent API
• Fix memory example (remove invalid user_id kwarg)
• Fix RAG example (consolidate knowledge parameters)
• Verify examples are copy-paste runnable
• Commit and push changes
• Create pull request

🔧 Changes Made

1. Fixed Memory Example (Lines 96-106):

# Before: ❌ Invalid API usage
agent = Agent(
    name="assistant", 
    memory=True,
    user_id="user_123"  # Invalid - not an Agent parameter
)

# After: ✅ Correct nested configuration
from praisonaiagents import Agent, MemoryConfig

agent = Agent(
    name="assistant",
    memory=MemoryConfig(
        backend="file",
        user_id="user_123"  # Correct - belongs in MemoryConfig
    )
)

2. Fixed RAG Example (Lines 112-123):

# Before: ❌ Conflicting parameters
agent = Agent(
    name="researcher",
    knowledge="./docs/", 
    knowledge_sources=[...]  # Invalid - doesn't exist on Agent
)

# After: ✅ Consolidated single parameter
from praisonaiagents import Agent

agent = Agent(
    name="researcher",
    knowledge=[  # Single parameter accepts list
        "./docs/",
        "https://example.com/api", 
        "./pdfs/"
    ]
)

🎯 Issue Resolution

• Root Cause: Documentation examples used invalid kwargs that don't exist on Agent constructor
• Fix: Updated to use proper nested config objects and consolidated parameters
• Validation: Confirmed against actual SDK source code in praisonaiagents/agent/agent.py and praisonaiagents/config/feature_configs.py
• Testing: Verified syntax is valid and examples are copy-paste runnable

📋 Pull Request

PR #217: docs: fix Agent API architectural drift in home.mdx

Both memory and RAG examples now correctly reflect the actual Agent constructor API and follow the documented patterns from AGENTS.md.

---