@ectplsm/relic 0.2.1 → 0.2.3

package/README.md

@@ -2,6 +2,7 @@
 |:---:|:---:|
 
 # PROJECT RELIC
+![NPM Downloads](https://img.shields.io/npm/dt/%40ectplsm%2Frelic)
 
 ```
     ____  ________    ____________
@@ -17,6 +18,7 @@ Relic manages AI **Engrams** (memory + personality) and injects them into coding
 
 ## Table of Contents
 
+- [Requirements](#requirements)
 - [Install](#install)
 - [Quick Start](#quick-start)
 - [What `relic init` Creates](#what-relic-init-creates)
@@ -29,9 +31,14 @@ Relic manages AI **Engrams** (memory + personality) and injects them into coding
 - [Memory Management](#memory-management)
 - [Configuration](#configuration)
 - [Creating Your Own Engram](#creating-your-own-engram)
+- [Deleting an Engram](#deleting-an-engram)
 - [Domain Glossary](#domain-glossary)
 - [Roadmap](#roadmap)
 
+## Requirements
+
+- Node.js 18 or later
+
 ## Install
 
 <img alt="version badge" src="https://img.shields.io/github/v/release/ectplsm/relic?filter=*.*.*">
@@ -98,12 +105,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/
@@ -112,7 +121,8 @@ 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.
 
@@ -123,11 +133,20 @@ As you keep using an Engram, more files are added to the same workspace:
 - `USER.md` is created or updated during memory distillation to record user preferences, tendencies, and work style.
 - `~/.relic/hooks/` and `~/.relic/gemini-system-default.md` are created later on first shell launch when hook registration or Gemini prompt caching is needed.
 
+### Migration
+
+If you want to manually update parts of an existing local setup that changed over time, use:
+
+```bash
+relic migrate engrams   # migrate legacy engram.json metadata to manifest.json
+relic refresh-samples   # refresh bundled sample personas like johnny and motoko
+```
+
 ## Sample Engrams
 
 `relic init` seeds two ready-to-use Engrams. Their SOUL.md and IDENTITY.md follow the [OpenClaw](https://github.com/openclaw/openclaw) format.
 
-> **Existing users:** The latest templates are always available in [`templates/engrams/`](templates/engrams/). Copy them over your `~/.relic/engrams/` files to update.
+> **Existing users:** Run `relic refresh-samples` to update bundled sample personas from the latest templates.
 
 ### Johnny Silverhand (`johnny`)
 
@@ -266,6 +285,7 @@ Session logs and memory entries are written automatically by a **background hook
 
 | Tool | Description |
 |------|-------------|
+| `relic_engram_create` | Create a new Engram with optional LLM-generated SOUL.md and IDENTITY.md |
 | `relic_archive_search` | Search the Engram's raw archive by keyword (newest-first) |
 | `relic_archive_pending` | Get un-distilled archive entries since the last distillation (up to 30) |
 | `relic_memory_write` | Write distilled memory to `memory/*.md`, optionally append to `MEMORY.md`, optionally update `USER.md`, and advance the archive cursor |
@@ -287,6 +307,7 @@ To suppress confirmation dialogs and auto-approve Relic tools across all project
   "permissions": {
     "allow": [
       "Edit(~/.relic/engrams/**)",
+      "mcp__relic__relic_engram_create",
       "mcp__relic__relic_archive_search",
       "mcp__relic__relic_archive_pending",
       "mcp__relic__relic_memory_write"
@@ -306,6 +327,9 @@ codex mcp add relic -- relic-mcp
 To suppress confirmation dialogs and auto-approve Relic tools, add the following to `~/.codex/config.toml`:
 
 ```toml
+[mcp_servers.relic.tools.relic_engram_create]
+approval_mode = "approve"
+
 [mcp_servers.relic.tools.relic_archive_search]
 approval_mode = "approve"
 
@@ -378,7 +402,7 @@ relic claw inject --engram motoko --yes
 Creates a new Engram from an existing Claw agent workspace.
 
 What `extract` writes locally:
-- New extract: `engram.json`, `SOUL.md`, `IDENTITY.md`, `USER.md`, `MEMORY.md`, `memory/*.md`
+- 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`
 
@@ -509,34 +533,29 @@ CLI flags always take precedence over config values.
 
 ## Creating Your Own Engram
 
-Create a directory under `~/.relic/engrams/` with the following structure:
+The easiest way to create a new Engram is with `relic create`:
 
-```
-~/.relic/engrams/your-persona/
-├── engram.json        # Metadata (id, name, description, tags)
-├── SOUL.md            # Core directive — how the persona thinks and acts
-├── IDENTITY.md        # Name, tone, background, personality
-├── AGENTS.md          # (optional) Tool usage policies
-├── USER.md            # (optional) User context
-├── MEMORY.md          # (optional) Memory index
-├── HEARTBEAT.md       # (optional) Periodic reflection
-└── memory/            # (optional) Dated memory entries
-    └── 2026-03-21.md
+```bash
+# Fully interactive — prompts for everything
+relic create
+
+# Pre-supply some fields
+relic create --id my-agent --name "My Agent" --description "A helpful assistant" --tags "custom,dev"
 ```
 
-**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"]
-}
+This creates the directory structure, writes `engram.json` / `manifest.json`, and seeds `SOUL.md` / `IDENTITY.md` with OpenClaw-compatible default templates. Customize the persona files, then launch a shell:
+
+```bash
+relic claude my-agent
 ```
 
-**SOUL.md** — The most important file. Defines how the persona behaves. Follows the [OpenClaw](https://github.com/openclaw/openclaw) format:
+You can also create Engrams via the `relic_engram_create` MCP tool — LLMs can ask about the desired personality and generate `SOUL.md` / `IDENTITY.md` content through conversation, then call the tool with the results.
+
+### Customizing the Persona
+
+After running `relic create`, edit `SOUL.md` and `IDENTITY.md` in the Engram directory. These follow the [OpenClaw](https://github.com/openclaw/openclaw) format:
+
+**SOUL.md** — The most important file. Defines how the persona behaves:
 ```markdown
 # SOUL.md - Who You Are
 
@@ -574,11 +593,14 @@ Each session, you wake up fresh. These files _are_ your memory. Read them. Updat
 
 See [`templates/engrams/`](templates/engrams/) for full working examples.
 
-After creating the directory, set it as your default Engram:
+## Deleting an Engram
+
 ```bash
-relic config default-engram your-persona
+relic delete my-agent
 ```
 
+If the Engram has memory data (`MEMORY.md`, `USER.md`, `memory/*.md`, `archive.md`), you'll need to type the Engram ID to confirm deletion. Use `--force` to skip all prompts.
+
 ## Domain Glossary
 
 | Term | Role | Description |
@@ -597,10 +619,11 @@ 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
+- [x] `relic create` — interactive Engram creation wizard + MCP tool
+- [x] `relic delete` — safe Engram deletion with memory-aware confirmation
 - [ ] Mikoshi cloud backend (`mikoshi.ectplsm.com`)
-- [ ] `relic create` — interactive Engram creation wizard
+- [ ] `relic mikoshi login` — authenticate with Mikoshi (OAuth Device Flow)
+- [ ] `relic mikoshi upload` / `relic mikoshi download` / `relic mikoshi sync` — sync Engrams with Mikoshi
 
 ## 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/create-engram.d.ts

@@ -0,0 +1,26 @@
+import type { Engram } from "../entities/engram.js";
+import type { EngramRepository } from "../ports/engram-repository.js";
+export declare class EngramAlreadyExistsError extends Error {
+    constructor(id: string);
+}
+export declare class InvalidEngramIdError extends Error {
+    constructor(id: string);
+}
+export interface CreateEngramParams {
+    id: string;
+    name: string;
+    description?: string;
+    tags?: string[];
+    soul: string;
+    identity: string;
+}
+export interface CreateEngramResult {
+    engram: Engram;
+}
+/** ID format: lowercase alphanumeric + hyphens, no leading/trailing hyphen */
+export declare const ENGRAM_ID_PATTERN: RegExp;
+export declare class CreateEngram {
+    private readonly repository;
+    constructor(repository: EngramRepository);
+    execute(params: CreateEngramParams): Promise<CreateEngramResult>;
+}

package/dist/core/usecases/create-engram.js

@@ -0,0 +1,54 @@
+// ============================================================
+// Errors
+// ============================================================
+export class EngramAlreadyExistsError extends Error {
+    constructor(id) {
+        super(`Engram "${id}" already exists. Delete it first or choose a different ID.`);
+        this.name = "EngramAlreadyExistsError";
+    }
+}
+export class InvalidEngramIdError extends Error {
+    constructor(id) {
+        super(`Invalid Engram ID "${id}". Use lowercase letters, numbers, and hyphens only (e.g. "my-agent").`);
+        this.name = "InvalidEngramIdError";
+    }
+}
+// ============================================================
+// Usecase
+// ============================================================
+/** ID format: lowercase alphanumeric + hyphens, no leading/trailing hyphen */
+export const ENGRAM_ID_PATTERN = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+export class CreateEngram {
+    repository;
+    constructor(repository) {
+        this.repository = repository;
+    }
+    async execute(params) {
+        // Validate ID format
+        if (!ENGRAM_ID_PATTERN.test(params.id)) {
+            throw new InvalidEngramIdError(params.id);
+        }
+        // Check for duplicates
+        const existing = await this.repository.get(params.id);
+        if (existing) {
+            throw new EngramAlreadyExistsError(params.id);
+        }
+        const now = new Date().toISOString();
+        const engram = {
+            meta: {
+                id: params.id,
+                name: params.name,
+                description: params.description,
+                tags: params.tags,
+                createdAt: now,
+                updatedAt: now,
+            },
+            files: {
+                soul: params.soul,
+                identity: params.identity,
+            },
+        };
+        await this.repository.save(engram);
+        return { engram };
+    }
+}

package/dist/core/usecases/delete-engram.d.ts

@@ -0,0 +1,24 @@
+import type { Engram } from "../entities/engram.js";
+import type { EngramRepository } from "../ports/engram-repository.js";
+export declare class DeleteEngramNotFoundError extends Error {
+    constructor(id: string);
+}
+export interface DeleteEngramInfo {
+    engram: Engram;
+    hasMemory: boolean;
+    hasUser: boolean;
+    hasArchive: boolean;
+    memoryEntryCount: number;
+}
+export declare class DeleteEngram {
+    private readonly repository;
+    constructor(repository: EngramRepository);
+    /**
+     * Inspect an Engram before deletion — returns info for confirmation UI.
+     */
+    inspect(id: string): Promise<DeleteEngramInfo>;
+    /**
+     * Actually delete the Engram. Call inspect() first for confirmation.
+     */
+    execute(id: string): Promise<void>;
+}

package/dist/core/usecases/delete-engram.js

@@ -0,0 +1,46 @@
+// ============================================================
+// Errors
+// ============================================================
+export class DeleteEngramNotFoundError extends Error {
+    constructor(id) {
+        super(`Engram "${id}" not found.`);
+        this.name = "DeleteEngramNotFoundError";
+    }
+}
+// ============================================================
+// Usecase
+// ============================================================
+export class DeleteEngram {
+    repository;
+    constructor(repository) {
+        this.repository = repository;
+    }
+    /**
+     * Inspect an Engram before deletion — returns info for confirmation UI.
+     */
+    async inspect(id) {
+        const engram = await this.repository.get(id);
+        if (!engram) {
+            throw new DeleteEngramNotFoundError(id);
+        }
+        return {
+            engram,
+            hasMemory: !!engram.files.memory,
+            hasUser: !!engram.files.user,
+            hasArchive: false, // archive.md is not loaded via EngramFiles; CLI checks separately
+            memoryEntryCount: engram.files.memoryEntries
+                ? Object.keys(engram.files.memoryEntries).length
+                : 0,
+        };
+    }
+    /**
+     * Actually delete the Engram. Call inspect() first for confirmation.
+     */
+    async execute(id) {
+        const existing = await this.repository.get(id);
+        if (!existing) {
+            throw new DeleteEngramNotFoundError(id);
+        }
+        await this.repository.delete(id);
+    }
+}