persist
Update this project's session config with rules, conventions, or feedback that should persist across all future sessions.
Usage: /persist or /persist <what to remember>
What This Updates
Session config = CLAUDE.md + GEMINI.md + MEMORY.md + memory files + procedure docs. Choose the right target:
| What to persist |
Where it goes |
Example |
| Behavioral rule or workflow change |
CLAUDE.md / GEMINI.md (if short) or procedure doc (if detailed) |
"Always use TDD", "Never delete DB without migrating" |
| User feedback or correction |
Memory file (feedback type) + MEMORY.md index |
"Don't summarize at end of responses" |
| Project decision or context |
Memory file (project type) + MEMORY.md index |
"ai-core is the platform, sergei is an instance" |
| Repeatable process |
Procedure doc in docs/procedures/ + link from CLAUDE.md/GEMINI.md |
Template propagation workflow |
Steps
- Identify what to persist — if invoked without context, ask: "What do you want to persist?"
- Choose the target — use the table above
- Revise existing content if needed:
- Persisting is not just appending — you must intelligently revise, compact, or offload instructions to keep within the limits.
- Rewrite sections that have grown verbose or outdated, or merge related entries.
- Hub Limits: projects-wide
250 lines; project-specific ~100 lines (350 combined). GEMINI.md uses a tighter ~150-line heuristic limit.
- If adding a rule pushes a file significantly over its limit, you MUST offload detailed content into a new
docs/procedures/ spoke file and leave only a short summary/link in the Hub config.
MEMORY.md soft limit: ~200 lines (it's an index, keep it concise by nature)
- Write the update:
- For CLAUDE.md / GEMINI.md: add to the appropriate section, or revise existing content in that section. Keep them synced in their respective roles.
- For memory files: create/update file with proper frontmatter, update MEMORY.md index (if using Claude; if Gemini, use
save_memory for global facts)
- For procedure docs: create/update in
docs/procedures/, add link from config docs if not already there
- Commit and push —
git add the changed files, commit with a descriptive message, and git push. Session config changes must be shipped immediately.
4-Layer Evaluation
Before writing anything, evaluate which layers this practice needs. Most practices need multiple layers — don't stop at the easiest one.
| Layer |
Loaded |
Purpose |
Put it here if... |
| Config (CLAUDE/GEMINI.md) |
Every session |
Concise behavioral rules (what/when/why) |
It affects planning or decision-making |
| docs/procedures/ |
When linked |
Detailed how-tos (steps, checklists, anti-patterns) |
It has multi-step workflows too long for main config files |
| Skills |
On invocation |
Execution mechanics |
It's triggered by a slash command |
| Memory files |
When relevant |
Cross-session context and state |
It's background knowledge, not a behavioral rule |
Key principle: If a practice affects how sessions plan or make decisions, it must go in CLAUDE.md and GEMINI.md — not just memory or skills.
Rules
- Read the target file before modifying — don't duplicate existing content
- Revise and compact freely — these files are living documents, not append-only logs.
- Config docs are for rules, not status or transient info
- Always check if a related procedure doc exists or should be created
- Always commit and push after persisting — session config changes must be shipped immediately
Relationship to Other Skills
/save-state — snapshots session state (memory, docs, git). Different purpose.
Auto-Exit / Refresh
After all persist work is complete:
- If running in Claude: trigger auto-exit so the ai auto-resume loop restarts Claude with fresh config:
touch "/tmp/cc-exit-${CC_TMUX_SESSION:-}"
- If running in Gemini CLI: suggest the user run
/memory reload to dynamically refresh the config.
Source: sergeiwallace/ai-cli-utils — distributed by TomeVault.
1---2name: persist3description: Update session config (CLAUDE.md, GEMINI.md, memory, procedures) with permanent rules or conventions Use when this capability is needed.4---56# persist78Update this project's session config with rules, conventions, or feedback that should persist across all future sessions.910**Usage:** `/persist` or `/persist <what to remember>`1112## What This Updates1314Session config = CLAUDE.md + GEMINI.md + MEMORY.md + memory files + procedure docs. Choose the right target:1516| What to persist | Where it goes | Example |17|----------------|---------------|---------|18| Behavioral rule or workflow change | CLAUDE.md / GEMINI.md (if short) or procedure doc (if detailed) | "Always use TDD", "Never delete DB without migrating" |19| User feedback or correction | Memory file (feedback type) + MEMORY.md index | "Don't summarize at end of responses" |20| Project decision or context | Memory file (project type) + MEMORY.md index | "ai-core is the platform, sergei is an instance" |21| Repeatable process | Procedure doc in `docs/procedures/` + link from CLAUDE.md/GEMINI.md | Template propagation workflow |2223## Steps24251. **Identify what to persist** — if invoked without context, ask: "What do you want to persist?"262. **Choose the target** — use the table above273. **Revise existing content if needed:**28 - Persisting is not just appending — you must **intelligently revise, compact, or offload** instructions to keep within the limits.29 - Rewrite sections that have grown verbose or outdated, or merge related entries.30 - **Hub Limits:** projects-wide ~250 lines; project-specific ~100 lines (~350 combined). `GEMINI.md` uses a tighter ~150-line heuristic limit.31 - If adding a rule pushes a file significantly over its limit, you MUST offload detailed content into a new `docs/procedures/` spoke file and leave only a short summary/link in the Hub config.32 - `MEMORY.md` soft limit: ~200 lines (it's an index, keep it concise by nature)334. **Write the update:**34 - For CLAUDE.md / GEMINI.md: add to the appropriate section, or revise existing content in that section. Keep them synced in their respective roles.35 - For memory files: create/update file with proper frontmatter, update MEMORY.md index (if using Claude; if Gemini, use `save_memory` for global facts)36 - For procedure docs: create/update in `docs/procedures/`, add link from config docs if not already there375. **Commit and push** — `git add` the changed files, commit with a descriptive message, and `git push`. Session config changes must be shipped immediately.3839## 4-Layer Evaluation4041Before writing anything, evaluate which layers this practice needs. Most practices need multiple layers — don't stop at the easiest one.4243| Layer | Loaded | Purpose | Put it here if... |44|-------|--------|---------|-------------------|45| **Config (CLAUDE/GEMINI.md)** | Every session | Concise behavioral rules (what/when/why) | It affects planning or decision-making |46| **docs/procedures/** | When linked | Detailed how-tos (steps, checklists, anti-patterns) | It has multi-step workflows too long for main config files |47| **Skills** | On invocation | Execution mechanics | It's triggered by a slash command |48| **Memory files** | When relevant | Cross-session context and state | It's background knowledge, not a behavioral rule |4950**Key principle:** If a practice affects how sessions *plan or make decisions*, it must go in CLAUDE.md and GEMINI.md — not just memory or skills.5152## Rules5354- Read the target file before modifying — don't duplicate existing content55- **Revise and compact freely** — these files are living documents, not append-only logs.56- Config docs are for **rules**, not status or transient info57- Always check if a related procedure doc exists or should be created58- Always commit and push after persisting — session config changes must be shipped immediately5960## Relationship to Other Skills6162- **`/save-state`** — snapshots session state (memory, docs, git). Different purpose.6364## Auto-Exit / Refresh6566After all persist work is complete:67- If running in Claude: trigger auto-exit so the ai auto-resume loop restarts Claude with fresh config: `touch "/tmp/cc-exit-${CC_TMUX_SESSION:-}"`68- If running in Gemini CLI: suggest the user run `/memory reload` to dynamically refresh the config.6970---71> Source: [sergeiwallace/ai-cli-utils](https://github.com/sergeiwallace/ai-cli-utils) — distributed by [TomeVault](https://tomevault.io).72<!-- tomevault:4.0:skill_md:2026-05-23 -->
tomevault-io