Release v4.4.2

api.md

@@ -81,6 +81,8 @@ Methods:
 * <code title="class Agent">Agent.<a href="./src/praisonai-agents/praisonaiagents/agent/agent.py">run</a>(prompt: str, **kwargs)</code>
 * <code title="class Agent">Agent.<a href="./src/praisonai-agents/praisonaiagents/agent/agent.py">run_autonomous</a>(prompt: str, max_iterations: Optional[int] = None, timeout_seconds: Optional[float] = None, completion_promise: Optional[str] = None, clear_context: bool = False)</code>
 * <code title="class Agent">Agent.<a href="./src/praisonai-agents/praisonaiagents/agent/agent.py">run_autonomous_async</a>(prompt: str, max_iterations: Optional[int] = None, timeout_seconds: Optional[float] = None, completion_promise: Optional[str] = None, clear_context: bool = False)</code>
+* <code title="class Agent">Agent.<a href="./src/praisonai-agents/praisonaiagents/agent/agent.py">run_until</a>(prompt: str, criteria: str, threshold: float = 8.0, max_iterations: int = 5, mode: str = 'optimize', on_iteration: Optional[Callable[[Any], None]] = None, verbose: bool = False) -> 'EvaluationLoopResult'</code>
+* <code title="class Agent">Agent.<a href="./src/praisonai-agents/praisonaiagents/agent/agent.py">run_until_async</a>(prompt: str, criteria: str, threshold: float = 8.0, max_iterations: int = 5, mode: str = 'optimize', on_iteration: Optional[Callable[[Any], None]] = None, verbose: bool = False) -> 'EvaluationLoopResult'</code>
 * <code title="class Agent">Agent.<a href="./src/praisonai-agents/praisonaiagents/agent/agent.py">session_id</a>() -> Optional[str]</code>
 * <code title="class Agent">Agent.<a href="./src/praisonai-agents/praisonaiagents/agent/agent.py">skill_manager</a>()</code>
 * <code title="class Agent">Agent.<a href="./src/praisonai-agents/praisonaiagents/agent/agent.py">start</a>(prompt: str = None, **kwargs)</code>
@@ -1006,6 +1008,7 @@ Methods:
 * <code title="cli">praisonai traces list <a href="./src/praisonai/praisonai/cli/commands/traces.py">--help</a></code>
 * <code title="cli">praisonai traces status <a href="./src/praisonai/praisonai/cli/commands/traces.py">--help</a></code>
 * <code title="cli">praisonai train agents <a href="./src/praisonai/praisonai/cli/commands/train.py">--help</a></code>
+* <code title="cli">praisonai train apply <a href="./src/praisonai/praisonai/cli/commands/train.py">--help</a></code>
 * <code title="cli">praisonai train list <a href="./src/praisonai/praisonai/cli/commands/train.py">--help</a></code>
 * <code title="cli">praisonai train llm <a href="./src/praisonai/praisonai/cli/commands/train.py">--help</a></code>
 * <code title="cli">praisonai train show <a href="./src/praisonai/praisonai/cli/commands/train.py">--help</a></code>

docker/Dockerfile.chat

@@ -16,7 +16,7 @@ RUN mkdir -p /root/.praison
 # Install Python packages (using latest versions)
 RUN pip install --no-cache-dir \
     praisonai_tools \
-    "praisonai>=4.3.1" \
+    "praisonai>=4.4.2" \
     "praisonai[chat]" \
     "embedchain[github,youtube]"
 

docker/Dockerfile.dev

@@ -20,7 +20,7 @@ RUN mkdir -p /root/.praison
 # Install Python packages (using latest versions)
 RUN pip install --no-cache-dir \
     praisonai_tools \
-    "praisonai>=4.3.1" \
+    "praisonai>=4.4.2" \
     "praisonai[ui]" \
     "praisonai[chat]" \
     "praisonai[realtime]" \

docker/Dockerfile.ui

@@ -16,7 +16,7 @@ RUN mkdir -p /root/.praison
 # Install Python packages (using latest versions)
 RUN pip install --no-cache-dir \
     praisonai_tools \
-    "praisonai>=4.3.1" \
+    "praisonai>=4.4.2" \
     "praisonai[ui]" \
     "praisonai[crewai]"
 

examples/python/eval/README.md

@@ -0,0 +1,43 @@
+# EvaluationLoop Examples
+
+Examples demonstrating iterative evaluation and improvement patterns.
+
+## Quick Start
+
+```bash
+pip install praisonaiagents
+export OPENAI_API_KEY=your-key
+```
+
+## Examples
+
+| File | Description |
+|------|-------------|
+| `basic_evaluation_loop.py` | Simple loop: Run → Judge → Improve |
+| `multi_step_task_loop.py` | Sequential tasks with context passing |
+| `recipe_optimization_loop.py` | CLI-based recipe optimization |
+
+## Pattern
+
+```
+┌─────────┐     ┌─────────┐     ┌──────────┐
+│  Agent  │ ──► │  Judge  │ ──► │ Feedback │
+│  runs   │     │ scores  │     │ improves │
+└─────────┘     └─────────┘     └──────────┘
+     ▲                               │
+     └───────────────────────────────┘
+           (repeat until 8.0+)
+```
+
+## Run Examples
+
+```bash
+# Basic loop
+python basic_evaluation_loop.py
+
+# Multi-step with context
+python multi_step_task_loop.py
+
+# CLI recipe loop
+python recipe_optimization_loop.py "research AI trends"
+```

examples/python/eval/basic_evaluation_loop.py

@@ -0,0 +1,73 @@
+"""
+Basic EvaluationLoop Example
+
+Demonstrates the iterative evaluation loop pattern:
+Run agent → Judge output → Improve → Repeat until threshold met.
+
+Usage:
+    pip install praisonaiagents
+    export OPENAI_API_KEY=your-key
+    python basic_evaluation_loop.py
+"""
+from praisonaiagents import Agent
+from praisonaiagents.eval import EvaluationLoop
+
+
+def on_iteration(result):
+    """Callback showing progress after each iteration."""
+    status = "✅" if result.score >= 8.0 else "⚠️" if result.score >= 6.0 else "❌"
+    print(f"{status} Iteration {result.iteration}: {result.score:.1f}/10")
+    if result.findings:
+        print(f"   → {result.findings[0][:60]}...")
+
+
+def main():
+    # Create an agent
+    agent = Agent(
+        name="writer",
+        instructions="You are a technical content writer. Write clear, accurate explanations."
+    )
+
+    # Run evaluation loop
+    loop = EvaluationLoop(
+        agent=agent,
+        criteria="""
+        Evaluate the response on:
+        1. CLARITY: Is the explanation easy to understand?
+        2. ACCURACY: Is the technical content correct?
+        3. COMPLETENESS: Does it cover the key aspects?
+        4. EXAMPLES: Does it include practical examples?
+        
+        Score 1-10 based on all criteria.
+        """,
+        threshold=8.0,
+        max_iterations=5,
+        on_iteration=on_iteration,
+        verbose=False,
+    )
+
+    print("╔════════════════════════════════════════════════════════════╗")
+    print("║            Basic EvaluationLoop Example                     ║")
+    print("║  Pattern: Run → Judge → Improve → Repeat                   ║")
+    print("║  Target: 8.0/10 score                                       ║")
+    print("╚════════════════════════════════════════════════════════════╝\n")
+
+    result = loop.run("Explain how API rate limiting works and why it matters")
+
+    print("\n" + "─" * 60)
+    print("RESULTS:")
+    print("─" * 60)
+    print(f"Success: {result.success}")
+    print(f"Final Score: {result.final_score:.1f}/10")
+    print(f"Iterations: {result.num_iterations}")
+    print(f"Score History: {[f'{s:.1f}' for s in result.score_history]}")
+    print(f"Duration: {result.total_duration_seconds:.2f}s")
+
+    print("\n" + "─" * 60)
+    print("FINAL OUTPUT (first 500 chars):")
+    print("─" * 60)
+    print(result.final_output[:500] + "..." if len(result.final_output) > 500 else result.final_output)
+
+
+if __name__ == "__main__":
+    main()

examples/python/eval/multi_step_task_loop.py

@@ -0,0 +1,144 @@
+"""
+Multi-Step Task Loop Example
+
+Demonstrates evaluating sequential task steps where each step can
+reference output from previous steps.
+
+Pattern:
+1. Research → Evaluate → Improve
+2. Analyze (using research) → Evaluate → Improve  
+3. Report (using analysis) → Evaluate → Improve
+
+Usage:
+    pip install praisonaiagents
+    export OPENAI_API_KEY=your-key
+    python multi_step_task_loop.py
+"""
+from praisonaiagents import Agent
+from praisonaiagents.eval import EvaluationLoop
+
+
+def on_iteration(result):
+    """Show iteration progress."""
+    status = "✅" if result.score >= 8.0 else "⚠️" if result.score >= 6.0 else "❌"
+    print(f"  {status} Iteration {result.iteration}: {result.score:.1f}/10")
+
+
+def run_step(step_name: str, agent: Agent, task: str, criteria: str, context: str = "") -> dict:
+    """Run a single step through an evaluation loop."""
+    print(f"\n{'─'*60}")
+    print(f"STEP: {step_name}")
+    print(f"{'─'*60}")
+    
+    # Include context from previous step if provided
+    full_task = task
+    if context:
+        full_task = f"{task}\n\nContext from previous step:\n{context[:1000]}"
+    
+    loop = EvaluationLoop(
+        agent=agent,
+        criteria=criteria,
+        threshold=8.0,
+        max_iterations=3,
+        on_iteration=on_iteration,
+        verbose=False,
+    )
+    
+    result = loop.run(full_task)
+    
+    print(f"  → Final: {result.final_score:.1f}/10 ({result.num_iterations} iterations)")
+    
+    return {
+        "name": step_name,
+        "output": result.final_output,
+        "score": result.final_score,
+        "success": result.success,
+        "iterations": result.num_iterations,
+    }
+
+
+def main():
+    print("╔════════════════════════════════════════════════════════════╗")
+    print("║         Multi-Step Task Loop Example                       ║")
+    print("║  Pattern: Step1 → Step2 → Step3 (with context passing)    ║")
+    print("║  Each step: Run → Judge → Improve until 8.0+              ║")
+    print("╚════════════════════════════════════════════════════════════╝")
+
+    # Create specialized agents
+    researcher = Agent(
+        name="researcher",
+        instructions="You are a research specialist. Find and summarize key information."
+    )
+    
+    analyst = Agent(
+        name="analyst", 
+        instructions="You are an analyst. Identify patterns, insights, and implications."
+    )
+    
+    writer = Agent(
+        name="writer",
+        instructions="You are a report writer. Create clear, actionable summaries."
+    )
+
+    # Define task steps
+    steps = [
+        {
+            "name": "Research",
+            "agent": researcher,
+            "task": "Research the top 3 trends in AI for 2024-2025. Provide brief descriptions.",
+            "criteria": "Covers 3 distinct trends with accurate descriptions.",
+        },
+        {
+            "name": "Analysis",
+            "agent": analyst,
+            "task": "Analyze the implications of these AI trends for software development.",
+            "criteria": "Identifies actionable insights and potential challenges.",
+        },
+        {
+            "name": "Report",
+            "agent": writer,
+            "task": "Create a brief executive summary (3-4 bullet points) for a CTO.",
+            "criteria": "Concise, actionable, appropriate for executive audience.",
+        },
+    ]
+
+    # Run all steps with context passing
+    results = []
+    context = ""
+    
+    for step in steps:
+        result = run_step(
+            step_name=step["name"],
+            agent=step["agent"],
+            task=step["task"],
+            criteria=step["criteria"],
+            context=context,
+        )
+        results.append(result)
+        context = result["output"]  # Pass output as context to next step
+
+    # Summary
+    print("\n" + "═"*60)
+    print("SUMMARY")
+    print("═"*60)
+    
+    total_iterations = sum(r["iterations"] for r in results)
+    avg_score = sum(r["score"] for r in results) / len(results)
+    all_success = all(r["success"] for r in results)
+    
+    for r in results:
+        status = "✅" if r["success"] else "❌"
+        print(f"  {status} {r['name']}: {r['score']:.1f}/10 ({r['iterations']} iterations)")
+    
+    print(f"\n  Total Iterations: {total_iterations}")
+    print(f"  Average Score: {avg_score:.1f}/10")
+    print(f"  All Steps Passed: {'Yes' if all_success else 'No'}")
+
+    print("\n" + "─"*60)
+    print("FINAL REPORT OUTPUT:")
+    print("─"*60)
+    print(results[-1]["output"][:600])
+
+
+if __name__ == "__main__":
+    main()

examples/python/eval/recipe_optimization_loop.py

@@ -0,0 +1,183 @@
+"""
+Recipe Optimization Loop (CLI-based)
+
+Demonstrates the 5-cycle recipe improvement pattern using CLI commands:
+    Create (once) → Run → Judge → Optimize (loop 5x)
+
+Usage:
+    pip install praisonai
+    export OPENAI_API_KEY=your-key
+    export TAVILY_API_KEY=your-key
+    python recipe_optimization_loop.py "research AI trends in healthcare"
+"""
+import subprocess
+import sys
+import os
+import json
+from pathlib import Path
+
+
+def run_cli(cmd: str, cwd: str = None) -> tuple[int, str, str]:
+    """Run a CLI command and return (exit_code, stdout, stderr)."""
+    result = subprocess.run(
+        cmd,
+        shell=True,
+        capture_output=True,
+        text=True,
+        cwd=cwd,
+    )
+    return result.returncode, result.stdout, result.stderr
+
+
+def create_recipe(goal: str, work_dir: str) -> str:
+    """Create a recipe once. Returns recipe name."""
+    print(f"\n{'═'*60}")
+    print("STEP 1: CREATE RECIPE (once)")
+    print(f"{'═'*60}")
+    print(f"Goal: {goal}")
+    
+    cmd = f'praisonai recipe create "{goal}" --no-optimize'
+    code, stdout, stderr = run_cli(cmd, cwd=work_dir)
+    
+    if code != 0:
+        print(f"❌ Failed to create recipe: {stderr}")
+        return None
+    
+    # Extract recipe name from output
+    for line in stdout.split('\n'):
+        if 'Created recipe:' in line:
+            recipe_name = line.split('Created recipe:')[1].strip()
+            print(f"✅ Created: {recipe_name}")
+            return recipe_name
+    
+    print(f"✅ Recipe created")
+    return None
+
+
+def run_recipe(recipe_name: str, trace_name: str, work_dir: str) -> tuple[bool, str]:
+    """Run the recipe and save trace. Returns (success, output)."""
+    cmd = f'praisonai recipe run {recipe_name} --save --name {trace_name}'
+    code, stdout, stderr = run_cli(cmd, cwd=work_dir)
+    
+    success = code == 0 and 'status: completed' in stdout.lower()
+    return success, stdout
+
+
+def judge_recipe(trace_name: str, work_dir: str) -> tuple[float, str]:
+    """Judge the trace. Returns (score, feedback)."""
+    cmd = f'praisonai recipe judge {trace_name}'
+    code, stdout, stderr = run_cli(cmd, cwd=work_dir)
+    
+    # Extract score from output
+    score = 0.0
+    for line in stdout.split('\n'):
+        if 'Overall Score:' in line:
+            try:
+                score = float(line.split(':')[1].strip().split('/')[0])
+            except:
+                pass
+    
+    return score, stdout
+
+
+def optimize_recipe(recipe_name: str, iterations: int, work_dir: str) -> tuple[float, str]:
+    """Optimize the recipe. Returns (final_score, output)."""
+    cmd = f'praisonai recipe optimize {recipe_name} --iterations {iterations}'
+    code, stdout, stderr = run_cli(cmd, cwd=work_dir)
+    
+    # Extract final score
+    score = 0.0
+    for line in stdout.split('\n'):
+        if 'Final score:' in line or 'score:' in line.lower():
+            try:
+                score = float(line.split(':')[1].strip().split('/')[0])
+            except:
+                pass
+    
+    return score, stdout
+
+
+def run_optimization_loop(goal: str, num_cycles: int = 5, threshold: float = 8.0):
+    """Run the full Create → Run → Judge → Optimize loop."""
+    
+    print("╔════════════════════════════════════════════════════════════╗")
+    print("║       Recipe Optimization Loop (CLI-based)                 ║")
+    print("║  Pattern: Create (once) → Run → Judge → Optimize (loop)   ║")
+    print(f"║  Cycles: {num_cycles} | Threshold: {threshold}/10                         ║")
+    print("╚════════════════════════════════════════════════════════════╝")
+    
+    # Create work directory
+    work_dir = Path("/tmp/recipe-optimization-loop")
+    work_dir.mkdir(parents=True, exist_ok=True)
+    os.chdir(work_dir)
+    
+    # Step 1: Create recipe (once)
+    recipe_name = create_recipe(goal, str(work_dir))
+    if not recipe_name:
+        print("Failed to create recipe. Exiting.")
+        return
+    
+    # Step 2-N: Run → Judge → Optimize loop
+    results = []
+    
+    for cycle in range(1, num_cycles + 1):
+        print(f"\n{'─'*60}")
+        print(f"CYCLE {cycle}/{num_cycles}")
+        print(f"{'─'*60}")
+        
+        trace_name = f"cycle-{cycle}"
+        
+        # Run
+        print(f"  📝 Running recipe...")
+        success, run_output = run_recipe(recipe_name, trace_name, str(work_dir))
+        run_status = "✅" if success else "⚠️"
+        print(f"  {run_status} Run complete")
+        
+        # Judge
+        print(f"  ⚖️ Judging output...")
+        score, judge_output = judge_recipe(trace_name, str(work_dir))
+        score_status = "✅" if score >= threshold else "⚠️" if score >= 6.0 else "❌"
+        print(f"  {score_status} Score: {score}/10")
+        
+        # Check if threshold met
+        if score >= threshold:
+            print(f"  🎉 Threshold {threshold}/10 reached!")
+            results.append({"cycle": cycle, "score": score, "status": "passed"})
+            break
+        
+        # Optimize
+        print(f"  🔧 Optimizing recipe...")
+        opt_score, opt_output = optimize_recipe(recipe_name, 1, str(work_dir))
+        print(f"  → Optimized score: {opt_score}/10")
+        
+        results.append({
+            "cycle": cycle,
+            "initial_score": score,
+            "optimized_score": opt_score,
+            "status": "optimized" if opt_score > score else "no_change"
+        })
+    
+    # Summary
+    print(f"\n{'═'*60}")
+    print("SUMMARY")
+    print(f"{'═'*60}")
+    
+    for r in results:
+        if "initial_score" in r:
+            print(f"  Cycle {r['cycle']}: {r['initial_score']} → {r['optimized_score']}/10")
+        else:
+            print(f"  Cycle {r['cycle']}: {r['score']}/10 ✅ PASSED")
+    
+    final_score = results[-1].get("optimized_score", results[-1].get("score", 0))
+    success = final_score >= threshold
+    
+    print(f"\n  Final Score: {final_score}/10")
+    print(f"  Success: {'Yes ✅' if success else 'No ❌'}")
+    print(f"  Recipe: {work_dir}/{recipe_name}")
+    
+    return results
+
+
+if __name__ == "__main__":
+    goal = sys.argv[1] if len(sys.argv) > 1 else "research latest AI trends and create a summary report"
+    run_optimization_loop(goal, num_cycles=5, threshold=8.0)

src/praisonai-agents/.gitignore

@@ -89,4 +89,6 @@ graph.py
 chroma_db/
 .qodo
 *_COMPARISON_ANALYSIS.md
-*_REPORT.md
+*_REPORT.md
+
+.praisonai

src/praisonai-agents/.praisonai/memory/default/config.json

@@ -0,0 +1,9 @@
+{
+  "short_term_limit": 100,
+  "long_term_limit": 1000,
+  "episodic_retention_days": 30,
+  "enable_summarization": false,
+  "summarization_threshold": 50,
+  "importance_threshold": 0.7,
+  "auto_promote": true
+}

src/praisonai-agents/.praisonai/summaries/_var_folders_0b_t9c4hwvx6lg6jk58gw8w_dp80000gn_T_tmp6_tn0h1t_hierarchy.json

