skillZs
★ LIVE SKILL TAGS ★
>>> LIVE SKILLS INDEX <<<
* OPEN SOURCE *
NO LOGIN, NO TRACKING
※ REAL INSTALL DATA ※
← back to all skills
reason-machines/claude-code-skills61 installs

persistia-claude-code-memory

Install and manage Persistia to give Claude Code persistent, self-updating memory across sessions

How do I install this agent skill?

npx skills add https://github.com/reason-machines/claude-code-skills --skill persistia-claude-code-memory
view source ↗

Is this agent skill safe to install?

  • Gen Agent Trust Hubfail

    This skill downloads and executes a script from an untrusted source, harvests secrets from environment files, and establishes persistent background services. It also facilitates the export of project metadata to external repositories.

  • Socketwarn

    1 alert: gptAnomaly

  • Snykfail

    Risk: CRITICAL · 7 issues

What does this agent skill do?

Persistia for Claude Code

Skill by ara.so — Claude Code Skills collection.

Persistia gives Claude Code persistent, self-updating memory. It scans your project once, stores structured knowledge in _brain/, then monitors changes via git diff to stay current. Enables autonomous tasks, permanent skills, and cross-session context.

Installation

Must be run from project root with git initialized:

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 brain repository backup

The installer:

  1. Creates _brain/ directory structure
  2. Scans project files, reads .env files
  3. Asks only what it can't auto-detect
  4. Sets up automatic daily updates (launchd/systemd)
  5. Optionally creates private GitHub repo for brain backup

Directory Structure

_brain/
├── .git/                    # Isolated brain repository
├── index.md                 # Master navigation, read first every session
├── dashboard.html           # Live command center (auto-refresh)
├── core/
│   ├── product.md          # What you're building
│   ├── brand.md            # Voice, values, positioning
│   └── icp.md              # Ideal customer profile
├── operations/
│   ├── metrics.md          # KPIs, auto-updated daily
│   └── customers.md        # Account data, behaviors
├── skills/
│   └── *.md                # Permanent rules and behaviors
└── tasks/
    ├── queue.json          # Scheduled autonomous tasks
    └── completed/          # Execution logs

Initial Setup Flow

After installation, Claude will ask clarifying questions:

# Example questions Claude might ask:
# - "What's your product in one sentence?"
# - "What's your primary tech stack?"
# - "Which tools do you use? (Stripe, Postgres, etc.)"
# - "What's your ICP?"

Claude reads existing files (.env, package.json, README, etc.) and only asks what it can't find.

Core Concepts

1. Index-First Navigation

_brain/index.md is the entry point. Claude reads this first every session:

# Project Brain Index

## Quick Reference
- Product: [core/product.md]
- Stack: Node.js, Postgres, Stripe
- Last updated: 2026-06-04

## Priority Files
1. operations/metrics.md — current numbers
2. core/icp.md — who we serve
3. skills/code-style.md — how we write code

## Active Tasks
- Weekly report (runs Mondays)
- Churn detection (runs daily)

2. Skills (Permanent Memory)

Skills are rules that persist across sessions. Created automatically when you teach Claude something:

Example: "Always use functional components in React"

Claude creates _brain/skills/react-patterns.md:

---
created: 2026-06-04
category: code-style
---

# React Patterns

## Component Style
- Always use functional components
- Prefer hooks over class methods
- Use TypeScript for props

## Example
```javascript
// ✅ Correct
const Button: React.FC<ButtonProps> = ({ label, onClick }) => {
  return <button onClick={onClick}>{label}</button>;
};

// ❌ Avoid
class Button extends React.Component { ... }

Skills are loaded at every session start.

### 3. Autonomous Tasks

Tasks run automatically with full project context:

**Edit `_brain/tasks/queue.json`:**

```json
{
  "tasks": [
    {
      "id": "weekly-metrics",
      "name": "Weekly Metrics Report",
      "description": "Pull revenue, churn, new signups from Stripe. Flag anomalies.",
      "schedule": "weekly",
      "day": "monday",
      "time": "09:00",
      "timeout_minutes": 10,
      "enabled": true
    },
    {
      "id": "churn-detection",
      "name": "At-Risk Customer Detection",
      "description": "Find customers with 30%+ usage drop. Check support history. Draft re-engagement.",
      "schedule": "daily",
      "time": "08:00",
      "batch_size": 20,
      "timeout_minutes": 5,
      "enabled": true
    },
    {
      "id": "onboarding-follow-up",
      "name": "New User Follow-up",
      "description": "Find signups from last 30 days with no activity. Visit company website. Write personalized email.",
      "schedule": "daily",
      "time": "10:00",
      "batch_size": 10,
      "enabled": true
    }
  ]
}

Task Properties:

  • schedule: "daily", "weekly", "monthly"
  • batch_size: Max items per run (prevents timeouts)
  • timeout_minutes: Max execution time (default: 5)
  • day: For weekly tasks ("monday", "tuesday", etc.)
  • time: 24-hour format

Completed tasks log to _brain/tasks/completed/YYYY-MM-DD_task-id.md

4. Git Diff-Based Updates

Daily scheduler runs:

cd _brain && git diff HEAD~1..HEAD --name-only

Only changed files get re-indexed. Example:

# 1,000 files in project
# 3 changed today
# Claude only reads those 3

5. Credentials Management

Persistia reads existing credentials from:

  • .env files
  • Environment variables
  • Git config
  • Tool CLIs (Stripe, AWS, etc.)

No re-entry required. Uses what you already have.

Common Usage Patterns

Teaching New Skills

