@ectplsm/relic 0.2.0 → 0.2.2

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)
 
-# Preview an Engram's composed prompt
-relic show motoko
+Register the MCP server so the Construct can search past conversations and distill memories. Pick your shell:
 
-# Launch a Shell (uses default Engram if --engram is omitted)
-relic claude
+```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).
+
+### 3. Launch a Shell
+
+```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/`.
@@ -73,12 +98,14 @@ Running `relic init` creates `~/.relic/`, writes `config.json`, and seeds two sa
 └── engrams/
     ├── johnny/
     │   ├── engram.json
+    │   ├── manifest.json
     │   ├── SOUL.md
     │   ├── IDENTITY.md
     │   └── memory/
     │       └── YYYY-MM-DD.md
     └── motoko/
         ├── engram.json
+        ├── manifest.json
         ├── SOUL.md
         ├── IDENTITY.md
         └── memory/
@@ -87,9 +114,12 @@ Running `relic init` creates `~/.relic/`, writes `config.json`, and seeds two sa
 
 - `config.json` stores global Relic settings such as `engramsPath`, `defaultEngram`, `clawPath`, and `memoryWindowSize`.
 - `engrams/<id>/` is one Engram workspace. This is where persona files and memory for that Engram live.
-- `engram.json` stores metadata like the Engram's ID, display name, description, and tags.
+- `engram.json` stores editable profile fields like display name, description, and tags.
+- `manifest.json` stores system-managed fields like the Engram ID and timestamps.
 - `SOUL.md` and `IDENTITY.md` define the persona itself.
 - `memory/YYYY-MM-DD.md` stores dated distilled memory entries. `relic init` seeds an initial memory file for each sample Engram.
+- `relic migrate engrams` can be used to front-load legacy Engrams into the new `manifest.json` format, although normal Engram reads also migrate automatically.
+- `relic refresh-samples` refreshes bundled sample personas like `johnny` and `motoko` without touching memory or archive files.
 
 As you keep using an Engram, more files are added to the same workspace:
 
@@ -314,11 +344,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 +368,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.
+
+What `extract` writes locally:
+- New extract: `engram.json`, `manifest.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`
 
-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.
+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 +399,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 +434,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
 
@@ -439,7 +518,8 @@ Create a directory under `~/.relic/engrams/` with the following structure:
 
 ```
 ~/.relic/engrams/your-persona/
-├── engram.json        # Metadata (id, name, description, tags)
+├── engram.json        # Editable profile (name, description, tags)
+├── manifest.json      # System-managed identity (id, createdAt, updatedAt)
 ├── SOUL.md            # Core directive — how the persona thinks and acts
 ├── IDENTITY.md        # Name, tone, background, personality
 ├── AGENTS.md          # (optional) Tool usage policies
@@ -453,15 +533,21 @@ Create a directory under `~/.relic/engrams/` with the following structure:
 **engram.json:**
 ```json
 {
-  "id": "your-persona",
   "name": "Display Name",
   "description": "A short description",
-  "createdAt": "2026-03-21T00:00:00Z",
-  "updatedAt": "2026-03-21T00:00:00Z",
   "tags": ["custom"]
 }
 ```
 