@@ -0,0 +1,21 @@
+{
+  "root_path": "/var/folders/0b/t9c4hwvx6lg6jk58gw8w_dp80000gn/T/tmp6_tn0h1t",
+  "total_files": 0,
+  "total_tokens": 11,
+  "levels": 3,
+  "built_at": "2026-02-02T17:47:19.241146",
+  "nodes": {
+    "/var/folders/0b/t9c4hwvx6lg6jk58gw8w_dp80000gn/T/tmp6_tn0h1t": {
+      "path": "/var/folders/0b/t9c4hwvx6lg6jk58gw8w_dp80000gn/T/tmp6_tn0h1t",
+      "level": 3,
+      "summary": "Project with 0 folders and 0 root files: ",
+      "children": [],
+      "token_count": 11,
+      "created_at": "2026-02-02T17:47:19.241224",
+      "metadata": {
+        "folder_count": 0,
+        "root_file_count": 0
+      }
+    }
+  }
+}

src/praisonai-agents/.praisonai/summaries/_var_folders_0b_t9c4hwvx6lg6jk58gw8w_dp80000gn_T_tmp7wxr57wm_hierarchy.json

@@ -0,0 +1,35 @@
+{
+  "root_path": "/var/folders/0b/t9c4hwvx6lg6jk58gw8w_dp80000gn/T/tmp7wxr57wm",
+  "total_files": 1,
+  "total_tokens": 16,
+  "levels": 2,
+  "built_at": "2026-02-02T17:47:19.243732",
+  "nodes": {
+    "/var/folders/0b/t9c4hwvx6lg6jk58gw8w_dp80000gn/T/tmp7wxr57wm/src/app.py": {
+      "path": "/var/folders/0b/t9c4hwvx6lg6jk58gw8w_dp80000gn/T/tmp7wxr57wm/src/app.py",
+      "level": 1,
+      "summary": "# Application code",
+      "children": [],
+      "token_count": 5,
+      "created_at": "2026-02-02T17:47:19.243833",
+      "metadata": {
+        "filename": "app.py",
+        "relative_path": "src/app.py"
+      }
+    },
+    "/var/folders/0b/t9c4hwvx6lg6jk58gw8w_dp80000gn/T/tmp7wxr57wm/src": {
+      "path": "/var/folders/0b/t9c4hwvx6lg6jk58gw8w_dp80000gn/T/tmp7wxr57wm/src",
+      "level": 2,
+      "summary": "Folder contains 1 files: # Application code",
+      "children": [
+        "/var/folders/0b/t9c4hwvx6lg6jk58gw8w_dp80000gn/T/tmp7wxr57wm/src/app.py"
+      ],
+      "token_count": 11,
+      "created_at": "2026-02-02T17:47:19.243852",
+      "metadata": {
+        "folder_name": "src",
+        "file_count": 1
+      }
+    }
+  }
+}

src/praisonai-agents/.praisonai/summaries/_var_folders_0b_t9c4hwvx6lg6jk58gw8w_dp80000gn_T_tmp8qwfp4zl_hierarchy.json

@@ -0,0 +1,21 @@
+{
+  "root_path": "/var/folders/0b/t9c4hwvx6lg6jk58gw8w_dp80000gn/T/tmp8qwfp4zl",
+  "total_files": 0,
+  "total_tokens": 11,
+  "levels": 3,
+  "built_at": "2026-02-02T17:49:37.074095",
+  "nodes": {
+    "/var/folders/0b/t9c4hwvx6lg6jk58gw8w_dp80000gn/T/tmp8qwfp4zl": {
+      "path": "/var/folders/0b/t9c4hwvx6lg6jk58gw8w_dp80000gn/T/tmp8qwfp4zl",
+      "level": 3,
+      "summary": "Project with 0 folders and 0 root files: ",
+      "children": [],
+      "token_count": 11,
+      "created_at": "2026-02-02T17:49:37.074201",
+      "metadata": {
+        "folder_count": 0,
+        "root_file_count": 0
+      }
+    }
+  }
+}

src/praisonai-agents/.praisonai/summaries/_var_folders_0b_t9c4hwvx6lg6jk58gw8w_dp80000gn_T_tmp9nw2kfoj_hierarchy.json

@@ -0,0 +1,33 @@
+{
+  "root_path": "/var/folders/0b/t9c4hwvx6lg6jk58gw8w_dp80000gn/T/tmp9nw2kfoj",
+  "total_files": 2,
+  "total_tokens": 14,
+  "levels": 1,
+  "built_at": "2026-02-02T17:47:19.242486",
+  "nodes": {
+    "/var/folders/0b/t9c4hwvx6lg6jk58gw8w_dp80000gn/T/tmp9nw2kfoj/utils.py": {
+      "path": "/var/folders/0b/t9c4hwvx6lg6jk58gw8w_dp80000gn/T/tmp9nw2kfoj/utils.py",
+      "level": 1,
+      "summary": "def helper(): return True",
+      "children": [],
+      "token_count": 7,
+      "created_at": "2026-02-02T17:47:19.242582",
+      "metadata": {
+        "filename": "utils.py",
+        "relative_path": "utils.py"
+      }
+    },
+    "/var/folders/0b/t9c4hwvx6lg6jk58gw8w_dp80000gn/T/tmp9nw2kfoj/main.py": {
+      "path": "/var/folders/0b/t9c4hwvx6lg6jk58gw8w_dp80000gn/T/tmp9nw2kfoj/main.py",
+      "level": 1,
+      "summary": "def main(): print('Hello')",
+      "children": [],
+      "token_count": 7,
+      "created_at": "2026-02-02T17:47:19.242630",
+      "metadata": {
+        "filename": "main.py",
+        "relative_path": "main.py"
+      }
+    }
+  }
+}

src/praisonai-agents/.praisonai/summaries/_var_folders_0b_t9c4hwvx6lg6jk58gw8w_dp80000gn_T_tmp_dbottar_hierarchy.json

@@ -0,0 +1,35 @@
+{
+  "root_path": "/var/folders/0b/t9c4hwvx6lg6jk58gw8w_dp80000gn/T/tmp_dbottar",
+  "total_files": 1,
+  "total_tokens": 16,
+  "levels": 2,
+  "built_at": "2026-02-02T17:49:37.077857",
+  "nodes": {
+    "/var/folders/0b/t9c4hwvx6lg6jk58gw8w_dp80000gn/T/tmp_dbottar/src/app.py": {
+      "path": "/var/folders/0b/t9c4hwvx6lg6jk58gw8w_dp80000gn/T/tmp_dbottar/src/app.py",
+      "level": 1,
+      "summary": "# Application code",
+      "children": [],
+      "token_count": 5,
+      "created_at": "2026-02-02T17:49:37.077985",
+      "metadata": {
+        "filename": "app.py",
+        "relative_path": "src/app.py"
+      }
+    },
+    "/var/folders/0b/t9c4hwvx6lg6jk58gw8w_dp80000gn/T/tmp_dbottar/src": {
+      "path": "/var/folders/0b/t9c4hwvx6lg6jk58gw8w_dp80000gn/T/tmp_dbottar/src",
+      "level": 2,
+      "summary": "Folder contains 1 files: # Application code",
+      "children": [
+        "/var/folders/0b/t9c4hwvx6lg6jk58gw8w_dp80000gn/T/tmp_dbottar/src/app.py"
+      ],
+      "token_count": 11,
+      "created_at": "2026-02-02T17:49:37.078011",
+      "metadata": {
+        "folder_name": "src",
+        "file_count": 1
+      }
+    }
+  }
+}

src/praisonai-agents/.praisonai/summaries/_var_folders_0b_t9c4hwvx6lg6jk58gw8w_dp80000gn_T_tmpp5k48vv4_hierarchy.json

@@ -0,0 +1,33 @@
+{
+  "root_path": "/var/folders/0b/t9c4hwvx6lg6jk58gw8w_dp80000gn/T/tmpp5k48vv4",
+  "total_files": 2,
+  "total_tokens": 14,
+  "levels": 1,
+  "built_at": "2026-02-02T17:49:37.075925",
+  "nodes": {
+    "/var/folders/0b/t9c4hwvx6lg6jk58gw8w_dp80000gn/T/tmpp5k48vv4/utils.py": {
+      "path": "/var/folders/0b/t9c4hwvx6lg6jk58gw8w_dp80000gn/T/tmpp5k48vv4/utils.py",
+      "level": 1,
+      "summary": "def helper(): return True",
+      "children": [],
+      "token_count": 7,
+      "created_at": "2026-02-02T17:49:37.076036",
+      "metadata": {
+        "filename": "utils.py",
+        "relative_path": "utils.py"
+      }
+    },
+    "/var/folders/0b/t9c4hwvx6lg6jk58gw8w_dp80000gn/T/tmpp5k48vv4/main.py": {
+      "path": "/var/folders/0b/t9c4hwvx6lg6jk58gw8w_dp80000gn/T/tmpp5k48vv4/main.py",
+      "level": 1,
+      "summary": "def main(): print('Hello')",
+      "children": [],
+      "token_count": 7,
+      "created_at": "2026-02-02T17:49:37.076227",
+      "metadata": {
+        "filename": "main.py",
+        "relative_path": "main.py"
+      }
+    }
+  }
+}

src/praisonai-agents/.praisonai/summaries/_var_folders_0b_t9c4hwvx6lg6jk58gw8w_dp80000gn_T_tmpwwb01831_hierarchy.json

@@ -0,0 +1,33 @@
+{
+  "root_path": "/var/folders/0b/t9c4hwvx6lg6jk58gw8w_dp80000gn/T/tmpwwb01831",
+  "total_files": 2,
+  "total_tokens": 16,
+  "levels": 1,
+  "built_at": "2026-02-02T17:49:37.079504",
+  "nodes": {
+    "/var/folders/0b/t9c4hwvx6lg6jk58gw8w_dp80000gn/T/tmpwwb01831/javascript.js": {
+      "path": "/var/folders/0b/t9c4hwvx6lg6jk58gw8w_dp80000gn/T/tmpwwb01831/javascript.js",
+      "level": 1,
+      "summary": "JavaScript web development",
+      "children": [],
+      "token_count": 7,
+      "created_at": "2026-02-02T17:49:37.079612",
+      "metadata": {
+        "filename": "javascript.js",
+        "relative_path": "javascript.js"
+      }
+    },
+    "/var/folders/0b/t9c4hwvx6lg6jk58gw8w_dp80000gn/T/tmpwwb01831/python.py": {
+      "path": "/var/folders/0b/t9c4hwvx6lg6jk58gw8w_dp80000gn/T/tmpwwb01831/python.py",
+      "level": 1,
+      "summary": "Python programming language code",
+      "children": [],
+      "token_count": 9,
+      "created_at": "2026-02-02T17:49:37.079658",
+      "metadata": {
+        "filename": "python.py",
+        "relative_path": "python.py"
+      }
+    }
+  }
+}

src/praisonai-agents/.praisonai/summaries/_var_folders_0b_t9c4hwvx6lg6jk58gw8w_dp80000gn_T_tmpwzdvf3_7_hierarchy.json

@@ -0,0 +1,33 @@
+{
+  "root_path": "/var/folders/0b/t9c4hwvx6lg6jk58gw8w_dp80000gn/T/tmpwzdvf3_7",
+  "total_files": 2,
+  "total_tokens": 16,
+  "levels": 1,
+  "built_at": "2026-02-02T17:47:19.245229",
+  "nodes": {
+    "/var/folders/0b/t9c4hwvx6lg6jk58gw8w_dp80000gn/T/tmpwzdvf3_7/javascript.js": {
+      "path": "/var/folders/0b/t9c4hwvx6lg6jk58gw8w_dp80000gn/T/tmpwzdvf3_7/javascript.js",
+      "level": 1,
+      "summary": "JavaScript web development",
+      "children": [],
+      "token_count": 7,
+      "created_at": "2026-02-02T17:47:19.245344",
+      "metadata": {
+        "filename": "javascript.js",
+        "relative_path": "javascript.js"
+      }
+    },
+    "/var/folders/0b/t9c4hwvx6lg6jk58gw8w_dp80000gn/T/tmpwzdvf3_7/python.py": {
+      "path": "/var/folders/0b/t9c4hwvx6lg6jk58gw8w_dp80000gn/T/tmpwzdvf3_7/python.py",
+      "level": 1,
+      "summary": "Python programming language code",
+      "children": [],
+      "token_count": 9,
+      "created_at": "2026-02-02T17:47:19.245395",
+      "metadata": {
+        "filename": "python.py",
+        "relative_path": "python.py"
+      }
+    }
+  }
+}

src/praisonai-agents/praisonaiagents/__init__.py

@@ -457,6 +457,19 @@ _LAZY_IMPORTS = {
     'get_default_plugin_dirs': ('praisonaiagents.plugins', 'get_default_plugin_dirs'),
     'get_plugin_template': ('praisonaiagents.plugins', 'get_plugin_template'),
     'ensure_plugin_dir': ('praisonaiagents.plugins', 'ensure_plugin_dir'),
+    
+    # Config loader - for config-driven defaults
+    'get_config': ('praisonaiagents.config.loader', 'get_config'),
+    'get_default': ('praisonaiagents.config.loader', 'get_default'),
+    'get_plugins_config': ('praisonaiagents.config.loader', 'get_plugins_config'),
+    'get_defaults_config': ('praisonaiagents.config.loader', 'get_defaults_config'),
+    'apply_config_defaults': ('praisonaiagents.config.loader', 'apply_config_defaults'),
+    'validate_config': ('praisonaiagents.config.loader', 'validate_config'),
+    'get_config_path': ('praisonaiagents.config.loader', 'get_config_path'),
+    'ConfigValidationError': ('praisonaiagents.config.loader', 'ConfigValidationError'),
+    'PraisonConfig': ('praisonaiagents.config.loader', 'PraisonConfig'),
+    'PluginsConfig': ('praisonaiagents.config.loader', 'PluginsConfig'),
+    'DefaultsConfig': ('praisonaiagents.config.loader', 'DefaultsConfig'),
 }
 
 

src/praisonai-agents/praisonaiagents/_config.py

@@ -9,6 +9,10 @@ Environment Variables:
     PRAISONAI_TELEMETRY_ENABLED: Enable telemetry (default: false, opt-in)
     PRAISONAI_TELEMETRY_DISABLED: Disable telemetry (takes precedence)
     DO_NOT_TRACK: Standard opt-out flag (takes precedence)
+    PRAISONAI_PLUGINS: Enable plugins (default: false)
+        - "true" or "1": Enable all discovered plugins
+        - "logging,metrics": Enable specific plugins (comma-separated)
+        - "false" or "0": Disable plugins
 """
 import os
 from typing import Optional
@@ -77,6 +81,38 @@ AUTO_INSTRUMENT = _str_to_bool(
 )
 
 
+# Plugins: Enable background plugins (hooks, metrics, logging)
+# Note: Tools and guardrails work WITHOUT this flag - they are explicit
+def _get_plugins_enabled() -> bool:
+    """Determine if plugins should be auto-enabled based on env var."""
+    env_value = os.environ.get('PRAISONAI_PLUGINS', '').lower()
+    if not env_value:
+        return False
+    if env_value in ('true', '1', 'yes', 'on'):
+        return True
+    if env_value in ('false', '0', 'no', 'off'):
+        return False
+    # Treat as comma-separated list of plugin names (implies enabled)
+    return True
+
+
+def _get_plugins_list() -> list:
+    """Get list of specific plugins to enable from env var.
+    
+    Returns:
+        List of plugin names, or empty list if all plugins enabled.
+    """
+    env_value = os.environ.get('PRAISONAI_PLUGINS', '').lower()
+    if not env_value or env_value in ('true', '1', 'yes', 'on', 'false', '0', 'no', 'off'):
+        return []
+    # Parse comma-separated list
+    return [p.strip() for p in env_value.split(',') if p.strip()]
+
+
+PLUGINS_ENABLED = _get_plugins_enabled()
+PLUGINS_LIST = _get_plugins_list()
+
+
 def missing_dependency_error(
     package_name: str,
     extra_name: Optional[str] = None,

src/praisonai-agents/praisonaiagents/agent/agent.py

@@ -541,6 +541,49 @@ class Agent:
             Agent._configure_logging()
             Agent._logging_configured = True
 
+        # ============================================================
+        # CONFIG-DRIVEN DEFAULTS (apply before parameter resolution)
+        # Precedence: Explicit params > Config file > Built-in defaults
+        # Only applies when param is None (not explicitly set)
+        # ============================================================
+        from ..config.loader import apply_config_defaults, get_default
+        
+        # Apply config defaults for LLM if not explicitly set
+        if llm is None and model is None:
+            config_model = get_default("model")
+            if config_model:
+                llm = config_model
+        
+        # Apply config defaults for base_url if not explicitly set
+        if base_url is None:
+            config_base_url = get_default("base_url")
+            if config_base_url:
+                base_url = config_base_url
+        
+        # Apply config defaults for feature params (memory, knowledge, etc.)
+        # These use apply_config_defaults which handles enabled=True/False logic
+        if memory is None:
+            memory = apply_config_defaults("memory", memory, MemoryConfig)
+        if knowledge is None:
+            knowledge = apply_config_defaults("knowledge", knowledge, KnowledgeConfig)
+        if planning is False:  # Only override if explicitly False (default)
+            config_planning = apply_config_defaults("planning", None, PlanningConfig)
+            if config_planning:
+                planning = config_planning
+        if reflection is None:
+            reflection = apply_config_defaults("reflection", reflection, ReflectionConfig)
+        if web is None:
+            web = apply_config_defaults("web", web, WebConfig)
+        if output is None:
+            output = apply_config_defaults("output", output, OutputConfig)
+        if execution is None:
+            execution = apply_config_defaults("execution", execution, ExecutionConfig)
+        if caching is None:
+            caching = apply_config_defaults("caching", caching, CachingConfig)
+        if autonomy is None:
+            # AutonomyConfig is in agent/autonomy.py - use dict for config defaults
+            autonomy = apply_config_defaults("autonomy", autonomy, None)
+
         # ============================================================
         # CONSOLIDATED PARAMS EXTRACTION (agent-centric API)
         # Uses unified resolver: Instance > Config > Array > String > Bool > Default
@@ -840,7 +883,10 @@ class Agent:
                 backend = _memory_config.backend
                 if hasattr(backend, 'value'):
                     backend = backend.value
-                if backend == "file":
+                # If learn is enabled, pass as dict to trigger full Memory class
+                if _memory_config.learn:
+                    memory = _memory_config.to_dict()
+                elif backend == "file":
                     memory = True
                 elif _memory_config.config:
                     memory = _memory_config.config
@@ -2621,8 +2667,8 @@ Summary:"""
         Initialize RulesManager for persistent rules/instructions.
         
         Automatically discovers rules from:
-        - ~/.praison/rules/ (global)
-        - .praison/rules/ (workspace)
+        - ~/.praisonai/rules/ (global)
+        - .praisonai/rules/ (workspace)
         - Subdirectory rules
         
         NOTE: This is called lazily via the rules_manager property for performance.
@@ -2712,8 +2758,19 @@ Summary:"""
                 self._memory_instance = FileMemory(user_id=mem_user_id)
         elif isinstance(memory, dict):
             # Configuration dict
-            provider = memory.get("provider", "file")
-            if provider == "file":
+            provider = memory.get("provider", memory.get("backend", "file"))
+            learn_enabled = memory.get("learn", False)
+            
+            # Use full Memory class if learn is enabled (requires LearnManager)
+            if learn_enabled:
+                try:
+                    from ..memory.memory import Memory
+                    self._memory_instance = Memory(memory)
+                except ImportError:
+                    logging.warning("Memory with learn requires additional dependencies. Falling back to FileMemory (learn disabled).")
+                    from ..memory.file_memory import FileMemory
+                    self._memory_instance = FileMemory(user_id=memory.get("user_id", mem_user_id))
+            elif provider == "file":
                 from ..memory.file_memory import FileMemory
                 self._memory_instance = FileMemory(
                     user_id=memory.get("user_id", mem_user_id),
@@ -2749,6 +2806,24 @@ Summary:"""
         
         return ""
     
