| name | memex-update |
| description | Sync an installed memex with upstream — reconcile the scaffolded files against the current upstream memex: auto-apply changes to files you never touched, agent-merge the ones you edited, and never touch living vault content. Use when upstream memex changed scaffolded content (a renamed term, a reworded skill) and you want it pulled in without clobbering local edits. |
update — Reconcile the installed memex against upstream
Pull upstream changes into an installed memex's scaffolded content without clobbering local edits. The deterministic work (fetch, classify, auto-apply the safe cases) is the engine's; you only merge the files that genuinely conflict.
Announce at start: "Reconciling memex against upstream..."
What is managed
Only file-backed scaffold content, each compared by sha256 against a tracked baseline (.memex/.update-manifest.json):
| Local path | Upstream source (in the clone) |
|---|
.agents/skills/memex-<name>/SKILL.md (recall, brainstorming, writing-plans, link, new-pr, code-review, update) | <clone>/skills/memex/scaffold/skills/memex-<name>/SKILL.md |
.memex/spec-driven-development.md | <clone>/skills/memex/scaffold/vault-docs/spec-driven-development.md |
.memex/scripts/validate-spec.sh | <clone>/skills/memex/scaffold/vault-scripts/validate-spec.sh |
.memex/scripts/memex-update.sh | <clone>/skills/memex/scaffold/vault-scripts/memex-update.sh |
the ### Spec flow block of AGENTS.md | the ### Spec flow block of <clone>/skills/memex/references/agents-md-template.md |
Never touched: .memex/_index/*, .memex/learnings/*, .memex/conventions/*, .memex/specs/*, the per-repo intro and non-spec-flow sections of AGENTS.md, and constitution.md. Prose-generated content (templates, rules.md, MOCs, the constitution) is out of scope — it has no single upstream file to hash.
Run the engine
bash .memex/scripts/memex-update.sh --run
It fetches the current upstream memex (git clone --depth 1 — needs network), classifies every managed path, auto-applies the safe updates, and prints a report. No network → it stops with a clear message; re-run when online.
Read the report. The first line is the clone location:
clone /tmp/tmp.XXXXXX
then one line per managed path: current / updated / local-only / conflict + a tab + the path.
current — already matches upstream. Nothing to do.updated — the file was untouched since last sync and upstream changed it; the engine already copied the new version in. (For the AGENTS block, only the ### Spec flow block was replaced; the per-repo intro is intact.)local-only — you edited it; upstream did not. Left as-is.conflict — both you and upstream changed it. Needs a merge (below).
Merge each conflict
For every conflict line, keep the clone path from the report's first line and:
- Read the local file and its upstream counterpart (the source column above, under
<clone>/…).
- Produce a merge that keeps the local edits and applies the upstream change — same intent the user customized for, with upstream's new wording/structure folded in. For an
AGENTS.md#spec-flow conflict, merge only the block between ### Spec flow and the next ## header.
- Write the merged file.
- Record the new baseline so the next run is precise (records the upstream hash you reconciled against):
bash .memex/scripts/memex-update.sh --record <local-path> <clone>
You are the only non-deterministic actor, and only on conflicts. If a "conflict" turns out to be a file you don't recognize (e.g. a skill that was never installed locally), treat upstream as the source of truth and write it in.
First run with no manifest (2-way)
A legacy install (scaffolded before this command existed) has no .memex/.update-manifest.json. The first run degrades to 2-way: files equal to upstream report current; everything else reports conflict (the engine cannot tell "you edited it" from "upstream changed it" without a baseline). Merge those conflicts as above; the run writes a manifest, so the next update is fully 3-way and precise. Say this explicitly when you see an all-conflict first run.
Report the summary
Print counts built from the report's STATUS\tpath lines, categorized as current / updated / merged (the conflicts you resolved) / local-only, then:
Review git diff, commit when satisfied. This command never commits and never opens a PR.
Boundaries
- No commit, no push, no PR. This is a maintenance command, not the spec-flow delivery —
/memex:new-pr stays the only PR path.
- Only the managed set. Never read-for-overwrite anything under the "never touched" list.
- The temp clone is left in place for the merge step; it is disposable (under
/tmp).
