persistia-memory-for-claude-code
Install and configure Persistia to give Claude Code self-updating persistent memory across sessions
How do I install this agent skill?
npx skills add https://github.com/reason-machines/claude-code-skills --skill persistia-memory-for-claude-codeIs this agent skill safe to install?
- Gen Agent Trust Hubfail
This skill is highly dangerous as it downloads and executes a script directly from an untrusted GitHub account, which could allow an attacker to gain full control over your system. It also establishes permanent access by installing background services and scans your entire project—including sensitive files like .env—to read private API keys and database credentials.
- Socketwarn
1 alert: gptAnomaly
- Snykfail
Risk: CRITICAL · 4 issues
What does this agent skill do?
Persistia Memory for Claude Code
Skill by ara.so — Claude Code Skills collection.
Persistia gives Claude Code self-updating persistent memory by creating a _brain/ directory that tracks your project context, skills, tasks, and operations. It uses git diffs to update only what changed, making it token-efficient and always current.
What It Does
- Initial project scan — reads code, docs, configs, environment files on first run
- Self-updating context — runs
git diffdaily, only reads changed files - Persistent skills — rules taught once are saved to
_brain/skills/and loaded every session - Autonomous tasks — schedule tasks in plain language with
batch_sizeandtimeout_minutescontrols - Proactive monitoring — scans metrics and customers every 3 days when idle
- Private git repo — entire brain is version-controlled in isolated repository with optional GitHub backup
Installation
Run from project root:
curl -fsSL https://raw.githubusercontent.com/bernardohcrocha/persistia-for-claude-code/main/setup.sh | bash
Requirements:
- git
- Node.js 18+
- Optional: GitHub CLI (
gh) for automatic private repo creation and cloud backup
The setup script:
- Creates
_brain/directory structure - Performs initial project scan
- Asks for missing context (credentials, product details)
- Initializes isolated git repository
- Installs scheduler (launchd on macOS, systemd on Linux)
- Optionally creates private GitHub remote
Directory Structure
_brain/
├── .git/ # Isolated brain repository
├── index.md # Agent reads this first every session
├── dashboard.html # Live command center (auto-refreshes every 5 min)
├── core/ # Product, brand, ICP definitions
│ ├── product.md
│ ├── brand.md
│ └── icp.md
├── operations/ # Auto-updated metrics and customer data
│ ├── metrics.json
│ └── customers/
├── skills/ # Permanent rules and behaviors
│ ├── code-style.md
│ ├── deployment.md
│ └── ...
└── tasks/ # Scheduled task queue
├── queue.json
└── completed/
Key Concepts
Skills (Permanent Memory)
Skills are persistent rules that apply to all future sessions. Create them conversationally:
Example interaction:
You: "Always use TypeScript strict mode and include JSDoc for public APIs"
Claude: [creates _brain/skills/typescript-conventions.md]
Skills are automatically loaded at session start via index.md.
Tasks (Autonomous Scheduling)
Schedule tasks in _brain/tasks/queue.json:
{
"tasks": [
{
"id": "weekly-metrics",
"description": "Pull last week's numbers from Stripe, flag anomalies, queue follow-ups for accounts below quota",
"schedule": "weekly",
"day": "monday",
"time": "09:00",
"batch_size": 50,
"timeout_minutes": 10,
"enabled": true
},
{
"id": "inactive-signups",
"description": "Find signups from last 30 days with no activity. Visit company websites and draft personalized re-engagement emails",
"schedule": "daily",
"time": "14:00",
"batch_size": 20,
"timeout_minutes": 5,
"enabled": true
}
]
}
Task properties:
batch_size— cap items processed per run (prevents timeouts)timeout_minutes— default 5, increase for complex operationsschedule—daily,weekly,monthlyenabled— toggle without deleting
Operations (Auto-Updated Context)
_brain/operations/ contains auto-updated data from your tools:
metrics.json example:
{
"updated_at": "2026-06-04T10:00:00Z",
"revenue": {
"mrr": 45000,
"change_30d": 12.5
},
"customers": {
"total": 234,
"active": 198,
"at_risk": 12
},
"support": {
"open_tickets": 8,
"avg_response_hours": 2.3
}
}
Persistia reads credentials from .env to update this automatically.
Common Usage Patterns
Initial Setup Conversation
You: "Install persistia"
Claude: [runs setup.sh]
Claude: "I need a few details. What's your product positioning in one sentence?"
You: "Developer platform for real-time data sync"
Claude: "What integrations should I track?"
You: "Stripe for revenue, Intercom for support, PostgreSQL for usage"
Claude: [creates _brain/core/product.md, configures integrations]
Teaching a Skill
You: "When deploying, always run tests, build, then push to staging before production"
Claude: [creates _brain/skills/deployment-process.md]
# Next session
You: "Deploy the latest changes"
Claude: [automatically follows deployment-process.md]
Scheduling a Task
You: "Every Monday at 9am, check which customers had usage drops >30% and draft personalized check-in emails"
Claude: [adds task to _brain/tasks/queue.json with batch_size and timeout]
Asking Cross-Tool Questions
You: "Which customers churned this month and what were their last support interactions?"
Claude: [queries _brain/operations/metrics.json and customer records, cross-references support history]
Viewing Dashboard
Open _brain/dashboard.html in browser — auto-refreshes every 5 minutes showing:
- Recent metrics trends
- Task queue status
- At-risk customers
- Pending actions
Configuration
Environment Variables
Persistia reads existing .env files for integrations. Common variables:
# Stripe
STRIPE_API_KEY=sk_live_xxxxx
# Database
DATABASE_URL=postgresql://user:pass@host:5432/db
# Support
INTERCOM_ACCESS_TOKEN=xxxxx
# GitHub (optional, for brain repo backup)
GITHUB_TOKEN=ghp_xxxxx
Customizing Update Frequency
Edit scheduler configuration:
macOS (launchd):
nano ~/Library/LaunchAgents/com.persistia.brain-update.plist
Linux (systemd):
nano ~/.config/systemd/user/persistia-brain-update.timer
Default: daily at 3am. Change <integer> values for Hour and Minute.
Batch Size and Timeout Tuning
For large datasets, adjust task settings:
{
"id": "large-customer-outreach",
"batch_size": 100, // Process 100 at a time
"timeout_minutes": 15, // Allow 15 min per batch
"enabled": true
}
Troubleshooting
Brain Not Updating
Check scheduler status:
macOS:
launchctl list | grep persistia
launchctl start com.persistia.brain-update
Linux:
systemctl --user status persistia-brain-update.timer
systemctl --user start persistia-brain-update.service
View logs:
# macOS
tail -f ~/Library/Logs/persistia-brain-update.log
# Linux
journalctl --user -u persistia-brain-update.service -f
Context Not Loading
Verify _brain/index.md exists and contains navigation to all sections:
cat _brain/index.md
Should reference core/, skills/, operations/, and tasks/.
GitHub Sync Failing
Re-authenticate GitHub CLI:
gh auth login
gh auth refresh -s repo
Manually push brain repo:
cd _brain
git push origin main
High Token Usage
Persistia uses git diff to minimize token consumption. If still high:
-
Check
git diffoutput size:git diff --stat -
Add large generated files to
.gitignore:echo "dist/" >> .gitignore echo "build/" >> .gitignore -
Reduce task
batch_sizein_brain/tasks/queue.json
Task Timeouts
Increase timeout_minutes for complex tasks:
{
"id": "complex-analysis",
"timeout_minutes": 20,
"batch_size": 10
}
Or split into smaller subtasks with dependencies.
Manual Commands
Force brain update:
cd _brain && git diff HEAD~1 && npm run update
View brain commit history:
cd _brain && git log --oneline
Export brain to share with team:
cd _brain && git bundle create ../project-brain.bundle --all
Import shared brain:
git clone project-brain.bundle _brain
Disable proactive scanning:
echo '{"proactive_scan": false}' > _brain/config.json
Best Practices
- Teach incrementally — add skills as you work, not all upfront
- Use descriptive task IDs — makes queue management easier
- Start with small batch_size — increase after confirming reliability
- Review proactive suggestions — Persistia suggests, you decide
- Commit brain changes — treat
_brain/like documentation - Back up to GitHub — install
ghfor automatic cloud sync - Share skills with team — clone brain repo across team members
Architecture Notes
- Brain repo is isolated — separate
.gitfrom main project - Uses symbolic execution for git operations (no submodules)
- Scheduler runs in user space (no sudo required)
- All data plain text and version-controlled
- No external APIs except GitHub (optional)
For detailed architecture: ARCHITECTURE.md
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/reason-machines/claude-code-skills/persistia-memory-for-claude-code">View persistia-memory-for-claude-code on skillZs</a>