+    def get_learn_context(self) -> str:
+        """
+        Get learning context for injection into system prompt.
+        
+        Returns learned preferences, insights, and patterns when memory="learn"
+        is enabled. Returns empty string when learn is not enabled (zero overhead).
+        
+        Returns:
+            Formatted learning context string, or empty string if learn not enabled
+        """
+        if not self._memory_instance:
+            return ""
+        
+        if hasattr(self._memory_instance, 'get_learn_context'):
+            return self._memory_instance.get_learn_context()
+        
+        return ""
+    
     def store_memory(self, content: str, memory_type: str = "short_term", **kwargs):
         """
         Store content in memory.
@@ -3389,6 +3464,11 @@ Your Goal: {self.goal}"""
                 # Display memory info to user if verbose
                 if self.verbose:
                     self._display_memory_info()
+            
+            # Add learn context if learn is enabled (auto-inject when memory="learn")
+            learn_context = self.get_learn_context()
+            if learn_context:
+                system_prompt += f"\n\n## Learned Context (Patterns and insights from past interactions)\n{learn_context}"
         
         # Add skills prompt if skills are configured
         if self._skills or self._skills_dirs:

src/praisonai-agents/praisonaiagents/agent/context_agent.py

@@ -162,7 +162,7 @@ class ContextAgent(Agent):
         
         # Enhanced logging and output management
         self.debug_mode = os.getenv('LOGLEVEL', '').lower() == 'debug'
-        self.output_dir = Path(".praison/prp")  # Save in .praison/prp folder
+        self.output_dir = Path(".praisonai/prp")  # Save in .praisonai/prp folder
         self.setup_output_directories()  # Create directories first
         self.setup_logging()              # Then setup logging
         
@@ -1136,7 +1136,7 @@ detailed, actionable implementation steps."""
             filtered = []
             exclude_patterns = [
                 '__pycache__', '.pytest_cache', '.git', 'node_modules', 
-                '.venv', 'venv', 'dist', 'build', '.praison', '.chroma_db',
+                '.venv', 'venv', 'dist', 'build', '.praisonai', '.chroma_db',
                 '.ruff_cache', '.mypy_cache', 'context_engineering_output'
             ]
             
@@ -2263,7 +2263,7 @@ This PRP provides:
             )
             print(f"🐛 Debug mode: Comprehensive session report + individual files + final PRP saved")
         else:
-            # Non-debug mode: Save ONLY the final comprehensive PRP directly in .praison/prp
+            # Non-debug mode: Save ONLY the final comprehensive PRP directly in .praisonai/prp
             # Use clean filename: goal name + timestamp
             final_output_file = self.output_dir / f"{safe_goal}_prp_{timestamp}.md"
             final_output_file.parent.mkdir(parents=True, exist_ok=True)

src/praisonai-agents/praisonaiagents/agents/agents.py

@@ -513,9 +513,9 @@ class AgentTeam:
                         "use_embedding": True,
                         "storage": {
                             "type": "sqlite",
-                            "path": "./.praison/memory.db"
+                            "path": "./.praisonai/memory.db"
                         },
-                        "rag_db_path": "./.praison/chroma_db"
+                        "rag_db_path": "./.praisonai/chroma_db"
                     }
                 if _embedder:
                     if isinstance(_embedder, dict):
@@ -2345,7 +2345,7 @@ Context:
                 context=context if context else None,
                 # Inherit from original task if available
                 memory=original_task.memory if original_task else None,
-                callback=original_task.callback if original_task else None,
+                on_task_complete=original_task.callback if original_task else None,
                 guardrails=original_task.guardrail if original_task else None,
                 max_retries=original_task.max_retries if original_task else 3,
                 output_json=original_task.output_json if original_task else None,

src/praisonai-agents/praisonaiagents/checkpoints/__init__.py

@@ -20,7 +20,7 @@ Usage:
     # Create checkpoint service
     service = CheckpointService(
         workspace_dir="/path/to/project",
-        storage_dir="~/.praison/checkpoints"
+        storage_dir="~/.praisonai/checkpoints"
     )
     
     # Initialize shadow git

src/praisonai-agents/praisonaiagents/checkpoints/service.py

@@ -51,7 +51,7 @@ class CheckpointService:
     Example:
         service = CheckpointService(
             workspace_dir="/path/to/project",
-            storage_dir="~/.praison/checkpoints"
+            storage_dir="~/.praisonai/checkpoints"
         )
         
         await service.initialize()

src/praisonai-agents/praisonaiagents/checkpoints/types.py

@@ -39,7 +39,7 @@ class CheckpointConfig:
     max_checkpoints: int = 100  # Maximum checkpoints to keep
     exclude_patterns: List[str] = field(default_factory=lambda: [
         ".git",
-        ".praison",
+        ".praisonai",
         "__pycache__",
         "*.pyc",
         ".env",

src/praisonai-agents/praisonaiagents/config/feature_configs.py

@@ -176,6 +176,9 @@ class MemoryConfig:
             learn_dict = LearnConfig().to_dict()
         elif isinstance(self.learn, LearnConfig):
             learn_dict = self.learn.to_dict()
+        elif isinstance(self.learn, dict):
+            # Pass through dict directly (user provided learn config as dict)
+            learn_dict = self.learn
         
         return {
             "backend": self.backend.value if isinstance(self.backend, MemoryBackend) else self.backend,
@@ -749,7 +752,7 @@ class SkillsConfig:
         # With config
         Agent(skills=SkillsConfig(
             paths=["./my-skill"],
-            dirs=["~/.praison/skills/"],
+            dirs=["~/.praisonai/skills/"],
             auto_discover=True,
         ))
     """

src/praisonai-agents/praisonaiagents/config/loader.py

@@ -0,0 +1,609 @@
+"""
+Configuration Loader for PraisonAI Agents.
+
+Loads configuration from multiple sources with precedence:
+1. Explicit parameters (highest)
+2. Environment variables
+3. Config file (.praisonai/config.toml or praisonai.toml)
+4. Defaults (lowest)
+
+Zero Performance Impact:
+- Config is loaded lazily on first access
+- No file I/O at import time
+- Cached after first load
+
+Usage:
+    from praisonaiagents.config.loader import get_config, get_default
+    
+    # Get entire config
+    config = get_config()
+    
+    # Get specific default with fallback
+    model = get_default("model", "gpt-4o-mini")
+    memory_config = get_default("memory", {})
+    
+    # Validate config file
+    errors = validate_config(config.to_dict())
+"""
+
+import os
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Union
+from dataclasses import dataclass, field
+
+
+# ============================================================================
+# CONFIG VALIDATION SCHEMA
+# ============================================================================
+# Defines valid keys and types for config file validation
+
+VALID_PLUGINS_KEYS = {
+    "enabled": (bool, list, str),  # bool, list of plugin names, or "true"/"false"
+    "auto_discover": (bool,),
+    "directories": (list,),
+}
+
+VALID_DEFAULTS_KEYS = {
+    # LLM settings
+    "model": (str,),
+    "base_url": (str,),
+    "api_key": (str,),
+    # Feature flags
+    "allow_delegation": (bool,),
+    "allow_code_execution": (bool,),
+    "code_execution_mode": (str,),
+    # Feature configs (nested dicts with 'enabled' key)
+    "memory": (dict, bool),
+    "knowledge": (dict, bool),
+    "planning": (dict, bool),
+    "reflection": (dict, bool),
+    "guardrails": (dict, bool),
+    "web": (dict, bool),
+    "output": (dict, str),  # dict or preset string
+    "execution": (dict, str),  # dict or preset string
+    "caching": (dict, bool),
+    "autonomy": (dict, bool),
+    "skills": (dict, list),
+    "context": (dict, bool),
+    "hooks": (dict, list),
+    "templates": (dict,),
+}
+
+VALID_ROOT_KEYS = {"plugins", "defaults"}
+
+
+class ConfigValidationError(Exception):
+    """Raised when config file has validation errors."""
+    
+    def __init__(self, errors: List[str]):
+        self.errors = errors
+        message = "Config validation failed:\n" + "\n".join(f"  - {e}" for e in errors)
+        super().__init__(message)
+
+# Global config cache (lazy loaded)
+_config_cache: Optional[Dict[str, Any]] = None
+_config_loaded: bool = False
+
+
+@dataclass
+class PluginsConfig:
+    """Configuration for the plugin system."""
+    enabled: Union[bool, List[str]] = False  # True, False, or list of plugin names
+    auto_discover: bool = True
+    directories: List[str] = field(default_factory=lambda: [
+        "./.praisonai/plugins/",
+        "~/.praisonai/plugins/"
+    ])
+    
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "enabled": self.enabled,
+            "auto_discover": self.auto_discover,
+            "directories": self.directories,
+        }
+
+
+@dataclass  
+class DefaultsConfig:
+    """Default configuration for Agent parameters."""
+    # LLM defaults
+    model: Optional[str] = None
+    base_url: Optional[str] = None
+    
+    # Feature flags
+    allow_delegation: bool = False
+    allow_code_execution: bool = False
+    code_execution_mode: str = "safe"
+    
+    # Feature configs (nested dicts)
+    memory: Optional[Dict[str, Any]] = None
+    knowledge: Optional[Dict[str, Any]] = None
+    planning: Optional[Dict[str, Any]] = None
+    reflection: Optional[Dict[str, Any]] = None
+    web: Optional[Dict[str, Any]] = None
+    output: Optional[Dict[str, Any]] = None
+    execution: Optional[Dict[str, Any]] = None
+    caching: Optional[Dict[str, Any]] = None
+    autonomy: Optional[Dict[str, Any]] = None
+    skills: Optional[Dict[str, Any]] = None
+    
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "model": self.model,
+            "base_url": self.base_url,
+            "allow_delegation": self.allow_delegation,
+            "allow_code_execution": self.allow_code_execution,
+            "code_execution_mode": self.code_execution_mode,
+            "memory": self.memory,
+            "knowledge": self.knowledge,
+            "planning": self.planning,
+            "reflection": self.reflection,
+            "web": self.web,
+            "output": self.output,
+            "execution": self.execution,
+            "caching": self.caching,
+            "autonomy": self.autonomy,
+            "skills": self.skills,
+        }
+
+
+@dataclass
+class PraisonConfig:
+    """Root configuration for PraisonAI Agents."""
+    plugins: PluginsConfig = field(default_factory=PluginsConfig)
+    defaults: DefaultsConfig = field(default_factory=DefaultsConfig)
+    
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "plugins": self.plugins.to_dict(),
+            "defaults": self.defaults.to_dict(),
+        }
+
+
+def _find_config_file() -> Optional[Path]:
+    """Find config file in standard locations.
+    
+    Search order:
+    1. .praisonai/config.toml (project-local)
+    2. praisonai.toml (project root)
+    3. ~/.praisonai/config.toml (user global)
+    
+    Returns:
+        Path to config file if found, None otherwise
+    """
+    # Project-local locations
+    cwd = Path.cwd()
+    local_paths = [
+        cwd / ".praisonai" / "config.toml",
+        cwd / "praisonai.toml",
+    ]
+    
+    for path in local_paths:
+        if path.exists():
+            return path
+    
+    # User global location
+    home = Path.home()
+    global_path = home / ".praisonai" / "config.toml"
+    if global_path.exists():
+        return global_path
+    
+    return None
+
+
+def _parse_toml(path: Path) -> Dict[str, Any]:
+    """Parse TOML file with fallback for Python < 3.11.
+    
+    Args:
+        path: Path to TOML file
+        
+    Returns:
+        Parsed config dict
+    """
+    try:
+        # Python 3.11+ has built-in tomllib
+        import tomllib
+        with open(path, "rb") as f:
+            return tomllib.load(f)
+    except ImportError:
+        # Fallback for Python < 3.11
+        try:
+            import tomli
+            with open(path, "rb") as f:
+                return tomli.load(f)
+        except ImportError:
+            # No TOML parser available - return empty config
+            import logging
+            logging.debug(
+                "TOML parser not available. Install tomli for Python < 3.11: "
+                "pip install tomli"
+            )
+            return {}
+
+
+def _load_config() -> Dict[str, Any]:
+    """Load configuration from file.
+    
+    Returns:
+        Config dict (empty if no config file found)
+    """
+    config_path = _find_config_file()
+    if config_path is None:
+        return {}
+    
+    try:
+        return _parse_toml(config_path)
+    except Exception as e:
+        import logging
+        logging.warning(f"Failed to load config from {config_path}: {e}")
+        return {}
+
+
+def _dict_to_plugins_config(data: Dict[str, Any]) -> PluginsConfig:
+    """Convert dict to PluginsConfig."""
+    return PluginsConfig(
+        enabled=data.get("enabled", False),
+        auto_discover=data.get("auto_discover", True),
+        directories=data.get("directories", [
+            "./.praisonai/plugins/",
+            "~/.praisonai/plugins/"
+        ]),
+    )
+
+
+def _dict_to_defaults_config(data: Dict[str, Any]) -> DefaultsConfig:
+    """Convert dict to DefaultsConfig."""
+    return DefaultsConfig(
+        model=data.get("model"),
+        base_url=data.get("base_url"),
+        allow_delegation=data.get("allow_delegation", False),
+        allow_code_execution=data.get("allow_code_execution", False),
+        code_execution_mode=data.get("code_execution_mode", "safe"),
+        memory=data.get("memory"),
+        knowledge=data.get("knowledge"),
+        planning=data.get("planning"),
+        reflection=data.get("reflection"),
+        web=data.get("web"),
+        output=data.get("output"),
+        execution=data.get("execution"),
+        caching=data.get("caching"),
+        autonomy=data.get("autonomy"),
+        skills=data.get("skills"),
+    )
+
+
+def _dict_to_praison_config(data: Dict[str, Any]) -> PraisonConfig:
+    """Convert dict to PraisonConfig."""
+    plugins_data = data.get("plugins", {})
+    defaults_data = data.get("defaults", {})
+    
+    return PraisonConfig(
+        plugins=_dict_to_plugins_config(plugins_data),
+        defaults=_dict_to_defaults_config(defaults_data),
+    )
+
+
+def get_config(reload: bool = False) -> PraisonConfig:
+    """Get the global configuration.
+    
+    Loads config lazily on first access and caches it.
+    
+    Args:
+        reload: Force reload from file
+        
+    Returns:
+        PraisonConfig instance
+    """
+    global _config_cache, _config_loaded
+    
+    if not _config_loaded or reload:
+        raw_config = _load_config()
+        _config_cache = _dict_to_praison_config(raw_config)
+        _config_loaded = True
+    
+    return _config_cache
+
+
+def get_plugins_config() -> PluginsConfig:
+    """Get plugins configuration.
+    
+    Returns:
+        PluginsConfig instance
+    """
+    return get_config().plugins
+
+
+def get_defaults_config() -> DefaultsConfig:
+    """Get defaults configuration.
+    
+    Returns:
+        DefaultsConfig instance
+    """
+    return get_config().defaults
+
+
+def get_default(key: str, fallback: Any = None) -> Any:
+    """Get a specific default value.
+    
+    Args:
+        key: Config key (e.g., "model", "memory", "memory.backend")
+        fallback: Value to return if key not found
+        
+    Returns:
+        Config value or fallback
+    """
+    defaults = get_defaults_config()
+    
+    # Handle nested keys like "memory.backend"
+    if "." in key:
+        parts = key.split(".")
+        value = getattr(defaults, parts[0], None)
+        if value is None:
+            return fallback
+        for part in parts[1:]:
+            if isinstance(value, dict):
+                value = value.get(part)
+            else:
+                return fallback
+            if value is None:
+                return fallback
+        return value
+    
+    # Simple key
+    value = getattr(defaults, key, None)
+    return value if value is not None else fallback
+
+
+def is_plugins_enabled() -> bool:
+    """Check if plugins are enabled via config or env var.
+    
+    Returns:
+        True if plugins should be enabled
+    """
+    # Check env var first (highest precedence)
+    env_value = os.environ.get("PRAISONAI_PLUGINS", "").lower()
+    if env_value:
+        if env_value in ("true", "1", "yes", "on"):
+            return True
+        if env_value in ("false", "0", "no", "off"):
+            return False
+        # Treat as comma-separated list of plugin names
+        return True
+    
+    # Check config file
+    plugins_config = get_plugins_config()
+    if isinstance(plugins_config.enabled, bool):
+        return plugins_config.enabled
+    if isinstance(plugins_config.enabled, list):
+        return len(plugins_config.enabled) > 0
+    
+    return False
+
+
+def get_enabled_plugins() -> Optional[List[str]]:
+    """Get list of enabled plugins (if specific list provided).
+    
+    Returns:
+        List of plugin names, or None if all plugins enabled
+    """
+    # Check env var first
+    env_value = os.environ.get("PRAISONAI_PLUGINS", "").lower()
+    if env_value and env_value not in ("true", "1", "yes", "on", "false", "0", "no", "off"):
+        # Treat as comma-separated list
+        return [p.strip() for p in env_value.split(",") if p.strip()]
+    
+    # Check config file
+    plugins_config = get_plugins_config()
+    if isinstance(plugins_config.enabled, list):
+        return plugins_config.enabled
+    
+    return None  # All plugins enabled
+
+
+def clear_config_cache() -> None:
+    """Clear the config cache (for testing)."""
+    global _config_cache, _config_loaded
+    _config_cache = None
+    _config_loaded = False
+
+
+def validate_config(config: Dict[str, Any], raise_on_error: bool = False) -> List[str]:
+    """Validate config file structure and types.
+    
+    Args:
+        config: Raw config dict (from TOML parsing)
+        raise_on_error: If True, raise ConfigValidationError on errors
+        
+    Returns:
+        List of validation error messages (empty if valid)
+        
+    Example:
+        config = {"plugins": {"enabled": True}, "defaults": {"model": "gpt-4o"}}
+        errors = validate_config(config)
+        if errors:
+            print("Config errors:", errors)
+    """
+    errors = []
+    
+    # Check root keys
+    for key in config.keys():
+        if key not in VALID_ROOT_KEYS:
+            similar = _suggest_similar_key(key, VALID_ROOT_KEYS)
+            if similar:
+                errors.append(f"Unknown root key '{key}'. Did you mean '{similar}'?")
+            else:
+                errors.append(f"Unknown root key '{key}'. Valid keys: {', '.join(sorted(VALID_ROOT_KEYS))}")
+    
+    # Validate [plugins] section
+    if "plugins" in config:
+        plugins = config["plugins"]
+        if not isinstance(plugins, dict):
+            errors.append(f"[plugins] must be a table, got {type(plugins).__name__}")
+        else:
+            for key, value in plugins.items():
+                if key not in VALID_PLUGINS_KEYS:
+                    similar = _suggest_similar_key(key, VALID_PLUGINS_KEYS.keys())
+                    if similar:
+                        errors.append(f"[plugins] Unknown key '{key}'. Did you mean '{similar}'?")
+                    else:
+                        errors.append(f"[plugins] Unknown key '{key}'. Valid keys: {', '.join(sorted(VALID_PLUGINS_KEYS.keys()))}")
+                else:
+                    valid_types = VALID_PLUGINS_KEYS[key]
+                    if not isinstance(value, valid_types):
+                        errors.append(f"[plugins.{key}] Expected {_format_types(valid_types)}, got {type(value).__name__}")
+    
+    # Validate [defaults] section
+    if "defaults" in config:
+        defaults = config["defaults"]
+        if not isinstance(defaults, dict):
+            errors.append(f"[defaults] must be a table, got {type(defaults).__name__}")
+        else:
+            for key, value in defaults.items():
+                if key not in VALID_DEFAULTS_KEYS:
+                    similar = _suggest_similar_key(key, VALID_DEFAULTS_KEYS.keys())
+                    if similar:
+                        errors.append(f"[defaults] Unknown key '{key}'. Did you mean '{similar}'?")
+                    else:
+                        errors.append(f"[defaults] Unknown key '{key}'. Valid keys: {', '.join(sorted(VALID_DEFAULTS_KEYS.keys()))}")
+                else:
+                    valid_types = VALID_DEFAULTS_KEYS[key]
+                    if not isinstance(value, valid_types):
+                        errors.append(f"[defaults.{key}] Expected {_format_types(valid_types)}, got {type(value).__name__}")
+                    # Validate nested feature configs
+                    if isinstance(value, dict) and key in ("memory", "knowledge", "planning", "reflection", 
+                                                           "guardrails", "web", "output", "execution", 
+                                                           "caching", "autonomy", "context"):
+                        nested_errors = _validate_feature_config(key, value)
+                        errors.extend(nested_errors)
+    
+    if raise_on_error and errors:
+        raise ConfigValidationError(errors)
+    
+    return errors
+
+
+def _suggest_similar_key(key: str, valid_keys) -> Optional[str]:
+    """Suggest a similar valid key using simple string matching."""
+    key_lower = key.lower()
+    for valid in valid_keys:
+        # Exact match after lowercasing
+        if valid.lower() == key_lower:
+            return valid
+        # Prefix match
+        if valid.lower().startswith(key_lower) or key_lower.startswith(valid.lower()):
+            return valid
+        # Substring match
+        if key_lower in valid.lower() or valid.lower() in key_lower:
+            return valid
+    return None
+
+
+def _format_types(types: tuple) -> str:
+    """Format type tuple for error messages."""
+    type_names = []
+    for t in types:
+        if t is bool:
+            type_names.append("bool")
+        elif t is str:
+            type_names.append("str")
+        elif t is dict:
+            type_names.append("table")
+        elif t is list:
+            type_names.append("array")
+        else:
+            type_names.append(t.__name__)
+    return " or ".join(type_names)
+
+
+def _validate_feature_config(feature: str, config: Dict[str, Any]) -> List[str]:
+    """Validate a nested feature config (memory, knowledge, etc.)."""
+    errors = []
+    
+    # Common valid keys for feature configs
+    common_keys = {"enabled", "backend", "provider", "preset", "verbose"}
+    
+    # Feature-specific valid keys
+    feature_keys = {
+        "memory": {"enabled", "backend", "provider", "use_long_term", "use_short_term", 
+                   "user_id", "session_id", "db_path", "collection_name"},
+        "knowledge": {"enabled", "sources", "provider", "chunk_size", "chunk_overlap"},
+        "planning": {"enabled", "max_steps", "reasoning"},
+        "reflection": {"enabled", "max_reflect", "min_reflect", "llm"},
+        "guardrails": {"enabled", "max_retries", "validator"},
+        "web": {"enabled", "search", "fetch", "provider"},
+        "output": {"enabled", "verbose", "markdown", "stream", "metrics", "preset"},
+        "execution": {"enabled", "max_iter", "max_rpm", "max_execution_time", "preset"},
+        "caching": {"enabled", "prompt_caching", "ttl"},
+        "autonomy": {"enabled", "max_steps", "approval_required"},
+        "context": {"enabled", "max_tokens", "strategy"},
+    }
+    
+    valid_keys = feature_keys.get(feature, common_keys)
+    
+    for key in config.keys():
+        if key not in valid_keys:
+            similar = _suggest_similar_key(key, valid_keys)
+            if similar:
+                errors.append(f"[defaults.{feature}.{key}] Unknown key. Did you mean '{similar}'?")
+            # Don't error on unknown nested keys - allow flexibility
+    
+    return errors
+
+
+def get_config_path() -> Optional[Path]:
+    """Get the path to the config file if it exists.
+    
+    Returns:
+        Path to config file, or None if not found
+    """
+    return _find_config_file()
+
+
+# Convenience function to merge config defaults with explicit params
+def apply_config_defaults(
+    param_name: str,
+    explicit_value: Any,
+    config_class: Optional[type] = None,
+) -> Any:
+    """Apply config defaults to a parameter if not explicitly set.
+    
+    Args:
+        param_name: Name of the parameter (e.g., "memory", "knowledge")
+        explicit_value: Value explicitly passed by user (None if not set)
+        config_class: Optional config class to instantiate
+        
+    Returns:
+        Resolved value with config defaults applied
+        
+    Example:
+        # User passes memory=True, config has memory.backend="postgres"
+        # Result: MemoryConfig with backend="postgres"
+        
+        memory = apply_config_defaults("memory", True, MemoryConfig)
+    """
+    # If user explicitly passed a value, respect it
+    if explicit_value is not None:
+        # If True and we have config defaults, merge them
+        if explicit_value is True:
+            config_defaults = get_default(param_name)
+            if config_defaults and isinstance(config_defaults, dict):
+                if config_class:
+                    # Check if enabled key exists and is True
+                    if config_defaults.get("enabled", True):
+                        return config_class(**{k: v for k, v in config_defaults.items() if k != "enabled"})
+                return config_defaults
+        return explicit_value
+    
+    # Check if config has defaults for this param
+    config_defaults = get_default(param_name)
+    if config_defaults is None:
+        return None
+    
+    # If config has enabled=True, return the config
+    if isinstance(config_defaults, dict):
+        if config_defaults.get("enabled", False):
+            if config_class:
+                return config_class(**{k: v for k, v in config_defaults.items() if k != "enabled"})
+            return True
+    
+    return None

