@ectplsm/relic 0.2.0 → 0.2.1

package/README.md

@@ -42,27 +42,52 @@ npm install -g @ectplsm/relic
 
 ## Quick Start
 
+### 1. Initialize
+
 ```bash
-# Initialize — creates config and sample Engrams
 relic init
 # → Prompts: "Set a default Engram? (press Enter for "johnny", or enter ID, or "n" to skip):"
 
-# List available Engrams
-relic list
+relic list                            # List available Engrams
+relic config default-engram motoko   # (Optional) Set your default Engram
+```
+
+### 2. Set Up Memory (MCP)
+
+Register the MCP server so the Construct can search past conversations and distill memories. Pick your shell:
+
+```bash
+# Claude Code
+claude mcp add --scope user relic -- relic-mcp
+
+# Codex CLI
+codex mcp add relic -- relic-mcp
+
+# Gemini CLI — add to ~/.gemini/settings.json:
+#   { "mcpServers": { "relic": { "command": "relic-mcp", "trust": true } } }
+```
+
+> For auto-approval setup and per-shell details, see [MCP Server](#mcp-server).
 
-# Preview an Engram's composed prompt
-relic show motoko
+### 3. Launch a Shell
 
-# Launch a Shell (uses default Engram if --engram is omitted)
-relic claude
+```bash
+relic claude                   # Uses default Engram
+relic claude --engram motoko   # Specify explicitly
 relic codex
 relic gemini
-
-# Or specify explicitly
-relic claude --engram motoko
-relic codex --engram johnny
 ```
 
+### 4. Organize Memories
+
+As you use a Construct, conversation logs are automatically saved to `archive.md` by background hooks. To distill these into lasting memory, periodically tell the Construct:
+
+> **"Organize my memories"**
+
+The Construct will review recent conversations, extract key facts and decisions into `memory/*.md`, promote important long-term insights to `MEMORY.md`, and update your preferences in `USER.md`. These distilled memories are then loaded into future sessions automatically.
+
+> For details on the memory system, see [Memory Management](#memory-management).
+
 ## What `relic init` Creates
 
 Running `relic init` creates `~/.relic/`, writes `config.json`, and seeds two sample Engrams under `~/.relic/engrams/`.
@@ -314,11 +339,23 @@ Add to `~/.gemini/settings.json`:
 
 Relic Engrams are natively compatible with [OpenClaw](https://github.com/openclaw/openclaw) workspaces — their file structure maps 1:1 (SOUL.md, IDENTITY.md, memory/, etc.). For other Claw-derived frameworks (Nanobot, gitagent, etc.) that fold identity into SOUL.md, the `--merge-identity` flag merges IDENTITY.md into SOUL.md on inject. Combined with `--dir`, Relic can target any Claw-compatible workspace.
 
-Agent Name = Engram ID. All Claw commands live under `relic claw`:
+Current rule: **Agent Name = Engram ID**. Relic treats them as the same name by default. This keeps Claw integration simple: once Engram and agent names diverge, Relic has to introduce explicit mapping logic, which adds complexity that the current workflow does not need.
+
+All Claw commands live under `relic claw`:
+
+### Command Summary
+
+| Command | Direction | Description |
+|---------|-----------|-------------|
+| `relic claw inject -e <id>` | Relic → Claw | Push persona + auto-sync (`--yes` skips overwrite confirmation, `--no-sync` skips sync, `--merge-identity` for non-OpenClaw) |
+| `relic claw extract -a <name>` | Claw → Relic | New import or persona-only overwrite, then auto-sync that target (`--force`, `--yes`, `--no-sync`) |
+| `relic claw sync` | Relic ↔ Claw | Bidirectional merge (memory, MEMORY.md, USER.md; `--target` limits sync to one target) |
 
 ### Inject — Push an Engram into a Claw workspace
 
-Injects persona files (SOUL.md, IDENTITY.md) into the agent's workspace directory, then automatically runs a sync for that pair. USER.md and memory are handled by the auto-sync (bidirectional merge, not overwrite). AGENTS.md and HEARTBEAT.md are left to the Claw agent.
+Writes the persona files (`SOUL.md`, `IDENTITY.md`) into the agent workspace, then syncs `USER.md` and memory files (`MEMORY.md`, `memory/*.md`). The sync is bidirectional and merge-based, not a blind overwrite. `AGENTS.md` and `HEARTBEAT.md` remain under Claw's control.
+
+If persona files already exist in the target workspace and differ from the local Relic Engram, `inject` asks for confirmation by default. Use `--yes` to skip the prompt. If the target persona already matches, Relic skips the persona rewrite and only runs the memory sync.
 
 > **Note:** The Claw agent must already exist (e.g. `openclaw agents add <name>`). Inject writes persona files into an existing workspace — it does not create new agents.
 
@@ -326,20 +363,26 @@ Injects persona files (SOUL.md, IDENTITY.md) into the agent's workspace director
 # Inject Engram "motoko" → workspace-motoko/
 relic claw inject --engram motoko
 
-# Inject into a differently-named agent
-relic claw inject --engram motoko --to main
-# → workspace/ receives motoko's persona
-
 # Override Claw directory (or configure once with: relic config claw-path)
 relic claw inject --engram motoko --dir /path/to/.fooclaw
 
 # Non-OpenClaw frameworks: merge IDENTITY.md into SOUL.md
 relic claw inject --engram motoko --dir ~/.nanobot --merge-identity
+
+# Skip overwrite confirmation if persona files differ
+relic claw inject --engram motoko --yes
 ```
 
-### Extract — Import a Claw agent as a new Engram
+### Extract — Import a Claw agent as an Engram
+
+Creates a new Engram from an existing Claw agent workspace.
 
-Creates a new Engram from an existing Claw agent workspace. This is a **one-time initial import** — if the Engram already exists, use `relic claw inject` to push updates.
+What `extract` writes locally:
+- New extract: `engram.json`, `SOUL.md`, `IDENTITY.md`, `USER.md`, `MEMORY.md`, `memory/*.md`
+- `extract --force`: only `SOUL.md` and `IDENTITY.md`
+- `extract --force --name`: `SOUL.md`, `IDENTITY.md`, and `engram.json.name`
+
+After `extract`, Relic automatically runs a targeted sync for that same Engram/agent target. Use `--no-sync` to skip it.
 
 ```bash
 # Extract from the default (main) agent
@@ -351,18 +394,32 @@ relic claw extract --agent johnny
 # Set a custom display name
 relic claw extract --agent analyst --name "Data Analyst"
 
+# Overwrite local persona files from the Claw workspace
+relic claw extract --agent johnny --force
+
+# Skip overwrite confirmation
+relic claw extract --agent johnny --force --yes
+
+# Skip the automatic targeted sync after extract
+relic claw extract --agent johnny --no-sync
+
 # Override Claw directory
 relic claw extract --agent johnny --dir /path/to/.fooclaw
 ```
 
 ### Sync — Bidirectional merge
 
-Merges `memory/*.md`, `MEMORY.md`, and `USER.md` between matching Engram/agent pairs. Only pairs where both the Engram and agent exist are synced. Also runs automatically after `inject` (skip with `--no-sync`).
+Merges `memory/*.md`, `MEMORY.md`, and `USER.md` between matching Engram/agent targets. Only targets where both the Engram and agent exist are synced. Also runs automatically after `inject` (skip with `--no-sync`).
+
+By default, `sync` scans all matching targets. Use `--target <id>` to sync only one target by shared Engram/agent name.
 
 ```bash
-# Sync all matching pairs
+# Sync all matching targets
 relic claw sync
 
+# Sync only one matching target
+relic claw sync --target johnny
+
 # Override Claw directory
 relic claw sync --dir /path/to/.fooclaw
 ```
@@ -372,13 +429,30 @@ Merge rules:
 - Same content → skipped
 - Different content → merged (deduplicated) and written to both sides
 
-### Command Summary
-
-| Command | Direction | Description |
-|---------|-----------|-------------|
-| `relic claw inject -e <id>` | Relic → Claw | Push persona + auto-sync (`--no-sync` to skip, `--merge-identity` for non-OpenClaw) |
-| `relic claw extract -a <name>` | Claw → Relic | One-time import (new Engrams only) |
-| `relic claw sync` | Relic ↔ Claw | Bidirectional merge (memory, MEMORY.md, USER.md) |
+### Behavior Matrix
+
+| Command | State | Flags | Result |
+|---------|------|------|------|
+| `inject` | Workspace missing | none | Fail and ask you to create the agent first |
+| `inject` | Persona matches local Engram | none | Skip persona rewrite, then auto-sync that target |
+| `inject` | Persona differs from local Engram | none | Ask for confirmation before overwriting persona, then auto-sync that target |
+| `inject` | Persona differs from local Engram | `--yes` | Overwrite persona without confirmation, then auto-sync that target |
+| `inject` | any successful inject | `--no-sync` | Skip the automatic targeted sync |
+| `extract` | Local Engram missing | none | Create a new Engram from workspace files, then auto-sync that target |
+| `extract` | Local Engram missing | `--force` | Same as normal new extract, then auto-sync that target |
+| `extract` | Local Engram exists | none | Fail and require `--force` |
+| `extract` | Local Engram exists, no persona drift | `--force` | Skip persona overwrite, then auto-sync that target |
+| `extract` | Local Engram exists, persona differs | `--force` | Ask for confirmation before overwriting `SOUL.md` / `IDENTITY.md`, then auto-sync that target |
+| `extract` | Local Engram exists, persona differs | `--force --yes` | Overwrite `SOUL.md` / `IDENTITY.md` without confirmation, then auto-sync that target |
+| `extract` | any successful extract | `--no-sync` | Skip the automatic targeted sync |
+| `sync` | no target | none | Scan and sync all matching targets |
+| `sync` | explicit target | `--target <id>` | Sync one matching target where `agentName = engramId` |
+
+Notes:
+- "Persona" means `SOUL.md` and `IDENTITY.md`
+- `extract --force` only overwrites `SOUL.md` and `IDENTITY.md`
+- `extract --force` does not overwrite `USER.md`, `MEMORY.md`, or `memory/*.md`
+- If `--name` is provided together with `extract --force`, Relic also updates `engram.json.name`
 
 ## Memory Management
 

package/dist/core/usecases/extract.d.ts

@@ -1,4 +1,15 @@
 import type { EngramRepository } from "../ports/engram-repository.js";
+export type ExtractPersonaFileDiff = "missing" | "same" | "different";
+export interface ExtractPersonaDiffResult {
+    engramId: string;
+    engramName: string;
+    sourcePath: string;
+    existing: boolean;
+    name: ExtractPersonaFileDiff;
+    soul: ExtractPersonaFileDiff;
+    identity: ExtractPersonaFileDiff;
+    overwriteRequired: boolean;
+}
 export interface ExtractResult {
     engramId: string;
     engramName: string;
@@ -14,10 +25,16 @@ export interface ExtractResult {
 export declare class Extract {
     private readonly repository;
     constructor(repository: EngramRepository);
+    inspectPersona(agentName: string, options?: {
+        name?: string;
+        openclawDir?: string;
+    }): Promise<ExtractPersonaDiffResult>;
     execute(agentName: string, options?: {
         name?: string;
         openclawDir?: string;
+        force?: boolean;
     }): Promise<ExtractResult>;
+    private comparePersonaFile;
     private readFiles;
 }
 export declare class WorkspaceNotFoundError extends Error {

package/dist/core/usecases/extract.js

@@ -13,41 +13,95 @@ export class Extract {
     constructor(repository) {
         this.repository = repository;
     }
+    async inspectPersona(agentName, options) {
+        const sourcePath = resolveWorkspacePath(agentName, options?.openclawDir);
+        if (!existsSync(sourcePath)) {
+            throw new WorkspaceNotFoundError(sourcePath);
+        }
+        const { files } = await this.readFiles(sourcePath);
+        const existing = await this.repository.get(agentName);
+        if (!existing) {
+            return {
+                engramId: agentName,
+                engramName: options?.name ?? agentName,
+                sourcePath,
+                existing: false,
+                name: "missing",
+                soul: "missing",
+                identity: "missing",
+                overwriteRequired: false,
+            };
+        }
+        const requestedName = options?.name ?? existing.meta.name;
+        const name = requestedName === existing.meta.name ? "same" : "different";
+        const soul = this.comparePersonaFile(existing.files.soul, files.soul);
+        const identity = this.comparePersonaFile(existing.files.identity, files.identity);
+        return {
+            engramId: agentName,
+            engramName: existing.meta.name,
+            sourcePath,
+            existing: true,
+            name,
+            soul,
+            identity,
+            overwriteRequired: name === "different" ||
+                soul === "different" ||
+                identity === "different",
+        };
+    }
     async execute(agentName, options) {
         const sourcePath = resolveWorkspacePath(agentName, options?.openclawDir);
         if (!existsSync(sourcePath)) {
             throw new WorkspaceNotFoundError(sourcePath);
         }
-        // 既存Engramがあればエラー — Relic側が真のデータソース
         const existing = await this.repository.get(agentName);
-        if (existing) {
+        if (existing && !options?.force) {
             throw new AlreadyExtractedError(agentName);
         }
         const { files, filesRead } = await this.readFiles(sourcePath);
         if (filesRead.length === 0) {
             throw new WorkspaceEmptyError(sourcePath);
         }
-        const engramName = options?.name ?? agentName;
         const now = new Date().toISOString();
-        const engram = {
-            meta: {
-                id: agentName,
-                name: engramName,
-                description: `Extracted from OpenClaw workspace (${agentName})`,
-                createdAt: now,
-                updatedAt: now,
-                tags: ["extracted", "openclaw"],
-            },
-            files,
-        };
+        const engram = existing && options?.force
+            ? {
+                meta: {
+                    ...existing.meta,
+                    name: options?.name ?? existing.meta.name,
+                    updatedAt: now,
+                },
+                // Force extract only replaces persona files from Claw.
+                files: {
+                    ...existing.files,
+                    soul: files.soul ?? existing.files.soul,
+                    identity: files.identity ?? existing.files.identity,
+                },
+            }
+            : {
+                meta: {
+                    id: agentName,
+                    name: options?.name ?? agentName,
+                    description: `Extracted from OpenClaw workspace (${agentName})`,
+                    createdAt: now,
+                    updatedAt: now,
+                    tags: ["extracted", "openclaw"],
+                },
+                files,
+            };
         await this.repository.save(engram);
         return {
             engramId: agentName,
-            engramName,
+            engramName: engram.meta.name,
             sourcePath,
             filesRead,
         };
     }
+    comparePersonaFile(currentContent, incomingContent) {
+        if (currentContent === undefined || incomingContent === undefined) {
+            return "missing";
+        }
+        return currentContent === incomingContent ? "same" : "different";
+    }
     async readFiles(sourcePath) {
         const files = {};
         const filesRead = [];
@@ -88,7 +142,7 @@ export class WorkspaceEmptyError extends Error {
 }
 export class AlreadyExtractedError extends Error {
     constructor(id) {
-        super(`Engram "${id}" already exists. Relic is the source of truth — use "relic claw inject" to push changes.`);
+        super(`Engram "${id}" already exists. Re-run with "--force" option to overwrite local persona files from the Claw workspace.`);
         this.name = "AlreadyExtractedError";
     }
 }

package/dist/core/usecases/index.d.ts

@@ -1,8 +1,8 @@
 export { Summon, EngramNotFoundError, type SummonResult } from "./summon.js";
 export { ListEngrams } from "./list-engrams.js";
 export { Init, type InitResult } from "./init.js";
-export { Inject, InjectEngramNotFoundError, InjectClawDirNotFoundError, InjectWorkspaceNotFoundError, type InjectResult, } from "./inject.js";
-export { Extract, WorkspaceNotFoundError, WorkspaceEmptyError, AlreadyExtractedError, type ExtractResult, } from "./extract.js";
+export { Inject, InjectEngramNotFoundError, InjectClawDirNotFoundError, InjectWorkspaceNotFoundError, type InjectPersonaFileDiff, type InjectPersonaDiffResult, type InjectResult, } from "./inject.js";
+export { Extract, WorkspaceNotFoundError, WorkspaceEmptyError, AlreadyExtractedError, type ExtractPersonaFileDiff, type ExtractPersonaDiffResult, type ExtractResult, } from "./extract.js";
 export { MemoryWrite, MemoryWriteEngramNotFoundError, type MemoryWriteResult, } from "./memory-write.js";
 export { Sync, SyncOpenclawDirNotFoundError, type SyncTarget, type SyncResult, type SyncInitialResult, } from "./sync.js";
 export { ArchivePending, ArchivePendingEngramNotFoundError, type ArchivePendingResult, } from "./archive-pending.js";

package/dist/core/usecases/inject.d.ts

@@ -1,4 +1,13 @@
 import type { EngramRepository } from "../ports/engram-repository.js";
+export type InjectPersonaFileDiff = "missing" | "same" | "different" | "skipped";
+export interface InjectPersonaDiffResult {
+    engramId: string;
+    engramName: string;
+    targetPath: string;
+    soul: InjectPersonaFileDiff;
+    identity: InjectPersonaFileDiff;
+    overwriteRequired: boolean;
+}
 export interface InjectResult {
     engramId: string;
     engramName: string;
@@ -15,11 +24,17 @@ export interface InjectResult {
 export declare class Inject {
     private readonly repository;
     constructor(repository: EngramRepository);
+    inspectPersona(engramId: string, options?: {
+        openclawDir?: string;
+        mergeIdentity?: boolean;
+    }): Promise<InjectPersonaDiffResult>;
     execute(engramId: string, options?: {
-        to?: string;
         openclawDir?: string;
         mergeIdentity?: boolean;
     }): Promise<InjectResult>;
+    private loadInjectTarget;
+    private resolveInjectedContent;
+    private compareTargetFile;
     private writeFiles;
 }
 export declare class InjectEngramNotFoundError extends Error {

package/dist/core/usecases/inject.js

@@ -1,6 +1,6 @@
 import { join } from "node:path";
 import { existsSync } from "node:fs";
-import { writeFile } from "node:fs/promises";
+import { readFile, writeFile } from "node:fs/promises";
 import { INJECT_FILE_MAP, resolveWorkspacePath } from "../../shared/openclaw.js";
 /**
  * Inject — EngramのファイルをOpenClawワークスペースに注入する
@@ -14,27 +14,65 @@ export class Inject {
     constructor(repository) {
         this.repository = repository;
     }
+    async inspectPersona(engramId, options) {
+        const { engram, targetPath } = await this.loadInjectTarget(engramId, options);
+        const mergeIdentity = options?.mergeIdentity ?? false;
+        const soul = await this.compareTargetFile(join(targetPath, INJECT_FILE_MAP.soul), this.resolveInjectedContent("soul", engram.files, mergeIdentity));
+        const identity = mergeIdentity
+            ? "skipped"
+            : await this.compareTargetFile(join(targetPath, INJECT_FILE_MAP.identity), this.resolveInjectedContent("identity", engram.files, mergeIdentity));
+        return {
+            engramId: engram.meta.id,
+            engramName: engram.meta.name,
+            targetPath,
+            soul,
+            identity,
+            overwriteRequired: soul === "different" || identity === "different",
+        };
+    }
     async execute(engramId, options) {
+        const { engram, targetPath } = await this.loadInjectTarget(engramId, options);
+        const filesWritten = await this.writeFiles(targetPath, engram.files, options?.mergeIdentity ?? false);
+        return {
+            engramId: engram.meta.id,
+            engramName: engram.meta.name,
+            targetPath,
+            filesWritten,
+        };
+    }
+    async loadInjectTarget(engramId, options) {
         const engram = await this.repository.get(engramId);
         if (!engram) {
             throw new InjectEngramNotFoundError(engramId);
         }
-        // ベースディレクトリ（--dir）の存在チェック
         if (options?.openclawDir && !existsSync(options.openclawDir)) {
             throw new InjectClawDirNotFoundError(options.openclawDir);
         }
-        const agentName = options?.to ?? engramId;
-        const targetPath = resolveWorkspacePath(agentName, options?.openclawDir);
+        const targetPath = resolveWorkspacePath(engramId, options?.openclawDir);
         if (!existsSync(targetPath)) {
-            throw new InjectWorkspaceNotFoundError(agentName);
+            throw new InjectWorkspaceNotFoundError(engramId);
         }
-        const filesWritten = await this.writeFiles(targetPath, engram.files, options?.mergeIdentity ?? false);
-        return {
-            engramId: engram.meta.id,
-            engramName: engram.meta.name,
-            targetPath,
-            filesWritten,
-        };
+        return { engram, targetPath };
+    }
+    resolveInjectedContent(key, files, mergeIdentity) {
+        if (mergeIdentity && key === "identity") {
+            return undefined;
+        }
+        let content = files[key];
+        if (mergeIdentity && key === "soul" && files.identity) {
+            content = content + "\n" + files.identity;
+        }
+        return content;
+    }
+    async compareTargetFile(filePath, expectedContent) {
+        if (expectedContent === undefined) {
+            return "skipped";
+        }
+        if (!existsSync(filePath)) {
+            return "missing";
+        }
+        const currentContent = await readFile(filePath, "utf-8");
+        return currentContent === expectedContent ? "same" : "different";
     }
     async writeFiles(targetPath, files, mergeIdentity) {
         const written = [];
@@ -43,11 +81,7 @@ export class Inject {
             if (mergeIdentity && key === "identity") {
                 continue;
             }
-            let content = files[key];
-            // --merge-identity: append IDENTITY.md content to SOUL.md
-            if (mergeIdentity && key === "soul" && files.identity) {
-                content = content + "\n" + files.identity;
-            }
+            const content = this.resolveInjectedContent(key, files, mergeIdentity);
             if (content !== undefined) {
                 await writeFile(join(targetPath, filename), content, "utf-8");
                 written.push(filename);

package/dist/interfaces/cli/commands/claw.js

@@ -1,3 +1,6 @@
+import { createInterface } from "node:readline/promises";
+import { stdin as input, stdout as output } from "node:process";
+import { existsSync } from "node:fs";
 import { LocalEngramRepository } from "../../../adapters/local/index.js";
 import { Inject, InjectEngramNotFoundError, InjectClawDirNotFoundError, InjectWorkspaceNotFoundError, Extract, WorkspaceNotFoundError, WorkspaceEmptyError, AlreadyExtractedError, Sync, SyncOpenclawDirNotFoundError, } from "../../../core/usecases/index.js";
 import { resolveEngramsPath, resolveClawPath } from "../../../shared/config.js";
@@ -11,9 +14,9 @@ export function registerClawCommand(program) {
         .command("inject")
         .description("Push an Engram into a Claw workspace")
         .requiredOption("-e, --engram <id>", "Engram ID to inject")
-        .option("--to <agent>", "Inject into a different agent name")
         .option("--dir <dir>", "Override Claw directory path (default: ~/.openclaw)")
         .option("--merge-identity", "Merge IDENTITY.md into SOUL.md (for non-OpenClaw Claw frameworks)")
+        .option("-y, --yes", "Skip persona overwrite confirmation")
         .option("--no-sync", "Skip automatic memory sync after inject")
         .option("-p, --path <dir>", "Override engrams directory path")
         .action(async (opts) => {
@@ -22,19 +25,34 @@ export function registerClawCommand(program) {
         const repo = new LocalEngramRepository(engramsPath);
         const inject = new Inject(repo);
         try {
-            const result = await inject.execute(opts.engram, {
-                to: opts.to,
+            const diff = await inject.inspectPersona(opts.engram, {
                 openclawDir: clawDir,
                 mergeIdentity: opts.mergeIdentity,
             });
-            console.log(`Injected "${result.engramName}" into ${result.targetPath}`);
-            console.log(`  Files written: ${result.filesWritten.join(", ")}`);
+            const alreadyInjected = diff.soul === "same" &&
+                (diff.identity === "same" || diff.identity === "skipped");
+            if (diff.overwriteRequired &&
+                !opts.yes &&
+                !(await confirmOverwrite(`SOUL.md and/or IDENTITY.md already exist and differ in ${diff.targetPath}. Overwrite with local Relic version? [y/N] `))) {
+                console.error("Error: Persona files already exist and differ. Re-run with --yes to overwrite from local Relic Engram.");
+                process.exit(1);
+            }
+            if (alreadyInjected) {
+                console.log(`  Already injected (${diff.targetPath})`);
+            }
+            else {
+                const result = await inject.execute(opts.engram, {
+                    openclawDir: clawDir,
+                    mergeIdentity: opts.mergeIdentity,
+                });
+                console.log(`Injected "${result.engramName}" into ${result.targetPath}`);
+                console.log(`  Files written: ${result.filesWritten.join(", ")}`);
+            }
             if (!opts.sync)
                 return;
             // Auto-sync memory after inject
             const sync = new Sync(repo, engramsPath);
-            const agentName = opts.to ?? opts.engram;
-            const workspacePath = resolveWorkspacePath(agentName, clawDir);
+            const workspacePath = resolveWorkspacePath(opts.engram, clawDir);
             const syncResult = await sync.syncPair({
                 engramId: opts.engram,
                 workspacePath,
@@ -73,21 +91,82 @@ export function registerClawCommand(program) {
         .option("-a, --agent <name>", "Agent name to extract from (default: main)")
         .option("--name <name>", "Engram display name (defaults to agent name)")
         .option("--dir <dir>", "Override Claw directory path (default: ~/.openclaw)")
+        .option("-f, --force", "Allow overwriting local persona files from the Claw workspace")
+        .option("-y, --yes", "Skip persona overwrite confirmation")
+        .option("--no-sync", "Skip automatic memory sync after extract")
         .option("-p, --path <dir>", "Override engrams directory path")
         .action(async (opts) => {
         const engramsPath = await resolveEngramsPath(opts.path);
         const clawDir = await resolveClawPath(opts.dir);
         const repo = new LocalEngramRepository(engramsPath);
         const extract = new Extract(repo);
+        const sync = new Sync(repo, engramsPath);
         try {
             const agentName = opts.agent ?? "main";
-            const result = await extract.execute(agentName, {
+            const diff = await extract.inspectPersona(agentName, {
                 name: opts.name,
                 openclawDir: clawDir,
             });
-            console.log(`Extracted "${result.engramName}" from ${result.sourcePath}`);
-            console.log(`  Files read: ${result.filesRead.join(", ")}`);
-            console.log(`  Saved as Engram: ${result.engramId}`);
+            if (diff.existing && !opts.force) {
+                throw new AlreadyExtractedError(agentName);
+            }
+            const alreadyExtracted = diff.existing &&
+                diff.name === "same" &&
+                diff.soul === "same" &&
+                diff.identity === "same";
+            if (diff.existing &&
+                diff.overwriteRequired &&
+                !opts.yes &&
+                !(await confirmOverwrite(`SOUL.md and/or IDENTITY.md already exist in local Engram "${agentName}" and differ from ${diff.sourcePath}. Overwrite with the Claw version? [y/N] `))) {
+                console.error("Error: Persona files already exist and differ. Re-run with --yes to overwrite from the Claw workspace.");
+                process.exit(1);
+            }
+            if (alreadyExtracted) {
+                console.log(opts.force
+                    ? `  Already extracted and updated (${agentName})`
+                    : `  Already extracted (${agentName})`);
+            }
+            else {
+                const result = await extract.execute(agentName, {
+                    name: opts.name,
+                    openclawDir: clawDir,
+                    force: opts.force,
+                });
+                console.log(`Extracted "${result.engramName}" from ${result.sourcePath}`);
+                if (diff.existing) {
+                    console.log(`  Files overwritten: SOUL.md, IDENTITY.md`);
+                    if (diff.name === "different") {
+                        console.log(`  Metadata updated: engram.json (name)`);
+                    }
+                    console.log(`  Saved as Engram: ${result.engramId}`);
+                }
+                else {
+                    console.log(`  Files extracted: ${result.filesRead.join(", ")}`);
+                    console.log(`  Saved as Engram: ${result.engramId}`);
+                }
+            }
+            if (!opts.sync)
+                return;
+            const syncResult = await sync.syncPair({
+                engramId: agentName,
+                workspacePath: diff.sourcePath,
+            });
+            const details = [];
+            if (syncResult.memoryFilesMerged > 0) {
+                details.push(`${syncResult.memoryFilesMerged} memory file(s)`);
+            }
+            if (syncResult.memoryIndexMerged) {
+                details.push("MEMORY.md");
+            }
+            if (syncResult.userMerged) {
+                details.push("USER.md");
+            }
+            if (details.length > 0) {
+                console.log(`  Synced: ${details.join(", ")}`);
+            }
+            else {
+                console.log(`  Already in sync`);
+            }
         }
         catch (err) {
             if (err instanceof WorkspaceNotFoundError ||
@@ -103,6 +182,7 @@ export function registerClawCommand(program) {
     claw
         .command("sync")
         .description("Bidirectional memory sync between Engrams and Claw workspaces")
+        .option("-t, --target <id>", "Sync one target only by shared Engram/agent name")
         .option("--dir <dir>", "Override Claw directory path (default: ~/.openclaw)")
         .option("-p, --path <dir>", "Override engrams directory path")
         .action(async (opts) => {
@@ -111,6 +191,44 @@ export function registerClawCommand(program) {
         const repo = new LocalEngramRepository(engramsPath);
         const sync = new Sync(repo, engramsPath);
         try {
+            if (opts.target) {
+                const targetId = opts.target.trim();
+                if (!targetId) {
+                    console.error(`Error: Invalid sync target "${opts.target}".`);
+                    process.exit(1);
+                }
+                const engram = await repo.get(targetId);
+                if (!engram) {
+                    console.error(`Error: Engram "${targetId}" not found.`);
+                    process.exit(1);
+                }
+                const workspacePath = resolveWorkspacePath(targetId, clawDir);
+                if (!existsSync(workspacePath)) {
+                    console.error(`Error: Claw agent "${targetId}" workspace not found.`);
+                    process.exit(1);
+                }
+                const result = await sync.syncPair({
+                    engramId: targetId,
+                    workspacePath,
+                });
+                const details = [];
+                if (result.memoryFilesMerged > 0) {
+                    details.push(`${result.memoryFilesMerged} memory file(s)`);
+                }
+                if (result.memoryIndexMerged) {
+                    details.push("MEMORY.md");
+                }
+                if (result.userMerged) {
+                    details.push("USER.md");
+                }
+                if (details.length > 0) {
+                    console.log(`  ${targetId}: merged ${details.join(", ")}`);
+                }
+                else {
+                    console.log(`  Already in sync (${targetId})`);
+                }
+                return;
+            }
             const result = await sync.execute(clawDir);
             if (result.synced.length === 0 && result.skipped.length === 0) {
                 console.log("No Claw workspaces found.");
@@ -131,7 +249,7 @@ export function registerClawCommand(program) {
                     console.log(`  ${s.engramId}: merged ${details.join(", ")}`);
                 }
                 else {
-                    console.log(`  ${s.engramId}: already in sync`);
+                    console.log(`  Already in sync (${s.engramId})`);
                 }
             }
             if (result.skipped.length > 0) {
@@ -147,3 +265,16 @@ export function registerClawCommand(program) {
         }
     });
 }
+async function confirmOverwrite(message) {
+    if (!input.isTTY || !output.isTTY) {
+        return false;
+    }
+    const rl = createInterface({ input, output });
+    try {
+        const answer = await rl.question(message);
+        return /^(y|yes)$/i.test(answer.trim());
+    }
+    finally {
+        rl.close();
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ectplsm/relic",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "PROJECT RELIC — Engram injection system for AI constructs",
   "license": "MIT",
   "repository": {