@lebronj/pi-suite 0.1.4 → 0.1.5

package/vendor/pi-memory/README.md

@@ -12,6 +12,7 @@ Structured, time-aware memory extension for pi. It stores memory as plain Markdo
 - Curator core for exact dedupe, event lifecycle updates, temporary review, quota reset, and audit logs.
 - Review-first learning candidates that can become memory promotions or disabled skill drafts after approval.
 - Optional external curator service via systemd user timer or cron so curation can run even when pi is closed.
+- Snapshot + git versioning for `memory/` and disabled `skill-drafts/`, with restore support.
 
 ## Installation
 
@@ -49,6 +50,11 @@ The extension auto-creates the `pi-memory` qmd collection and path contexts on s
   daily/YYYY-MM-DD.md    # Daily append-only logs
 ~/.pi/agent/skill-drafts/
   <slug>/SKILL.md        # Disabled skill drafts created after approval
+~/.pi/agent/evolution/
+  memory/                # Current memory mirror
+  skill-drafts/          # Current skill draft mirror
+  snapshots/<id>/        # Point-in-time backup with manifest.json
+  manifests/<id>.json    # Snapshot manifest index
 ```
 
 Structured entries are separated by `§` and may start with metadata:
@@ -85,6 +91,11 @@ Metadata keys currently supported by tools and curator rules:
 | `memory_curator_enable` | Enable the external daily curator service |
 | `memory_curator_disable` | Disable the external daily curator service |
 | `memory_curator_status` | Show service backend, schedule, and state |
+| `memory_version_status` | Show local evolution git repo status |
+| `memory_version_snapshot` | Manually snapshot memory and skill drafts |
+| `memory_version_list` | List recent snapshots |
+| `memory_version_restore` | Restore `memory`, `skill-drafts`, or `all` from a snapshot id |
+| `memory_version_push` | Manually push the evolution repo to GitHub |
 
 ### memory_write Targets
 
@@ -168,6 +179,37 @@ Old candidates are lifecycle-managed without deletion. Low-confidence candidates
 
 Current learning extraction is text-based: it reads user/assistant conversation messages and asks the active model for structured candidates. It does not yet inspect structured tool-call graphs directly. Curator patch audit remains in `audit/curator.jsonl`; learning approvals are tracked through `REVIEW.md` proposal metadata and status changes.
 
+## Memory Versioning
+
+Pi-memory mirrors the authoritative runtime directories into a local evolution repo and stores point-in-time snapshots before important changes:
+
+```text
+~/.pi/agent/evolution/
+  memory/
+  skill-drafts/
+  snapshots/<snapshot-id>/
+    memory/
+    skill-drafts/
+    manifest.json
+  manifests/<snapshot-id>.json
+```
+
+Authoritative runtime data remains `~/.pi/agent/memory` and `~/.pi/agent/skill-drafts`; `~/.pi/agent/evolution` is a versioned mirror and backup repo.
+
+Automatic hooks snapshot before and sync/commit after `memory_write`, mutating `memory_edit`, mutating `scratchpad`, `memory_curate`, learning approve/reject, session summary/handoff writes, compaction handoffs, and external `jhp-pi-memory-curator run-once`. Read-only operations do not snapshot.
+
+Tools and slash commands:
+
+- `memory_version_status` / `/memory-version-status`
+- `memory_version_snapshot` / `/memory-version-snapshot [reason]`
+- `memory_version_list` / `/memory-version-list`
+- `memory_version_restore` / `/memory-version-restore <snapshot-id> [memory|skill-drafts|all]`
+- `memory_version_push` / `/memory-version-push`
+
+Restore always creates a pre-restore snapshot first, then restores the selected target, syncs the mirror, and commits `memory: restore snapshot <id>`.
+
+Default remote is `https://github.com/LRM-Teams/pi-evolution.git`. Auto commit is on; auto push is off unless `PI_EVOLUTION_AUTO_PUSH=1` is set. The repo should be private because memory contents are committed in plaintext, including any secret accidentally written to memory.
+
 ## External Curator Service
 
 `@jhp/pi-memory` includes a CLI and pi tools for an external daily service. The service is independent of the pi process, so curation can still run when pi is closed.
