Persisto

A persistent AI agent that remembers, learns, and works for you.

Persisto wraps Claude Code with an always-on daemon, long-term memory, scheduled tasks, and a personality you shape over time. Build any kind of agent — research, operations, writing, sales, development, personal assistant — one command to start, everything else is automatic.

• Persistent memory — the agent remembers across sessions, compactions, and restarts
• Learns your patterns — builds a behavioral profile that deepens over weeks and months
• Proactive heartbeat — rotating checks that surface insights, connections, and surprises you didn't ask for
• Scheduled tasks — cron jobs that run in the background and deliver results to you
• Self-managing tools — the agent installs its own MCP servers, changes its own permissions
• Integrations — Slack, Gmail, Google Calendar, Chrome browser control, GitHub
• Your agent, your way — soul files, skills, and memory that evolve with you

Why Claude Code

Persisto isn't a wrapper around the Anthropic API — it's a layer on top of Claude Code CLI, the most capable agentic AI tool available.

Claude Code already gives you file read/write/edit, bash execution, web search, MCP tool use, git integration, agent delegation, and more. Persisto adds what Claude Code doesn't have on its own:

• Persistence — memory that survives across sessions and context compactions
• Background daemon — adaptive heartbeat, cron scheduler, webhook listener, Slack bridge
• Self-management — the agent installs tools, updates its own soul, and manages permissions
• Notification delivery — results routed to your tmux chat, Slack channels, or webhooks
• Personality system — soul files, skills, and operating instructions that make the agent yours
• Behavioral learning — the agent observes your patterns and gets better at anticipating your needs

Every Claude Code feature — skills, hooks, MCP servers, permission modes — works natively inside Persisto. You lose nothing, you gain everything.

How Persisto Differs from OpenClaw

| | Persisto | OpenClaw | |---|---|---| | Architecture | Wraps Claude Code CLI directly — inherits every update automatically | Builds its own agent loop | | Memory | Markdown files + hybrid BM25/vector search with temporal decay. Human-readable, git-trackable, editable. | Custom memory system | | Proactive intelligence | Adaptive heartbeat with rotating checks, context injection, user profile learning, and value-filtered delivery | Static heartbeat checklist | | Self-management | Agent installs/removes its own MCP tools, changes permissions, updates soul — all from conversation | Limited self-modification | | Integrations | Native Slack Socket Mode, Gmail, Calendar, Chrome browser — all via MCP | Varies by fork | | Security | Permission tiers, credential isolation, secret detection/rejection, security audit CLI | Basic permissions | | Setup | One command (persisto chat). No Docker, no database setup. | More complex setup | | Philosophy | Base general agent you build on. Ships with personality, skills, cron — you shape it into your agent. | Framework-first approach |

Install

npm install -g @dfeirstein/persisto

Prerequisites:

• Node.js >= 20
• Claude Code — npm install -g @anthropic-ai/claude-code (and run claude login)
• tmux — brew install tmux (macOS) or apt install tmux (Linux)

Quick Start

persisto chat

That's it. On first run, Persisto automatically:

1. Creates the ~/.persisto/ directory with all templates
2. Runs the interactive setup wizard
3. Installs persistence hooks into Claude Code
4. Starts the background daemon
5. Opens your tmux chat session

On subsequent runs, it skips completed steps and opens the chat instantly.

Setup Wizard

The first time you run persisto chat, the setup wizard walks you through personalizing your agent:

| Question | What it controls | |----------|-----------------| | Your name | How the agent addresses you | | Timezone | Cron job scheduling, daily log timestamps | | Working hours | When the agent is most active (e.g., 9am-6pm EST) | | Agent name | The agent's identity (default: "Persisto") | | Agent role | What the agent focuses on (e.g., "research analyst", "operations manager", "writing partner") | | Heartbeat checks | What the agent monitors in the background (comma-separated) | | Permission level | How much autonomy the agent has (conservative / balanced / autonomous) |

Press Enter to keep defaults. You can re-run the wizard anytime with persisto setup, and every answer can be changed later by editing the soul files directly.

Best Practices for Setup

• Start with "balanced" permissions. This gives the agent read access to its workspace and web search, but prompts you before writes or bash commands. Upgrade to "autonomous" once you're comfortable.
• Spend time on the agent role. This shapes the agent's behavior more than anything else. Be specific: "market research analyst focused on B2B SaaS competitive intelligence" is better than "research assistant."
• Set relevant heartbeat checks. Examples: "Check for unread emails from clients", "Review today's calendar for meeting prep", "Scan my project files for items needing follow-up." The heartbeat fires every 30 minutes by default with rotating check types.
• Run persisto security after setup. This audits file permissions, scans for leaked secrets, and verifies security guidance is in place. Use --fix to auto-remediate.