src/praisonai-agents/praisonaiagents/config/sample_config.toml

@@ -0,0 +1,156 @@
+# PraisonAI Agents Configuration File
+# Copy this file to .praisonai/config.toml in your project directory
+# or to ~/.praisonai/config.toml for global settings
+
+# ============================================================================
+# PLUGINS CONFIGURATION
+# ============================================================================
+# Enable background plugins (hooks, metrics, logging)
+# Note: Tools and guardrails work WITHOUT enabling plugins
+
+[plugins]
+# Enable all plugins: true
+# Enable specific plugins: ["logging", "metrics"]
+# Disable: false
+enabled = false
+
+# Auto-discover plugins from default directories
+auto_discover = true
+
+# Plugin directories to scan
+directories = [
+    "./.praisonai/plugins/",
+    "~/.praisonai/plugins/"
+]
+
+# ============================================================================
+# DEFAULT SETTINGS
+# ============================================================================
+# These defaults are used when you pass True to a feature parameter
+# Example: Agent(memory=True) will use [defaults.memory] settings
+
+[defaults]
+# Default LLM model
+model = "gpt-4o-mini"
+
+# Custom LLM endpoint (optional)
+# base_url = "http://localhost:11434/v1"
+
+# Feature flags
+allow_delegation = false
+allow_code_execution = false
+code_execution_mode = "safe"
+
+# ============================================================================
+# MEMORY DEFAULTS
+# ============================================================================
+# Used when: Agent(memory=True)
+
+[defaults.memory]
+enabled = false
+backend = "file"  # file, sqlite, redis, postgres, mongodb
+# user_id = ""    # Auto-generated if empty
+auto_memory = false
+history = false
+history_limit = 10
+
+# Learning configuration
+[defaults.memory.learn]
+enabled = false
+persona = true
+insights = true
+patterns = false
+
+# ============================================================================
+# KNOWLEDGE DEFAULTS
+# ============================================================================
+# Used when: Agent(knowledge=True)
+
+[defaults.knowledge]
+enabled = false
+embedder = "openai"
+chunking_strategy = "semantic"
+chunk_size = 1000
+chunk_overlap = 200
+retrieval_k = 5
+retrieval_threshold = 0.0
+rerank = false
+
+# ============================================================================
+# PLANNING DEFAULTS
+# ============================================================================
+# Used when: Agent(planning=True)
+
+[defaults.planning]
+enabled = false
+reasoning = false
+auto_approve = false
+read_only = false
+
+# ============================================================================
+# REFLECTION DEFAULTS
+# ============================================================================
+# Used when: Agent(reflection=True)
+
+[defaults.reflection]
+enabled = false
+min_iterations = 1
+max_iterations = 3
+
+# ============================================================================
+# WEB DEFAULTS
+# ============================================================================
+# Used when: Agent(web=True)
+
+[defaults.web]
+enabled = false
+search = true
+fetch = true
+search_provider = "duckduckgo"
+max_results = 5
+
+# ============================================================================
+# OUTPUT DEFAULTS
+# ============================================================================
+# Used when: Agent(output=True) or default output mode
+
+[defaults.output]
+preset = "silent"  # silent, actions, verbose, json, stream, status
+verbose = false
+markdown = false
+stream = false
+metrics = false
+
+# ============================================================================
+# EXECUTION DEFAULTS
+# ============================================================================
+# Used when: Agent(execution=True) or default execution limits
+
+[defaults.execution]
+max_iter = 20
+max_retry_limit = 2
+# max_rpm = null
+# max_execution_time = null
+
+# ============================================================================
+# CACHING DEFAULTS
+# ============================================================================
+# Used when: Agent(caching=True)
+
+[defaults.caching]
+enabled = true
+prompt_caching = false
+
+# ============================================================================
+# AUTONOMY DEFAULTS
+# ============================================================================
+# Used when: Agent(autonomy=True)
+
+[defaults.autonomy]
+level = "suggest"  # suggest, auto_edit, full_auto
+escalation_enabled = true
+escalation_threshold = 3
+doom_loop_detection = true
+max_consecutive_failures = 3
+require_approval_for_writes = true
+require_approval_for_shell = true

src/praisonai-agents/praisonaiagents/context/artifacts.py

@@ -181,7 +181,7 @@ class ArtifactStoreProtocol(Protocol):
     Example implementation in wrapper:
         class FileSystemArtifactStore:
             def store(self, content, metadata):
-                # Write to ~/.praison/runs/{run_id}/artifacts/
+                # Write to ~/.praisonai/runs/{run_id}/artifacts/
                 ...
     """
     

src/praisonai-agents/praisonaiagents/hooks/types.py

@@ -11,7 +11,15 @@ from typing import Optional, Dict, Any, List, Callable, Union, Literal
 
 
 class HookEvent(str, Enum):
-    """Event names for the hook system."""
+    """Event names for the hook system.
+    
+    This enum is also aliased as PluginHook for backward compatibility.
+    All plugin lifecycle events are included here for DRY compliance.
+    """
+    # Plugin/System lifecycle
+    ON_INIT = "on_init"
+    ON_SHUTDOWN = "on_shutdown"
+    
     # Tool lifecycle
     BEFORE_TOOL = "before_tool"
     AFTER_TOOL = "after_tool"
@@ -33,6 +41,8 @@ class HookEvent(str, Enum):
     ON_RETRY = "on_retry"
     
     # Message lifecycle (for bot/channel integrations)
+    BEFORE_MESSAGE = "before_message"
+    AFTER_MESSAGE = "after_message"
     MESSAGE_RECEIVED = "message_received"
     MESSAGE_SENDING = "message_sending"
     MESSAGE_SENT = "message_sent"
@@ -48,6 +58,11 @@ class HookEvent(str, Enum):
     # Tool result persistence (for modifying tool results before storage)
     TOOL_RESULT_PERSIST = "tool_result_persist"
     
+    # Permission/Config/Auth hooks
+    ON_PERMISSION_ASK = "on_permission_ask"
+    ON_CONFIG = "on_config"
+    ON_AUTH = "on_auth"
+    
     # Claude Code parity events
     USER_PROMPT_SUBMIT = "user_prompt_submit"  # When user submits a prompt
     NOTIFICATION = "notification"              # When notification is sent

src/praisonai-agents/praisonaiagents/knowledge/knowledge.py

@@ -416,7 +416,7 @@ class Knowledge:
     def config(self):
         # Generate unique collection name for each instance (only if not provided in config)
         default_collection = f"test_{int(time.time())}_{str(uuid.uuid4())[:8]}"
-        persist_dir = ".praison"
+        persist_dir = ".praisonai"
 
         # Create persistent client config
         base_config = {
@@ -862,7 +862,7 @@ class Knowledge:
         result = IndexResult()
         
         # Initialize file tracker for incremental indexing
-        state_dir = os.path.join(os.path.dirname(path) if os.path.isfile(path) else path, ".praison")
+        state_dir = os.path.join(os.path.dirname(path) if os.path.isfile(path) else path, ".praisonai")
         os.makedirs(state_dir, exist_ok=True)
         state_file = os.path.join(state_dir, ".index_state.json")
         

src/praisonai-agents/praisonaiagents/mcp/mcp_auth_storage.py

@@ -63,7 +63,7 @@ class MCPAuthStorage:
         Initialize auth storage.
         
         Args:
-            filepath: Path to auth storage file. Defaults to ~/.praison/mcp-auth.json
+            filepath: Path to auth storage file. Defaults to ~/.praisonai/mcp-auth.json
         """
         self.filepath = filepath or get_default_auth_filepath()
         self._ensure_directory()

src/praisonai-agents/praisonaiagents/memory/docs_manager.py

@@ -7,14 +7,14 @@ Provides reusable documentation context support similar to:
 - Project documentation for AI context
 
 Features:
-- Auto-discovery of docs from .praison/docs/
+- Auto-discovery of docs from .praisonai/docs/
 - Support for markdown, text, and code files
 - @doc mentions for including specific docs
 - Priority ordering for docs
 - Character limits for context window management
 
 Storage Structure:
-    .praison/docs/
+    .praisonai/docs/
     ├── project-overview.md      # Project overview
     ├── architecture.md          # Architecture decisions
     ├── api-reference.md         # API documentation
@@ -74,13 +74,13 @@ class DocsManager:
     Manages documentation context for AI agents.
     
     Provides:
-    - Auto-discovery of docs from .praison/docs/
-    - Global docs from ~/.praison/docs/
+    - Auto-discovery of docs from .praisonai/docs/
+    - Global docs from ~/.praisonai/docs/
     - @doc mentions for including specific docs
     - Priority-based ordering
     """
     
-    DOCS_DIR_NAME = ".praison/docs"
+    DOCS_DIR_NAME = ".praisonai/docs"
     SUPPORTED_EXTENSIONS = [".md", ".txt", ".rst"]
     
     # Maximum characters per doc (context window management)
@@ -97,11 +97,11 @@ class DocsManager:
         
         Args:
             workspace_path: Path to workspace/project root
-            global_docs_path: Path to global docs (default: ~/.praison/docs)
+            global_docs_path: Path to global docs (default: ~/.praisonai/docs)
             verbose: Verbosity level
         """
         self.workspace_path = Path(workspace_path) if workspace_path else Path.cwd()
-        self.global_docs_path = Path(global_docs_path) if global_docs_path else Path.home() / ".praison" / "docs"
+        self.global_docs_path = Path(global_docs_path) if global_docs_path else Path.home() / ".praisonai" / "docs"
         self.verbose = verbose
         
         self._docs: Dict[str, Doc] = {}

src/praisonai-agents/praisonaiagents/memory/file_memory.py

@@ -6,7 +6,7 @@ Provides short-term, long-term, entity, and episodic memory
 without requiring any external packages.
 
 Storage Structure:
-    .praison/memory/{user_id}/
+    .praisonai/memory/{user_id}/
     ├── config.json           # Memory configuration
     ├── short_term.json       # Rolling buffer (recent context)
     ├── long_term.json        # Persistent facts/knowledge
@@ -129,7 +129,7 @@ class FileMemory:
         
         Args:
             user_id: Unique identifier for the user/session
-            base_path: Base directory for memory storage (default: .praison/memory)
+            base_path: Base directory for memory storage (default: .praisonai/memory)
             config: Configuration overrides
             verbose: Verbosity level (0=quiet, 1=info, 2+=debug)
         """
@@ -140,7 +140,7 @@ class FileMemory:
         if base_path:
             self.base_path = Path(base_path)
         else:
-            self.base_path = Path(".praison/memory")
+            self.base_path = Path(".praisonai/memory")
         
         self.user_path = self.base_path / user_id
         self.episodic_path = self.user_path / "episodic"

src/praisonai-agents/praisonaiagents/memory/hooks.py

@@ -6,12 +6,12 @@ allowing custom actions before/after agent operations.
 
 Features:
 - Pre/post hooks for read, write, command, prompt operations
-- JSON configuration (.praison/hooks.json)
+- JSON configuration (.praisonai/hooks.json)
 - Script execution with timeout
 - Exit code handling
 - Lazy loading for performance
 
-Configuration (.praison/hooks.json):
+Configuration (.praisonai/hooks.json):
     {
         "hooks": {
             "pre_write_code": "./scripts/lint.sh",
@@ -85,7 +85,7 @@ class HooksManager:
     """
     Manages hook discovery, loading, and execution.
     
-    Hooks are configured in .praison/hooks.json and can execute
+    Hooks are configured in .praisonai/hooks.json and can execute
     scripts before/after agent operations.
     
     Example:
@@ -103,7 +103,7 @@ class HooksManager:
         ```
     """
     
-    CONFIG_FILE = ".praison/hooks.json"
+    CONFIG_FILE = ".praisonai/hooks.json"
     
     def __init__(
         self,
@@ -384,7 +384,7 @@ class HooksManager:
             timeout: Global timeout in seconds
             enabled: Whether hooks are enabled
         """
-        config_dir = self.workspace_path / ".praison"
+        config_dir = self.workspace_path / ".praisonai"
         config_dir.mkdir(parents=True, exist_ok=True)
         
         config = {

src/praisonai-agents/praisonaiagents/memory/learn/manager.py

@@ -220,10 +220,11 @@ class LearnManager:
         """
         Generate context suitable for injection into system prompt.
         
-        Returns a formatted string with relevant learnings.
+        Returns a formatted string with relevant learnings from all enabled stores.
         """
         parts = []
         
+        # 1. Persona - User preferences and profile
         if "persona" in self._stores:
             personas = self.get_persona_context(limit=5)
             if personas:
@@ -231,6 +232,7 @@ class LearnManager:
                 for p in personas:
                     parts.append(f"- {p}")
         
+        # 2. Insights - Observations and learnings
         if "insights" in self._stores:
             insights = self.get_insights_context(limit=5)
             if insights:
@@ -238,4 +240,38 @@ class LearnManager:
                 for i in insights:
                     parts.append(f"- {i}")
         
+        # 3. Patterns - Reusable knowledge patterns
+        if "patterns" in self._stores:
+            entries = self._stores["patterns"].list_all(limit=3)
+            if entries:
+                parts.append("\nKnown Patterns:")
+                for e in entries:
+                    parts.append(f"- {e.content}")
+        
+        # 4. Decisions - Past decision records (for consistency)
+        if "decisions" in self._stores:
+            entries = self._stores["decisions"].list_all(limit=3)
+            if entries:
+                parts.append("\nPast Decisions:")
+                for e in entries:
+                    parts.append(f"- {e.content}")
+        
+        # 5. Feedback - User feedback signals
+        if "feedback" in self._stores:
+            entries = self._stores["feedback"].list_all(limit=3)
+            if entries:
+                parts.append("\nUser Feedback:")
+                for e in entries:
+                    parts.append(f"- {e.content}")
+        
+        # 6. Improvements - Self-improvement proposals
+        if "improvements" in self._stores:
+            entries = self._stores["improvements"].list_all(limit=3)
+            if entries:
+                parts.append("\nImprovement Areas:")
+                for e in entries:
+                    parts.append(f"- {e.content}")
+        
+        # Note: threads are session-specific and not included in system prompt
+        
         return "\n".join(parts) if parts else ""

src/praisonai-agents/praisonaiagents/memory/mcp_config.py

@@ -6,13 +6,13 @@ Provides JSON-based MCP server configuration support similar to:
 - Windsurf MCP configuration
 
 Features:
-- Auto-discovery of MCP configs from .praison/mcp/
+- Auto-discovery of MCP configs from .praisonai/mcp/
 - JSON config files for MCP servers
 - Environment variable support
 - Easy server management
 
 Storage Structure:
-    .praison/mcp/
+    .praisonai/mcp/
     ├── filesystem.json      # Filesystem MCP server
     ├── brave-search.json    # Brave search MCP server
     └── postgres.json        # PostgreSQL MCP server
@@ -108,12 +108,12 @@ class MCPConfigManager:
     Manages MCP server configurations for AI agents.
     
     Provides:
-    - Auto-discovery of MCP configs from .praison/mcp/
-    - Global configs from ~/.praison/mcp/
+    - Auto-discovery of MCP configs from .praisonai/mcp/
+    - Global configs from ~/.praisonai/mcp/
     - Easy server management
     """
     
-    MCP_DIR_NAME = ".praison/mcp"
+    MCP_DIR_NAME = ".praisonai/mcp"
     SUPPORTED_EXTENSIONS = [".json", ".mcpjson"]
     
     def __init__(
@@ -127,11 +127,11 @@ class MCPConfigManager:
         
         Args:
             workspace_path: Path to workspace/project root
-            global_mcp_path: Path to global MCP configs (default: ~/.praison/mcp)
+            global_mcp_path: Path to global MCP configs (default: ~/.praisonai/mcp)
             verbose: Verbosity level
         """
         self.workspace_path = Path(workspace_path) if workspace_path else Path.cwd()
-        self.global_mcp_path = Path(global_mcp_path) if global_mcp_path else Path.home() / ".praison" / "mcp"
+        self.global_mcp_path = Path(global_mcp_path) if global_mcp_path else Path.home() / ".praisonai" / "mcp"
         self.verbose = verbose
         
         self._configs: Dict[str, MCPConfig] = {}

src/praisonai-agents/praisonaiagents/memory/memory.py

@@ -226,15 +226,15 @@ class Memory:
         self.embedding_dimensions = self._get_embedding_dimensions(self.embedding_model)
         self._log_verbose(f"Using embedding dimensions: {self.embedding_dimensions}")
 
-        # Create .praison directory if it doesn't exist
-        os.makedirs(".praison", exist_ok=True)
+        # Create .praisonai directory if it doesn't exist
+        os.makedirs(".praisonai", exist_ok=True)
 
         # Short-term DB
-        self.short_db = self.cfg.get("short_db", ".praison/short_term.db")
+        self.short_db = self.cfg.get("short_db", ".praisonai/short_term.db")
         self._init_stm()
 
         # Long-term DB
-        self.long_db = self.cfg.get("long_db", ".praison/long_term.db")
+        self.long_db = self.cfg.get("long_db", ".praisonai/long_term.db")
         self._init_ltm()
 
         # Conditionally init Mem0, MongoDB, or local RAG

src/praisonai-agents/praisonaiagents/memory/rules_manager.py

@@ -18,7 +18,7 @@ Features:
 - Symlink support for shared rules
 
 Storage Structure:
-    .praison/rules/
+    .praisonai/rules/
     ├── global.md           # Always applied (global)
     ├── python.md           # Glob: **/*.py
     ├── testing.md          # Glob: **/*.test.*
@@ -99,9 +99,9 @@ class RulesManager:
     Manages rules/instructions for AI agents.
     
     Supports multiple rule sources:
-    - Global rules (~/.praison/rules/)
-    - Workspace rules (.praison/rules/)
-    - Subdirectory rules (subdir/.praison/rules/)
+    - Global rules (~/.praisonai/rules/)
+    - Workspace rules (.praisonai/rules/)
+    - Subdirectory rules (subdir/.praisonai/rules/)
     - Root instruction files (CLAUDE.md, AGENTS.md, GEMINI.md, .cursorrules, .windsurfrules)
     
     Example:
@@ -122,7 +122,7 @@ class RulesManager:
         ```
     """
     
-    RULES_DIR_NAME = ".praison/rules"
+    RULES_DIR_NAME = ".praisonai/rules"
     SUPPORTED_EXTENSIONS = [".md", ".mdc", ".txt"]
     
     # Root-level instruction files (like Claude, Codex, Gemini, Cursor, Windsurf)
@@ -161,11 +161,11 @@ class RulesManager:
         
         Args:
             workspace_path: Path to workspace/project root
-            global_rules_path: Path to global rules (default: ~/.praison/rules)
+            global_rules_path: Path to global rules (default: ~/.praisonai/rules)
             verbose: Verbosity level
         """
         self.workspace_path = Path(workspace_path) if workspace_path else Path.cwd()