+**manifest.json:**
+```json
+{
+  "id": "your-persona",
+  "createdAt": "2026-03-21T00:00:00Z",
+  "updatedAt": "2026-03-21T00:00:00Z"
+}
+```
+
 **SOUL.md** — The most important file. Defines how the persona behaves. Follows the [OpenClaw](https://github.com/openclaw/openclaw) format:
 ```markdown
 # SOUL.md - Who You Are
@@ -523,9 +609,9 @@ relic config default-engram your-persona
 - [x] Claw integration (inject / extract / sync)
 - [x] `relic claw sync` — bidirectional memory sync with Claw workspaces
 - [x] `relic config` — manage default Engram, Claw path, memory window
-- [ ] `relic login` — authenticate with Mikoshi (OAuth Device Flow)
-- [ ] `relic push` / `relic pull` — sync Engrams with Mikoshi
 - [ ] Mikoshi cloud backend (`mikoshi.ectplsm.com`)
+- [ ] `relic mikoshi login` — authenticate with Mikoshi (OAuth Device Flow)
+- [ ] `relic mikoshi upload` / `relic mikoshi download` / `relic mikoshi sync` — sync Engrams with Mikoshi
 - [ ] `relic create` — interactive Engram creation wizard
 
 ## License

package/dist/adapters/local/local-engram-repository.d.ts

@@ -6,7 +6,8 @@ import type { EngramRepository } from "../../core/ports/engram-repository.js";
  *
  * ディレクトリ構造:
  *   {basePath}/{engramId}/
- *     ├── engram.json     (メタデータ)
+ *     ├── engram.json     (ユーザー編集可能なプロフィール)
+ *     ├── manifest.json   (システム管理の識別子・タイムスタンプ)
  *     ├── SOUL.md
  *     ├── IDENTITY.md
  *     ├── AGENTS.md       (optional)
@@ -24,5 +25,8 @@ export declare class LocalEngramRepository implements EngramRepository {
     save(engram: Engram): Promise<void>;
     delete(id: string): Promise<void>;
     private readMeta;
+    private toProfile;
+    private toManifest;
+    private writeMetaFiles;
     private readFiles;
 }

package/dist/adapters/local/local-engram-repository.js

@@ -1,7 +1,7 @@
 import { readdir, readFile, writeFile, mkdir, rm } from "node:fs/promises";
 import { join } from "node:path";
 import { existsSync } from "node:fs";
-import { EngramMetaSchema } from "../../core/entities/engram.js";
+import { EngramManifestSchema, EngramMetaSchema, EngramProfileSchema, } from "../../core/entities/engram.js";
 /**
  * OpenClaw互換のファイル名マッピング
  * EngramFiles のキー → 実ファイル名
@@ -14,7 +14,8 @@ const FILE_MAP = {
     memory: "MEMORY.md",
     heartbeat: "HEARTBEAT.md",
 };
-const META_FILE = "engram.json";
+const PROFILE_FILE = "engram.json";
+const MANIFEST_FILE = "manifest.json";
 const MEMORY_DIR = "memory";
 /**
  * LocalEngramRepository — ローカルファイルシステム上の
@@ -22,7 +23,8 @@ const MEMORY_DIR = "memory";
  *
  * ディレクトリ構造:
  *   {basePath}/{engramId}/
- *     ├── engram.json     (メタデータ)
+ *     ├── engram.json     (ユーザー編集可能なプロフィール)
+ *     ├── manifest.json   (システム管理の識別子・タイムスタンプ)
  *     ├── SOUL.md
  *     ├── IDENTITY.md
  *     ├── AGENTS.md       (optional)
@@ -45,13 +47,9 @@ export class LocalEngramRepository {
         const dirs = entries.filter((e) => e.isDirectory());
         const metas = [];
         for (const dir of dirs) {
-            const metaPath = join(this.basePath, dir.name, META_FILE);
-            if (!existsSync(metaPath))
-                continue;
-            const raw = await readFile(metaPath, "utf-8");
-            const parsed = EngramMetaSchema.safeParse(JSON.parse(raw));
-            if (parsed.success) {
-                metas.push(parsed.data);
+            const meta = await this.readMeta(join(this.basePath, dir.name));
+            if (meta) {
+                metas.push(meta);
             }
         }
         return metas;
@@ -61,7 +59,7 @@ export class LocalEngramRepository {
         if (!existsSync(engramDir)) {
             return null;
         }
-        const meta = await this.readMeta(engramDir);
+        const meta = await this.readMeta(engramDir, { migrateLegacy: true });
         if (!meta)
             return null;
         const files = await this.readFiles(engramDir);
@@ -70,8 +68,7 @@ export class LocalEngramRepository {
     async save(engram) {
         const engramDir = join(this.basePath, engram.meta.id);
         await mkdir(engramDir, { recursive: true });
-        // メタデータ書き込み
-        await writeFile(join(engramDir, META_FILE), JSON.stringify(engram.meta, null, 2), "utf-8");
+        await this.writeMetaFiles(engramDir, engram.meta);
         // 必須ファイル書き込み
         for (const [key, filename] of Object.entries(FILE_MAP)) {
             const content = engram.files[key];
@@ -95,13 +92,50 @@ export class LocalEngramRepository {
         }
     }
     // --- private ---
-    async readMeta(engramDir) {
-        const metaPath = join(engramDir, META_FILE);
-        if (!existsSync(metaPath))
+    async readMeta(engramDir, options) {
+        const profilePath = join(engramDir, PROFILE_FILE);
+        if (!existsSync(profilePath))
             return null;
-        const raw = await readFile(metaPath, "utf-8");
-        const parsed = EngramMetaSchema.safeParse(JSON.parse(raw));
-        return parsed.success ? parsed.data : null;
+        const profileRaw = JSON.parse(await readFile(profilePath, "utf-8"));
+        const manifestPath = join(engramDir, MANIFEST_FILE);
+        if (existsSync(manifestPath)) {
+            const profile = EngramProfileSchema.safeParse(profileRaw);
+            if (!profile.success)
+                return null;
+            const manifest = EngramManifestSchema.safeParse(JSON.parse(await readFile(manifestPath, "utf-8")));
+            if (!manifest.success)
+                return null;
+            return {
+                ...profile.data,
+                ...manifest.data,
+            };
+        }
+        // 後方互換: 旧形式では engram.json に profile + manifest が同居していた
+        const legacy = EngramMetaSchema.safeParse(profileRaw);
+        if (!legacy.success)
+            return null;
+        if (options?.migrateLegacy) {
+            await this.writeMetaFiles(engramDir, legacy.data);
+        }
+        return legacy.data;
+    }
+    toProfile(meta) {
+        return {
+            name: meta.name,
+            description: meta.description,
+            tags: meta.tags,
+        };
+    }
+    toManifest(meta) {
+        return {
+            id: meta.id,
+            createdAt: meta.createdAt,
+            updatedAt: meta.updatedAt,
+        };
+    }
+    async writeMetaFiles(engramDir, meta) {
+        await writeFile(join(engramDir, PROFILE_FILE), JSON.stringify(this.toProfile(meta), null, 2), "utf-8");
+        await writeFile(join(engramDir, MANIFEST_FILE), JSON.stringify(this.toManifest(meta), null, 2), "utf-8");
     }
     async readFiles(engramDir) {
         const files = {};

package/dist/core/entities/engram.d.ts

@@ -37,31 +37,72 @@ export declare const EngramFileSchema: z.ZodObject<{
 }>;
 export type EngramFiles = z.infer<typeof EngramFileSchema>;
 /**
- * Engramメタデータ — Mikoshiでの管理情報
+ * Engramプロフィール — ユーザーが編集可能な表示用メタデータ
  */
-export declare const EngramMetaSchema: z.ZodObject<{
-    /** 一意識別子 (例: "ghost-in-the-shell") */
-    id: z.ZodString;
+export declare const EngramProfileSchema: z.ZodObject<{
     /** 表示名 (例: "攻殻機動隊の少佐") */
     name: z.ZodString;
     /** 説明 */
     description: z.ZodOptional<z.ZodString>;
+    /** タグ */
+    tags: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+}, "strip", z.ZodTypeAny, {
+    name: string;
+    description?: string | undefined;
+    tags?: string[] | undefined;
+}, {
+    name: string;
+    description?: string | undefined;
+    tags?: string[] | undefined;
+}>;
+export type EngramProfile = z.infer<typeof EngramProfileSchema>;
+/**
+ * Engramマニフェスト — システム管理の不変識別子と監査情報
+ */
+export declare const EngramManifestSchema: z.ZodObject<{
+    /** 一意識別子 (例: "ghost-in-the-shell") */
+    id: z.ZodString;
     /** 作成日時 */
     createdAt: z.ZodString;
     /** 最終更新日時 */
     updatedAt: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    createdAt: string;
+    updatedAt: string;
+}, {
+    id: string;
+    createdAt: string;
+    updatedAt: string;
+}>;
+export type EngramManifest = z.infer<typeof EngramManifestSchema>;
+/**
+ * Engramメタデータ — プロフィールとマニフェストを結合した利用時ビュー
+ */
+export declare const EngramMetaSchema: z.ZodObject<{
+    /** 表示名 (例: "攻殻機動隊の少佐") */
+    name: z.ZodString;
+    /** 説明 */
+    description: z.ZodOptional<z.ZodString>;
     /** タグ */
     tags: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+} & {
+    /** 一意識別子 (例: "ghost-in-the-shell") */
+    id: z.ZodString;
+    /** 作成日時 */
+    createdAt: z.ZodString;
+    /** 最終更新日時 */
+    updatedAt: z.ZodString;
 }, "strip", z.ZodTypeAny, {
-    id: string;
     name: string;
+    id: string;
     createdAt: string;
     updatedAt: string;
     description?: string | undefined;
     tags?: string[] | undefined;
 }, {
-    id: string;
     name: string;
+    id: string;
     createdAt: string;
     updatedAt: string;
     description?: string | undefined;
@@ -74,28 +115,29 @@ export type EngramMeta = z.infer<typeof EngramMetaSchema>;
  */
 export declare const EngramSchema: z.ZodObject<{
     meta: z.ZodObject<{
-        /** 一意識別子 (例: "ghost-in-the-shell") */
-        id: z.ZodString;
         /** 表示名 (例: "攻殻機動隊の少佐") */
         name: z.ZodString;
         /** 説明 */
         description: z.ZodOptional<z.ZodString>;
+        /** タグ */
+        tags: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    } & {
+        /** 一意識別子 (例: "ghost-in-the-shell") */
+        id: z.ZodString;
         /** 作成日時 */
         createdAt: z.ZodString;
         /** 最終更新日時 */
         updatedAt: z.ZodString;
-        /** タグ */
-        tags: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
     }, "strip", z.ZodTypeAny, {
-        id: string;
         name: string;
+        id: string;
         createdAt: string;
         updatedAt: string;
         description?: string | undefined;
         tags?: string[] | undefined;
     }, {
-        id: string;
         name: string;
+        id: string;
         createdAt: string;
         updatedAt: string;
         description?: string | undefined;
@@ -135,8 +177,8 @@ export declare const EngramSchema: z.ZodObject<{
     }>;
 }, "strip", z.ZodTypeAny, {
     meta: {
-        id: string;
         name: string;
+        id: string;
         createdAt: string;
         updatedAt: string;
         description?: string | undefined;
@@ -153,8 +195,8 @@ export declare const EngramSchema: z.ZodObject<{
     };
 }, {
     meta: {
-        id: string;
         name: string;
+        id: string;
         createdAt: string;
         updatedAt: string;
         description?: string | undefined;

package/dist/core/entities/engram.js

@@ -23,22 +23,31 @@ export const EngramFileSchema = z.object({
     memoryEntries: z.record(z.string(), z.string()).optional(),
 });
 /**
- * Engramメタデータ — Mikoshiでの管理情報
+ * Engramプロフィール — ユーザーが編集可能な表示用メタデータ
  */
-export const EngramMetaSchema = z.object({
-    /** 一意識別子 (例: "ghost-in-the-shell") */
-    id: z.string(),
+export const EngramProfileSchema = z.object({
     /** 表示名 (例: "攻殻機動隊の少佐") */
     name: z.string(),
     /** 説明 */
     description: z.string().optional(),
+    /** タグ */
+    tags: z.array(z.string()).optional(),
+});
+/**
+ * Engramマニフェスト — システム管理の不変識別子と監査情報
+ */
+export const EngramManifestSchema = z.object({
+    /** 一意識別子 (例: "ghost-in-the-shell") */
+    id: z.string(),
     /** 作成日時 */
     createdAt: z.string().datetime(),
     /** 最終更新日時 */
     updatedAt: z.string().datetime(),
-    /** タグ */
-    tags: z.array(z.string()).optional(),
 });
+/**
+ * Engramメタデータ — プロフィールとマニフェストを結合した利用時ビュー
+ */
+export const EngramMetaSchema = EngramProfileSchema.merge(EngramManifestSchema);
 /**
  * Engram — 完全な人格データセット
  * メタデータとファイル群の統合体

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

@@ -1 +1 @@
-export { EngramSchema, EngramFileSchema, EngramMetaSchema, ConstructStatusSchema, ShellTypeSchema, type Engram, type EngramFiles, type EngramMeta, type ConstructStatus, type ShellType, } from "./engram.js";
+export { EngramSchema, EngramFileSchema, EngramProfileSchema, EngramManifestSchema, EngramMetaSchema, ConstructStatusSchema, ShellTypeSchema, type Engram, type EngramFiles, type EngramProfile, type EngramManifest, type EngramMeta, type ConstructStatus, type ShellType, } from "./engram.js";

package/dist/core/entities/index.js

@@ -1 +1 @@
-export { EngramSchema, EngramFileSchema, EngramMetaSchema, ConstructStatusSchema, ShellTypeSchema, } from "./engram.js";
+export { EngramSchema, EngramFileSchema, EngramProfileSchema, EngramManifestSchema, EngramMetaSchema, ConstructStatusSchema, ShellTypeSchema, } from "./engram.js";

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 {