Personalizing Your Agent

Your agent's personality and behavior live in ~/.persisto/soul/. Edit these files anytime — changes take effect on the next session start.

Soul Files

| File | Purpose | |------|---------| | SOUL.md | Identity, values, personality — who the agent is | | USER.md | Facts about you — name, timezone, preferences | | BOOT.md | Instructions loaded at every session start — operating rules | | HEARTBEAT.md | Philosophy and rules for the agent's background pulse | | PROFILE.md | Auto-generated behavioral profile (updated nightly by the profile-builder) |

Deepening USER.md

The more the agent knows about you, the better it performs. The default USER.md is minimal — here's what a well-developed one looks like:

# User

## Identity
- Name: Jordan Rivera
- Timezone: America/Chicago
- Working hours: 8am-5pm CST

## Preferences
- Communication style: direct and concise, skip preamble
- I prefer structured summaries with bullet points
- Always include sources when researching
- Prioritize actionable insights over background context

## Current Work
- Managing product launches for a mid-size consumer brand
- Running competitive analysis across 5 key markets
- Preparing quarterly board presentations
- Coordinating with the marketing team on campaign performance

## Tools I Use
- Google Workspace (Docs, Sheets, Slides)
- Slack for team communication
- Figma for reviewing creative assets
- HubSpot for CRM

Updating Soul Over Time

• Edit files directly — open ~/.persisto/soul/SOUL.md in any editor
• Ask the agent — "Update your soul to be more proactive about suggesting improvements"
• Add skills — drop new .md files in ~/.persisto/skills/ for reusable capabilities
• The agent's full context (CLAUDE.md) is auto-regenerated from these files

The Adaptive Heartbeat

The heartbeat is what makes Persisto proactive. Every 30 minutes, the agent wakes up and runs one of four rotating checks:

| Check | Cadence | What it does | |-------|---------|-------------| | Status check | 30 min | Quick scan for pending tasks, deadlines, or items needing attention | | Follow-up | 60 min | Reviews recent sessions for unfinished work or patterns worth noting | | Delight | 120 min | Asks "what would genuinely surprise and delight this user right now?" | | Dormant memory | 180 min | Surfaces forgotten context that connects to recent activity |

Each tick gets injected with rich context: your behavioral profile, recent sessions, patterns detected, time of day, and previous observations. A value filter ensures the agent only speaks when it has something genuinely useful — most ticks return NO_REPLY, and that's by design.

How It Gets Smarter Over Time

1. Session hooks capture behavioral signals after every session (what you worked on, how you worked, what patterns emerged)
2. Profile builder runs nightly, synthesizing raw data into soul/PROFILE.md — preserving older observations while incorporating new ones
3. Context injection feeds this ever-richer profile into each heartbeat tick
4. Observation log records what the heartbeat found, building cross-tick awareness
5. Memory search with temporal decay means old work resurfaces when it becomes relevant again

Week 1 is mostly silent. By month 3, the agent knows your rhythms, your projects, your patterns — and starts making connections you wouldn't think to ask for.

Configuration

Control heartbeat behavior in ~/.persisto/config.json:

{
  "heartbeat": {
    "activeHours": { "start": "08:00", "end": "22:00" },
    "deliverTo": ["tmux", "memory"],
    "model": "claude-haiku-4-5",
    "maxBudgetUsd": 0.05
  }
}

• activeHours — skip heartbeat outside these hours (null = always active)
• deliverTo — where to send results: tmux, memory, slack:#channel, webhook:https://...
• model — which model to use for heartbeat ticks (cheaper models for cost control)
• maxBudgetUsd — spending cap per tick

Getting the Most Out of Your Agent

Memory

Persisto gives your agent memory that persists across sessions, context compactions, and restarts:

• MEMORY.md — durable facts that persist indefinitely
• Daily logs (YYYY-MM-DD.md) — session observations with temporal decay in search ranking
• Hybrid search — BM25 keyword matching + semantic vector search across all memory files

The agent writes to memory automatically, but you can guide it:

• "Remember that our client meetings are always on Tuesdays"
• "Save this research finding to memory"
• "What do you remember about the competitor analysis we did last week?"

Self-Improvement