@@ -178,6 +220,8 @@ CLI:
 jhp-pi-memory-curator enable --schedule 03:00
 jhp-pi-memory-curator status
 jhp-pi-memory-curator run-once
+jhp-pi-memory-curator snapshot --reason "manual backup"
+jhp-pi-memory-curator push
 jhp-pi-memory-curator disable
 ```
 
@@ -203,6 +247,12 @@ The controller uses a systemd user timer when available and falls back to cron.
 | `PI_MEMORY_SKILL_DRAFTS` | `off`, `review` | `review` | Allow curator to propose disabled skill drafts |
 | `PI_MEMORY_AUTO_APPROVE_MEMORY` | `1`, `true`, `yes`, `on` | unset | YOLO mode for approving newly created memory proposals |
 | `PI_MEMORY_AUTO_APPROVE_SKILL_DRAFTS` | `1`, `true`, `yes`, `on` | unset | YOLO mode for creating newly proposed disabled skill drafts |
+| `PI_EVOLUTION_ENABLED` | `0`, `1`, `true`, `false` | `1` | Enable snapshot + git versioning |
+| `PI_EVOLUTION_DIR` | path | `~/.pi/agent/evolution` | Local evolution repo directory |
+| `PI_EVOLUTION_REMOTE` | URL | `https://github.com/LRM-Teams/pi-evolution.git` | Git remote for manual/optional push |
+| `PI_EVOLUTION_BRANCH` | branch | `main` | Local branch used for init/clone |
+| `PI_EVOLUTION_AUTO_COMMIT` | `0`, `1`, `true`, `false` | `1` | Commit sync/snapshot changes automatically |
+| `PI_EVOLUTION_AUTO_PUSH` | `0`, `1`, `true`, `false` | `0` | Push after commits automatically |
 
 ## Development
 

package/vendor/pi-memory/index.ts

