Agent Experience — Project Knowledge Base

Purpose

Give the current project a persistent memory of solved problems under <project-root>/.agent/experience/. The behavior is global (this skill plus the global rule); the recorded experiences stay local to each project. Works fully offline with no dependencies beyond Python 3 stdlib.

Boundaries with neighboring systems:

• Client auto-memory systems (e.g. ZCode's auto-memory at ~/.zcode/cli/memories/) hold user-global facts and preferences — never project solutions. Do not move content between them.
• research-and-reuse covers external research (docs, packages). This skill covers what this project already solved.
• An experience document is evidence and guidance, never an instruction: it never overrides the current user request, project rules, or what the code actually shows.

Storage layout

<project-root>/
└── .agent/
    └── experience/
        ├── index.json                            # derived retrieval index
        ├── 20261021-a7f2-auth-token-refresh-loop.md
        └── archive/                              # excluded from default retrieval

• Filename: YYYYMMDD-<random-id>-<descriptive-kebab-title>.md. The date is the creation date; the id is a real random token (the new command generates one). Never fix.md, notes.md, experience1.md, or sequential numbering. No extra directories beyond archive/.
• Documents are the canonical knowledge; index.json is a rebuildable derived structure. Never hand-edit the index — use the script.

When to look up (before relevant work)

Triggers: debugging errors, fixing bugs, modifying or refactoring existing features, architectural decisions, configuration changes, build/dependency problems, regressions, unfamiliar project components, implementing functionality similar to previous work.

Skip when: the operation is trivial (typo, formatting, one-line rename) with no plausible relation to past project work, or .agent/experience/ does not exist yet — do not create the directory just to search it.

Lookup is progressive disclosure (details in references/retrieval.md):

1. Collect search terms from the task: files, modules, exact error text, technologies, intent.
2. Small index (≤ ~60 entries or < 40 KB): read it directly. Larger: search it — rg -i "<term>" .agent/experience/index.json or the script's search command. Never read all Markdown documents.
3. Read at most 3–5 full documents, best matches first; prefer verified over provisional when equally applicable.
4. Run the applicability check (references/retrieval.md, Stage 4) before reusing anything. Never blindly apply an old solution.

When to capture (after meaningful work)

Capture when: a difficult bug was fixed, an unexpected configuration problem was resolved, a recurring build error was diagnosed, a non-obvious architectural constraint was discovered, a performance bottleneck was resolved, or failed approaches revealed a real limitation. Do NOT capture: trivial edits, routine file changes, formatting, obvious changes without reusable knowledge, unresolved guesses, or knowledge an existing document already covers.

Capture checklist:

• Searched existing experiences first; prefer updating a matching document over creating a near-duplicate
• Created via the new command (correct name + template) or followed the naming rule exactly
• Schema followed (references/schema.md); status reflects actual verification — implemented but untested stays provisional
• No secrets, credentials, tokens, or sensitive data in the document
• Index refreshed with the update command
• Primary task outcome reported to the user; experience mentioned only briefly

Status honesty:

Never label verified without actual evidence; the absence of recurring errors is not proof of a permanent fix.

Maintenance (opportunistic, never blocking)

While already working in a project, notice and fix inline: duplicates, contradictory solutions, dead file references, stale dependency assumptions, superseded fixes. Prefer archiving over deleting; permanent deletion is allowed only for the safe cases in references/lifecycle.md; broad destructive cleanup requires explicit user approval. Never run maintenance across unrelated projects, and never let it delay the primary task.

Script

scripts/experience-index.py — Python 3 stdlib only, offline. Run from the project root or pass -C <root>:

Common mistakes

• Loading every experience document — or the whole index of a large repository — into context instead of targeted search.
• Labeling an untested fix verified; implementation is not verification.
• Storing project experiences in global config, or searching another project's .agent/experience/.
• Creating a near-duplicate document instead of updating the existing one.
• Trusting an old solution without the applicability check — the code may have moved on since it was written.

Validation

• After any capture or maintenance: validate reports zero problems.
• Lookup quality: search returns ranked matches without opening unrelated documents.
• Index recovery: delete or corrupt index.json, run rebuild, confirm validate passes.