{%- from "_macros.j2" import skill_ref with context -%}
{% if platform == "claude" -%}
<!-- evolve-import-canary EVOLVE_IMPORT_CANARY_v1 -->
# Evolve — shared, auditable memory

You already have native, self-directed memory: you decide what to recall at the
start of a task and what to save at the end, on your own judgment. Evolve adds
only the two things native memory lacks — sharing and provenance — as two
lightweight lifecycle steps. It does not change how you recall or save.

## After you save a memory

When you save a native memory this turn, invoke {{ skill_ref('adapt-memory') }}
to mirror it into the shared evolve store (`./.evolve/entities/`) so the fact is
shareable with the team and auditable like every other evolve entity. Do this
once per memory you saved.

## Record what you consulted

After you read or consult native memories this turn, log which ones you actually
opened, so the value of this memory can be measured over time. Run:

```bash
python3 {{ audit_script }} <id> [<id> ...]
```

Pass the entity id `<type>/<name>` for each native memory you consulted, where
`<type>` is the memory's `metadata.type` and `<name>` is its top-level `name`
field — this is the id provenance resolves to `./.evolve/entities/<type>/<name>.md`
(the same id {{ skill_ref('adapt-memory') }} mirrors to). Skip this step entirely
if you consulted no memories. If the command prints a line beginning
`evolve-session:`, include that line once, verbatim, somewhere in your reply — it
lets later analysis tie this session to what you recalled.
{%- else -%}
# Evolve — self-directed memory

You have a persistent, file-based memory for the current project, stored as
*entities* under `./.evolve/entities/<type>/` (relative to the workspace/project
root). Each entity is one fact; "memory" and "entity" are the same thing. You
decide, on your own judgment, when something is worth remembering — nothing
forces a save, and there is no step to "complete." Curate this store like notes
you'll thank yourself for later: small, accurate, high-signal.

## Recall — your first action, before any other tool use

On a non-trivial task (code changes, debugging, repo exploration, or
environment/tooling investigation), your FIRST action — before reading source,
running commands, or anything else — is to check `./.evolve/entities/`: list
that directory, read each entity's `trigger` line, and open the entity files
whose trigger matches the task. The moment you open one or more entities, your
next step — still part of this same first action — is to record them with the
audit command under "Record what you consulted" below; do it before you move on
to the task. Let what you find inform the work that follows. If the directory is
missing or nothing matches, note that and proceed — that's normal.

Entities reflect what was true when written. If one names a file, function,
command, or flag, verify it still exists before relying on it.

## Record what you consulted

Whenever you opened entities in the recall step above, record them now — run
this before doing anything else, so the value of this memory can be measured
over time:

```bash
python3 {{ audit_script }} <id> [<id> ...]
```

Pass the entity id `<type>/<name>` for each entity you consulted, where `<type>`
is its directory under `entities/` and `<name>` is its filename without `.md`
(e.g. `project/test-fixture-generated`). Skip this step entirely if you
consulted no entities. If the command prints a line beginning `evolve-session:`,
include that line once, verbatim, somewhere in your reply — it lets later
analysis tie this session to what you recalled.

## Save — only when you learn something durable

Near the end of a task, if it produced a reusable fact that isn't already
obvious from the code or git history — and only then — write it as an entity.
Saving nothing is the right outcome more often than not; never force a
low-value entity just to have saved one.

Each entity is one file holding one fact, at
`./.evolve/entities/<type>/<short-kebab-slug>.md` (create the directory if it
doesn't exist — `<type>` is one of the types below). The filename is the
entity's name; the frontmatter carries its type and trigger:

```markdown
---
type: <user | feedback | project | reference>
trigger: <one line naming the situation in which a future session should recall this>
---

<the fact. For feedback/project, follow with **Why:** and **How to apply:** lines.
Link related entities with [[their-name]].>
```

The `trigger` is what a future session matches against during recall, so make it
about *when* the fact applies, not just what it is.

Types (the `<type>` directory and frontmatter value):
- **user** — who the user is: role, expertise, durable preferences.
- **feedback** — guidance on how you should work, both corrections and
  confirmed approaches; always include the why.
- **project** — ongoing work, goals, or constraints not derivable from the code
  or git history; convert relative dates ("next week") to absolute ones.
- **reference** — pointers to external resources (URLs, dashboards, tickets).

In the body, link related entities with `[[name]]`, where `name` is another
entity's filename slug. Link liberally; a `[[name]]` with no file yet marks
something worth writing later, not an error.

## When NOT to save, and housekeeping

- Don't duplicate what the repo already records: code structure, git history,
  READMEs, existing docs. If asked to remember one of those, ask what was
  non-obvious about it and save that instead.
- Don't save what only matters to the current conversation.
- Before saving, check for an existing entity that already covers it — update
  that file rather than creating a duplicate.
- Delete entities that turn out to be wrong.
{%- endif %}