Your agent gets better the more you use it:

• Ask it to create skills — "Create a skill for how we handle client onboarding"
• Refine soul files — if the agent is too verbose, update SOUL.md personality section
• Review memory — periodically scan memory/MEMORY.md and clean up stale entries
• Update heartbeat — as your workflow evolves, adjust what the agent monitors
• Let it learn — the agent extracts lessons from each session and stores them for future reference

Cron Jobs

Schedule recurring tasks that run in the background:

[
  {
    "name": "morning-briefing",
    "schedule": "0 0 8 * * *",
    "timezone": "America/New_York",
    "prompt": "Check my email for anything urgent, review today's calendar, and compile a morning briefing.",
    "model": "claude-sonnet-4-6",
    "deliverTo": ["tmux", "slack:#general"]
  }
]

Or just tell the agent what you want:

"Set up a cron job that checks my email every morning at 8am and posts a summary to Slack."

The agent writes cron/jobs.json directly — no manual JSON editing required. The daemon hot-reloads within 10 seconds.

Delivery targets: tmux (your chat), memory (daily log), slack:#channel, webhook:https://..., or any combination.

Extending with Skills

Persisto runs inside Claude Code, so the entire Claude Code skills ecosystem works natively.

Community Skills (skills.sh)

Browse and install community skills from skills.sh:

# Browse available skills in a repo
npx skills add owner/repo --list

# Install Vercel's official skill collection (globally)
npx skills add vercel-labs/agent-skills -g

# Install a specific skill
npx skills add owner/repo --skill frontend-design

# Install from any GitHub URL
npx skills add https://github.com/owner/repo

Use -g to install globally (available in all projects) or omit it for project-scoped skills.

Persisto's Built-in Skills

Persisto ships with its own skills in ~/.persisto/skills/:

| Skill | Purpose | |-------|---------| | github.md | PR reviews, issue triage, commit conventions | | bootstrap.md | First-run onboarding flow | | notifications.md | Notification routing rules (inform, auto-fetch, auto-act) | | workspace.md | Directory organization conventions | | permissions.md | Permission level management |

Create Your Own

Add a SKILL.md to ~/.claude/skills/<skill-name>/:

---
name: client-research
description: Research a client before meetings
disable-model-invocation: true
---

Research $ARGUMENTS:
1. Search the web for recent news and press releases
2. Check memory for any previous interactions or notes
3. Compile a brief with key talking points and recent developments

Skills become available as /client-research slash commands. Claude also auto-invokes skills when relevant to your conversation (unless you set disable-model-invocation: true).

How-To Guides

Install a New Tool (Just Ask)

The agent can install MCP servers from conversation — no manual config needed:

"I need you to be able to browse the web and search for documents."

The agent calls mcp_install_server, saves context to memory, restarts the session, and the new tools are ready.

Built-in catalog: playwright, context7, perplexity, sequential-thinking, filesystem, puppeteer, github, and more. Custom servers are also supported with --command and --args.

From the CLI: persisto mcp list to see what's available, persisto mcp install playwright to install.

Connect Gmail

1. Open Claude Code settings → Integrations → MCP → Enable Gmail
2. Authorize access to your Google account
3. Restart your Persisto session — the agent auto-discovers cloud MCP servers on startup

Now your agent can read, search, and draft emails:

"Check my inbox for anything urgent from this week." "Draft a reply to the partnership inquiry we got yesterday."

Connect Google Calendar

Same flow as Gmail:

1. Claude Code settings → Integrations → MCP → Enable Google Calendar
2. Authorize access
3. Restart Persisto

Capabilities: list/create/update/delete events, find free time, check for conflicts.

"What's on my calendar tomorrow?" "Schedule a 30-minute call with the design team for Thursday afternoon."

Browser Control (Chrome Extension)

Install the Claude-in-Chrome extension to give your agent full browser control:

• Navigate to URLs, click elements, fill forms
• Take screenshots and record GIFs
• Execute JavaScript on any page
• Extract data from web pages
• Read console logs and network requests

Works seamlessly with persisto chat sessions. Great for web research, data extraction, form automation, and testing.

Remote Control

persisto chat --remote

Starts the agent in Claude Code remote-control mode. Connect from the Claude mobile app or web interface to control your agent from anywhere.

• Agent runs in tmux on your machine
• Connect from your phone, tablet, or another computer
• Trigger tasks, check status, review results — all remotely

Slack Integration

persisto slack setup

The interactive wizard walks you through:

