Praison AI

Storage Paths

Where PraisonAI stores data — global vs project-local directories and how to customize them

PraisonAI uses two directories to organize data: a global directory in your home folder and a project-local directory in your working directory. All paths resolve through a single paths module and honor the PRAISONAI_HOME environment variable.

Diagram

Project-Local — ./.praisonai/

sessions/

knowledge/

summaries/

prp/

Global — ~/.praisonai/

config.yaml

rules/

config.yaml (schedules)

snapshots/

storage.db

mcp-auth.json

memory/

plugins/

cache/

Directory Layout

Global — ~/.praisonai/

User-level configuration and state. Applies across all projects.

PathPurposeHelper
(root)Data rootget_data_dir()
sessions/Global sessionsget_sessions_dir()
skills/User skillsget_skills_dir()
plugins/User-installed pluginsget_plugins_dir()
mcp/MCP configget_mcp_dir()
mcp-auth.jsonMCP auth tokensget_mcp_auth_path()
docs/Documentation dataget_docs_dir()
rules/Guardrail rulesget_rules_dir()
permissions/Permission dataget_permissions_dir()
storage/Generic storageget_storage_dir()
storage.dbDefault SQLite DBget_storage_path()
config.yaml → schedulesSchedule jobsget_config_path()
schedules/Legacy scheduler stateget_schedules_dir()
checkpoints/Checkpoint dataget_checkpoints_dir()
snapshots/Autonomy snapshotsget_snapshots_dir()
learn/Learning storesget_learn_dir()
cache/Disposable cacheget_cache_dir()
memory/Short/long-term DBsget_memory_dir()
workflows/Workflow dataget_workflows_dir()
summaries/RAG summariesget_summaries_dir()
prp/PRP outputget_prp_dir()
runs/Run artifactsget_runs_dir()

Project-Local — ./.praisonai/

Per-project data in your working directory. Add .praisonai/ to .gitignore.

PathPurposeHelper
(root)Project data rootget_project_data_dir()
sessions/Conversation sessionsget_project_sessions_dir()
knowledge/Knowledge base vectorsget_project_knowledge_dir()
summaries/RAG summariesget_project_summaries_dir()
prp/Context engineering outputget_project_prp_dir()

Customizing Storage Location

PRAISONAI_HOME Environment Variable

Override the global directory location:

bash
# Redirect all global paths
export PRAISONAI_HOME=/custom/path
ScenarioSetting
DockerENV PRAISONAI_HOME=/app/data
Team shared configexport PRAISONAI_HOME=/shared/team/config
CI/CDPRAISONAI_HOME=/tmp/praisonai

Legacy Migration

If ~/.praison/ exists but ~/.praisonai/ doesn’t, PraisonAI uses the legacy path with a deprecation warning:

DeprecationWarning: Using legacy data directory ~/.praison/.
Run 'praisonai migrate-data' to migrate to ~/.praisonai/.

Python API

All paths resolve through the paths module:

python
from praisonaiagents.paths import (
    # Global paths — ~/.praisonai/
    get_data_dir,           # ~/.praisonai/
    get_config_path,        # ~/.praisonai/config.yaml
    get_rules_dir,          # ~/.praisonai/rules/
    get_schedules_dir,      # ~/.praisonai/schedules/
    get_snapshots_dir,      # ~/.praisonai/snapshots/
    get_storage_dir,        # ~/.praisonai/storage/
    get_storage_path,       # ~/.praisonai/storage.db
    get_memory_dir,         # ~/.praisonai/memory/
    get_mcp_auth_path,      # ~/.praisonai/mcp-auth.json
    get_plugins_dir,        # ~/.praisonai/plugins/
    get_cache_dir,          # ~/.praisonai/cache/

    # Project-local paths — ./.praisonai/
    get_project_data_dir,       # ./.praisonai/
    get_project_sessions_dir,   # ./.praisonai/sessions/
    get_project_knowledge_dir,  # ./.praisonai/knowledge/
    get_project_summaries_dir,  # ./.praisonai/summaries/
    get_project_prp_dir,        # ./.praisonai/prp/

    # Utilities
    ensure_dir,             # Create dir if missing
    get_all_paths,          # Dict of all path names → Path objects
)

CLI

bash
# Show all resolved paths with Rich table output
praisonai paths show

# Machine-readable output
praisonai paths show --json

Example output:

Global:  /Users/you/.praisonai/
Project: /Users/you/my-app/.praisonai/
Env:     PRAISONAI_HOME (not set)

Common Patterns

Solo Developer

~/my-project/
├── main.py
└── .praisonai/          ← project data
    ├── sessions/
    └── knowledge/

~/.praisonai/            ← global config
├── config.yaml
└── mcp-auth.json

Multiple Projects

~/project-A/.praisonai/  ← isolated per project
~/project-B/.praisonai/  ← own sessions & knowledge

~/.praisonai/            ← shared config
├── rules/               ← same guardrails
└── plugins/             ← same plugins

Docker

dockerfile
ENV PRAISONAI_HOME=/app/data
WORKDIR /app

# All global paths → /app/data/
# Project paths → /app/.praisonai/

Team / CI

bash
export PRAISONAI_HOME=/shared/team/config
# All team members use same rules, schedules, plugins
# Project data stays local in ./.praisonai/

Related

Memory

Agent memory storage

 Knowledge

Knowledge base management

 Session Management

Conversation sessions

 Store Types

Storage backend comparison