Replace migrate slash command with a harness-independent skill

[jfrancoa]

Motivation

Anyone switching to Engram from another local memory system arrives with an existing
store of accumulated memories and no way to bring it along. This PR adds a one-shot
importer with claude-mem as the first supported source, exposed as a skill rather
than a slash command: commands are a Claude-Code-only component type, while the Codex
plugin manifest carries skills, mcpServers, and hooks — a skill keeps the guided
flow portable. Bumps the plugin to 1.1.0.

Supersedes #6 (same feature with a slash command; only one of the two should merge).
Shaped by review: Engram classifies topics itself (@augustas1), no per-run waiting and
shared scope resolution (@danmichaeljones), no source-side curation (@danmichaeljones).

How it works

• Adapters (plugin/core/migrate/) stream plain records — uid, content, original
  timestamp, project hint. Every observation row migrates; Engram's extraction decides
  what each memory becomes and what to keep. A new source is one adapter module plus a
  registry entry.
• Engram owns topics. Records group into chronological conversations (one per
  project and day) submitted through the extraction pipeline with their original dates
  as context. The migration never names a topic, so any topic setup works.
• Scope matches the hooks. Per-project properties come from
  core.scope.resolve_scope on the project's directory — the same function, config
  files, and source cascades realtime adds use. The group schema is fetched only to
  learn which properties are required; a project whose required properties can't be
  resolved is skipped and reported (--map/--property recover it). A resolution error
  in one project (broken .engram.json, offline schema fetch) skips that project
  instead of aborting the run.
• Directory discovery works for any layout. Project names are located through
  Claude Code's own session registry (~/.claude/projects/), whose munged entries
  decode to every directory the user ever worked in — no workspace convention assumed.
  Explicit --repos-dir dirs win; cwd and its parent are a last resort for stores
  copied from another machine.
• Submit, then settle. Conversations are submitted back-to-back in chronological
  order (Engram queues internally); a settle pass polls the checkpointed run ids to
  report what committed. Exit codes: 0 done, 1 failures, 3 still in the pipeline.
• Idempotent and reversible. A per-source checkpoint makes re-runs send only what's
  missing; --rollback deletes via the server's per-run commit manifests, so organic
  memories are untouchable, and refuses to reset state it cannot verify.
• Skill (plugin/skills/migrate-memories/): dry-run stripped of
  --execute/--rollback → report → fresh confirmation → execute → summary, invoked
  through a self-locating scripts/migrate.sh with no host env dependencies.

Key areas for review

• engine.py execute/settle/reconcile_pending — checkpoint discipline around
  no-wait submission; failed runs release their items for resubmission
• __main__.py _props_builder — hook-parity resolution, per-project error handling,
  --map/--property precedence
• claude_projects.py — the munged-name decoder (listing-pruned, iterative) and the
  registry index
• engine.py rollback — manifest-driven deletion; still-running runs and non-404
  delete failures keep the checkpoint

Testing

• 27 unit tests (plugin venv; the SDK is assumed per review): adapter selection and
  composition, sqlite read-only enforcement including URI-reserved path characters,
  chronological planning, skip/undated/skip_uids handling, discovery layers, props
  building (error-skip, map/extra merge), checkpoint roundtrip and corruption handling,
  reconcile, submit-without-wait, submit-error stop, settle including the timeout path,
  manifest rollback. ruff clean.
• Live against a real store (10k observations, 1.2k summaries, 33 projects): registry
  discovery resolved every project whose directory still exists (skips dropped from 17
  projects to 5), dry-run offline and with a corrupted per-project .engram.json
  degrade to per-project skips (both previously crashed — reproduced first), and a full
  production migration ran earlier in the PR's history with zero failures.

🤖 Generated with Claude Code

[orca-security-eu]

Orca Security Scan Summary

Status	Check	Issues by priority
Passed	Secrets	0   0   0   0	View in Orca

[Copilot]

Pull request overview

This PR replaces the previous Claude-Code-only /engram:migrate guided migration slash command with a harness-independent migrate-memories skill, so the migration flow can work across hosts that support skills (e.g., future Codex dual-host manifests).

Changes:

• Added a new migrate-memories skill that documents a safe, confirmation-gated migration flow (dry-run → review → confirm → execute → summarize).
• Added a self-locating scripts/migrate.sh wrapper that resolves the plugin root from its own path and delegates to plugin/bin/engram-migrate without relying on host env vars.
• Updated README migration instructions and removed the old plugin/commands/migrate.md slash-command implementation; added eval prompts for future iteration.

Reviewed changes

Copilot reviewed 12 out of 14 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
README.md	Updates user-facing migration guidance to point to the new skill and CLI usage.
plugin/skills/migrate-memories/SKILL.md	Introduces the skill definition and step-by-step migration flow (dry-run + explicit confirmation gates).
plugin/skills/migrate-memories/scripts/migrate.sh	Adds a harness-independent entrypoint that locates and executes the migration CLI.
plugin/skills/migrate-memories/evals/evals.json	Adds behavioral eval prompts/assertions for the skill-driven migration flow.
plugin/commands/migrate.md	Removes the old /engram:migrate slash command guidance/implementation.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[orca-security-eu]