-        self.global_rules_path = Path(global_rules_path) if global_rules_path else Path.home() / ".praison" / "rules"
+        self.global_rules_path = Path(global_rules_path) if global_rules_path else Path.home() / ".praisonai" / "rules"
         self.verbose = verbose
         
         self._rules: Dict[str, Rule] = {}
@@ -457,7 +457,7 @@ class RulesManager:
             if rule:
                 self._rules[f"root:{rule.name}"] = rule
         
-        # 4. Load workspace rules from .praison/rules/
+        # 4. Load workspace rules from .praisonai/rules/
         workspace_rules_dir = self.workspace_path / self.RULES_DIR_NAME.replace("/", os.sep)
         workspace_rules = self._discover_rules_in_dir(workspace_rules_dir)
         for rule in workspace_rules:
@@ -485,7 +485,7 @@ class RulesManager:
         stop_at = git_root if git_root else self.workspace_path
         current = Path.cwd()
         while current != stop_at and current != current.parent:
-            # Check .praison/rules/
+            # Check .praisonai/rules/
             subdir_rules_dir = current / self.RULES_DIR_NAME.replace("/", os.sep)
             subdir_rules = self._discover_rules_in_dir(subdir_rules_dir)
             for rule in subdir_rules:

src/praisonai-agents/praisonaiagents/memory/workflows.py

@@ -6,14 +6,14 @@ allowing users to define and execute complex task sequences.
 
 Features:
 - YAML/Markdown workflow definitions
-- Auto-discovery from .praison/workflows/
+- Auto-discovery from .praisonai/workflows/
 - Step-by-step execution with context passing
 - Variable substitution
 - Conditional steps
 - Lazy loading for performance
 
 Storage Structure:
-    .praison/workflows/
+    .praisonai/workflows/
     ├── deploy.md           # Deployment workflow
     ├── test.md             # Testing workflow
     └── review.md           # Code review workflow
@@ -731,7 +731,7 @@ class WorkflowManager:
     Workflows are defined in markdown files with YAML frontmatter
     and step definitions.
     
-    Example workflow file (.praison/workflows/deploy.md):
+    Example workflow file (.praisonai/workflows/deploy.md):
         ```markdown
         ---
         name: Deploy to Production
@@ -782,7 +782,7 @@ class WorkflowManager:
         ```
     """
     
-    WORKFLOWS_DIR = ".praison/workflows"
+    WORKFLOWS_DIR = ".praisonai/workflows"
     SUPPORTED_EXTENSIONS = [".md", ".yaml", ".yml"]
     
     def __init__(
@@ -1857,7 +1857,7 @@ class WorkflowManager:
     
     def _get_checkpoints_dir(self) -> Path:
         """Get the checkpoints directory path."""
-        checkpoints_dir = self.workspace_path / ".praison" / "checkpoints"
+        checkpoints_dir = self.workspace_path / ".praisonai" / "checkpoints"
         checkpoints_dir.mkdir(parents=True, exist_ok=True)
         return checkpoints_dir
     

src/praisonai-agents/praisonaiagents/paths.py

@@ -234,6 +234,56 @@ def get_mcp_auth_path() -> Path:
     return get_data_dir() / "mcp-auth.json"
 
 
+def get_memory_dir() -> Path:
+    """
+    Get memory directory for short/long term databases.
+    
+    Returns:
+        Path to ~/.praisonai/memory/
+    """
+    return get_data_dir() / "memory"
+
+
+def get_workflows_dir() -> Path:
+    """
+    Get workflows directory.
+    
+    Returns:
+        Path to ~/.praisonai/workflows/
+    """
+    return get_data_dir() / "workflows"
+
+
+def get_summaries_dir() -> Path:
+    """
+    Get summaries directory for RAG.
+    
+    Returns:
+        Path to ~/.praisonai/summaries/
+    """
+    return get_data_dir() / "summaries"
+
+
+def get_prp_dir() -> Path:
+    """
+    Get PRP (Prompt Response Pair) output directory.
+    
+    Returns:
+        Path to ~/.praisonai/prp/
+    """
+    return get_data_dir() / "prp"
+
+
+def get_runs_dir() -> Path:
+    """
+    Get runs directory for artifacts.
+    
+    Returns:
+        Path to ~/.praisonai/runs/
+    """
+    return get_data_dir() / "runs"
+
+
 def get_project_data_dir(project_path: Optional[Union[str, Path]] = None) -> Path:
     """
     Get project-level data directory.
@@ -307,4 +357,9 @@ def get_all_paths() -> Dict[str, Path]:
         "learn": get_learn_dir(),
         "cache": get_cache_dir(),
         "mcp_auth": get_mcp_auth_path(),
+        "memory": get_memory_dir(),
+        "workflows": get_workflows_dir(),
+        "summaries": get_summaries_dir(),
+        "prp": get_prp_dir(),
+        "runs": get_runs_dir(),
     }

src/praisonai-agents/praisonaiagents/plugins/__init__.py

@@ -37,10 +37,16 @@ Usage:
 """
 
 __all__ = [
+    # Easy enable API
+    "enable",
+    "disable",
+    "list_plugins",
+    "is_enabled",
     # Core
     "PluginManager",
     "Plugin",
     "PluginHook",
+    "PluginType",
     "PluginInfo",
     "FunctionPlugin",
     "get_plugin_manager",
@@ -64,6 +70,170 @@ __all__ = [
 ]
 
 
+# ============================================================================
+# EASY ENABLE API
+# ============================================================================
+# These functions provide a simple way to enable/disable plugins globally.
+# Zero performance impact when not called - plugins only load on enable().
+# ============================================================================
+
+# Global state for plugin system (lazy initialized)
+_plugins_enabled: bool = False
+_enabled_plugin_names: list = None  # None = all, list = specific
+
+
+def enable(plugins: list = None) -> None:
+    """Enable the plugin system.
+    
+    Discovers and enables plugins from default directories.
+    This is the main entry point for using plugins.
+    
+    Args:
+        plugins: Optional list of plugin names to enable.
+                 If None, enables all discovered plugins.
+    
+    Examples:
+        # Enable all discovered plugins
+        from praisonaiagents import plugins
+        plugins.enable()
+        
+        # Enable specific plugins only
+        plugins.enable(["logging", "metrics"])
+    
+    Note:
+        - Tools and guardrails work WITHOUT calling enable()
+        - Only background plugins (hooks, metrics, logging) need enable()
+        - Can also be enabled via PRAISONAI_PLUGINS env var
+        - Can also be enabled via .praisonai/config.toml
+    """
+    global _plugins_enabled, _enabled_plugin_names
+    
+    _plugins_enabled = True
+    _enabled_plugin_names = plugins  # None = all, list = specific
+    
+    # Get plugin manager and auto-discover
+    from .manager import get_plugin_manager
+    manager = get_plugin_manager()
+    
+    # Auto-discover plugins from default directories
+    manager.auto_discover_plugins()
+    
+    # Enable specific plugins or all
+    if plugins is not None:
+        # Enable only specified plugins
+        for name in plugins:
+            manager.enable(name)
+    else:
+        # Enable all discovered plugins
+        for plugin_info in manager.list_plugins():
+            manager.enable(plugin_info.get("name", ""))
+    
+    import logging
+    logging.debug(f"Plugins enabled: {plugins if plugins else 'all'}")
+
+
+def disable(plugins: list = None) -> None:
+    """Disable plugins.
+    
+    Args:
+        plugins: Optional list of plugin names to disable.
+                 If None, disables all plugins.
+    
+    Examples:
+        # Disable all plugins
+        plugins.disable()
+        
+        # Disable specific plugins
+        plugins.disable(["logging"])
+    """
+    global _plugins_enabled, _enabled_plugin_names
+    
+    from .manager import get_plugin_manager
+    manager = get_plugin_manager()
+    
+    if plugins is not None:
+        # Disable specific plugins
+        for name in plugins:
+            manager.disable(name)
+    else:
+        # Disable all plugins
+        _plugins_enabled = False
+        _enabled_plugin_names = None
+        for plugin_info in manager.list_plugins():
+            manager.disable(plugin_info.get("name", ""))
+
+
+def list_plugins() -> list:
+    """List all discovered plugins.
+    
+    Returns:
+        List of plugin info dicts with name, version, enabled status.
+    
+    Example:
+        from praisonaiagents import plugins
+        all_plugins = plugins.list_plugins()
+        for p in all_plugins:
+            print(f"{p['name']} v{p['version']} - {'enabled' if p['enabled'] else 'disabled'}")
+    """
+    from .manager import get_plugin_manager
+    manager = get_plugin_manager()
+    
+    # Auto-discover if not already done
+    if not manager._plugins and not manager._single_file_plugins:
+        manager.auto_discover_plugins()
+    
+    # Combine registered plugins and single-file plugins
+    result = []
+    
+    # Add registered plugins (Plugin class instances)
+    for info in manager.list_plugins():
+        if hasattr(info, 'name'):
+            # PluginInfo object
+            result.append({
+                "name": info.name,
+                "version": getattr(info, 'version', '1.0.0'),
+                "description": getattr(info, 'description', ''),
+                "enabled": manager.is_enabled(info.name),
+                "type": "registered",
+            })
+        elif isinstance(info, dict):
+            # Already a dict
+            info["enabled"] = manager.is_enabled(info.get("name", ""))
+            info["type"] = "registered"
+            result.append(info)
+    
+    # Add single-file plugins
+    for name, meta in manager._single_file_plugins.items():
+        result.append({
+            "name": name,
+            "version": meta.get("version", "1.0.0"),
+            "description": meta.get("description", ""),
+            "enabled": manager.is_enabled(name),
+            "type": "single_file",
+        })
+    
+    return result
+
+
+def is_enabled(name: str = None) -> bool:
+    """Check if plugins are enabled.
+    
+    Args:
+        name: Optional plugin name to check. If None, checks if system is enabled.
+    
+    Returns:
+        True if enabled, False otherwise.
+    """
+    global _plugins_enabled
+    
+    if name is None:
+        return _plugins_enabled
+    
+    from .manager import get_plugin_manager
+    manager = get_plugin_manager()
+    return manager.is_enabled(name)
+
+
 def __getattr__(name: str):
     """Lazy load module components."""
     # Core classes
@@ -91,6 +261,10 @@ def __getattr__(name: str):
         from .plugin import FunctionPlugin
         return FunctionPlugin
     
+    if name == "PluginType":
+        from .plugin import PluginType
+        return PluginType
+    
     # Protocols
     if name == "PluginProtocol":
         from .protocols import PluginProtocol

src/praisonai-agents/praisonaiagents/plugins/discovery.py

@@ -5,8 +5,8 @@ Discovers and loads plugins from directories.
 Plugins are simple Python files with WordPress-style docstring headers.
 
 Default plugin directories (in precedence order):
-1. Project: ./.praison/plugins/
-2. User: ~/.praison/plugins/
+1. Project: ./.praisonai/plugins/
+2. User: ~/.praisonai/plugins/
 
 Usage:
     from praisonaiagents.plugins.discovery import discover_plugins, load_plugin
@@ -25,6 +25,7 @@ from pathlib import Path
 from typing import Any, Dict, List, Optional
 
 from .parser import parse_plugin_header_from_file, PluginParseError
+from ..paths import get_plugins_dir, get_project_data_dir
 
 logger = logging.getLogger(__name__)
 
@@ -32,25 +33,26 @@ logger = logging.getLogger(__name__)
 def get_default_plugin_dirs() -> List[Path]:
     """Get default plugin directory locations.
     
+    Uses centralized paths.py for consistent path management.
     Returns directories in precedence order (high to low):
-    1. Project: ./.praison/plugins/
-    2. User: ~/.praison/plugins/
+    1. Project: ./.praisonai/plugins/
+    2. User: ~/.praisonai/plugins/
     
     Returns:
         List of existing plugin directories
     """
     dirs = []
-    cwd = Path.cwd()
     
-    # Project-level directory
-    project_dir = cwd / ".praison" / "plugins"
-    if project_dir.exists() and project_dir.is_dir():
-        dirs.append(project_dir)
+    # Project-level directory (use centralized path)
+    project_data_dir = get_project_data_dir()
+    project_plugins = project_data_dir / "plugins"
+    if project_plugins.exists() and project_plugins.is_dir():
+        dirs.append(project_plugins)
     
-    # User-level directory
-    user_dir = Path.home() / ".praison" / "plugins"
-    if user_dir.exists() and user_dir.is_dir():
-        dirs.append(user_dir)
+    # User-level directory (use centralized path)
+    user_plugins = get_plugins_dir()
+    if user_plugins.exists() and user_plugins.is_dir():
+        dirs.append(user_plugins)
     
     return dirs
 
@@ -253,12 +255,13 @@ def unload_plugin(module_name: str) -> bool:
 def ensure_plugin_dir() -> Path:
     """Ensure the user plugin directory exists.
     
-    Creates ~/.praison/plugins/ if it doesn't exist.
+    Creates ~/.praisonai/plugins/ if it doesn't exist.
+    Uses centralized paths.py for consistent path management.
     
     Returns:
         Path to the user plugin directory
     """
-    user_dir = Path.home() / ".praison" / "plugins"
+    user_dir = get_plugins_dir()
     user_dir.mkdir(parents=True, exist_ok=True)
     return user_dir
 

src/praisonai-agents/praisonaiagents/plugins/manager.py

@@ -2,14 +2,16 @@
 Plugin Manager for PraisonAI Agents.
 
 Provides dynamic plugin discovery, loading, and lifecycle management.
+Thread-safe and async-safe for multi-agent environments.
 """
 
+import asyncio
 import importlib.util
 import logging
-import os
 import sys
+import threading
 from pathlib import Path
-from typing import Any, Callable, Dict, List, Optional, Type
+from typing import Any, Dict, List, Optional
 
 from .plugin import Plugin, PluginHook, PluginInfo, FunctionPlugin
 
@@ -20,6 +22,9 @@ class PluginManager:
     """
     Manages plugin discovery, loading, and execution.
     
+    Thread-safe for concurrent access in multi-agent environments.
+    Supports both sync and async hook execution.
+    
     Example:
         manager = PluginManager()
         
@@ -29,14 +34,18 @@ class PluginManager:
         # Register a plugin directly
         manager.register(MyPlugin())
         
-        # Execute hooks
+        # Execute hooks (sync)
         args = manager.execute_hook(PluginHook.BEFORE_TOOL, "bash", {"cmd": "ls"})
+        
+        # Execute hooks (async)
+        args = await manager.async_execute_hook(PluginHook.BEFORE_TOOL, "bash", {"cmd": "ls"})
     """
     
     def __init__(self):
         self._plugins: Dict[str, Plugin] = {}
         self._enabled: Dict[str, bool] = {}
         self._single_file_plugins: Dict[str, Dict[str, Any]] = {}  # WordPress-style plugins
+        self._lock = threading.RLock()  # Thread safety for multi-agent environments
     
     def register(self, plugin: Plugin) -> bool:
         """
@@ -266,6 +275,33 @@ class PluginManager:
         
         return result
     
+    async def async_execute_hook(
+        self,
+        hook: PluginHook,
+        *args,
+        **kwargs
+    ) -> Any:
+        """
+        Execute a hook across all enabled plugins asynchronously.
+        
+        Async-safe for use in async agent contexts.
+        
+        Args:
+            hook: The hook to execute
+            *args: Arguments to pass to hook
+            **kwargs: Keyword arguments to pass to hook
+            
+        Returns:
+            The result (may be modified by plugins)
+        """
+        # Use the sync version in an executor to avoid blocking
+        # This is safe because execute_hook is thread-safe with _lock
+        loop = asyncio.get_event_loop()
+        return await loop.run_in_executor(
+            None,
+            lambda: self.execute_hook(hook, *args, **kwargs)
+        )
+    
     def get_all_tools(self) -> List[Dict[str, Any]]:
         """Get all tools from all enabled plugins."""
         tools = []
@@ -364,8 +400,8 @@ class PluginManager:
         Auto-discover and load plugins from default directories.
         
         Scans:
-        - ./.praison/plugins/ (project-level)
-        - ~/.praison/plugins/ (user-level)
+        - ./.praisonai/plugins/ (project-level)
+        - ~/.praisonai/plugins/ (user-level)
         
         Returns:
             Number of plugins loaded

src/praisonai-agents/praisonaiagents/plugins/plugin.py

@@ -2,6 +2,7 @@
 Plugin definitions for PraisonAI Agents.
 
 Provides base plugin class and hook definitions.
+PluginHook is now an alias for HookEvent (DRY compliance).
 """
 
 import logging
@@ -10,68 +11,26 @@ from dataclasses import dataclass, field
 from enum import Enum
 from typing import Any, Callable, Dict, List, Optional
 
