persistia-memory-system

用途

Persistia 为 Claude Code 提供持久化、自更新的项目记忆和运维能力。它扫描代码库、架构、文档和配置，并通过 git diff 监控变更，使记忆保持最新。记忆存储在 _brain/ 目录中，以纯文本文件形式存在，使用 git 版本管理，可选备份到私有 GitHub 仓库。

主要能力

记忆索引：_brain/index.md 是每次会话首先读取的文件，包含项目概览、架构、所有记忆文件链接、最近变更摘要和导航结构。
自更新记忆：每日运行 git diff 检测变更，仅重新索引修改过的文件，自动提交并推送到记忆仓库。
技能（Skills）：永久性能力存储在 _brain/skills/ 中，一旦写入，每次会话都会加载。可通过自然语言创建，如“记住部署前总是运行测试”。
定时任务：在 _brain/tasks/queue.json 中定义，支持 batch_size（每次运行最大条目数）、timeout_minutes（默认 5 分钟）、enabled（暂停而不删除）等属性。
主动扫描：空闲时每 3 天自动扫描指标趋势、客户行为模式、支持渠道和代码变更，标记观察结果并建议行动，但不会单方面执行。
仪表板：_brain/dashboard.html 提供实时视图，每 5 分钟自动刷新，显示最近记忆更新、定时任务状态、主动扫描结果和快速导航。

使用方式

安装

在项目根目录运行：

curl -fsSL https://raw.githubusercontent.com/bernardohcrocha/persistia-for-claude-code/main/setup.sh | bash

要求：git、Node.js 18+，可选 GitHub CLI（gh）用于自动云备份。

安装过程会：扫描项目结构、创建 _brain/ 目录及索引记忆、仅询问无法自动找到的信息、安装调度器（macOS 用 launchd，Linux 用 systemd）、创建私有 git 仓库、设置每日自动更新。

目录结构

_brain/
├── .git/                    # 隔离的记忆仓库
├── index.md                 # 主导航文件（每次会话首先读取）
├── dashboard.html           # 实时仪表板（每 5 分钟自动刷新）
├── core/                    # 产品、品牌、ICP 定义
│   ├── product.md
│   ├── brand.md
│   └── icp.md
├── operations/              # 指标和客户数据（每日自动更新）
│   ├── metrics.md
│   └── customers.md
├── skills/                  # 永久规则和能力
│   └── [skill-name].md
└── tasks/                   # 定时任务管理
    ├── queue.json
    ├── completed/
    └── failed/

创建技能

---
name: deployment-checklist
created: 2026-06-04
---

# Deployment Checklist

Before every deployment:
1. Run full test suite
2. Check environment variables match production
3. Verify database migrations are reversible
4. Update CHANGELOG.md
5. Tag release in git

可通过自然语言创建，如“添加处理客户数据导出的技能”。

定义定时任务

{
  "tasks": [
    {
      "id": "weekly-metrics",
      "name": "Weekly Metrics Report",
      "schedule": "every Monday at 9am",
      "description": "Pull last week's metrics from Stripe, flag anomalies, queue follow-ups for accounts below quota",
      "batch_size": 50,
      "timeout_minutes": 10,
      "enabled": true
    }
  ]
}

手动操作

强制更新记忆：

cd _brain
git add .
git commit -m "Manual memory update"
git push

查看记忆历史：

cd _brain
git log --oneline
git diff HEAD~1

团队共享记忆：

# 第一台机器
cd _brain
git remote -v

# 第二台机器（项目根目录）
git clone <brain-repo-url> _brain

禁用自动更新：

# macOS
launchctl unload ~/Library/LaunchAgents/persistia.brain.plist

# Linux
systemctl --user disable persistia-brain.timer

重新启用自动更新：

# macOS
launchctl load ~/Library/LaunchAgents/persistia.brain.plist

# Linux
systemctl --user enable persistia-brain.timer
systemctl --user start persistia-brain.timer

故障排除

记忆仓库未推送到 GitHub：

gh auth status
gh auth login

记忆更新未自动运行：

# macOS
launchctl list | grep persistia

# Linux
systemctl --user status persistia-brain.timer

查看日志：

# macOS
tail -f ~/Library/Logs/persistia-brain.log

# Linux
journalctl --user -u persistia-brain.service -f

任务超时：在 _brain/tasks/queue.json 中增加 timeout_minutes。

记忆文件过大：按主题拆分大文件，更新 _brain/index.md 链接所有部分。

完全重置记忆：

rm -rf _brain
curl -fsSL https://raw.githubusercontent.com/bernardohcrocha/persistia-for-claude-code/main/setup.sh | bash

适用场景

需要让 Claude Code 长期记住项目上下文、架构和配置的开发团队。
希望自动化日常运维任务（如每周指标报告、不活跃用户外联）的项目。
需要跨机器或跨团队成员共享项目记忆的场景。
需要将记忆版本化并备份到私有 GitHub 仓库的团队。

限制

需要 git 和 Node.js 18+，自动云备份需要 GitHub CLI。
定时任务依赖系统调度器（launchd 或 systemd），仅支持 macOS 和 Linux。
主动扫描仅标记观察结果并建议行动，不会自动执行。
记忆文件为纯文本，需注意文件大小，过大时需手动拆分。
任务有超时限制，默认 5 分钟，复杂任务需调整 timeout_minutes。
具体收费、价格、平台支持范围等未在资料中提供。