feat(platform-integrations): stable native-to-entity id linkage for provenance

Closes the correlation-id gap that broke provenance on Claude. The adapter now
derives the entity slug from the native memory's name field, so the entity id is
a deterministic, derivable <type>/<name> on both the save and recall sides, and
re-mirroring overwrites in place (idempotent, no -N suffix). The entity also
stamps native_path as a back-reference.

- entity_io.write_entity_file: optional filename/overwrite for deterministic
  in-place writes (default behavior unchanged for existing callers); native_path
  added to _FRONTMATTER_KEYS
- adapt_memory.py: parse native name, write <type>/<name>.md, print the id
- Claude EVOLVE.md recall-audit now logs the entity id <type>/<name> (not native
  paths), which provenance resolves to .evolve/entities/<type>/<name>.md

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: illeatmyhat

platform-integrations/bob/evolve-lite/lib/evolve-lite/entity_io.py

@@ -154,7 +154,7 @@ def unique_filename(directory, slug):
 # Markdown <-> dict conversion
 # ---------------------------------------------------------------------------
 
-_FRONTMATTER_KEYS = ("type", "trigger", "trajectory", "owner", "source", "visibility", "published_at")
+_FRONTMATTER_KEYS = ("type", "trigger", "trajectory", "owner", "source", "native_path", "visibility", "published_at")
 
 
 def entity_to_markdown(entity):
@@ -354,12 +354,24 @@ def load_all_entities(entities_dir):
     return entities
 
 
-def write_entity_file(directory, entity):
+def write_entity_file(directory, entity, filename=None, overwrite=False):
     """Write a single entity as a markdown file under *directory*.
 
     The file is placed in a ``{type}/`` subdirectory.  Uses atomic
     write (write to ``.tmp``, then ``os.rename``).
 
+    Args:
+        directory: Entities root directory.
+        entity: The entity dict to serialize.
+        filename: Optional explicit slug for the target file (without the
+            ``.md`` suffix). When omitted, the slug is derived from the
+            entity content (the historical default).
+        overwrite: When True, the entity is written to a deterministic
+            ``{type}/{filename}.md`` path, overwriting any existing file in
+            place (stable id, idempotent re-mirroring). When False (the
+            default), the historical collision-avoiding behavior is kept —
+            a ``-2``/``-3`` suffix is appended on collision.
+
     Returns:
         Path to the written file.
     """
@@ -370,7 +382,7 @@ def write_entity_file(directory, entity):
     type_dir = Path(directory) / entity_type
     type_dir.mkdir(parents=True, exist_ok=True)
 
-    slug = slugify(entity.get("content", "entity"))
+    slug = filename if filename else slugify(entity.get("content", "entity"))
     content = entity_to_markdown(entity)
 
     # Write to a unique temp file first (avoids predictable .tmp collisions)
@@ -381,6 +393,13 @@ def write_entity_file(directory, entity):
         os.close(fd)
         fd = None
 
+        if overwrite:
+            # Deterministic target: overwrite any existing file in place so
+            # the entity id is stable across re-mirroring.
+            target = type_dir / f"{slug}.md"
+            os.replace(tmp_path, target)
+            return target
+
         # Atomically claim the target using O_EXCL; retry on race
         while True:
             target = unique_filename(type_dir, slug)

platform-integrations/bob/evolve-lite/skills/evolve-lite-adapt-memory/scripts/adapt_memory.py

@@ -48,6 +48,7 @@
 from entity_io import (  # noqa: E402
     find_entities_dir,
     get_default_entities_dir,
+    slugify,
     write_entity_file,
     log as _log,
 )
@@ -58,14 +59,15 @@ def log(message):
 
 
 def parse_native_memory(text):
-    """Split a native memory file into (description, body).
+    """Split a native memory file into (name, description, body).
 
     Native frontmatter is simple ``key: value`` lines plus a nested