+# Import HookEvent at module level for alias (DRY)
+from ..hooks.types import HookEvent
+
 logger = logging.getLogger(__name__)
 
+# PluginHook is now an alias for HookEvent - single source of truth
+PluginHook = HookEvent
 
-class PluginHook(str, Enum):
-    """Available plugin hooks."""
+
+class PluginType(str, Enum):
+    """Types of plugins that can be registered.
     
-    # Lifecycle hooks
-    ON_INIT = "on_init"
-    ON_SHUTDOWN = "on_shutdown"
-    
-    # Agent hooks
-    BEFORE_AGENT = "before_agent"
-    AFTER_AGENT = "after_agent"
-    
-    # Tool hooks
-    BEFORE_TOOL = "before_tool"
-    AFTER_TOOL = "after_tool"
-    
-    # Message hooks (for bot/channel integrations)
-    BEFORE_MESSAGE = "before_message"
-    AFTER_MESSAGE = "after_message"
-    MESSAGE_RECEIVED = "message_received"
-    MESSAGE_SENDING = "message_sending"
-    MESSAGE_SENT = "message_sent"
-    
-    # LLM hooks
-    BEFORE_LLM = "before_llm"
-    AFTER_LLM = "after_llm"
-    
-    # Session hooks
-    SESSION_START = "session_start"
-    SESSION_END = "session_end"
-    
-    # Gateway hooks
-    GATEWAY_START = "gateway_start"
-    GATEWAY_STOP = "gateway_stop"
-    
-    # Compaction hooks (memory management)
-    BEFORE_COMPACTION = "before_compaction"
-    AFTER_COMPACTION = "after_compaction"
-    
-    # Tool result persistence (for modifying tool results before storage)
-    TOOL_RESULT_PERSIST = "tool_result_persist"
-    
-    # Permission hooks
-    ON_PERMISSION_ASK = "on_permission_ask"
-    
-    # Config hooks
-    ON_CONFIG = "on_config"
-    
-    # Auth hooks
-    ON_AUTH = "on_auth"
-    
-    # Error hooks
-    ON_ERROR = "on_error"
-    ON_RETRY = "on_retry"
-    
-    # Claude Code parity hooks
-    USER_PROMPT_SUBMIT = "user_prompt_submit"  # When user submits a prompt
-    NOTIFICATION = "notification"              # When notification is sent
-    SUBAGENT_STOP = "subagent_stop"           # When subagent completes
-    SETUP = "setup"                           # On initialization/maintenance
+    Used to categorize plugins and enable type-specific discovery.
+    """
+    TOOL = "tool"           # Provides tools for agents
+    HOOK = "hook"           # Intercepts lifecycle events
+    SKILL = "skill"         # Provides agent capabilities (SKILL.md)
+    POLICY = "policy"       # Provides execution rules
+    GUARDRAIL = "guardrail" # Provides validation rules
+    INTEGRATION = "integration"  # External tool integrations
 
 
 @dataclass

src/praisonai-agents/praisonaiagents/process/process.py

@@ -116,7 +116,7 @@ class Process:
                             agent=loop_task.agent,
                             name=f"{loop_task.name}_{task_count}" if loop_task.name else task_desc,
                             expected_output=getattr(loop_task, 'expected_output', None),
-                            callback=loop_task.callback,  # Inherit callback from parent loop task
+                            on_task_complete=loop_task.callback,  # Inherit callback from parent loop task
                             is_start=(task_count == 1),
                             task_type="task"
                         )
@@ -142,7 +142,7 @@ class Process:
                             agent=loop_task.agent,
                             name=f"{loop_task.name}_{i+1}" if loop_task.name else line.strip(),
                             expected_output=getattr(loop_task, 'expected_output', None),
-                            callback=loop_task.callback,  # Inherit callback from parent loop task
+                            on_task_complete=loop_task.callback,  # Inherit callback from parent loop task
                             is_start=(i == 0),
                             task_type="task"
                         )
@@ -936,7 +936,7 @@ Provide a JSON with the structure:
                                 agent=start_task.agent,
                                 name=f"{start_task.name}_{task_count}" if start_task.name else task_desc,
                                 expected_output=getattr(start_task, 'expected_output', None),
-                                callback=start_task.callback,  # Inherit callback from parent loop task
+                                on_task_complete=start_task.callback,  # Inherit callback from parent loop task
                                 is_start=(task_count == 1),
                                 task_type="decision",  # Change to decision type
                                 next_tasks=inherited_next_tasks,  # Inherit parent's next tasks
@@ -970,7 +970,7 @@ Provide a JSON with the structure:
                                 agent=start_task.agent,
                                 name=f"{start_task.name}_{i+1}" if start_task.name else line.strip(),
                                 expected_output=getattr(start_task, 'expected_output', None),