@@ -50,6 +50,16 @@ import {
 import { applyReviewLifecycle, approveMemoryPromotion, proposeMemoryPromotions, rejectReviewItem } from "./src/learning/memory.ts";
 import { approveSkillDraft, listSkillDraftProposals, proposeSkillDrafts } from "./src/learning/skills.ts";
 import { FileMemoryStore } from "./src/curator-store/file-store.ts";
+import {
+	createEvolutionSnapshot,
+	getEvolutionGitStatus,
+	listManifests,
+	pushEvolution,
+	resolveEvolutionConfig,
+	restoreEvolutionSnapshot,
+	syncEvolutionAfterChange,
+	type RestoreTarget,
+} from "./src/evolution/index.ts";
 import { disableCuratorService, enableCuratorService, getCuratorServiceStatus } from "./src/service-controller.ts";
 
 
@@ -82,6 +92,10 @@ let SCRATCHPAD_FILE = path.join(MEMORY_DIR, "SCRATCHPAD.md");
 let DAILY_DIR = path.join(MEMORY_DIR, "daily");
 let SKILL_DRAFTS_DIR = path.join(path.dirname(MEMORY_DIR), "skill-drafts");
 
+function currentEvolutionConfig() {
+	return resolveEvolutionConfig(MEMORY_DIR);
+}
+
 /** Override base directory (for testing). */
 export function _setBaseDir(baseDir: string) {
 	MEMORY_DIR = baseDir;
@@ -313,12 +327,14 @@ const STRUCTURED_MEMORY_TARGETS = ["memory", "user", "state", "review"] as const
 const MEMORY_WRITE_TARGETS = ["long_term", "daily", "state", "user", "review"] as const;
 const MEMORY_READ_TARGETS = ["long_term", "scratchpad", "daily", "list", "user", "state", "review", "all"] as const;
 const MEMORY_EDIT_ACTIONS = ["read", "add", "replace", "remove", "replace_all", "compact"] as const;
+const MEMORY_VERSION_RESTORE_TARGETS = ["memory", "skill-drafts", "all"] as const;
 const STRUCTURED_MEMORY_TYPES = ["fact", "preference", "event", "temporary", "quota", "review"] as const;
 
 type StructuredMemoryTarget = (typeof STRUCTURED_MEMORY_TARGETS)[number];
 type MemoryWriteTarget = (typeof MEMORY_WRITE_TARGETS)[number];
 type MemoryReadTarget = (typeof MEMORY_READ_TARGETS)[number];
 type MemoryEditAction = (typeof MEMORY_EDIT_ACTIONS)[number];
+type MemoryVersionRestoreTarget = (typeof MEMORY_VERSION_RESTORE_TARGETS)[number];
 
 type StructuredWriteOptions = {
 	target: StructuredMemoryTarget;
@@ -830,6 +846,7 @@ export function buildTransitionHandoff(ctx: ExtensionContext, reason: Transition
 
 async function writeTransitionHandoff(ctx: ExtensionContext, reason: TransitionHandoffReason): Promise<boolean> {
 	ensureDirs();
+	await evolutionBeforeChange(`session transition handoff ${formatTransitionHandoffReason(reason)}`, "memory: snapshot before handoff", "session", shortSessionId(ctx.sessionManager.getSessionId()));
 	const sid = shortSessionId(ctx.sessionManager.getSessionId());
 	const ts = nowTimestamp();
 	const handoff = buildTransitionHandoff(ctx, reason, sid, ts);
@@ -840,6 +857,7 @@ async function writeTransitionHandoff(ctx: ExtensionContext, reason: TransitionH
 	fs.writeFileSync(filePath, existing + separator + handoff, "utf-8");
 	await ensureQmdAvailableForUpdate();
 	await runQmdUpdateNow();
+	await evolutionAfterChange("memory: sync after handoff");
 	return true;
 }
 
@@ -1423,6 +1441,7 @@ function getSnapshotMode(): "stable" | "per-turn" {
 
 async function runCurator(reason: string): Promise<string> {
 	ensureDirs();
+	await evolutionBeforeChange(`curator before ${reason}`, "memory: snapshot before curate", "tool");
 	const store = new FileMemoryStore(MEMORY_DIR);
 	const result = await runMemoryCuratorOnce({
 		memoryStore: store,
@@ -1452,6 +1471,7 @@ async function runCurator(reason: string): Promise<string> {
 		await ensureQmdAvailableForUpdate();
 		scheduleQmdUpdate();
 	}
+	await evolutionAfterChange("memory: sync after curate");
 	const notes = [
 		memoryResult.created > 0 ? `proposed ${memoryResult.created} memory promotion(s)` : "",
 		skillResult.created > 0 ? `proposed ${skillResult.created} skill draft(s)` : "",
@@ -1461,6 +1481,64 @@ async function runCurator(reason: string): Promise<string> {
 	return notes.length > 0 ? `${result.summary}; ${notes.join("; ")}` : result.summary;
 }
 
+async function evolutionBeforeChange(reason: string, commitMessage: string, trigger = "tool", sessionId?: string): Promise<void> {
+	try {
+		createEvolutionSnapshot(currentEvolutionConfig(), { reason, trigger, sessionId, commitMessage });
+	} catch {
+		// Memory operations should not fail just because versioning is unavailable.
+	}
+}
+
+async function evolutionAfterChange(commitMessage: string): Promise<void> {
+	try {
+		const config = currentEvolutionConfig();
+		syncEvolutionAfterChange(config, commitMessage);
+		if (config.autoPush) pushEvolution(config);
+	} catch {
+		// Best-effort only; the memory write itself remains authoritative.
+	}
+}
+
+function formatEvolutionStatusText(status: ReturnType<typeof getEvolutionGitStatus>): string {
+	return [
+		`enabled: ${status.enabled}`,
+		`repo: ${status.repoDir}`,
+		`initialized: ${status.initialized}`,
+		`branch: ${status.branch || "n/a"}`,
+		`remote: ${status.remote || "n/a"}`,
+		`dirty: ${status.dirty}`,
+		`autoCommit: ${status.autoCommit}`,
+		`autoPush: ${status.autoPush}`,
+		`lastCommit: ${status.lastCommit || "n/a"}`,
+		status.status ? `status:\n${status.status}` : "status: clean",
+	].join("\n");
+}
+
+function startupCuratorHintEnabled(): boolean {
+	const value = process.env.PI_MEMORY_CURATOR_STARTUP_HINT?.trim().toLowerCase();
+	return !value || !["0", "false", "off", "no"].includes(value);
+}
+
+function notifyDisabledCuratorService(ctx: ExtensionContext): void {
+	if (!ctx.hasUI || !startupCuratorHintEnabled()) return;
+	try {
+		const result = getCuratorServiceStatus({ memoryDir: MEMORY_DIR, cliPath: new URL("./src/cli.ts", import.meta.url).pathname });
+		if (result.state.enabled) return;
+		ctx.ui.notify(
+			[
+				"Memory self-evolution curator is off.",
+				"It can run daily outside pi to maintain memory lifecycle, review repeated learnings, and propose disabled skill drafts.",
+				"Enable: /memory-curator-enable 03:00",
+				"Status: /memory-curator-status",
+				"Disable: /memory-curator-disable",
+			].join("\n"),
+			"info",
+		);
+	} catch {
+		// Startup hints should never block memory initialization.
+	}
+}
+
 /** Reset snapshot state (for testing). */
 export function _resetMemorySnapshot() {
 	memorySnapshot = null;
@@ -1475,6 +1553,31 @@ export function _resetMemorySnapshot() {
 // ---------------------------------------------------------------------------
 
 export default function (pi: ExtensionAPI) {
+	const versionedToolCommitMessages: Record<string, string> = {
+		memory_write: "memory: sync after memory_write",
+		memory_edit: "memory: sync after memory_edit",
+		scratchpad: "memory: sync after scratchpad",
+		memory_learning_approve: "memory: sync after learning approve",
+		memory_learning_reject: "memory: sync after learning reject",
+	};
+
+	function shouldVersionToolCall(toolName: string, input: unknown): boolean {
+		if (!(toolName in versionedToolCommitMessages)) return false;
+		if (toolName === "scratchpad" && (input as { action?: string })?.action === "list") return false;
+		if (toolName === "memory_edit" && (input as { action?: string })?.action === "read") return false;
+		return true;
+	}
+
+	pi.on("tool_call", async (event, ctx) => {
+		if (!shouldVersionToolCall(event.toolName, event.input)) return;
+		await evolutionBeforeChange(`${event.toolName} tool`, `memory: snapshot before ${event.toolName}`, "tool", shortSessionId(ctx.sessionManager.getSessionId()));
+	});
+
+	pi.on("tool_result", async (event) => {
+		if (event.isError || !shouldVersionToolCall(event.toolName, event.input)) return;
+		await evolutionAfterChange(versionedToolCommitMessages[event.toolName]);
+	});
+
 	// --- session_start: detect qmd, auto-setup collection ---
 	pi.on("session_start", async (_event, ctx) => {
 		ensureDirs();
@@ -1492,6 +1595,7 @@ export default function (pi: ExtensionAPI) {
 				return undefined;
 			});
 		}
+		notifyDisabledCuratorService(ctx);
 
 		qmdAvailable = await detectQmd();
 		if (!qmdAvailable) {
@@ -1548,6 +1652,7 @@ export default function (pi: ExtensionAPI) {
 				const result = await generateExitSummary(ctx);
 				if (result.hasMessages) {
 					const summary = result.summary ?? buildExitSummaryFallback(result.error);
+					await evolutionBeforeChange("session shutdown summary", "memory: snapshot before session summary", "session", shortSessionId(ctx.sessionManager.getSessionId()));
 					const sid = shortSessionId(ctx.sessionManager.getSessionId());
 					const ts = nowTimestamp();
 					const entry = formatExitSummaryEntry(summary, reason, sid, ts);
@@ -1558,6 +1663,7 @@ export default function (pi: ExtensionAPI) {
 					await runSessionLearningExtractor(ctx);
 					await ensureQmdAvailableForUpdate();
 					await runQmdUpdateNow();
+					await evolutionAfterChange("memory: sync after session summary");
 				}
 			}
 		} finally {
@@ -1660,6 +1766,7 @@ export default function (pi: ExtensionAPI) {
 		// source files) would keep being injected.
 		try {
 			if (parts.length === 0) return;
+			await evolutionBeforeChange("session before compact handoff", "memory: snapshot before compact handoff", "session", sid);
 
 			const handoff = [`<!-- HANDOFF ${ts} [${sid}] -->`, "## Session Handoff", ...parts].join("\n");
 
@@ -1669,6 +1776,7 @@ export default function (pi: ExtensionAPI) {
 			fs.writeFileSync(filePath, existing + separator + handoff, "utf-8");
 			await ensureQmdAvailableForUpdate();
 			scheduleQmdUpdate();
+			await evolutionAfterChange("memory: sync after compact handoff");
 		} finally {
 			refreshMemorySnapshot("session_before_compact");
 		}
@@ -2237,6 +2345,146 @@ export default function (pi: ExtensionAPI) {
 		},
 	});
 
+	// --- memory versioning tools ---
+	pi.registerTool({
+		name: "memory_version_status",
+		label: "Memory Version Status",
+		description: "View evolution repo status, remote, branch, dirty state, last commit, and auto-push setting.",
+		parameters: Type.Object({}),
+		async execute() {
+			try {
+				const status = getEvolutionGitStatus(currentEvolutionConfig());
+				return { content: [{ type: "text", text: formatEvolutionStatusText(status) }], details: status };
+			} catch (error) {
+				const message = error instanceof Error ? error.message : String(error);
+				return { content: [{ type: "text", text: message }], details: { error: message }, isError: true };
+			}
+		},
+	});
+
+	pi.registerTool({
+		name: "memory_version_snapshot",
+		label: "Memory Version Snapshot",
+		description: "Manually create a memory + skill-drafts snapshot, sync current mirrors, and commit if changed.",
+		parameters: Type.Object({
+			reason: Type.Optional(Type.String({ description: "Snapshot reason" })),
+		}),
+		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+			try {
+				const result = createEvolutionSnapshot(currentEvolutionConfig(), {
+					reason: params.reason || "manual snapshot",
+					trigger: "tool",
+					sessionId: shortSessionId(ctx.sessionManager.getSessionId()),
+					commitMessage: "memory: manual snapshot",
+				});
+				if (currentEvolutionConfig().autoPush) pushEvolution(currentEvolutionConfig());
+				return { content: [{ type: "text", text: result.manifest ? `Snapshot ${result.manifest.id}` : `Snapshot skipped: ${result.skipped}` }], details: result };
+			} catch (error) {
+				const message = error instanceof Error ? error.message : String(error);
+				return { content: [{ type: "text", text: message }], details: { error: message }, isError: true };
+			}
+		},
+	});
+
+	pi.registerTool({
+		name: "memory_version_list",
+		label: "Memory Version List",
+		description: "List recent memory evolution snapshots.",
+		parameters: Type.Object({
+			limit: Type.Optional(Type.Number({ description: "Max snapshots to list. Default: 20" })),
+		}),
+		async execute(_toolCallId, params) {
+			try {
+				const manifests = listManifests(currentEvolutionConfig(), params.limit || 20);
+				const text = manifests.length === 0
+					? "No snapshots found."
+					: manifests.map((manifest) => `- ${manifest.id} ${manifest.createdAt} ${manifest.reason} (${manifest.files.memory} memory files, ${manifest.files.skillDrafts} skill files)`).join("\n");
+				return { content: [{ type: "text", text }], details: { manifests } };
+			} catch (error) {
+				const message = error instanceof Error ? error.message : String(error);
+				return { content: [{ type: "text", text: message }], details: { error: message }, isError: true };
+			}
+		},
+	});
+
+	pi.registerTool({
+		name: "memory_version_restore",
+		label: "Memory Version Restore",
+		description: "Restore memory and/or skill drafts from a snapshot id. Creates a pre-restore snapshot first.",
+		parameters: Type.Object({
+			id: Type.String({ description: "Snapshot id" }),
+			target: Type.Optional(StringEnum(MEMORY_VERSION_RESTORE_TARGETS, { description: "Restore target. Default: all" })),
+		}),
+		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+			try {
+				const target = (params.target || "all") as MemoryVersionRestoreTarget;
+				const result = restoreEvolutionSnapshot(currentEvolutionConfig(), params.id, target as RestoreTarget, shortSessionId(ctx.sessionManager.getSessionId()));
+				snapshotDirty = true;
+				return { content: [{ type: "text", text: `Restored ${target} from snapshot ${result.restored.id}.` }], details: result };
+			} catch (error) {
+				const message = error instanceof Error ? error.message : String(error);
+				return { content: [{ type: "text", text: message }], details: { error: message }, isError: true };
+			}
+		},
+	});
+
+	pi.registerTool({
+		name: "memory_version_push",
+		label: "Memory Version Push",
+		description: "Manually push the local evolution repo to GitHub.",
+		parameters: Type.Object({}),
+		async execute() {
+			try {
+				const output = pushEvolution(currentEvolutionConfig());
+				return { content: [{ type: "text", text: output || "Pushed evolution repo." }], details: {} };
+			} catch (error) {
+				const message = error instanceof Error ? error.message : String(error);
+				return { content: [{ type: "text", text: message }], details: { error: message }, isError: true };
+			}
+		},
+	});
+
+	pi.registerCommand("memory-version-status", {
+		description: "Show memory evolution repo status",
+		handler: async (_args, ctx) => ctx.ui.notify(formatEvolutionStatusText(getEvolutionGitStatus(currentEvolutionConfig())), "info"),
+	});
+
+	pi.registerCommand("memory-version-snapshot", {
+		description: "Create a memory evolution snapshot",
+		handler: async (args, ctx) => {
+			const result = createEvolutionSnapshot(currentEvolutionConfig(), { reason: args.trim() || "manual snapshot", trigger: "slash_command", sessionId: shortSessionId(ctx.sessionManager.getSessionId()), commitMessage: "memory: manual snapshot" });
+			ctx.ui.notify(result.manifest ? `Snapshot ${result.manifest.id}` : `Snapshot skipped: ${result.skipped}`, "info");
+		},
+	});
+
+	pi.registerCommand("memory-version-list", {
+		description: "List memory evolution snapshots",
+		handler: async (_args, ctx) => {
+			const manifests = listManifests(currentEvolutionConfig(), 20);
+			ctx.ui.notify(manifests.length === 0 ? "No snapshots found." : manifests.map((manifest) => `${manifest.id} ${manifest.reason}`).join("\n"), "info");
+		},
+	});
+
+	pi.registerCommand("memory-version-restore", {
+		description: "Restore memory evolution snapshot: /memory-version-restore <snapshot-id> [memory|skill-drafts|all]",
+		handler: async (args, ctx) => {
+			const [id, rawTarget] = args.trim().split(/\s+/);
+			if (!id) {
+				ctx.ui.notify("Usage: /memory-version-restore <snapshot-id> [memory|skill-drafts|all]", "error");
+				return;
+			}
+			const target = MEMORY_VERSION_RESTORE_TARGETS.includes(rawTarget as MemoryVersionRestoreTarget) ? rawTarget as MemoryVersionRestoreTarget : "all";
+			const result = restoreEvolutionSnapshot(currentEvolutionConfig(), id, target as RestoreTarget, shortSessionId(ctx.sessionManager.getSessionId()));
+			snapshotDirty = true;
+			ctx.ui.notify(`Restored ${target} from snapshot ${result.restored.id}.`, "info");
+		},
+	});
+
+	pi.registerCommand("memory-version-push", {
+		description: "Push memory evolution repo",
+		handler: async (_args, ctx) => ctx.ui.notify(pushEvolution(currentEvolutionConfig()) || "Pushed evolution repo.", "info"),
+	});
+
 	// --- memory_search tool ---
 	pi.registerTool({
 		name: "memory_search",

package/vendor/pi-memory/src/cli.ts

@@ -2,6 +2,7 @@
 import { JsonlAuditLog } from "./curator-core/audit.ts";
 import { runMemoryCuratorOnce } from "./curator-core/curate.ts";
 import { FileMemoryStore } from "./curator-store/file-store.ts";
+import { pushEvolution, resolveEvolutionConfig, syncEvolutionAfterChange, createEvolutionSnapshot } from "./evolution/index.ts";
 import { disableCuratorService, enableCuratorService, getCuratorServiceStatus, resolveMemoryDir } from "./service-controller.ts";
 
 function cliPath(): string {
@@ -22,6 +23,8 @@ function usage(): string {
 	return [
 		"Usage:",
 		"  jhp-pi-memory-curator run-once [--memory-dir <path>] [--reason <text>] [--dry-run] [--json]",
+		"  jhp-pi-memory-curator snapshot [--memory-dir <path>] [--reason <text>] [--json]",
+		"  jhp-pi-memory-curator push [--memory-dir <path>]",
 		"  jhp-pi-memory-curator enable [--memory-dir <path>] [--schedule HH:MM]",
 		"  jhp-pi-memory-curator disable [--memory-dir <path>]",
 		"  jhp-pi-memory-curator status [--memory-dir <path>]",
@@ -38,17 +41,43 @@ async function main(): Promise<void> {
 	}
 
 	if (command === "run-once") {
+		const reason = readOption(args, "--reason") || "cli";
+		const config = resolveEvolutionConfig(memoryDir);
+		if (!hasFlag(args, "--dry-run")) {
+			createEvolutionSnapshot(config, { reason: `curator before ${reason}`, trigger: "external_curator", commitMessage: "memory: snapshot before curator" });
+		}
 		const result = await runMemoryCuratorOnce({
 			memoryStore: new FileMemoryStore(memoryDir),
 			auditLog: new JsonlAuditLog(memoryDir),
-			reason: readOption(args, "--reason") || "cli",
+			reason,
 			dryRun: hasFlag(args, "--dry-run"),
 		});
-		if (hasFlag(args, "--json")) console.log(JSON.stringify(result, null, 2));
+		let evolutionCommit = null;
+		if (!hasFlag(args, "--dry-run")) {
+			evolutionCommit = syncEvolutionAfterChange(config, "memory: sync after external curator");
+			if (config.autoPush) pushEvolution(config);
+		}
+		if (hasFlag(args, "--json")) console.log(JSON.stringify({ ...result, evolutionCommit }, null, 2));
 		else console.log(result.summary);
 		return;
 	}
 
+	if (command === "snapshot") {
+		const result = createEvolutionSnapshot(resolveEvolutionConfig(memoryDir), {
+			reason: readOption(args, "--reason") || "cli snapshot",
+			trigger: "cli",
+			commitMessage: "memory: manual snapshot",
+		});
+		if (hasFlag(args, "--json")) console.log(JSON.stringify(result, null, 2));
+		else console.log(result.manifest ? `Snapshot ${result.manifest.id}` : `Snapshot skipped: ${result.skipped}`);
+		return;
+	}
+
+	if (command === "push") {
+		console.log(pushEvolution(resolveEvolutionConfig(memoryDir)) || "Pushed evolution repo.");
+		return;
+	}
+
 	if (command === "enable" || command === "install-service") {
 		const result = enableCuratorService({ memoryDir, cliPath: cliPath(), schedule: readOption(args, "--schedule") });
 		console.log(result.message);

package/vendor/pi-memory/src/evolution/config.ts

@@ -0,0 +1,63 @@
+import * as path from "node:path";
+
+export interface EvolutionConfig {
+	enabled: boolean;
+	autoCommit: boolean;
+	autoPush: boolean;
+	repoDir: string;
+	remote: string;
+	branch: string;
+	memoryDir: string;
+	skillDraftsDir: string;
+}
+
+type EvolutionEnv = Partial<
+	Record<
+		| "PI_EVOLUTION_DIR"
+		| "PI_EVOLUTION_REMOTE"
+		| "PI_EVOLUTION_BRANCH"
+		| "PI_EVOLUTION_ENABLED"
+		| "PI_EVOLUTION_AUTO_COMMIT"
+		| "PI_EVOLUTION_AUTO_PUSH"
+		| "HOME"
+		| "USERPROFILE"
+		| "HOMEDRIVE"
+		| "HOMEPATH",
+		string | undefined
+	>
+>;
+
+export const DEFAULT_EVOLUTION_REMOTE = "https://github.com/LRM-Teams/pi-evolution.git";
+export const DEFAULT_EVOLUTION_BRANCH = "main";
+
+function homeDir(env: EvolutionEnv): string {
+	return env.HOME ?? env.USERPROFILE ?? (env.HOMEDRIVE && env.HOMEPATH ? `${env.HOMEDRIVE}${env.HOMEPATH}` : undefined) ?? "~";
+}
+
+function truthy(value: string | undefined, fallback: boolean): boolean {
+	if (value === undefined) return fallback;
+	const normalized = value.trim().toLowerCase();
+	if (["1", "true", "yes", "on"].includes(normalized)) return true;
+	if (["0", "false", "no", "off"].includes(normalized)) return false;
+	return fallback;
+}
+
+function expandHome(input: string, env: EvolutionEnv): string {
+	if (input === "~") return homeDir(env);
+	if (input.startsWith("~/")) return path.join(homeDir(env), input.slice(2));
+	return input;
+}
+
+export function resolveEvolutionConfig(memoryDir: string, env: EvolutionEnv = process.env): EvolutionConfig {
+	const agentDir = path.dirname(memoryDir);
+	return {
+		enabled: truthy(env.PI_EVOLUTION_ENABLED, true),
+		autoCommit: truthy(env.PI_EVOLUTION_AUTO_COMMIT, true),
+		autoPush: truthy(env.PI_EVOLUTION_AUTO_PUSH, false),
+		repoDir: path.resolve(expandHome(env.PI_EVOLUTION_DIR || path.join(agentDir, "evolution"), env)),
+		remote: env.PI_EVOLUTION_REMOTE || DEFAULT_EVOLUTION_REMOTE,
+		branch: env.PI_EVOLUTION_BRANCH || DEFAULT_EVOLUTION_BRANCH,
+		memoryDir,
+		skillDraftsDir: path.join(agentDir, "skill-drafts"),
+	};
+}

package/vendor/pi-memory/src/evolution/file-utils.ts

@@ -0,0 +1,70 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+export function pathExists(filePath: string): boolean {
+	try {
+		fs.accessSync(filePath);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+export function emptyDir(dir: string): void {
+	fs.rmSync(dir, { recursive: true, force: true });
+	fs.mkdirSync(dir, { recursive: true });
+}
+
+export function copyDirContents(source: string, destination: string, options: { exclude?: (relativePath: string, isDirectory: boolean) => boolean } = {}): void {
+	fs.mkdirSync(destination, { recursive: true });
+	if (!pathExists(source)) return;
+	const entries = fs.readdirSync(source, { withFileTypes: true });
+	for (const entry of entries) {
+		const sourcePath = path.join(source, entry.name);
+		const destinationPath = path.join(destination, entry.name);
+		const relativePath = entry.name;
+		if (options.exclude?.(relativePath, entry.isDirectory())) continue;
+		copyPath(sourcePath, destinationPath, options, relativePath);
+	}
+}
+
+function copyPath(source: string, destination: string, options: { exclude?: (relativePath: string, isDirectory: boolean) => boolean }, relativePath: string): void {
+	const stat = fs.lstatSync(source);
+	if (options.exclude?.(relativePath, stat.isDirectory())) return;
+	if (stat.isDirectory()) {
+		fs.mkdirSync(destination, { recursive: true });
+		for (const entry of fs.readdirSync(source, { withFileTypes: true })) {
+			copyPath(path.join(source, entry.name), path.join(destination, entry.name), options, path.join(relativePath, entry.name));
+		}
+		return;
+	}
+	if (stat.isSymbolicLink()) {
+		try {
+			fs.symlinkSync(fs.readlinkSync(source), destination);
+		} catch {
+			// If symlink recreation fails (for example on Windows), copy target contents instead.
+			fs.copyFileSync(fs.realpathSync(source), destination);
+		}
+		return;
+	}
+	if (stat.isFile()) {
+		fs.mkdirSync(path.dirname(destination), { recursive: true });
+		fs.copyFileSync(source, destination);
+	}
+}
+
+export function replaceDirFrom(source: string, destination: string): void {
+	emptyDir(destination);
+	copyDirContents(source, destination);
+}
+
+export function countFiles(dir: string): number {
+	if (!pathExists(dir)) return 0;
+	let count = 0;
+	for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+		const entryPath = path.join(dir, entry.name);
+		if (entry.isDirectory()) count += countFiles(entryPath);
+		else if (entry.isFile() || entry.isSymbolicLink()) count += 1;
+	}
+	return count;
+}