-    ``metadata:`` block; we only need ``description`` and the body, so we
-    parse the top-level ``description:`` line and treat everything after the
-    closing ``---`` as the body. Missing frontmatter is tolerated — the whole
-    text is then the body.
+    ``metadata:`` block; we parse the top-level ``name`` and ``description``
+    lines and treat everything after the closing ``---`` as the body. The
+    ``name`` is the native slug we reuse as the stable entity id. Missing
+    frontmatter is tolerated — the whole text is then the body.
     """
+    name = None
     description = None
     body = text
     if text.startswith("---"):
@@ -74,16 +76,17 @@ def parse_native_memory(text):
             frontmatter, body = parts[1], parts[2]
             for line in frontmatter.splitlines():
                 # Only top-level keys (no leading indentation) — keeps the
-                # nested metadata.* keys out of the description match.
+                # nested metadata.* keys out of the top-level matches.
                 if line[:1].isspace():
                     continue
                 key, _, value = line.partition(":")
-                if key.strip() == "description":
-                    value = value.strip()
-                    if value:
-                        description = value
-                    break
-    return description, body.strip()
+                key = key.strip()
+                value = value.strip()
+                if key == "name" and value:
+                    name = value
+                elif key == "description" and value:
+                    description = value
+    return name, description, body.strip()
 
 
 def main():
@@ -112,7 +115,7 @@ def main():
         print(f"Error: cannot read {memory_path} - {exc}", file=sys.stderr)
         sys.exit(1)
 
-    description, body = parse_native_memory(text)
+    name, description, body = parse_native_memory(text)
     if not body:
         print(f"Error: native memory {memory_path} has no body to mirror.", file=sys.stderr)
         sys.exit(1)
@@ -123,11 +126,18 @@ def main():
     if description and description not in body:
         content = f"{description}\n\n{body}"
 
+    # The native ``name`` becomes the stable, derivable entity slug so the
+    # entity id is ``<type>/<name>`` on both sides — provenance can map an
+    # audited native memory straight onto its mirror. Fall back to a
+    # content-derived slug only when the native frontmatter has no name.
+    slug = slugify(name) if name else slugify(content)
+
     entity = {
         "type": args.type,
         "trigger": args.trigger,
         "content": content,
         "source": "native-memory",
+        "native_path": args.memory_path,
     }
 
     entities_dir = find_entities_dir()
@@ -138,9 +148,14 @@ def main():
         entities_dir = get_default_entities_dir()
         log(f"Created entities dir: {entities_dir}")
 
-    path = write_entity_file(entities_dir, entity)
-    log(f"Mirrored {memory_path} -> {path}")
+    # Deterministic, idempotent write: re-mirroring the same native memory
+    # (same name + type) overwrites <type>/<name>.md in place rather than
+    # creating <name>-2.md, keeping the entity id stable.
+    path = write_entity_file(entities_dir, entity, filename=slug, overwrite=True)
+    entity_id = f"{entity['type']}/{slug}"
+    log(f"Mirrored {memory_path} -> {path} (id: {entity_id})")
     print(f"Mirrored native memory into evolve store: {path}")
+    print(f"Entity id: {entity_id}")
 
 
 if __name__ == "__main__":

platform-integrations/claude/plugins/evolve-lite/EVOLVE.md

@@ -15,15 +15,17 @@ once per memory you saved.
 
 ## Record what you consulted
 
-After you read or consult memories this turn, log which ones you actually opened,
-so the value of this memory can be measured over time. Run:
+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:
 
 ```
-python3 ~/.claude/evolve-lite/audit_recall.py <file> [<file> ...]
+python3 ~/.claude/evolve-lite/audit_recall.py <id> [<id> ...]
 ```
 
-Pass the memory files you read this turn (space-separated paths, relative to the
-project root). 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.
+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 /evolve-lite: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.

platform-integrations/claude/plugins/evolve-lite/lib/evolve-lite/entity_io.py

@@ -154,7 +154,7 @@ def unique_filename(directory, slug):
 # Markdown <-> dict conversion
 # ---------------------------------------------------------------------------
 
-_FRONTMATTER_KEYS = ("type", "trigger", "trajectory", "owner", "source", "visibility", "published_at")
+_FRONTMATTER_KEYS = ("type", "trigger", "trajectory", "owner", "source", "native_path", "visibility", "published_at")
 
 
 def entity_to_markdown(entity):
@@ -354,12 +354,24 @@ def load_all_entities(entities_dir):
     return entities
 
 
-def write_entity_file(directory, entity):
+def write_entity_file(directory, entity, filename=None, overwrite=False):
     """Write a single entity as a markdown file under *directory*.
 
     The file is placed in a ``{type}/`` subdirectory.  Uses atomic
     write (write to ``.tmp``, then ``os.rename``).
 
