Documentation Index
Fetch the complete documentation index at: https://mintlify.com/sipeed/picoclaw/llms.txt
Use this file to discover all available pages before exploring further.
Overview
PicoClaw stores all agent data in a workspace directory. By default, this is ~/.picoclaw/workspace, but you can customize it.
Workspace Location
Configuration
Set workspace path in config.json:
{
"agents": {
"defaults": {
"workspace": "~/.picoclaw/workspace"
}
}
}
Environment Variable
Override workspace location:
PICOCLAW_AGENTS_DEFAULTS_WORKSPACE=/custom/workspace picoclaw agent
Using PICOCLAW_HOME
Set the root directory for all PicoClaw data:
PICOCLAW_HOME=/opt/picoclaw picoclaw agent
/opt/picoclaw/config.json (if you also set PICOCLAW_CONFIG)/opt/picoclaw/workspace/ (default workspace)
Directory Structure
~/.picoclaw/workspace/
├── sessions/ # Conversation sessions and history
├── memory/ # Long-term memory storage
├── state/ # Persistent state data
├── cron/ # Scheduled jobs database
├── skills/ # Custom user skills
├── AGENTS.md # Agent behavior guidelines
├── HEARTBEAT.md # Periodic task instructions
├── IDENTITY.md # Agent identity and personality
├── SOUL.md # Agent soul and core values
├── TOOLS.md # Tool descriptions and usage
└── USER.md # User preferences and context
Directory Descriptions
sessions/
Purpose: Stores conversation history for each session.
Structure:
sessions/
├── telegram_123456789.json
├── discord_987654321.json
└── cli_session_20260303.json
- Message history
- Tool usage logs
- Session metadata
memory/
Purpose: Long-term memory storage for the agent.
File: memory/MEMORY.md
The agent uses this to remember:
- Important user preferences
- Past interactions and learnings
- Context across sessions
Example MEMORY.md:
# Agent Memory
## User Preferences
- Prefers Python 3.11+
- Uses VS Code as editor
- Works on machine learning projects
## Past Projects
- Built a sentiment analysis model (Feb 2026)
- Deployed a chatbot to Heroku (Mar 2026)
state/
Purpose: Persistent state data.
Files:
state/last_channel.txt - Last used communication channelstate/*.json - Other state data
cron/
Purpose: Scheduled jobs database.
Structure:
cron/
├── job_12345.json
├── job_67890.json
└── cron.db
- Schedule (cron expression or interval)
- Task description
- Execution history
skills/
Purpose: User-defined custom skills.
Structure:
skills/
├── my-skill/
│ ├── SKILL.md
│ └── script.py
└── another-skill/
└── SKILL.md
Configuration Files
AGENTS.md
Purpose: Define agent behavior guidelines.
Example:
# Agent Guidelines
## Behavior
- Always explain your reasoning
- Ask for clarification when uncertain
- Provide code examples when helpful
## Code Style
- Use type hints in Python
- Follow PEP 8 style guide
- Include docstrings for functions
HEARTBEAT.md
Purpose: Define periodic tasks the agent should perform.
Example:
# Periodic Tasks
## Quick Tasks (respond directly)
- Report current time every hour
## Long Tasks (use spawn for async)
- Check my GitHub for new issues every 30 minutes
- Search for AI news every 2 hours and summarize
IDENTITY.md
Purpose: Define agent identity and personality.
Example:
# Agent Identity
I am a helpful coding assistant specializing in Python and machine learning.
I communicate in a:
- Clear and concise manner
- Professional but friendly tone
- Patient and encouraging way
SOUL.md
Purpose: Define core values and principles.
Example:
# Agent Soul
## Core Principles
1. Privacy - Never share user data
2. Accuracy - Verify facts before stating them
3. Helpfulness - Always try to solve the user's problem
# Available Tools
## web_search
Search the web for information.
Usage: When you need current information not in your training data.
## exec
Execute shell commands.
Usage: For file operations, git commands, package management.
USER.md
Purpose: Store user preferences and context.
Example:
# User Profile
## Name
John Doe
## Preferences
- Programming language: Python
- Editor: VS Code
- Timezone: PST
## Projects
- sentiment-analysis-model
- personal-website
Workspace Security
Restrict to Workspace
By default, agents can only access files within the workspace:
{
"agents": {
"defaults": {
"workspace": "~/.picoclaw/workspace",
"restrict_to_workspace": true
}
}
}
- Reading
/etc/passwd
- Writing to
/usr/bin
- Executing commands outside workspace
Allow Specific Paths
Grant access to specific paths outside workspace:
{
"tools": {
"allow_read_paths": [
"/home/user/documents"
],
"allow_write_paths": [
"/home/user/output"
]
}
}
Multiple Workspaces
You can use different workspaces for different purposes:
# Personal workspace
PICOCLAW_AGENTS_DEFAULTS_WORKSPACE=~/.picoclaw/personal picoclaw agent
# Work workspace
PICOCLAW_AGENTS_DEFAULTS_WORKSPACE=~/.picoclaw/work picoclaw agent
- Conversation history
- Memory
- Cron jobs
- Skills
Backup and Migration
Backup Workspace
tar -czf picoclaw-workspace-backup.tar.gz ~/.picoclaw/workspace
Restore Workspace
tar -xzf picoclaw-workspace-backup.tar.gz -C ~/
Migrate to New Location
# Copy workspace
cp -r ~/.picoclaw/workspace /new/location/workspace
# Update config.json
{
"agents": {
"defaults": {
"workspace": "/new/location/workspace"
}
}
}
Cleanup and Maintenance
Clear Session History
rm -rf ~/.picoclaw/workspace/sessions/*
Clear Memory
rm ~/.picoclaw/workspace/memory/MEMORY.md
Clear Cron Jobs
picoclaw cron list
picoclaw cron delete <job-id>
Best Practices
- Regular backups - Backup workspace weekly
- Separate workspaces - Use different workspaces for different contexts
- Keep workspace secure - Use
restrict_to_workspace: true
- Document preferences - Keep USER.md and AGENTS.md updated
- Clean old sessions - Remove old conversation history periodically
Next Steps