persistia-claude-code-memory

用途

Persistia for Claude Code 为 Claude Code 提供持久化、可自我更新的记忆能力。它扫描一次项目，把结构化知识保存在 _brain/ 中，随后通过 git diff 监控变更以保持内容最新，进而支持自主任务、永久技能与跨会话上下文。

安装

必须在已初始化 git 的项目根目录运行：

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

要求：

git
Node.js 18+
可选：GitHub CLI（gh），用于自动备份私有 brain 仓库

安装器会：创建 _brain/ 目录结构；扫描项目文件、读取 .env 文件；只询问无法自动检测的信息；设置每日自动更新（launchd/systemd）；可选创建私有 GitHub 仓库用于 brain 备份。

目录结构

_brain/
├── .git/                    # 隔离的 brain 仓库
├── index.md                 # 主导航，每次会话首先读取
├── dashboard.html           # 实时命令中心（自动刷新）
├── core/
│   ├── product.md          # 你在构建什么
│   ├── brand.md            # 语气、价值观、定位
│   └── icp.md              # 理想客户画像
├── operations/
│   ├── metrics.md          # KPI，每日自动更新
│   └── customers.md        # 账户数据、行为
├── skills/
│   └── *.md                # 永久规则与行为
└── tasks/
    ├── queue.json          # 计划中的自主任务
    └── completed/          # 执行日志

初始设置流程

安装后，Claude 会提出澄清性问题，例如产品一句话描述、主要技术栈、使用的工具（Stripe、Postgres 等）、ICP 等。Claude 会读取现有文件（.env、package.json、README 等），只询问找不到的信息。

核心概念

1. 索引优先导航

_brain/index.md 是入口。Claude 每次会话先读它，其中包含快速参考、优先文件列表与活动任务。

2. 技能（永久记忆）

技能是跨会话持续的规则。当你教 Claude 某事时会自动创建，例如“React 中始终使用函数式组件”会生成 _brain/skills/react-patterns.md。技能在每次会话开始时加载。

3. 自主任务

任务在完整项目上下文中自动运行，通过编辑 _brain/tasks/queue.json 配置。可配置属性包括：schedule（daily、weekly、monthly）、batch_size（每次运行最大条目数，防止超时）、timeout_minutes（最大执行时间，默认 5）、day（周任务使用）、time（24 小时制）。完成的任务记录到 _brain/tasks/completed/YYYY-MM-DD_task-id.md。

4. 基于 git diff 的更新

每日调度器运行 cd _brain && git diff HEAD~1..HEAD --name-only，只有变更的文件会被重新索引。

5. 凭据管理

Persistia 从 .env 文件、环境变量、git 配置、工具 CLI（Stripe、AWS 等）读取现有凭据，无需重新录入。

常见使用方式

教授新技能：用户提出规则，Claude 创建对应 _brain/skills/*.md。
安排跨工具任务：例如每周一拉取 Stripe 收入并与 Postgres 用量指标对比、标记差异，Claude 会加入 queue.json 并编写执行逻辑脚本。
更新核心知识：如业务转向，Claude 更新 _brain/core/icp.md 与 _brain/core/product.md 并提交。
查询运营数据：Claude 读取自动更新的 _brain/operations/customers.md 直接回答，无需 API 调用。

仪表盘

在浏览器中打开 _brain/dashboard.html，每 5 分钟自动刷新，显示最近指标、活动任务状态、上次 brain 更新时间与快捷操作。

故障排查

brain 未更新：检查调度器状态。macOS 使用 launchctl list | grep persistia、launchctl start com.persistia.update；Linux 使用 systemctl status persistia-update.timer、systemctl start persistia-update.service。
任务超时：增大 timeout_minutes 或减小 batch_size。
记忆过时：强制重新索引，cd _brain && rm -rf operations/ 后重启 Claude Code 会话。
brain 仓库 git 冲突：cd _brain && git fetch origin && git reset --hard origin/main。

高级配置

自定义更新频率：macOS 编辑 ~/Library/LaunchAgents/com.persistia.update.plist 中的 StartInterval；Linux 编辑 ~/.config/systemd/user/persistia-update.timer。
排除索引文件：在项目根 .gitignore 添加条目，Persistia 遵循 .gitignore。
多智能体团队：共享 brain 仓库，先添加 remote 并 push，团队成员安装 Persistia 后 clone 到 _brain。

最佳实践

一次教授，长期受益——解释后请 Claude 保存为技能。
让 git diff 完成工作——不要手动更新 _brain/。
大批量操作分批——用 batch_size 防止超时。
每周查看任务日志 _brain/tasks/completed/。
把 _brain/ 当作代码提交有意义更新。

文件格式

所有 brain 文件是带可选 YAML frontmatter 的 Markdown，Claude 会自动更新，同时尊重手动编辑。