Orca Security Scan Summary

Status	Check	Issues by priority
Passed	Infrastructure as Code	0   0   0   0	View in Orca
Passed	SAST	0   0   0   0	View in Orca
Passed	Secrets	0   0   0   0	View in Orca
Passed	Vulnerabilities	0   0   0   0	View in Orca

[Copilot]

Pull request overview

Copilot reviewed 12 out of 14 changed files in this pull request and generated no new comments.

Suppressed comments (3)

plugin/core/migrate/main.py:52

• Same as above: sys.exit(<message>) exits with status 1 here; for malformed NAME=VALUE pairs this should be treated as a usage error (exit 2) and written to stderr.

        # an empty half silently doing nothing (e.g. --map proj= falling through to the
        # git probe) is worse than an error
        if not k.strip() or not v.strip():
            sys.exit(f"--{flag} {p!r}: name and value must be non-empty")
        out[k.strip()] = v.strip()

plugin/core/migrate/engine.py:373

• In rollback(), iterating ops.created assumes both committed_operations and its created list are always present and non-null. If the API/SDK returns committed_operations.created = null (or omits it) for runs with no creates, this will raise and prevent rollback from completing.

        ops = rs.committed_operations
        ids = [op.memory_id for op in (ops.created if ops else [])]

plugin/core/migrate/main.py:47

• The module docstring says exit code 2 is for usage errors, but _parse_kv uses sys.exit(<message>), which exits with status 1. Prefer emitting the message to stderr and exiting with code 2 for invalid --map/--topic-map/--property values.

This issue also appears on line 48 of the same file.

        if "=" not in p:
            sys.exit(f"--{flag} expects NAME=VALUE, got {p!r}")
        k, v = p.split("=", 1)

[Copilot]

Pull request overview

Copilot reviewed 12 out of 14 changed files in this pull request and generated no new comments.

Suppressed comments (2)

plugin/core/migrate/engine.py:373

• rollback() assumes client.runs.get() always returns an object with a committed_operations attribute and that it always has a created iterable. If the SDK omits committed_operations for some terminal run states (or created is None), this will raise AttributeError/TypeError and abort rollback, leaving the checkpoint and partially deleted state.

        ops = rs.committed_operations
        ids = [op.memory_id for op in (ops.created if ops else [])]

plugin/skills/migrate-memories/SKILL.md:46

• This option suggests running --execute directly, but the flow above explicitly requires always doing a dry-run first and only appending --execute after a fresh in-conversation confirmation. As written, this conflicts with the skill’s safety gate.

- `--limit N --execute` — a small smoke run before committing to a full migration.

[augustas1]

Since topics are Engram's strength, we might want to make it more flexible and closer to the plugin behaviour.
Plugin checks configured topics of the live project for the only reason that there might be scope properties (which would be required at input).

I am thinking maybe it's better to let Engram extract and classify memories (instead of using pre-extracted mode here) so this migrations works regardless of topic setup (e.g. currently it fails if project has topics with no properties). We might still need to fetch topics from project just to see what properties are configured, just to figure out property setup. The plugin does it this way:

1. Fetches project's group to see what properties are configured on topics
2. Pass required properties (default repo_name, session_id if configured) when adding memories
   OR pass no properties if none are configured.
3. Plugins also let's configure custom properties (other than repo_name, session_id) but maybe we don't need to build this for the migration skill.

[jfrancoa]

Re-implemented in 54e9ddf exactly along these lines: conversation input is now the only ingestion path, so Engram's extraction classifies every memory itself — the whole kind→topic mapping (and --topic-map, --input, the pre-extracted planner) is gone. The group schema is fetched only to learn the configured scope properties: repo_name is attached per batch only when the group configures it, and when it doesn't, unresolvable projects migrate too since nothing can be mis-filed. session_id keeps its migration marker when configured; custom --property stays since it was already built and small.

[Copilot]

Pull request overview

Copilot reviewed 12 out of 14 changed files in this pull request and generated no new comments.

Suppressed comments (1)

plugin/core/client.py:92

• get_client() imports the Engram SDK unconditionally; when with-venv.sh falls back to system python (e.g., first run before deps are installed), this will raise ImportError and crash the hook/CLI instead of failing open as intended. Consider importing only after confirming an API key is present and catching ImportError to return None.

def get_client():
    # SDK import stays local: everything else in this module (key/identity resolution, the
    # REST helper) is stdlib-only and must keep working where the SDK isn't installed.
    from engram import EngramClient

[Copilot]

Pull request overview

Copilot reviewed 10 out of 12 changed files in this pull request and generated no new comments.

Suppressed comments (4)

plugin/core/migrate/engine.py:84

