persistia-memory-for-claude-code

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 diff daily, 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_size and timeout_minutes controls
• 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:

1. Creates _brain/ directory structure
2. Performs initial project scan
3. Asks for missing context (credentials, product details)
4. Initializes isolated git repository
5. Installs scheduler (launchd on macOS, systemd on Linux)
6. 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 operations
• schedule — daily, weekly, monthly
• enabled — 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:

1. Check git diff output size:

   git diff --stat
   

2. Add large generated files to .gitignore:

   echo "dist/" >> .gitignore
   echo "build/" >> .gitignore
   

3. Reduce task batch_size in _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

1. Teach incrementally — add skills as you work, not all upfront
2. Use descriptive task IDs — makes queue management easier
3. Start with small batch_size — increase after confirming reliability
4. Review proactive suggestions — Persistia suggests, you decide
5. Commit brain changes — treat _brain/ like documentation
6. Back up to GitHub — install gh for automatic cloud sync
7. Share skills with team — clone brain repo across team members

Architecture Notes

• Brain repo is isolated — separate .git from 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