+    Args:
+        directory: Entities root directory.
+        entity: The entity dict to serialize.
+        filename: Optional explicit slug for the target file (without the
+            ``.md`` suffix). When omitted, the slug is derived from the
+            entity content (the historical default).
+        overwrite: When True, the entity is written to a deterministic
+            ``{type}/{filename}.md`` path, overwriting any existing file in
+            place (stable id, idempotent re-mirroring). When False (the
+            default), the historical collision-avoiding behavior is kept —
+            a ``-2``/``-3`` suffix is appended on collision.
+
     Returns:
         Path to the written file.
     """
@@ -370,7 +382,7 @@ def write_entity_file(directory, entity):
     type_dir = Path(directory) / entity_type
     type_dir.mkdir(parents=True, exist_ok=True)
 
-    slug = slugify(entity.get("content", "entity"))
+    slug = filename if filename else slugify(entity.get("content", "entity"))
     content = entity_to_markdown(entity)
 
     # Write to a unique temp file first (avoids predictable .tmp collisions)
@@ -381,6 +393,13 @@ def write_entity_file(directory, entity):
         os.close(fd)
         fd = None
 
+        if overwrite:
+            # Deterministic target: overwrite any existing file in place so
+            # the entity id is stable across re-mirroring.
+            target = type_dir / f"{slug}.md"
+            os.replace(tmp_path, target)
+            return target
+
         # Atomically claim the target using O_EXCL; retry on race
         while True:
             target = unique_filename(type_dir, slug)

platform-integrations/claude/plugins/evolve-lite/skills/evolve-lite/adapt-memory/scripts/adapt_memory.py

@@ -48,6 +48,7 @@
 from entity_io import (  # noqa: E402
     find_entities_dir,
     get_default_entities_dir,
+    slugify,
     write_entity_file,
     log as _log,
 )
@@ -58,14 +59,15 @@ def log(message):
 
 
 def parse_native_memory(text):
-    """Split a native memory file into (description, body).
+    """Split a native memory file into (name, description, body).
 
     Native frontmatter is simple ``key: value`` lines plus a nested
-    ``metadata:`` block; we only need ``description`` and the body, so we
-    parse the top-level ``description:`` line and treat everything after the
-    closing ``---`` as the body. Missing frontmatter is tolerated — the whole
-    text is then the body.
+    ``metadata:`` block; we parse the top-level ``name`` and ``description``
+    lines and treat everything after the closing ``---`` as the body. The
+    ``name`` is the native slug we reuse as the stable entity id. Missing
+    frontmatter is tolerated — the whole text is then the body.
     """
+    name = None
     description = None
     body = text
     if text.startswith("---"):
@@ -74,16 +76,17 @@ def parse_native_memory(text):
             frontmatter, body = parts[1], parts[2]
             for line in frontmatter.splitlines():
                 # Only top-level keys (no leading indentation) — keeps the
-                # nested metadata.* keys out of the description match.
+                # nested metadata.* keys out of the top-level matches.
                 if line[:1].isspace():
                     continue
                 key, _, value = line.partition(":")
-                if key.strip() == "description":
-                    value = value.strip()
-                    if value:
-                        description = value
-                    break
-    return description, body.strip()
+                key = key.strip()
+                value = value.strip()
+                if key == "name" and value:
+                    name = value
+                elif key == "description" and value:
+                    description = value
+    return name, description, body.strip()
 
 
 def main():
@@ -112,7 +115,7 @@ def main():
         print(f"Error: cannot read {memory_path} - {exc}", file=sys.stderr)
         sys.exit(1)
 