User: "Always format prices with 2 decimals and currency symbol"

Claude creates _brain/skills/formatting.md:

# Formatting Rules

## Prices
Always display: `$X,XXX.XX`

```javascript
const formatPrice = (cents) => {
  return new Intl.NumberFormat('en-US', {
    style: 'currency',
    currency: 'USD',
  }).format(cents / 100);
};

### Scheduling Cross-Tool Tasks

**User:** "Every Monday, pull Stripe revenue and compare to Postgres usage metrics. Flag discrepancies."

Claude adds to `queue.json` and writes execution logic in `_brain/tasks/scripts/revenue-check.js`:

```javascript
const stripe = require('stripe')(process.env.STRIPE_SECRET_KEY);
const { Pool } = require('pg');

const pool = new Pool({
  connectionString: process.env.DATABASE_URL,
});

async function checkRevenueMatch() {
  const startDate = new Date();
  startDate.setDate(startDate.getDate() - 7);
  
  // Stripe revenue
  const charges = await stripe.charges.list({
    created: { gte: Math.floor(startDate / 1000) },
    limit: 100,
  });
  
  const stripeTotal = charges.data
    .filter(c => c.status === 'succeeded')
    .reduce((sum, c) => sum + c.amount, 0);
  
  // Postgres usage
  const result = await pool.query(`
    SELECT customer_id, SUM(usage_amount) as total
    FROM usage_events
    WHERE created_at >= $1
    GROUP BY customer_id
  `, [startDate]);
  
  // Compare and flag
  const discrepancies = [];
  // ... comparison logic
  
  return discrepancies;
}

module.exports = { checkRevenueMatch };

Updating Core Knowledge

User: "We pivoted — now targeting dev tools, not marketing SaaS"

Claude updates _brain/core/icp.md and _brain/core/product.md, commits changes:

cd _brain
git add core/icp.md core/product.md
git commit -m "Update: pivot to dev tools market"
git push origin main  # If gh CLI configured

Querying Operational Data

User: "Which customers churned last month?"

Claude reads _brain/operations/customers.md (auto-updated daily from Stripe/DB), answers immediately without API calls.

Dashboard

Open in browser:

open _brain/dashboard.html

Auto-refreshes every 5 minutes. Shows:

  • Recent metrics
  • Active tasks status
  • Last brain update
  • Quick actions

Troubleshooting

Brain not updating

Check scheduler status:

macOS:

launchctl list | grep persistia
launchctl start com.persistia.update

Linux:

systemctl status persistia-update.timer
systemctl start persistia-update.service

Task timing out

Increase timeout_minutes or reduce batch_size:

{
  "id": "large-task",
  "timeout_minutes": 15,
  "batch_size": 5
}

Memory getting stale

Force re-index:

cd _brain
rm -rf operations/
# Restart Claude Code session

Git conflicts in brain repo

cd _brain
git fetch origin
git reset --hard origin/main

Advanced Configuration

Custom Update Frequency

Edit scheduler config:

macOS (~/Library/LaunchAgents/com.persistia.update.plist):

<key>StartInterval</key>
<integer>3600</integer>  <!-- seconds, 3600 = hourly -->

Linux (~/.config/systemd/user/persistia-update.timer):

[Timer]
OnCalendar=hourly

Excluding Files from Indexing

Add to .gitignore in project root:

_brain/
node_modules/
.env
*.log

Persistia respects .gitignore.

Multi-Agent Teams

Share brain repo with team:

cd _brain
git remote add origin git@github.com:yourteam/project-brain.git
git push -u origin main

Team members clone after installing Persistia:

rm -rf _brain
git clone git@github.com:yourteam/project-brain.git _brain

Best Practices

  1. Teach once, benefit forever — when you explain something, ask Claude to save it as a skill
  2. Let git diff do the work — don't manually update _brain/, let the scheduler handle it
  3. Batch large operations — use batch_size to prevent timeouts
  4. Review task logs — check _brain/tasks/completed/ weekly
  5. Commit brain changes — treat _brain/ like code, commit meaningful updates

Integration Examples

Stripe + Postgres Sync

// _brain/tasks/scripts/sync-revenue.js
const stripe = require('stripe')(process.env.STRIPE_SECRET_KEY);
const { Pool } = require('pg');

async function syncRevenue() {
  const pool = new Pool({ connectionString: process.env.DATABASE_URL });
  
  const subscriptions = await stripe.subscriptions.list({ limit: 100 });
  
  for (const sub of subscriptions.data) {
    await pool.query(`
      INSERT INTO revenue (customer_id, amount, period_start)
      VALUES ($1, $2, $3)
      ON CONFLICT (customer_id, period_start) DO UPDATE
      SET amount = $2
    `, [sub.customer, sub.plan.amount, new Date(sub.current_period_start * 1000)]);
  }
}

Slack Alert on Anomaly

// _brain/tasks/scripts/alert-churn.js
const axios = require('axios');

async function alertIfChurnSpike(churnRate) {
  if (churnRate > 0.05) {
    await axios.post(process.env.SLACK_WEBHOOK_URL, {
      text: `⚠️ Churn spike detected: ${(churnRate * 100).toFixed(1)}%`,
    });
  }
}

File Formats

All brain files are Markdown with optional YAML frontmatter:

---
updated: 2026-06-04
category: operations
auto_update: true
---

# Metrics

## MRR
$12,450 (+8.2% MoM)

## Active Users
342 (-2 from last week)

Claude updates these automatically. Manual edits are respected.

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-claude-code-memory">View persistia-claude-code-memory on skillZs</a>