avizmarlon/permanent-learning-protocol

Permanent Learning Protocol

AI agents evolve only if learnings become part of their permanent instruction layer — auto-loaded in every future session. Session-only memory does not persist; only auto-loaded files survive across sessions.

This protocol moves learnings from chat to durable instruction files, with explicit user approval at each step. It prevents silent integration and ensures transparency.

1. Triggers

Automatic (natural session end — inferred from tone/context):

• Farewell signals (goodbye, thanks + session ending, "signing off")
• Gratitude + user disappears
• Clear pivot to unrelated topic after coherent work block
• Request to open new session / create handoff / create worktree for next phase
• Session approaching context limit

Manual: User invokes skill /learn, or says variations like "consolidate what you learned this session" / "what did you discover today?"

2. Agent Action — Reflection + Proposal in Chat

Quick scan across learning categories:

1. User Correction (explicit or implicit — user ignored approach and did differently) → feedback type
2. Validated Pattern (user approved non-obvious approach without technical criticism, or called it "exactly right" / "perfect") → feedback type (good-pattern)
3. Technical Discovery (tool gotcha, API behavior, effective workaround) → discovery type
4. New Project/Context Fact (new platform, credential, person, decision) → project type
5. External Resource Pointer (documentation, dashboard, repo, reference) → reference type

Present in chat as numbered proposal — DO NOT save yet:

📚 Proposed permanent learnings:

1. [feedback] User prefers X over Y
   Location: global-instructions.md (global scope)
   Why: incident from session / concrete reason
   How to apply: when/where to use this pattern

2. [discovery] Tool Z has gotcha W
   Location: project docs or global reference
   Type: behavioral / limitation / workaround

Approve all? Reject item N? Discuss any?

3. User Response

• "ok" / "approved" / "yes" / "go" / "save": Agent integrates permanently into files listed above in the same session. No follow-up. No "will do later".
• "reject N" / "remove N" / "keep only 1 and 3": Skip rejected items, integrate the rest.
• "discuss" / asks question: Converse before integrating.
• No response (session closes): Agent writes the proposal to <project-path>/_pending-approval.md (project scope) or global pending file (global scope). On next session, agent reads this file at start — if pending items exist, re-present in chat before proceeding.

4. Storage Destinations by Learning Type

| Learning Type | Primary Destination | Cross-Tool Mirror | |---|---|---| | Global operating preference | global-instructions.md | equivalent in all agent instruction files | | Project-specific behavioral rule | <project>/.agent-rules/<name>.md | .cursor/rules/<name>.mdc, mention in project instruction file | | Workflow / process pattern | dedicated rule file + note in global if cross-project | mirror as above | | Architecture decision | docs/adr/ADR-NNN.md + update docs/architecture.md | entry in CHANGELOG.md | | Reusable technical discovery | docs/<topic>.md in project | entry in CHANGELOG.md | | Discrete fact about project/context | memory file (<project>/_memory/<topic>.md) + entry in memory index | — | | External resource pointer | reference memory file + index entry | — |

5. Anti-Patterns (Prohibited)

• Silent integration without showing in chat — breaks approval contract. Permanent memory without approval = unilateral decision.
• Trigger on fixed keyword user must memorize ("learn now", "save this") — user should never have to remember special syntax.
• Duplicate entries instead of updating existing file (always check index/file before creating new).
• Save ephemeral or trivial facts ("today I ran git status", "session ended at 3 PM"). Only substantive learnings.
• Invent learnings to appear productive. If nothing substantive happened, "no new learnings this session" is the correct response.
• Wait until next session to integrate — no future agent with this chat history will exist.
• Save rule without Why and How to apply — becomes dogma. Future agents won't know how to judge edge cases.

6. Standards for Quality Learnings

A learning is worth saving if:

• It changes how an agent will operate on future tasks (new rule, new workaround, new gotcha)
• It discovered something non-obvious (not trivial to deduce from first principles)
• It applies to multiple projects or use cases
• It represents consensus after uncertainty or disagreement

A learning is NOT worth saving if:

• It's a one-time fact tied to this specific project/session
• It's restating the manual/docs (user should read them)
• It's generic best practice already documented elsewhere

Applies to

All AI agents in a skill system, every project, every session. Part of the standard agent bootstrap and lifecycle.