-    description, body = parse_native_memory(text)
+    name, description, body = parse_native_memory(text)
     if not body:
         print(f"Error: native memory {memory_path} has no body to mirror.", file=sys.stderr)
         sys.exit(1)
@@ -123,11 +126,18 @@ def main():
     if description and description not in body:
         content = f"{description}\n\n{body}"
 
+    # The native ``name`` becomes the stable, derivable entity slug so the
+    # entity id is ``<type>/<name>`` on both sides — provenance can map an
+    # audited native memory straight onto its mirror. Fall back to a
+    # content-derived slug only when the native frontmatter has no name.
+    slug = slugify(name) if name else slugify(content)
+
     entity = {
         "type": args.type,
         "trigger": args.trigger,
         "content": content,
         "source": "native-memory",
+        "native_path": args.memory_path,
     }
 
     entities_dir = find_entities_dir()
@@ -138,9 +148,14 @@ def main():
         entities_dir = get_default_entities_dir()
         log(f"Created entities dir: {entities_dir}")
 
-    path = write_entity_file(entities_dir, entity)
-    log(f"Mirrored {memory_path} -> {path}")
+    # Deterministic, idempotent write: re-mirroring the same native memory
+    # (same name + type) overwrites <type>/<name>.md in place rather than
+    # creating <name>-2.md, keeping the entity id stable.
+    path = write_entity_file(entities_dir, entity, filename=slug, overwrite=True)
+    entity_id = f"{entity['type']}/{slug}"
+    log(f"Mirrored {memory_path} -> {path} (id: {entity_id})")
     print(f"Mirrored native memory into evolve store: {path}")
+    print(f"Entity id: {entity_id}")
 
 
 if __name__ == "__main__":

platform-integrations/claw-code/plugins/evolve-lite/lib/evolve-lite/entity_io.py

@@ -154,7 +154,7 @@ def unique_filename(directory, slug):
 # Markdown <-> dict conversion
 # ---------------------------------------------------------------------------
 
-_FRONTMATTER_KEYS = ("type", "trigger", "trajectory", "owner", "source", "visibility", "published_at")
+_FRONTMATTER_KEYS = ("type", "trigger", "trajectory", "owner", "source", "native_path", "visibility", "published_at")
 
 
 def entity_to_markdown(entity):
@@ -354,12 +354,24 @@ def load_all_entities(entities_dir):
     return entities
 
 
-def write_entity_file(directory, entity):
+def write_entity_file(directory, entity, filename=None, overwrite=False):
     """Write a single entity as a markdown file under *directory*.
 
     The file is placed in a ``{type}/`` subdirectory.  Uses atomic
     write (write to ``.tmp``, then ``os.rename``).
 
+    Args:
+        directory: Entities root directory.
+        entity: The entity dict to serialize.
+        filename: Optional explicit slug for the target file (without the
+            ``.md`` suffix). When omitted, the slug is derived from the
+            entity content (the historical default).
+        overwrite: When True, the entity is written to a deterministic
+            ``{type}/{filename}.md`` path, overwriting any existing file in
+            place (stable id, idempotent re-mirroring). When False (the
+            default), the historical collision-avoiding behavior is kept —
+            a ``-2``/``-3`` suffix is appended on collision.
+
     Returns:
         Path to the written file.
     """
@@ -370,7 +382,7 @@ def write_entity_file(directory, entity):
     type_dir = Path(directory) / entity_type
     type_dir.mkdir(parents=True, exist_ok=True)
 
-    slug = slugify(entity.get("content", "entity"))
+    slug = filename if filename else slugify(entity.get("content", "entity"))
     content = entity_to_markdown(entity)
 
     # Write to a unique temp file first (avoids predictable .tmp collisions)
@@ -381,6 +393,13 @@ def write_entity_file(directory, entity):
         os.close(fd)
         fd = None
 
+        if overwrite:
+            # Deterministic target: overwrite any existing file in place so
+            # the entity id is stable across re-mirroring.
+            target = type_dir / f"{slug}.md"
+            os.replace(tmp_path, target)
+            return target
+
         # Atomically claim the target using O_EXCL; retry on race
         while True:
             target = unique_filename(type_dir, slug)