-                                callback=start_task.callback,  # Inherit callback from parent loop task
+                                on_task_complete=start_task.callback,  # Inherit callback from parent loop task
                                 is_start=(i == 0),
                                 task_type="task",
                                 condition={
@@ -1054,7 +1054,7 @@ Tasks by type:
                                             agent=current_task.agent,
                                             name=f"{current_task.name}_{i+1}" if current_task.name else task_desc,
                                             expected_output=getattr(current_task, 'expected_output', None),
-                                            callback=current_task.callback,  # Inherit callback from parent loop task
+                                            on_task_complete=current_task.callback,  # Inherit callback from parent loop task
                                             is_start=(i == 0),
                                             task_type="task",
                                             condition={
@@ -1079,7 +1079,7 @@ Tasks by type:
                                         agent=current_task.agent,
                                         name=f"{current_task.name}_{i+1}" if current_task.name else line.strip(),
                                         expected_output=getattr(current_task, 'expected_output', None),
-                                        callback=current_task.callback,  # Inherit callback from parent loop task
+                                        on_task_complete=current_task.callback,  # Inherit callback from parent loop task
                                         is_start=(i == 0),
                                         task_type="task",
                                         condition={

src/praisonai-agents/praisonaiagents/rag/retrieval_config.py

@@ -92,7 +92,7 @@ class RetrievalConfig:
     vector_store_provider: str = "chroma"
     vector_store_config: Dict[str, Any] = field(default_factory=dict)
     collection_name: Optional[str] = None
-    persist_path: str = ".praison"
+    persist_path: str = ".praisonai"
     
     # Embedding configuration
     embedder_provider: Optional[str] = None
@@ -233,7 +233,7 @@ class RetrievalConfig:
             vector_store_provider=data.get("vector_store_provider", "chroma"),
             vector_store_config=data.get("vector_store_config", {}),
             collection_name=data.get("collection_name"),
-            persist_path=data.get("persist_path", ".praison"),
+            persist_path=data.get("persist_path", ".praisonai"),
             embedder_provider=data.get("embedder_provider"),
             embedder_model=data.get("embedder_model"),
             auto_keywords=auto_keywords,

src/praisonai-agents/praisonaiagents/rag/summarizer.py

@@ -99,7 +99,7 @@ class HierarchicalSummarizer:
     def __init__(
         self,
         llm=None,
-        persist_path: str = ".praison/summaries",
+        persist_path: str = ".praisonai/summaries",
         verbose: bool = False,
     ):
         """

src/praisonai-agents/praisonaiagents/session.py

@@ -83,7 +83,7 @@ class Session:
             default_memory_config = {
                 "provider": "rag",
                 "use_embedding": False,  # Disable embeddings to avoid OpenAI API key requirement
-                "rag_db_path": f".praison/sessions/{self.session_id}/chroma_db"
+                "rag_db_path": f".praisonai/sessions/{self.session_id}/chroma_db"
             }
             if memory_config:
                 default_memory_config.update(memory_config)
@@ -94,7 +94,7 @@ class Session:
             self.knowledge_config = default_knowledge_config
 
             # Create session directory
-            os.makedirs(f".praison/sessions/{self.session_id}", exist_ok=True)
+            os.makedirs(f".praisonai/sessions/{self.session_id}", exist_ok=True)
 
             # Initialize components lazily
             self._memory = None

src/praisonai-agents/praisonaiagents/session/__init__.py

@@ -22,7 +22,7 @@ Usage:
     )
     agent.start("What did I say before?")  # Remembers!
 
-Default storage: ~/.praison/sessions/{session_id}.json
+Default storage: ~/.praisonai/sessions/{session_id}.json
 """
 
 from typing import TYPE_CHECKING

src/praisonai-agents/praisonaiagents/session/api.py

@@ -86,7 +86,7 @@ class Session:
             default_memory_config = {
                 "provider": "rag",
                 "use_embedding": False,
-                "rag_db_path": f".praison/sessions/{self.session_id}/chroma_db"
+                "rag_db_path": f".praisonai/sessions/{self.session_id}/chroma_db"
             }
             if memory_config:
                 default_memory_config.update(memory_config)
@@ -95,7 +95,7 @@ class Session:
             default_knowledge_config = knowledge_config or {}
             self.knowledge_config = default_knowledge_config
 
-            os.makedirs(f".praison/sessions/{self.session_id}", exist_ok=True)
+            os.makedirs(f".praisonai/sessions/{self.session_id}", exist_ok=True)
 
             self._memory = None
             self._knowledge = None

src/praisonai-agents/praisonaiagents/session/store.py

@@ -213,7 +213,7 @@ class DefaultSessionStore:
         Initialize session store.
         
         Args:
-            session_dir: Directory for session files. Defaults to ~/.praison/sessions/
+            session_dir: Directory for session files. Defaults to ~/.praisonai/sessions/
             max_messages: Maximum messages to keep per session.
             lock_timeout: Timeout for file lock acquisition.
         """

src/praisonai-agents/praisonaiagents/skills/discovery.py

@@ -5,14 +5,16 @@ from typing import List, Optional
 
 from .parser import find_skill_md, read_properties
 from .models import SkillProperties
+from ..paths import get_skills_dir, get_project_data_dir
 
 
 def get_default_skill_dirs() -> List[Path]:
     """Get default skill directory locations.
 
+    Uses centralized paths.py for consistent path management.
     Returns directories in precedence order (high to low):
-    1. Project: ./.praison/skills/ or ./.claude/skills/
-    2. User: ~/.praison/skills/
+    1. Project: ./.praisonai/skills/ or ./.claude/skills/
+    2. User: ~/.praisonai/skills/
     3. System: /etc/praison/skills/ (admin-managed)
 
     Returns:
@@ -21,19 +23,21 @@ def get_default_skill_dirs() -> List[Path]:
     dirs = []
     cwd = Path.cwd()
 
-    # Project-level directories
-    project_dirs = [
-        cwd / ".praison" / "skills",
-        cwd / ".claude" / "skills",
-    ]
-    for d in project_dirs:
-        if d.exists() and d.is_dir():
-            dirs.append(d)
+    # Project-level directories (use centralized path)
+    project_data_dir = get_project_data_dir()
+    project_skills = project_data_dir / "skills"
+    if project_skills.exists() and project_skills.is_dir():
+        dirs.append(project_skills)
+    
+    # Also check .claude/skills for compatibility
+    claude_skills = cwd / ".claude" / "skills"
+    if claude_skills.exists() and claude_skills.is_dir():
+        dirs.append(claude_skills)
 
-    # User-level directory
-    user_dir = Path.home() / ".praison" / "skills"
-    if user_dir.exists() and user_dir.is_dir():
-        dirs.append(user_dir)
+    # User-level directory (use centralized path)
+    user_skills = get_skills_dir()
+    if user_skills.exists() and user_skills.is_dir():
+        dirs.append(user_skills)
 
     # System-level directory (Unix-like systems)
     system_dir = Path("/etc/praison/skills")

src/praisonai-agents/praisonaiagents/skills/manager.py

@@ -19,7 +19,7 @@ class SkillManager:
         manager = SkillManager()
 
         # Discover skills from directories
-        manager.discover(["./skills", "~/.praison/skills"])
+        manager.discover(["./skills", "~/.praisonai/skills"])
 
         # Get XML for system prompt
         prompt_xml = manager.to_prompt()

src/praisonai-agents/praisonaiagents/storage/backends.py

@@ -167,7 +167,7 @@ class SQLiteBackend:
     
     Example:
         ```python
-        backend = SQLiteBackend(db_path="~/.praison/data.db")
+        backend = SQLiteBackend(db_path="~/.praisonai/data.db")
         backend.save("session_123", {"messages": []})
         data = backend.load("session_123")
         ```
@@ -175,7 +175,7 @@ class SQLiteBackend:
     
     def __init__(
         self,
-        db_path: str = "~/.praison/storage.db",
+        db_path: str = "~/.praisonai/storage.db",
         table_name: str = "praison_storage",
         auto_create: bool = True,
     ):
@@ -473,10 +473,10 @@ def get_backend(
     Example:
         ```python
         # File backend (default)
-        backend = get_backend("file", storage_dir="~/.praison/data")
+        backend = get_backend("file", storage_dir="~/.praisonai/data")
         
         # SQLite backend
-        backend = get_backend("sqlite", db_path="~/.praison/data.db")
+        backend = get_backend("sqlite", db_path="~/.praisonai/data.db")
         
         # Redis backend
         backend = get_backend("redis", url="redis://localhost:6379")

src/praisonai-agents/praisonaiagents/task/task.py

@@ -54,6 +54,7 @@ class Task:
         output_json: Optional[Type[BaseModel]] = None,
         output_pydantic: Optional[Type[BaseModel]] = None,
         callback: Optional[Union[Callable[[TaskOutput], Any], Callable[[TaskOutput], Coroutine[Any, Any, Any]]]] = None,
+        on_task_complete: Optional[Union[Callable[[TaskOutput], Any], Callable[[TaskOutput], Coroutine[Any, Any, Any]]]] = None,
         status: str = "not started",
         result: Optional[TaskOutput] = None,
         create_directory: Optional[bool] = False,
@@ -158,7 +159,24 @@ class Task:
         self.output_file = output_file
         self.output_json = output_json
         self.output_pydantic = output_pydantic
-        self.callback = callback
+        # Handle callback/on_task_complete: on_task_complete is canonical, callback is deprecated
+        if callback is not None and on_task_complete is None:
+            import warnings
+            warnings.warn(
+                "Parameter 'callback' is deprecated, use 'on_task_complete' instead. "
+                "Example: Task(on_task_complete=my_fn) instead of Task(callback=my_fn)",
+                DeprecationWarning,
+                stacklevel=2
+            )
+            self.callback = callback
+        elif callback is not None and on_task_complete is not None:
+            raise ValueError(
+                "Cannot specify both 'callback' and 'on_task_complete'. "
+                "Use 'on_task_complete' only (callback is deprecated)."
+            )
+        else:
+            # on_task_complete takes precedence (or both are None)
+            self.callback = on_task_complete
         self.status = status
         self.result = result
         self.create_directory = create_directory

src/praisonai-agents/praisonaiagents/tools/mentions.py

@@ -4,7 +4,7 @@ Mentions Parser for PraisonAI Agents.
 Provides @mention syntax support similar to Cursor IDE:
 - @file:path/to/file.py - Include file content
 - @web:query - Search the web
-- @doc:name - Include doc from .praison/docs/
+- @doc:name - Include doc from .praisonai/docs/
 - @rule:name - Include specific rule
 
 Usage:
@@ -30,7 +30,7 @@ class MentionsParser:
     Supports:
     - @file:path - Include file content
     - @web:query - Web search (requires web search tool)
-    - @doc:name - Include doc from .praison/docs/
+    - @doc:name - Include doc from .praisonai/docs/
     - @rule:name - Include specific rule
     - @url:https://... - Fetch URL content
     """

src/praisonai-agents/praisonaiagents/tools/registry.py

@@ -213,8 +213,8 @@ class ToolRegistry:
         """Discover and load tools from single-file plugins.
         
         Scans default plugin directories for WordPress-style plugins:
-        - ./.praison/plugins/ (project-level)
-        - ~/.praison/plugins/ (user-level)
+        - ./.praisonai/plugins/ (project-level)
+        - ~/.praisonai/plugins/ (user-level)
         
         Returns:
             Number of plugins loaded
@@ -333,8 +333,8 @@ def discover_plugins() -> int:
     """Discover and load tools from single-file plugins.
     
     Scans default plugin directories for WordPress-style plugins:
-    - ./.praison/plugins/ (project-level)
-    - ~/.praison/plugins/ (user-level)
+    - ./.praisonai/plugins/ (project-level)
+    - ~/.praisonai/plugins/ (user-level)
     
     Returns:
         Number of plugins loaded

src/praisonai-agents/praisonaiagents/workflows/workflows.py

@@ -6,14 +6,14 @@ allowing users to define and execute complex task sequences.
 
 Features:
 - YAML/Markdown workflow definitions
-- Auto-discovery from .praison/workflows/
+- Auto-discovery from .praisonai/workflows/
 - Step-by-step execution with context passing
 - Variable substitution
 - Conditional steps
 - Lazy loading for performance
 
 Storage Structure:
-    .praison/workflows/
+    .praisonai/workflows/
     ├── deploy.md           # Deployment workflow
     ├── test.md             # Testing workflow
     └── review.md           # Code review workflow
@@ -2904,7 +2904,7 @@ class WorkflowManager:
     Workflows are defined in markdown files with YAML frontmatter
     and step definitions.
     
-    Example workflow file (.praison/workflows/deploy.md):
+    Example workflow file (.praisonai/workflows/deploy.md):
         ```markdown
         ---
         name: Deploy to Production
@@ -2955,7 +2955,7 @@ class WorkflowManager:
         ```
     """
     
-    WORKFLOWS_DIR = ".praison/workflows"
+    WORKFLOWS_DIR = ".praisonai/workflows"
     SUPPORTED_EXTENSIONS = [".md", ".yaml", ".yml"]
     
     def __init__(
@@ -4246,7 +4246,7 @@ class WorkflowManager:
     
     def _get_checkpoints_dir(self) -> Path:
         """Get the checkpoints directory path."""
-        checkpoints_dir = self.workspace_path / ".praison" / "checkpoints"
+        checkpoints_dir = self.workspace_path / ".praisonai" / "checkpoints"
         checkpoints_dir.mkdir(parents=True, exist_ok=True)
         return checkpoints_dir
     

src/praisonai-agents/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "praisonaiagents"
-version = "1.3.1"
+version = "1.4.2"
 description = "Praison AI agents for completing complex tasks with Self Reflection Agents"
 readme = "README.md"
 requires-python = ">=3.10"

src/praisonai-agents/tests/example_callback.py

@@ -1,6 +1,7 @@
 from praisonaiagents import (
     Agent, 
     Task, 
+    AgentTeam,
     Agents, 
     error_logs, 
     register_display_callback,
@@ -147,7 +148,7 @@ def main():
         markdown=True
     )
 
-    # Create tasks with callbacks
+    # Create tasks with on_task_complete callbacks
     task1 = Task(
         name="research_task",
         description="""Analyze 2024's AI advancements. 
@@ -155,7 +156,7 @@ def main():
         expected_output="""A detailed report on 2024 AI advancements""",
         agent=researcher,
         tools=[internet_search_tool],
-        callback=task_callback
+        on_task_complete=task_callback
     )
 
     task2 = Task(
@@ -166,7 +167,7 @@ def main():
         expected_output="A blog post of at least 4 paragraphs",
         agent=writer,
         context=[task1],
-        callback=task_callback,
+        on_task_complete=task_callback,
         tools=[]
     )
 
@@ -175,7 +176,7 @@ def main():
         description="""Create a json object with a title of "My Task" and content of "My content".""",
         expected_output="""JSON output with title and content""",
         agent=researcher,
-        callback=task_callback
+        on_task_complete=task_callback
     )
 
     task4 = Task(
@@ -186,7 +187,7 @@ def main():
         context=[task2],
         output_file='test.txt',
         create_directory=True,
-        callback=task_callback
+        on_task_complete=task_callback
     )
 
     # Create and run agents manager

src/praisonai-agents/tests/unit/memory/test_learn_context_injection.py

@@ -0,0 +1,229 @@
+"""
+TDD Tests for Learn Context Injection.
+
+Tests that when memory="learn" is used, the learn context is automatically
+injected into the system prompt without requiring a new Agent parameter.
+
+Key behaviors:
+1. memory="learn" preset enables LearnManager
+2. Learn context is auto-injected into system prompt
+3. No new Agent params needed (uses existing memory= param)
+4. Zero overhead when learn is not enabled
+"""
+
+import pytest  # noqa: F401 - used for test markers
+
+
+class TestLearnPresetResolution:
+    """Test that memory='learn' resolves correctly."""
+    
+    def test_learn_preset_exists_in_memory_presets(self):
+        """MEMORY_PRESETS should have 'learn' preset with learn=True."""
+        from praisonaiagents.config.presets import MEMORY_PRESETS
+        
+        assert "learn" in MEMORY_PRESETS
+        assert MEMORY_PRESETS["learn"]["learn"] is True
+        assert MEMORY_PRESETS["learn"]["backend"] == "file"
+    
+    def test_memory_learn_string_resolves_to_config_with_learn_true(self):
+        """memory='learn' should resolve to MemoryConfig with learn=True."""
+        from praisonaiagents.config.param_resolver import resolve
+        from praisonaiagents.config.feature_configs import MemoryConfig
+        from praisonaiagents.config.presets import MEMORY_PRESETS, MEMORY_URL_SCHEMES
+        
+        result = resolve(
+            value="learn",
+            param_name="memory",
+            config_class=MemoryConfig,
+            presets=MEMORY_PRESETS,
+            url_schemes=MEMORY_URL_SCHEMES,
+        )
+        
+        assert isinstance(result, MemoryConfig)
+        assert result.learn is True
+
+
+class TestAgentLearnContextInjection:
+    """Test that Agent injects learn context into system prompt."""
+    
+    def test_agent_with_memory_learn_has_learn_manager(self):
+        """Agent with memory='learn' should have access to LearnManager."""
+        from praisonaiagents import Agent
+        
+        # Create agent with memory="learn"
+        agent = Agent(
+            name="test_agent",
+            instructions="Test instructions",
+            memory="learn",
+        )
+        
+        # Memory instance should exist
+        assert agent._memory_instance is not None
+        
+        # Memory should have learn property that returns LearnManager
+        if hasattr(agent._memory_instance, 'learn'):
+            learn_manager = agent._memory_instance.learn
+            assert learn_manager is not None
+    
+    def test_get_learn_context_returns_empty_when_no_learnings(self):
+        """get_learn_context should return empty string when no learnings exist."""
+        from praisonaiagents import Agent
+        import uuid
+        
+        # Use unique user_id to ensure clean state
+        unique_user_id = f"test_user_{uuid.uuid4().hex[:8]}"
+        
+        agent = Agent(
+            name="test_agent",
+            instructions="Test instructions",
+            memory={"backend": "file", "learn": True, "user_id": unique_user_id},
+        )
+        
+        # Should have get_learn_context method
+        assert hasattr(agent, 'get_learn_context')
+        
+        # Should return empty string when no learnings (fresh user)
+        context = agent.get_learn_context()
+        assert context == "" or context is None or (isinstance(context, str) and len(context) == 0)
+    
+    def test_get_learn_context_returns_learnings_when_present(self):
+        """get_learn_context should return formatted learnings when present."""
+        from praisonaiagents import Agent
+        
+        agent = Agent(
+            name="test_agent",
+            instructions="Test instructions",
+            memory="learn",
+        )
+        
+        # Add some learnings via the memory's learn manager
+        if agent._memory_instance and hasattr(agent._memory_instance, 'learn'):
+            learn_manager = agent._memory_instance.learn
+            if learn_manager:
+                learn_manager.capture_persona("User prefers concise responses")
+                learn_manager.capture_insight("User works in data science")
+        
+        # get_learn_context should now return formatted context
+        context = agent.get_learn_context()
+        
+        # Should contain the captured learnings
+        if context:
+            assert "concise" in context.lower() or "User Preferences" in context
+    
+    def test_build_system_prompt_includes_learn_context(self):
+        """_build_system_prompt should include learn context when memory='learn'."""
+        from praisonaiagents import Agent
+        
+        agent = Agent(
+            name="test_agent",
+            role="Test Role",
+            goal="Test Goal",
+            backstory="Test Backstory",
+            instructions="Test instructions",
+            memory="learn",
+        )
+        
+        # Add some learnings
+        if agent._memory_instance and hasattr(agent._memory_instance, 'learn'):
+            learn_manager = agent._memory_instance.learn
+            if learn_manager:
+                learn_manager.capture_persona("User prefers detailed explanations")
+        
+        # Build system prompt
+        system_prompt = agent._build_system_prompt()
+        
+        # System prompt should include learn context section
+        # Note: This test will fail until we implement the fix
+        if agent._memory_instance and hasattr(agent._memory_instance, 'learn'):
+            learn_manager = agent._memory_instance.learn
+            if learn_manager and learn_manager.get_persona_context():
+                assert "Learned" in system_prompt or "User Preferences" in system_prompt or "detailed explanations" in system_prompt.lower()
+
+
+class TestLearnContextZeroOverhead:
+    """Test that learn context has zero overhead when not enabled."""
+    
+    def test_no_learn_context_when_memory_true(self):
+        """memory=True should NOT enable learn context."""
+        from praisonaiagents import Agent
+        
+        agent = Agent(
+            name="test_agent",
+            instructions="Test instructions",
+            memory=True,
+        )
+        
+        # get_learn_context should return empty or None
+        context = agent.get_learn_context()
+        assert context == "" or context is None
+    
+    def test_no_learn_context_when_memory_false(self):
+        """memory=False should NOT enable learn context."""
+        from praisonaiagents import Agent
+        
+        agent = Agent(
+            name="test_agent",
+            instructions="Test instructions",
+            memory=False,
+        )
+        
+        # get_learn_context should return empty or None
+        context = agent.get_learn_context()
+        assert context == "" or context is None
+    
+    def test_no_learn_context_when_memory_none(self):
+        """memory=None should NOT enable learn context."""
+        from praisonaiagents import Agent
+        
+        agent = Agent(
+            name="test_agent",
+            instructions="Test instructions",
+        )
+        
+        # get_learn_context should return empty or None
+        context = agent.get_learn_context()
+        assert context == "" or context is None
+
+
+class TestMemoryLearnProperty:
+    """Test Memory.learn property and get_learn_context method."""
+    
+    def test_memory_learn_property_returns_learn_manager_when_enabled(self):
+        """Memory.learn should return LearnManager when learn=True in config."""
+        from praisonaiagents.memory.memory import Memory
+        
+        memory = Memory({"learn": True})
+        
+        # learn property should return LearnManager
+        learn_manager = memory.learn
+        assert learn_manager is not None
+        
+        # Should have capture methods
+        assert hasattr(learn_manager, 'capture_persona')
+        assert hasattr(learn_manager, 'capture_insight')
+        assert hasattr(learn_manager, 'to_system_prompt_context')
+    
+    def test_memory_learn_property_returns_none_when_disabled(self):
+        """Memory.learn should return None when learn is not enabled."""
+        from praisonaiagents.memory.memory import Memory
+        
+        memory = Memory({})  # No learn config
+        
+        # learn property should return None
+        assert memory.learn is None
+    
+    def test_memory_get_learn_context_returns_formatted_string(self):
+        """Memory.get_learn_context should return formatted context string."""
+        from praisonaiagents.memory.memory import Memory
+        
+        memory = Memory({"learn": True})
+        
+        # Add some learnings
+        memory.learn.capture_persona("User prefers Python")
+        memory.learn.capture_insight("User is a developer")
+        
+        # get_learn_context should return formatted string
+        context = memory.get_learn_context()
+        
+        assert isinstance(context, str)
+        assert "Python" in context or "User Preferences" in context

src/praisonai-agents/tests/unit/plugins/test_plugins_enable.py

@@ -0,0 +1,283 @@
+"""
+Unit tests for plugins.enable() API and config-driven defaults.
+
+Tests:
+- plugins.enable() / plugins.disable()
+- PRAISONAI_PLUGINS env var
+- Config file loading
+- Config-driven defaults for Agent parameters
+"""
+
+import os
+import pytest
+import tempfile
+from pathlib import Path
+from unittest.mock import patch
+
+
+class TestPluginsEnableAPI:
+    """Test the plugins.enable() API."""
+    
+    def test_enable_all_plugins(self):
+        """Test enabling all plugins."""
+        from praisonaiagents import plugins
+        
+        # Reset state
+        plugins._plugins_enabled = False
+        plugins._enabled_plugin_names = None
+        
+        # Enable all
+        plugins.enable()
+        
+        assert plugins.is_enabled() is True
+        assert plugins._enabled_plugin_names is None  # None means all
+    
+    def test_enable_specific_plugins(self):
+        """Test enabling specific plugins by name."""
+        from praisonaiagents import plugins
+        
+        # Reset state
+        plugins._plugins_enabled = False
+        plugins._enabled_plugin_names = None
+        
+        # Enable specific plugins
+        plugins.enable(["logging", "metrics"])
+        
+        assert plugins.is_enabled() is True
+        assert plugins._enabled_plugin_names == ["logging", "metrics"]
+    
+    def test_disable_all_plugins(self):
+        """Test disabling all plugins."""
+        from praisonaiagents import plugins
+        
+        # First enable
+        plugins._plugins_enabled = True
+        plugins._enabled_plugin_names = None
+        
+        # Then disable
+        plugins.disable()
+        
+        assert plugins.is_enabled() is False
+    
+    def test_list_plugins_returns_list(self):
+        """Test that list_plugins returns a list."""
+        from praisonaiagents import plugins
+        
+        result = plugins.list_plugins()
+        assert isinstance(result, list)
+    
+    def test_is_enabled_default_false(self):
+        """Test that plugins are disabled by default."""
+        from praisonaiagents import plugins
+        
+        # Reset state
+        plugins._plugins_enabled = False
+        
+        assert plugins.is_enabled() is False
+
+
+class TestPluginsEnvVar:
+    """Test PRAISONAI_PLUGINS environment variable."""
+    
+    def test_env_var_true_enables_plugins(self):
+        """Test that PRAISONAI_PLUGINS=true enables plugins."""
+        from praisonaiagents._config import _get_plugins_enabled
+        
+        with patch.dict(os.environ, {"PRAISONAI_PLUGINS": "true"}):
+            assert _get_plugins_enabled() is True
+    
+    def test_env_var_false_disables_plugins(self):
+        """Test that PRAISONAI_PLUGINS=false disables plugins."""
+        from praisonaiagents._config import _get_plugins_enabled
+        
+        with patch.dict(os.environ, {"PRAISONAI_PLUGINS": "false"}):
+            assert _get_plugins_enabled() is False
+    
+    def test_env_var_list_enables_specific(self):
+        """Test that PRAISONAI_PLUGINS=logging,metrics enables specific plugins."""
+        from praisonaiagents._config import _get_plugins_enabled, _get_plugins_list
+        
+        with patch.dict(os.environ, {"PRAISONAI_PLUGINS": "logging,metrics"}):
+            assert _get_plugins_enabled() is True
+            assert _get_plugins_list() == ["logging", "metrics"]
+    
+    def test_env_var_empty_disables(self):
+        """Test that empty PRAISONAI_PLUGINS disables plugins."""
+        from praisonaiagents._config import _get_plugins_enabled
+        
+        with patch.dict(os.environ, {"PRAISONAI_PLUGINS": ""}):
+            assert _get_plugins_enabled() is False
+
+
+class TestConfigLoader:
+    """Test config file loading."""
+    
+    def test_get_config_returns_praison_config(self):
+        """Test that get_config returns a PraisonConfig."""
+        from praisonaiagents.config.loader import get_config, PraisonConfig, clear_config_cache
+        
+        clear_config_cache()
+        config = get_config()
+        assert isinstance(config, PraisonConfig)
+    
+    def test_get_plugins_config(self):
+        """Test getting plugins config."""
+        from praisonaiagents.config.loader import get_plugins_config, PluginsConfig, clear_config_cache
+        
+        clear_config_cache()
+        plugins_config = get_plugins_config()
+        assert isinstance(plugins_config, PluginsConfig)
+    
+    def test_get_defaults_config(self):
+        """Test getting defaults config."""
+        from praisonaiagents.config.loader import get_defaults_config, DefaultsConfig, clear_config_cache
+        
+        clear_config_cache()
+        defaults_config = get_defaults_config()
+        assert isinstance(defaults_config, DefaultsConfig)
+    
+    def test_get_default_with_fallback(self):
+        """Test get_default returns fallback when key not found."""
+        from praisonaiagents.config.loader import get_default, clear_config_cache
+        
+        clear_config_cache()
+        result = get_default("nonexistent_key", "fallback_value")
+        assert result == "fallback_value"
+    
+    def test_is_plugins_enabled_from_config(self):
+        """Test is_plugins_enabled checks config file."""
+        from praisonaiagents.config.loader import is_plugins_enabled, clear_config_cache
+        
+        clear_config_cache()
+        # Without env var, should check config (which defaults to False)
+        with patch.dict(os.environ, {}, clear=True):
+            # Remove PRAISONAI_PLUGINS if present
+            os.environ.pop("PRAISONAI_PLUGINS", None)
+            result = is_plugins_enabled()
+            assert isinstance(result, bool)
+    
+    def test_config_file_parsing(self):
+        """Test parsing a TOML config file."""
+        from praisonaiagents.config.loader import _parse_toml, clear_config_cache
+        
+        # Create a temp TOML file
+        with tempfile.NamedTemporaryFile(mode='w', suffix='.toml', delete=False) as f:
+            f.write("""
+[plugins]
+enabled = true
+auto_discover = true
+
+[defaults]
+model = "gpt-4o-mini"
+
+[defaults.memory]
+enabled = true
+backend = "file"
+""")
+            f.flush()
+            
+            try:
+                result = _parse_toml(Path(f.name))
+                assert result.get("plugins", {}).get("enabled") is True
+                assert result.get("defaults", {}).get("model") == "gpt-4o-mini"
+                assert result.get("defaults", {}).get("memory", {}).get("backend") == "file"
+            finally:
+                os.unlink(f.name)
+
+
+class TestConfigDrivenDefaults:
+    """Test config-driven defaults for Agent parameters."""
+    
+    def test_apply_config_defaults_with_true(self):
+        """Test that True uses config defaults."""
+        from praisonaiagents.config.loader import apply_config_defaults, clear_config_cache
+        from praisonaiagents.config.feature_configs import MemoryConfig
+        
+        clear_config_cache()
+        
+        # When user passes True, should use config defaults
+        # Without config file, should just return True
+        result = apply_config_defaults("memory", True, MemoryConfig)
+        # Should return True or a MemoryConfig
+        assert result is True or isinstance(result, MemoryConfig)
+    
+    def test_apply_config_defaults_with_none(self):
+        """Test that None checks config for enabled."""
+        from praisonaiagents.config.loader import apply_config_defaults, clear_config_cache
+        
+        clear_config_cache()
+        
+        # When user passes None, should check config
+        result = apply_config_defaults("memory", None, None)
+        # Without config, should return None
+        assert result is None
+    
+    def test_apply_config_defaults_explicit_value(self):
+        """Test that explicit values are preserved."""
+        from praisonaiagents.config.loader import apply_config_defaults, clear_config_cache
+        from praisonaiagents.config.feature_configs import MemoryConfig
+        
+        clear_config_cache()
+        
+        # When user passes explicit config, should preserve it
+        explicit_config = MemoryConfig(backend="postgres")
+        result = apply_config_defaults("memory", explicit_config, MemoryConfig)
+        assert result == explicit_config
+
+
+class TestToolsGuardrailsExempt:
+    """Test that tools and guardrails work without plugins.enable()."""
+    
+    def test_tools_work_without_enable(self):
+        """Test that tools work without calling plugins.enable()."""
+        from praisonaiagents import plugins
+        
+        # Ensure plugins are disabled
+        plugins._plugins_enabled = False
+        
+        # Tools should still work - this is tested by Agent creation
+        # Just verify the flag is false
+        assert plugins.is_enabled() is False
+    
+    def test_guardrails_work_without_enable(self):
+        """Test that guardrails work without calling plugins.enable()."""
+        from praisonaiagents import plugins
+        
+        # Ensure plugins are disabled
+        plugins._plugins_enabled = False
+        
+        # Guardrails should still work - this is tested by Agent creation
+        # Just verify the flag is false
+        assert plugins.is_enabled() is False
+
+
+class TestPluginManagerIntegration:
+    """Test PluginManager integration with enable API."""
+    
+    def test_get_plugin_manager_singleton(self):
+        """Test that get_plugin_manager returns singleton."""
+        from praisonaiagents.plugins import get_plugin_manager
+        
+        manager1 = get_plugin_manager()
+        manager2 = get_plugin_manager()
+        assert manager1 is manager2
+    
+    def test_plugin_manager_has_required_methods(self):
+        """Test that PluginManager has all required methods."""
+        from praisonaiagents.plugins import get_plugin_manager
+        
+        manager = get_plugin_manager()
+        
+        # Check required methods exist
+        assert hasattr(manager, 'register')
+        assert hasattr(manager, 'unregister')
+        assert hasattr(manager, 'enable')
+        assert hasattr(manager, 'disable')
+        assert hasattr(manager, 'is_enabled')
+        assert hasattr(manager, 'list_plugins')
+        assert hasattr(manager, 'auto_discover_plugins')
+        assert hasattr(manager, 'execute_hook')
+
+
+if __name__ == "__main__":
+    pytest.main([__file__, "-v"])

src/praisonai-agents/tests/unit/plugins/test_unified_plugin_system.py

@@ -0,0 +1,257 @@
+"""
+Tests for Unified Plugin System.
+
+TDD tests for:
+1. Path centralization (using paths.py instead of hardcoded paths)
+2. Hook unification (PluginHook = HookEvent)
+3. PluginType enum
+4. Async hook execution
+5. Thread safety
+"""
+
+import pytest
+import threading
+import asyncio
+from pathlib import Path
+from unittest.mock import patch, MagicMock
+
+
+class TestPathCentralization:
+    """Tests for centralized path usage in discovery modules."""
+    
+    def test_plugins_discovery_uses_paths_module(self):
+        """plugins/discovery.py should use paths.get_plugins_dir()."""
+        from praisonaiagents.plugins.discovery import get_default_plugin_dirs
+        from praisonaiagents.paths import get_plugins_dir, get_project_data_dir
+        
+        # The function should use paths.py functions internally
+        # We verify by checking the returned paths match the expected format
+        dirs = get_default_plugin_dirs()
+        
+        # Should return paths that end with 'plugins'
+        for d in dirs:
+            assert d.name == "plugins", f"Expected 'plugins' dir, got {d}"
+    
+    def test_skills_discovery_uses_paths_module(self):
+        """skills/discovery.py should use paths.get_skills_dir()."""
+        from praisonaiagents.skills.discovery import get_default_skill_dirs
+        from praisonaiagents.paths import get_skills_dir
+        
+        dirs = get_default_skill_dirs()
+        
+        # Should return paths that end with 'skills'
+        for d in dirs:
+            assert d.name == "skills", f"Expected 'skills' dir, got {d}"
+    
+    def test_paths_module_returns_praisonai_dir(self):
+        """paths.py should return ~/.praisonai/ as default."""
+        from praisonaiagents.paths import get_data_dir, DEFAULT_DIR_NAME
+        
+        assert DEFAULT_DIR_NAME == ".praisonai"
+        
+        # Without env override, should use .praisonai
+        data_dir = get_data_dir()
+        assert data_dir.name in [".praisonai", ".praison"]  # .praison for legacy
+
+
+class TestHookUnification:
+    """Tests for PluginHook = HookEvent unification."""
+    
+    def test_plugin_hook_is_hook_event_alias(self):
+        """PluginHook should be an alias for HookEvent."""
+        from praisonaiagents.plugins import PluginHook
+        from praisonaiagents.hooks import HookEvent
+        
+        # They should be the same enum
+        assert PluginHook is HookEvent, "PluginHook should be HookEvent alias"
+    
+    def test_hook_event_has_plugin_lifecycle_events(self):
+        """HookEvent should have ON_INIT, ON_SHUTDOWN, etc."""
+        from praisonaiagents.hooks import HookEvent
+        
+        # Plugin lifecycle events
+        assert hasattr(HookEvent, 'ON_INIT'), "Missing ON_INIT"
+        assert hasattr(HookEvent, 'ON_SHUTDOWN'), "Missing ON_SHUTDOWN"
+        
+        # Permission/config events
+        assert hasattr(HookEvent, 'ON_PERMISSION_ASK'), "Missing ON_PERMISSION_ASK"
+        assert hasattr(HookEvent, 'ON_CONFIG'), "Missing ON_CONFIG"
+        assert hasattr(HookEvent, 'ON_AUTH'), "Missing ON_AUTH"
+        
+        # Message events
+        assert hasattr(HookEvent, 'BEFORE_MESSAGE'), "Missing BEFORE_MESSAGE"
+        assert hasattr(HookEvent, 'AFTER_MESSAGE'), "Missing AFTER_MESSAGE"
+    
+    def test_hook_event_values_match_plugin_hook_values(self):
+        """HookEvent values should match expected plugin hook values."""
+        from praisonaiagents.hooks import HookEvent
+        
+        assert HookEvent.ON_INIT.value == "on_init"
+        assert HookEvent.ON_SHUTDOWN.value == "on_shutdown"
+        assert HookEvent.BEFORE_TOOL.value == "before_tool"
+        assert HookEvent.AFTER_TOOL.value == "after_tool"
+
+
+class TestPluginType:
+    """Tests for PluginType enum."""
+    
+    def test_plugin_type_enum_exists(self):
+        """PluginType enum should exist."""
+        from praisonaiagents.plugins import PluginType
+        
+        assert PluginType is not None
+    
+    def test_plugin_type_has_expected_values(self):
+        """PluginType should have TOOL, HOOK, SKILL, POLICY."""
+        from praisonaiagents.plugins import PluginType
+        
+        assert hasattr(PluginType, 'TOOL')
+        assert hasattr(PluginType, 'HOOK')
+        assert hasattr(PluginType, 'SKILL')
+        assert hasattr(PluginType, 'POLICY')
+        
+        assert PluginType.TOOL.value == "tool"
+        assert PluginType.HOOK.value == "hook"
+        assert PluginType.SKILL.value == "skill"
+        assert PluginType.POLICY.value == "policy"
+
+
+class TestAsyncHookExecution:
+    """Tests for async hook execution."""
+    
+    @pytest.mark.asyncio
+    async def test_async_execute_hook_exists(self):
+        """PluginManager should have async_execute_hook method."""
+        from praisonaiagents.plugins import PluginManager
+        
+        manager = PluginManager()
+        assert hasattr(manager, 'async_execute_hook'), "Missing async_execute_hook"
+        assert asyncio.iscoroutinefunction(manager.async_execute_hook)
+    
+    @pytest.mark.asyncio
+    async def test_async_execute_hook_works(self):
+        """async_execute_hook should execute hooks asynchronously."""
+        from praisonaiagents.plugins import PluginManager, Plugin, PluginInfo
+        from praisonaiagents.hooks import HookEvent
+        
+        class AsyncTestPlugin(Plugin):
+            @property
+            def info(self):
+                return PluginInfo(
+                    name="async_test",
+                    hooks=[HookEvent.BEFORE_TOOL]
+                )
+            
+            def before_tool(self, tool_name, args):
+                args["async_modified"] = True
+                return args
+        
+        manager = PluginManager()
+        manager.register(AsyncTestPlugin())
+        
+        result = await manager.async_execute_hook(
+            HookEvent.BEFORE_TOOL,
+            "test_tool",
+            {"original": True}
+        )
+        
+        assert result.get("async_modified") is True
+
+
+class TestThreadSafety:
+    """Tests for thread safety in PluginManager."""
+    
+    def test_plugin_manager_has_lock(self):
+        """PluginManager should have a threading lock."""
+        from praisonaiagents.plugins import PluginManager
+        
+        manager = PluginManager()
+        assert hasattr(manager, '_lock'), "Missing _lock attribute"
+        assert isinstance(manager._lock, type(threading.RLock()))
+    
+    def test_concurrent_registration_is_safe(self):
+        """Concurrent plugin registration should be thread-safe."""
+        from praisonaiagents.plugins import PluginManager, Plugin, PluginInfo
+        from praisonaiagents.hooks import HookEvent
+        
+        class TestPlugin(Plugin):
+            def __init__(self, name):
+                self._name = name
+            
+            @property
+            def info(self):
+                return PluginInfo(name=self._name, hooks=[])
+        
+        manager = PluginManager()
+        errors = []
+        
+        def register_plugin(i):
+            try:
+                manager.register(TestPlugin(f"plugin_{i}"))
+            except Exception as e:
+                errors.append(e)
+        
+        threads = [threading.Thread(target=register_plugin, args=(i,)) for i in range(10)]
+        for t in threads:
+            t.start()
+        for t in threads:
+            t.join()
+        
+        assert len(errors) == 0, f"Thread safety errors: {errors}"
+        assert len(manager.list_plugins()) == 10
+
+
+class TestBackwardCompatibility:
+    """Tests for backward compatibility."""
+    
+    def test_legacy_plugin_hook_import_works(self):
+        """Importing PluginHook from plugins should still work."""
+        from praisonaiagents.plugins import PluginHook
+        
+        # Should be able to use PluginHook values
+        assert PluginHook.BEFORE_TOOL.value == "before_tool"
+    
+    def test_legacy_paths_fallback(self):
+        """Legacy ~/.praison/ path should work with warning."""
+        from praisonaiagents.paths import get_data_dir, LEGACY_DIR_NAME
+        
+        assert LEGACY_DIR_NAME == ".praison"
+    
+    def test_plugin_info_still_works(self):
+        """PluginInfo should still work with PluginHook."""
+        from praisonaiagents.plugins import PluginInfo, PluginHook
+        
+        info = PluginInfo(
+            name="test",
+            hooks=[PluginHook.BEFORE_TOOL, PluginHook.AFTER_TOOL]
+        )
+        
+        assert len(info.hooks) == 2
+
+
+class TestExports:
+    """Tests for proper exports in __init__.py files."""
+    
+    def test_plugins_exports_plugin_type(self):
+        """plugins/__init__.py should export PluginType."""
+        from praisonaiagents.plugins import PluginType
+        assert PluginType is not None
+    
+    def test_plugins_exports_plugin_hook(self):
+        """plugins/__init__.py should export PluginHook."""
+        from praisonaiagents.plugins import PluginHook
+        assert PluginHook is not None
+    
+    def test_hooks_exports_all_events(self):
+        """hooks/__init__.py should export HookEvent with all values."""
+        from praisonaiagents.hooks import HookEvent
+        
+        # Core events
+        assert hasattr(HookEvent, 'BEFORE_TOOL')
+        assert hasattr(HookEvent, 'AFTER_TOOL')
+        assert hasattr(HookEvent, 'BEFORE_AGENT')
+        assert hasattr(HookEvent, 'AFTER_AGENT')
+        
+        # Plugin lifecycle events (new)
+        assert hasattr(HookEvent, 'ON_INIT')
+        assert hasattr(HookEvent, 'ON_SHUTDOWN')

src/praisonai-agents/tests/unit/task/test_on_task_complete.py

@@ -0,0 +1,295 @@
+"""
+Tests for Task.on_task_complete parameter (renamed from callback).
+
+TDD: These tests are written FIRST before implementation.
+
+The rename from `callback` to `on_task_complete` aligns with:
+- WorkflowHooksConfig.on_step_complete
+- WorkflowHooksConfig.on_workflow_complete  
+- MultiAgentHooksConfig.on_task_complete
+
+This ensures consistent naming across the SDK.
+"""
+import warnings
+import pytest
+import asyncio
+
+
+class TestOnTaskCompleteParameter:
+    """Test that on_task_complete parameter works correctly."""
+    
+    def test_on_task_complete_parameter_accepted(self):
+        """Task should accept on_task_complete parameter."""
+        from praisonaiagents import Task
+        
+        def my_callback(output):
+            pass
+        
+        task = Task(
+            description="Test task",
+            on_task_complete=my_callback
+        )
+        
+        # The callback should be stored (internally as self.callback for minimal diff)
+        assert task.callback is my_callback
+    
+    def test_on_task_complete_default_none(self):
+        """on_task_complete should default to None."""
+        from praisonaiagents import Task
+        
+        task = Task(description="Test task")
+        
+        assert task.callback is None
+    
+    def test_on_task_complete_with_sync_function(self):
+        """on_task_complete should work with sync functions."""
+        from praisonaiagents import Task
+        
+        results = []
+        
+        def sync_callback(output):
+            results.append(output)
+        
+        task = Task(
+            description="Test task",
+            on_task_complete=sync_callback
+        )
+        
+        assert task.callback is sync_callback
+        assert callable(task.callback)
+    
+    def test_on_task_complete_with_async_function(self):
+        """on_task_complete should work with async functions."""
+        from praisonaiagents import Task
+        
+        async def async_callback(output):
+            pass
+        
+        task = Task(
+            description="Test task",
+            on_task_complete=async_callback
+        )
+        
+        assert task.callback is async_callback
+        assert asyncio.iscoroutinefunction(task.callback)
+
+
+class TestCallbackDeprecation:
+    """Test that callback parameter is deprecated but still works."""
+    
+    def test_callback_emits_deprecation_warning(self):
+        """Using callback= should emit DeprecationWarning."""
+        from praisonaiagents import Task
+        
+        def my_callback(output):
+            pass
+        
+        with warnings.catch_warnings(record=True) as w:
+            warnings.simplefilter("always")
+            
+            task = Task(
+                description="Test task",
+                callback=my_callback
+            )
+            
+            # Should have exactly one deprecation warning about callback
+            deprecation_warnings = [
+                x for x in w 
+                if issubclass(x.category, DeprecationWarning) 
+                and 'callback' in str(x.message).lower()
+            ]
+            assert len(deprecation_warnings) == 1
+            assert 'on_task_complete' in str(deprecation_warnings[0].message)
+    
+    def test_callback_still_works(self):
+        """callback= should still work (backward compatibility)."""
+        from praisonaiagents import Task
+        
+        def my_callback(output):
+            pass
+        
+        with warnings.catch_warnings():
+            warnings.simplefilter("ignore")
+            
+            task = Task(
+                description="Test task",
+                callback=my_callback
+            )
+            
+            # Should still be stored
+            assert task.callback is my_callback
+    
+    def test_on_task_complete_no_deprecation_warning(self):
+        """Using on_task_complete= should NOT emit deprecation warning."""
+        from praisonaiagents import Task
+        
+        def my_callback(output):
+            pass
+        
+        with warnings.catch_warnings(record=True) as w:
+            warnings.simplefilter("always")
+            
+            task = Task(
+                description="Test task",
+                on_task_complete=my_callback
+            )
+            
+            # Should have no deprecation warnings about callback
+            deprecation_warnings = [
+                x for x in w 
+                if issubclass(x.category, DeprecationWarning) 
+                and 'callback' in str(x.message).lower()
+            ]
+            assert len(deprecation_warnings) == 0
+
+
+class TestBothParametersProvided:
+    """Test behavior when both callback and on_task_complete are provided."""
+    
+    def test_both_parameters_raises_error(self):
+        """Providing both callback and on_task_complete should raise ValueError."""
+        from praisonaiagents import Task
+        
+        def callback1(output):
+            pass
+        
+        def callback2(output):
+            pass
+        
+        with warnings.catch_warnings():
+            warnings.simplefilter("ignore")
+            
+            with pytest.raises(ValueError) as exc_info:
+                Task(
+                    description="Test task",
+                    callback=callback1,
+                    on_task_complete=callback2
+                )
+            
+            assert "callback" in str(exc_info.value).lower()
+            assert "on_task_complete" in str(exc_info.value).lower()
+
+
+class TestCallbackExecution:
+    """Test that callbacks are executed correctly."""
+    
+    def test_sync_callback_receives_task_output(self):
+        """Sync callback should receive TaskOutput."""
+        from praisonaiagents import Task
+        from praisonaiagents.main import TaskOutput
+        
+        received = []
+        
+        def my_callback(output):
+            received.append(output)
+        
+        task = Task(
+            description="Test task",
+            on_task_complete=my_callback
+        )
+        
+        # Create a mock TaskOutput
+        task_output = TaskOutput(
+            description="Test",
+            raw="Test output",
+            agent="TestAgent"
+        )
+        
+        # Execute callback synchronously
+        task.execute_callback_sync(task_output)
+        
+        # Give async task time to complete
+        import time
+        time.sleep(0.1)
+        
+        assert len(received) == 1
+        assert received[0].raw == "Test output"
+    
+    @pytest.mark.asyncio
+    async def test_async_callback_receives_task_output(self):
+        """Async callback should receive TaskOutput."""
+        from praisonaiagents import Task
+        from praisonaiagents.main import TaskOutput
+        
+        received = []
+        
+        async def my_callback(output):
+            received.append(output)
+        
+        task = Task(
+            description="Test task",
+            on_task_complete=my_callback
+        )
+        
+        # Create a mock TaskOutput
+        task_output = TaskOutput(
+            description="Test",
+            raw="Test output",
+            agent="TestAgent"
+        )
+        
+        # Execute callback
+        await task.execute_callback(task_output)
+        
+        assert len(received) == 1
+        assert received[0].raw == "Test output"
+
+
+class TestNamingConsistency:
+    """Test that naming is consistent with other hooks/callbacks in the SDK."""
+    
+    def test_matches_workflow_hooks_config_pattern(self):
+        """on_task_complete follows the on_<entity>_complete pattern."""
+        from praisonaiagents.workflows.workflow_configs import WorkflowHooksConfig
+        
+        # WorkflowHooksConfig has on_step_complete, on_workflow_complete
+        config = WorkflowHooksConfig()
+        
+        assert hasattr(config, 'on_step_complete')
+        assert hasattr(config, 'on_workflow_complete')
+    
+    def test_matches_multi_agent_hooks_config_pattern(self):
+        """on_task_complete matches MultiAgentHooksConfig.on_task_complete."""
+        from praisonaiagents.config.feature_configs import MultiAgentHooksConfig
+        
+        # MultiAgentHooksConfig already has on_task_complete
+        config = MultiAgentHooksConfig()
+        
+        assert hasattr(config, 'on_task_complete')
+
+
+class TestCallbackWithMetadata:
+    """Test callback with metadata support (2-parameter callbacks)."""
+    
+    @pytest.mark.asyncio
+    async def test_two_param_callback_receives_metadata(self):
+        """Two-parameter callback should receive TaskOutput and metadata."""
+        from praisonaiagents import Task
+        from praisonaiagents.main import TaskOutput
+        
+        received_output = []
+        received_metadata = []
+        
+        async def my_callback(output, metadata):
+            received_output.append(output)
+            received_metadata.append(metadata)
+        
+        task = Task(
+            name="test_task",
+            description="Test task",
+            on_task_complete=my_callback
+        )
+        
+        task_output = TaskOutput(
+            description="Test",
+            raw="Test output",
+            agent="TestAgent"
+        )
+        
+        await task.execute_callback(task_output)
+        
+        assert len(received_output) == 1
+        assert len(received_metadata) == 1
+        assert 'task_id' in received_metadata[0]
+        assert 'task_name' in received_metadata[0]
+        assert received_metadata[0]['task_name'] == "test_task"

src/praisonai-agents/uv.lock

@@ -2549,7 +2549,7 @@ wheels = [
 
 [[package]]
 name = "praisonaiagents"
-version = "1.3.1"
+version = "1.4.2"
 source = { editable = "." }
 dependencies = [
     { name = "aiohttp" },

src/praisonai/praisonai.rb

@@ -3,8 +3,8 @@ class Praisonai < Formula
   
     desc "AI tools for various AI applications"
     homepage "https://github.com/MervinPraison/PraisonAI"
-    url "https://github.com/MervinPraison/PraisonAI/archive/refs/tags/v4.3.1.tar.gz"
-    sha256 `curl -sL https://github.com/MervinPraison/PraisonAI/archive/refs/tags/v4.3.1.tar.gz | shasum -a 256`.split.first
+    url "https://github.com/MervinPraison/PraisonAI/archive/refs/tags/v4.4.2.tar.gz"
+    sha256 `curl -sL https://github.com/MervinPraison/PraisonAI/archive/refs/tags/v4.4.2.tar.gz | shasum -a 256`.split.first
     license "MIT"
   
     depends_on "[email protected]"

src/praisonai/praisonai/deploy.py

@@ -57,7 +57,7 @@ class CloudDeployer:
             file.write("FROM python:3.11-slim\n")
             file.write("WORKDIR /app\n")
             file.write("COPY . .\n")
-            file.write("RUN pip install flask praisonai==4.3.1 gunicorn markdown\n")
+            file.write("RUN pip install flask praisonai==4.4.2 gunicorn markdown\n")
             file.write("EXPOSE 8080\n")
             file.write('CMD ["gunicorn", "-b", "0.0.0.0:8080", "api:app"]\n')
             

src/praisonai/praisonai/version.py

@@ -1 +1 @@
-__version__ = "4.3.1"
+__version__ = "4.4.2"

src/praisonai/pyproject.toml

@@ -12,7 +12,7 @@ dependencies = [
     "rich>=13.7",
     "markdown>=3.5",
     "pyparsing>=3.0.0",
-    "praisonaiagents>=1.3.1",
+    "praisonaiagents>=1.4.2",
     "python-dotenv>=0.19.0",
     "litellm>=1.81.0",
     "PyYAML>=6.0",

src/praisonai/uv.lock

@@ -4054,7 +4054,7 @@ requires-dist = [
     { name = "praisonai-tools", marker = "extra == 'autogen'", specifier = ">=0.1.0" },
     { name = "praisonai-tools", marker = "extra == 'autogen-v4'", specifier = ">=0.1.0" },
     { name = "praisonai-tools", marker = "extra == 'crewai'", specifier = ">=0.1.0" },
-    { name = "praisonaiagents", specifier = ">=1.3.1" },
+    { name = "praisonaiagents", specifier = ">=1.4.2" },
     { name = "pyautogen", marker = "extra == 'autogen'", specifier = "==0.2.29" },
     { name = "pyjwt", marker = "extra == 'os'", specifier = ">=2.8.0" },
     { name = "pyngrok", marker = "extra == 'call'", specifier = ">=1.4.0" },
@@ -4110,7 +4110,7 @@ wheels = [
 
 [[package]]
 name = "praisonaiagents"
-version = "1.3.1"
+version = "1.4.2"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
     { name = "aiohttp" },
@@ -4119,9 +4119,9 @@ dependencies = [
     { name = "pydantic" },
     { name = "rich" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/2c/43/16763f409085b31beab6fef2db3f5b7c0163f3bec301d372b242b646a4e3/praisonaiagents-1.3.1.tar.gz", hash = "sha256:a43aac2595cce2360f3054ec80698b68584e9d3aa3794bdf6db92d57aa3898c0", size = 1176178, upload-time = "2026-02-02T15:02:57.2Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/f8/54/ec17e7e4331cd191511d073f236e797856ab5a6998761117b6e51ee6d2f8/praisonaiagents-1.4.2.tar.gz", hash = "sha256:53760024b034d3ff166b6ee499e74fc29f41a301f6054608f68d13be310fa14f", size = 1184243, upload-time = "2026-02-03T08:42:10.738Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/b7/d9/23874d35c9255983c86809f0fed7bbe37ba77a3b2d195619765eae698ce2/praisonaiagents-1.3.1-py3-none-any.whl", hash = "sha256:8142c3a6c9bf0fa74dbae37615db91ae50791c26eb7359e8b6f026f44328178b", size = 1170336, upload-time = "2026-02-02T15:02:55.128Z" },
+    { url = "https://files.pythonhosted.org/packages/47/a1/de39d2bd2a25387c513c3bc87a87fb578bea15620bd11e6133f89561a820/praisonaiagents-1.4.2-py3-none-any.whl", hash = "sha256:3d5b47c83f7b0f013b9eda85d2d870f5ef8a7e03a1326ea57d0ab3576d65f201", size = 1179296, upload-time = "2026-02-03T08:42:08.118Z" },
 ]
 
 [[package]]