• Records with rec.project == None are always treated as unresolvable and skipped because props_for() is never called in that case (props_by_project is set to None). _props_builder(props_for) explicitly supports a missing project by returning only trustworthy required properties (e.g., session_id marker) + explicit overrides, so these records can migrate safely when the group doesn’t require repo_name.

        project = rec.project or "(none)"
        if project not in props_by_project:
            props_by_project[project] = props_for(rec.project) if rec.project else None
        props = props_by_project[project]
        if props is None:
            mapping[project] = None
            skipped[project] = skipped.get(project, 0) + 1
            continue

plugin/core/migrate/engine.py:25

• engine.py imports the Engram SDK (ConversationInput/MessageInput) at module import time. That makes even dry-run/report-only code paths fail in environments without the plugin venv, contradicting the stated goal that dry-run/tests can run SDK-free. Consider lazy-importing the SDK only when building/submitting ConversationInput (e.g., inside _build_input/execute) so planning/reporting works without the SDK installed.

from engram import ConversationInput, MessageInput

plugin/core/migrate/engine.py:126

• The skipped-projects note implies --map is the remedy for required-scope resolution failures, but projects can also be skipped due to other missing required properties (which are instead addressable via --property). This message can mislead users into trying only --map when they need to supply other required properties.

        lines.append(
            "  skipped — the group's required scope properties could not be resolved "
            "(--map=NAME=owner/repo supplies repo_name):"
        )

plugin/.claude-plugin/plugin.json:5

• PR description says the plugin is bumped to 0.2.0, but the manifest version is set to 1.1.0 (from 1.0.0). Please align the PR description and the shipped manifest version so downstream tooling (e.g., client_origin_header tests and plugin distribution) reflects the intended release.

  "description": "Persistent cross-session memory backed by Weaviate Engram. Stores each conversation turn and recalls relevant memories before Claude answers.",
  "version": "1.1.0",
  "author": { "name": "Weaviate" },

[Copilot]

Pull request overview

Copilot reviewed 10 out of 12 changed files in this pull request and generated no new comments.

Suppressed comments (6)

plugin/tests/test_migrate.py:54

• This comment is now inaccurate: the adapter/test intentionally includes unknown/new observation types (see test_selection_and_composition expecting obs:5). Update the comment to reflect that type is not used as a filter.

            # unknown type → never yielded

plugin/core/migrate/engine.py:80

• Records with an empty/None project are always skipped because props_for() is never called (line 79 sets props to None). This contradicts the intended behavior where migrations should still proceed when required scope properties can be satisfied without a project directory (e.g., groups without repo_name, or only requiring session_id). Call props_for() even when rec.project is falsy and let it decide whether required properties are satisfiable.

        project = rec.project or "(none)"
        if project not in props_by_project:
            props_by_project[project] = props_for(rec.project) if rec.project else None
        props = props_by_project[project]

plugin/tests/test_migrate.py:51

• This comment is now inaccurate: the adapter/test intentionally includes "discovery" observations (see test_selection_and_composition expecting obs:4). Update the comment so it doesn't imply these rows are excluded.

This issue also appears on line 54 of the same file.

            # excluded by default

plugin/skills/migrate-memories/SKILL.md:31

• This flow text says the report is "per repo and day", but the current implementation groups by (day, source project) (plugin/core/migrate/engine.py:77-99). Adjust the wording so the skill guidance matches what the CLI actually reports.

2. **Present the report**: how many memories per repo and day; which source projects were
   skipped because no git remote was found (offer `--map NAME=owner/repo` for ones worth

plugin/.claude-plugin/plugin.json:5

• PR description mentions bumping the plugin to 0.2.0, but this manifest changes the version from 1.0.0 to 1.1.0. Please align the PR description and the actual versioning scheme (either update the version here or adjust the stated version bump).

  "description": "Persistent cross-session memory backed by Weaviate Engram. Stores each conversation turn and recalls relevant memories before Claude answers.",
  "version": "1.1.0",
  "author": { "name": "Weaviate" },

README.md:131

• The migration engine groups records by (day, source project) (plugin/core/migrate/engine.py:77-99), not strictly by resolved repo_name. This README sentence says "per repo and day", which can be misleading if multiple source project names map to the same repo_name (via --map or source-side merges). Update wording to match the implementation.

so re-runs only send what's missing. Memories are grouped per repo and day into
chronological conversations and imported through Engram's extraction pipeline, with each
conversation's `created_at` telling the extractor when the data is from — so memory

[Copilot]

Pull request overview

Copilot reviewed 11 out of 13 changed files in this pull request and generated no new comments.

Suppressed comments (1)

plugin/core/migrate/claude_mem.py:121

• describe_selection() says rows with no usable content are dropped "at planning", but the adapter actually drops those rows while iterating the source DB (in _observations() / _summaries() it continues when content is empty). This is a small but concrete mismatch in the dry-run report text.

        return [
            f"observation rows: {by_type} — rows with no usable content are dropped "
            "at planning",