1. Create a Slack app at api.slack.com
2. Enable Socket Mode and create an app-level token (xapp-...)
3. Add bot scopes: chat:write, reactions:write, im:history, im:write, users:read
4. Subscribe to message.im event
5. Install to your workspace and copy the bot token (xoxb-...)

What you get:

• DM the bot — threaded conversations with full session continuity
• Channel delivery — cron jobs post results to Slack channels (deliverTo: ["slack:#general"])
• Channel reading — the agent reads and searches Slack as part of any task

Sample Agents

Persisto is a base you build on. Here are some examples of vertical agents you can create:

| Agent Type | How | |------------|-----| | Research analyst | Web search + document summarization + findings saved to memory + daily briefings via cron | | Executive assistant | Calendar management, email triage, meeting prep, daily briefings delivered to Slack | | Content strategist | Draft posts, track campaign performance, monitor competitors, schedule publishing tasks | | Sales operations | Track deals in CRM, prep for client calls, monitor competitive intel, follow up on leads | | Project coordinator | Track tasks, follow up on blockers, compile status reports, prep for standups | | Learning companion | Research topics, create study guides, quiz you on material, track progress | | Development partner | Code review, PR triage, test monitoring, deploy automation, repo management | | Personal CRM | Track contacts, follow-ups, meeting notes in structured memory | | Brand monitor | Track mentions, analyze sentiment, compile reports, alert on trends | | Financial tracker | Monitor accounts, flag unusual activity, compile expense reports |

The heartbeat learns what matters to your specific agent. A research analyst's heartbeat surfaces forgotten sources. A sales agent's heartbeat reminds you about follow-ups. The same system adapts to any domain.

Building From Here

Persisto is your base general agent — customize it for your workflow:

1. Shape the soul — edit ~/.persisto/soul/ files to define who your agent is
2. Add skills — drop .md files in ~/.persisto/skills/ or install from skills.sh
3. Schedule tasks — create cron jobs for recurring work
4. Connect integrations — Slack, Gmail, Calendar, browser, GitHub
5. Let it learn — the agent's memory, profile, and heartbeat grow with every session

The agent evolves with you. What starts as a general assistant becomes your personalized, domain-expert AI teammate.

CLI Reference

| Command | Description | |---------|-------------| | persisto chat | Start chat session (auto-setup on first run) | | persisto chat --new | Kill existing session and start fresh | | persisto chat --remote | Start in remote-control mode | | persisto setup | Re-run the setup wizard | | persisto status | Show daemon status and uptime | | persisto stop | Stop the background daemon | | persisto security | Run a full security audit | | persisto security --fix | Audit and auto-fix permission issues | | persisto mcp list | List installed and available MCP servers | | persisto mcp install <name> | Install an MCP server | | persisto slack setup | Configure Slack integration | | persisto hooks status | Show installed hooks |

Tmux Basics

Your chat runs inside tmux for disconnect safety:

• File browser: Ctrl+B, f — toggle a split pane showing your ~/.persisto/ workspace
• Detach: Ctrl+B, D — return to your shell, the agent keeps running
• Reattach: persisto chat — reconnects to the existing session
• Fresh start: persisto chat --new — kills the old session and starts over
• Scroll: Ctrl+B, [ — enter scroll mode (press q to exit)

Workspace File Browser

Press Ctrl+B, f to open a split pane showing your agent's files. Press it again to close.

 Persisto Workspace
 ~/.persisto/

  soul/
    1  SOUL.md
    2  BOOT.md
    3  USER.md
    4  HEARTBEAT.md
    5  TOOLS.md
  memory/
    6  MEMORY.md
    7  2026-03-03.md
  skills/
    8  github.md
    9  bootstrap.md
   10  notifications.md
  cron/
   11  jobs.json
  ./
   12  CLAUDE.md
   13  config.json

  [#] view file  [r]efresh  [q]uit

Type a number to view any file with scrolling. Press q to return to the file list, or q again to close the browser. Credentials are excluded for security.

Troubleshooting

| Issue | Fix | |-------|-----| | "claude binary not found" | npm install -g @anthropic-ai/claude-code | | "Daemon is already running" | persisto stop then persisto chat | | Hooks not firing | persisto hooks status to check — reinstall with persisto hooks install | | Notifications not appearing | Check daemon logs: tail -f ~/.persisto/daemon.log — daemon waits for 3s idle | | Permission denied errors | persisto security --fix to reset file permissions |

License

MIT