ai-agents knowledge-persistence.instructions.md

Knowledge Persistence Rule

This rule covers the mechanics of writing to a persistence surface: rule files, the mirrors generated from them, and Serena memories. It fires when you edit one of those trees.

Choosing which surface a fact belongs on binds earlier, before you know which tree you will open, so that decision procedure lives in the always-on Universal Rules under "Choosing a persistence surface".

MUST

1. Canonical rule lives in .claude/rules/. A convention that must bind across Claude, Codex, and Copilot MUST be written to .claude/rules/<name>.md, not only to Serena memory or Copilot Memory. AGENTS.md directs every harness to read .claude/rules/*.md first, so Claude (reads the tree directly) and Codex (reads AGENTS.md) both resolve to it, and Copilot reads the generated mirror.
2. Regenerate the mirrors in the same change. Adding or editing a .claude/rules/*.md file MUST regenerate .github/instructions/<name>.instructions.md and src/copilot-cli/instructions/<name>.instructions.md with build/scripts/generate_rules.py, committed in the same change. A stale mirror is torn state (see .claude/rules/generated-artifacts.md).
3. Leave the plugin manifests alone. .claude/ and src/copilot-cli/ ship in the project-toolkit plugin, but the manifests carry no version field: Claude Code resolves freshness from the commit SHA instead, so a rule change needs no manifest edit. Adding a version back fails build/scripts/validate_plugin_version_bump.py (see .claude/rules/plugin-version-bump.md and ADR-092).
4. Scope by paths:. Set paths: to the narrowest glob that fires where the convention applies (tests/**, **/*.ps1). A universally-binding convention sets paths: ["**"].
5. Index a new Serena memory by hand. A memory under .serena/memories/ MUST get a keyword line in memory-index.md in the same change, or keyword retrieval cannot reach it. memory_index.py --ci checks only that index rows resolve to files, never the reverse, so nothing catches the omission. Write (0) as the token placeholder; the memory-token-update pre-commit job rewrites it to the real count.
6. Repair token counts by hand when the autofix is skipped. memory-token-update carries skip: [merge, "test $SKIP_AUTOFIX = 1"], so a memory edited inside a merge commit, or committed with SKIP_AUTOFIX=1, keeps a stale count. Pre-push memory-index-token-ratchet then fails and names every stale entry. Fix it by running uv run --frozen python scripts/update_memory_index_tokens.py, not by editing the number by hand. Measured on pristine main before the ratchet existed: skills-git-index recorded 287 against an actual 324, a 13% undercount that merged (Issue #4441).