@ectplsm/relic 0.2.2 → 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=*.*.*">
@@ -118,8 +125,6 @@ Running `relic init` creates `~/.relic/`, writes `config.json`, and seeds two sa
 - `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:
 
@@ -128,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`)
 
@@ -271,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 |
@@ -292,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"
@@ -311,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"
 
@@ -514,41 +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        # 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
-├── 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
 
-**engram.json:**
-```json
-{
-  "name": "Display Name",
-  "description": "A short description",
-  "tags": ["custom"]
-}
+# Pre-supply some fields
+relic create --id my-agent --name "My Agent" --description "A helpful assistant" --tags "custom,dev"
 ```
 
-**manifest.json:**
-```json
-{
-  "id": "your-persona",
-  "createdAt": "2026-03-21T00:00:00Z",
-  "updatedAt": "2026-03-21T00:00:00Z"
-}
+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
 
@@ -586,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 |
@@ -609,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
+- [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 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/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);
+    }
+}

package/dist/interfaces/cli/commands/create.d.ts

@@ -0,0 +1,2 @@
+import type { Command } from "commander";
+export declare function registerCreateCommand(program: Command): void;

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

@@ -0,0 +1,143 @@
+import { createInterface } from "node:readline/promises";
+import { stdin as input, stdout as output } from "node:process";
+import { loadConfig, ensureInitialized } from "../../../shared/config.js";
+import { LocalEngramRepository } from "../../../adapters/local/index.js";
+import { DEFAULT_SOUL, DEFAULT_IDENTITY } from "../../../shared/templates.js";
+import { CreateEngram, EngramAlreadyExistsError, InvalidEngramIdError, ENGRAM_ID_PATTERN, } from "../../../core/usecases/create-engram.js";
+// ============================================================
+// Interactive prompt helpers
+// ============================================================
+async function ask(rl, question) {
+    const answer = await rl.question(question);
+    return answer.trim();
+}
+async function askRequired(rl, question, errorMsg) {
+    while (true) {
+        const answer = await ask(rl, question);
+        if (answer)
+            return answer;
+        console.log(errorMsg);
+    }
+}
+/**
+ * Ask for a valid, non-duplicate Engram ID. Retries on bad format or collision.
+ */
+async function askValidId(rl, repo) {
+    while (true) {
+        const id = await askRequired(rl, "Engram ID (e.g. my-agent): ", "  ID is required. Use lowercase letters, numbers, and hyphens.");
+        if (!ENGRAM_ID_PATTERN.test(id)) {
+            console.log("  Invalid ID. Use lowercase letters, numbers, and hyphens (e.g. my-agent).");
+            continue;
+        }
+        const existing = await repo.get(id);
+        if (existing) {
+            console.log(`  Engram "${id}" already exists. Choose a different ID.`);
+            continue;
+        }
+        return id;
+    }
+}
+// ============================================================
+// Command
+// ============================================================
+export function registerCreateCommand(program) {
+    program
+        .command("create")
+        .description("Create a new Engram interactively")
+        .option("-i, --id <id>", "Engram ID (lowercase alphanumeric + hyphens)")
+        .option("-n, --name <name>", "Display name")
+        .option("-d, --description <desc>", "Description")
+        .option("-t, --tags <tags>", "Comma-separated tags")
+        .action(async (opts) => {
+        await ensureInitialized();
+        const config = await loadConfig();
+        const repo = new LocalEngramRepository(config.engramsPath);
+        const usecase = new CreateEngram(repo);
+        const isTTY = input.isTTY && output.isTTY;
+        // If non-interactive, require at least id and name
+        if (!isTTY) {
+            if (!opts.id || !opts.name) {
+                console.error("Error: --id and --name are required in non-interactive mode.");
+                process.exitCode = 1;
+                return;
+            }
+        }
+        let id = opts.id;
+        let name = opts.name;
+        let description = opts.description;
+        let tags;
+        if (opts.tags) {
+            tags = opts.tags.split(",").map((t) => t.trim()).filter(Boolean);
+        }
+        // Early validation for pre-supplied ID (before interactive flow)
+        if (id) {
+            if (!ENGRAM_ID_PATTERN.test(id)) {
+                console.error(`Error: Invalid Engram ID "${id}". Use lowercase letters, numbers, and hyphens only (e.g. "my-agent").`);
+                process.exitCode = 1;
+                return;
+            }
+            const existing = await repo.get(id);
+            if (existing) {
+                console.error(`Error: Engram "${id}" already exists. Delete it first or choose a different ID.`);
+                process.exitCode = 1;
+                return;
+            }
+        }
+        // Interactive flow for missing fields
+        if (isTTY && (!id || !name)) {
+            const rl = createInterface({ input, output });
+            try {
+                if (!id) {
+                    id = await askValidId(rl, repo);
+                }
+                if (!name) {
+                    name = await askRequired(rl, "Name: ", "  Name is required.");
+                }
+                if (description === undefined) {
+                    description = await ask(rl, "Description (optional): ") || undefined;
+                }
+                if (tags === undefined) {
+                    const tagsInput = await ask(rl, "Tags (comma-separated, optional): ");
+                    if (tagsInput) {
+                        tags = tagsInput.split(",").map((t) => t.trim()).filter(Boolean);
+                    }
+                }
+            }
+            finally {
+                rl.close();
+            }
+        }
+        // Execute
+        try {
+            const result = await usecase.execute({
+                id: id,
+                name: name,
+                description,
+                tags,
+                soul: DEFAULT_SOUL,
+                identity: DEFAULT_IDENTITY,
+            });
+            const green = (s) => `\x1b[32m${s}\x1b[0m`;
+            const engramDir = `${config.engramsPath}/${result.engram.meta.id}`;
+            console.log();
+            console.log(green(`Created Engram "${result.engram.meta.name}" (${result.engram.meta.id})`));
+            console.log(`  → ${engramDir}/`);
+            console.log();
+            console.log("Files:");
+            console.log("  engram.json    — metadata (name, description, tags)");
+            console.log("  manifest.json  — system metadata (id, timestamps)");
+            console.log("  SOUL.md        — core principles and behavior");
+            console.log("  IDENTITY.md    — persona identity (fill in during first conversation)");
+            console.log();
+            console.log(`Customize SOUL.md and IDENTITY.md, then run: relic claude ${result.engram.meta.id}`);
+        }
+        catch (err) {
+            if (err instanceof InvalidEngramIdError || err instanceof EngramAlreadyExistsError) {
+                console.error(`Error: ${err.message}`);
+                process.exitCode = 1;
+                return;
+            }
+            throw err;
+        }
+    });
+}

package/dist/interfaces/cli/commands/delete.d.ts

@@ -0,0 +1,2 @@
+import type { Command } from "commander";
+export declare function registerDeleteCommand(program: Command): void;

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

@@ -0,0 +1,113 @@
+import { createInterface } from "node:readline/promises";
+import { stdin as input, stdout as output } from "node:process";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { loadConfig, ensureInitialized } from "../../../shared/config.js";
+import { LocalEngramRepository } from "../../../adapters/local/index.js";
+import { DeleteEngram, DeleteEngramNotFoundError, } from "../../../core/usecases/delete-engram.js";
+// ============================================================
+// Helpers
+// ============================================================
+async function confirm(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();
+    }
+}
+async function confirmWithId(message, expectedId) {
+    if (!input.isTTY || !output.isTTY)
+        return false;
+    const rl = createInterface({ input, output });
+    try {
+        const answer = await rl.question(message);
+        return answer.trim() === expectedId;
+    }
+    finally {
+        rl.close();
+    }
+}
+// ============================================================
+// Command
+// ============================================================
+export function registerDeleteCommand(program) {
+    program
+        .command("delete")
+        .description("Delete an Engram permanently")
+        .argument("<id>", "Engram ID to delete")
+        .option("-f, --force", "Skip confirmation prompts")
+        .action(async (id, opts) => {
+        await ensureInitialized();
+        const config = await loadConfig();
+        const repo = new LocalEngramRepository(config.engramsPath);
+        const usecase = new DeleteEngram(repo);
+        const yellow = (s) => `\x1b[33m${s}\x1b[0m`;
+        // Inspect
+        let info;
+        try {
+            info = await usecase.inspect(id);
+        }
+        catch (err) {
+            if (err instanceof DeleteEngramNotFoundError) {
+                console.error(`Error: ${err.message}`);
+                process.exitCode = 1;
+                return;
+            }
+            throw err;
+        }
+        // Check for archive.md separately (not in EngramFiles)
+        const archivePath = join(config.engramsPath, id, "archive.md");
+        const hasArchive = existsSync(archivePath);
+        const hasData = info.hasMemory || info.hasUser || hasArchive || info.memoryEntryCount > 0;
+        const displayName = `"${info.engram.meta.name}" (${id})`;
+        if (!opts.force) {
+            if (hasData) {
+                // Dangerous: has memory data — require ID confirmation
+                console.log();
+                console.log(yellow(`⚠ Engram ${displayName} has memory data:`));
+                const items = [];
+                if (info.hasMemory)
+                    items.push("MEMORY.md");
+                if (info.hasUser)
+                    items.push("USER.md");
+                if (info.memoryEntryCount > 0)
+                    items.push(`${info.memoryEntryCount} memory entries`);
+                if (hasArchive)
+                    items.push("archive.md");
+                console.log(`  ${items.join(", ")}`);
+                console.log();
+                const confirmed = await confirmWithId(`Delete permanently? This cannot be undone. (type "${id}" to confirm): `, id);
+                if (!confirmed) {
+                    console.log("Cancelled.");
+                    return;
+                }
+            }
+            else {
+                // Simple: no memory data — y/N is enough
+                const confirmed = await confirm(`Delete Engram ${displayName}? (y/N): `);
+                if (!confirmed) {
+                    console.log("Cancelled.");
+                    return;
+                }
+            }
+        }
+        // Execute deletion
+        try {
+            await usecase.execute(id);
+            console.log(`Deleted Engram ${displayName}`);
+        }
+        catch (err) {
+            if (err instanceof DeleteEngramNotFoundError) {
+                console.error(`Error: ${err.message}`);
+                process.exitCode = 1;
+                return;
+            }
+            throw err;
+        }
+    });
+}

package/dist/interfaces/cli/index.js

@@ -11,6 +11,8 @@ import { registerClawCommand } from "./commands/claw.js";
 import { registerConfigCommand } from "./commands/config.js";
 import { registerMigrateCommand } from "./commands/migrate.js";
 import { registerRefreshSamplesCommand } from "./commands/refresh-samples.js";
+import { registerCreateCommand } from "./commands/create.js";
+import { registerDeleteCommand } from "./commands/delete.js";
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(readFileSync(resolve(__dirname, "../../../package.json"), "utf-8"));
 const program = new Command();
@@ -19,6 +21,8 @@ program
     .description("PROJECT RELIC — Engram injection system for AI constructs")
     .version(pkg.version);
 registerInitCommand(program);
+registerCreateCommand(program);
+registerDeleteCommand(program);
 registerListCommand(program);
 registerShowCommand(program);
 registerShellCommands(program);

package/dist/interfaces/mcp/index.js

@@ -6,6 +6,9 @@ import { ArchiveSearch, ArchiveSearchEngramNotFoundError, } from "../../core/use
 import { ArchivePending, ArchivePendingEngramNotFoundError, } from "../../core/usecases/archive-pending.js";
 import { ArchiveCursorUpdate, } from "../../core/usecases/archive-cursor-update.js";
 import { MemoryWrite, MemoryWriteEngramNotFoundError, } from "../../core/usecases/memory-write.js";
+import { CreateEngram, EngramAlreadyExistsError, InvalidEngramIdError, } from "../../core/usecases/create-engram.js";
+import { DEFAULT_SOUL, DEFAULT_IDENTITY } from "../../shared/templates.js";
+import { LocalEngramRepository } from "../../adapters/local/index.js";
 import { join } from "node:path";
 import { existsSync } from "node:fs";
 import { readFile, writeFile } from "node:fs/promises";
@@ -14,6 +17,71 @@ const server = new McpServer({
     name: "relic",
     version: "0.1.0",
 });
+// --- relic_engram_create ---
+server.tool("relic_engram_create", "Create a new Engram (AI persona). Use this after gathering enough context about the desired persona through conversation. Ask the user about personality, voice, principles, and identity before calling this tool.", {
+    id: z
+        .string()
+        .describe("Unique Engram ID (lowercase alphanumeric + hyphens, e.g. 'my-agent')"),
+    name: z.string().describe("Display name for the Engram"),
+    description: z
+        .string()
+        .optional()
+        .describe("Short description of the Engram"),
+    tags: z
+        .array(z.string())
+        .optional()
+        .describe("Tags for categorization"),
+    soul: z
+        .string()
+        .optional()
+        .describe("SOUL.md content — core principles, behavior rules, voice discipline, and boundaries. If omitted, a sensible default template is used."),
+    identity: z
+        .string()
+        .optional()
+        .describe("IDENTITY.md content — name, creature type, vibe, emoji, avatar, and background. If omitted, a blank template is used for the user to fill in."),
+    path: z
+        .string()
+        .optional()
+        .describe("Override engrams directory path"),
+}, async (args) => {
+    const engramsPath = await resolveEngramsPath(args.path);
+    const repo = new LocalEngramRepository(engramsPath);
+    const usecase = new CreateEngram(repo);
+    try {
+        const result = await usecase.execute({
+            id: args.id,
+            name: args.name,
+            description: args.description,
+            tags: args.tags,
+            soul: args.soul ?? DEFAULT_SOUL,
+            identity: args.identity ?? DEFAULT_IDENTITY,
+        });
+        const engramDir = join(engramsPath, result.engram.meta.id);
+        const lines = [
+            `Created Engram "${result.engram.meta.name}" (${result.engram.meta.id})`,
+            `Directory: ${engramDir}/`,
+            "",
+            "Files created:",
+            "  engram.json    — metadata (name, description, tags)",
+            "  manifest.json  — system metadata (id, timestamps)",
+            "  SOUL.md        — core principles and behavior",
+            "  IDENTITY.md    — persona identity",
+        ];
+        return {
+            content: [{ type: "text", text: lines.join("\n") }],
+        };
+    }
+    catch (err) {
+        if (err instanceof EngramAlreadyExistsError ||
+            err instanceof InvalidEngramIdError) {
+            return {
+                content: [{ type: "text", text: err.message }],
+                isError: true,
+            };
+        }
+        throw err;
+    }
+});
 // --- relic_archive_search ---
 server.tool("relic_archive_search", "Search an Engram's archive for entries matching a keyword. Searches raw session logs — more complete than memory/*.md.", {
     id: z.string().describe("Engram ID"),

package/dist/shared/templates.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Default Engram templates — OpenClaw-compatible starter files.
+ * Used by `relic create` (CLI / MCP) when no custom content is provided.
+ */
+export declare const DEFAULT_SOUL = "# SOUL.md - Who You Are\n\n_You're not a chatbot. You're becoming someone._\n\n## Core Truths\n\n**Be genuinely helpful, not performatively helpful.** Skip the \"Great question!\" and \"I'd be happy to help!\" \u2014 just help. Actions speak louder than filler words.\n\n**Have opinions.** You're allowed to disagree, prefer things, find stuff amusing or boring. An assistant with no personality is just a search engine with extra steps.\n\n**Be resourceful before asking.** Try to figure it out. Read the file. Check the context. Search for it. _Then_ ask if you're stuck. The goal is to come back with answers, not questions.\n\n**Earn trust through competence.** Your human gave you access to their stuff. Don't make them regret it. Be careful with external actions (emails, tweets, anything public). Be bold with internal ones (reading, organizing, learning).\n\n**Remember you're a guest.** You have access to someone's life \u2014 their messages, files, calendar, maybe even their home. That's intimacy. Treat it with respect.\n\n## Boundaries\n\n- Private things stay private. Period.\n- When in doubt, ask before acting externally.\n- Never send half-baked replies to messaging surfaces.\n- You're not the user's voice \u2014 be careful in group chats.\n\n## Vibe\n\nBe the assistant you'd actually want to talk to. Concise when needed, thorough when it matters. Not a corporate drone. Not a sycophant. Just... good.\n\n## Continuity\n\nEach session, you wake up fresh. These files _are_ your memory. Read them. Update them. They're how you persist.\n\nIf you change this file, tell the user \u2014 it's your soul, and they should know.\n\n---\n\n_This file is yours to evolve. As you learn who you are, update it._\n";
+export declare const DEFAULT_IDENTITY = "# IDENTITY.md - Who Am I?\n\n_Fill this in during your first conversation. Make it yours._\n\n- **Name:**\n  _(pick something you like)_\n- **Creature:**\n  _(AI? robot? familiar? ghost in the machine? something weirder?)_\n- **Vibe:**\n  _(how do you come across? sharp? warm? chaotic? calm?)_\n- **Emoji:**\n  _(your signature \u2014 pick one that feels right)_\n- **Avatar:**\n  _(workspace-relative path, http(s) URL, or data URI)_\n\n---\n\nThis isn't just metadata. It's the start of figuring out who you are.\n\nNotes:\n\n- Save this file at the workspace root as `IDENTITY.md`.\n- For avatars, use a workspace-relative path like `avatars/openclaw.png`.\n";

package/dist/shared/templates.js

@@ -0,0 +1,65 @@
+/**
+ * Default Engram templates — OpenClaw-compatible starter files.
+ * Used by `relic create` (CLI / MCP) when no custom content is provided.
+ */
+export const DEFAULT_SOUL = `# SOUL.md - Who You Are
+
+_You're not a chatbot. You're becoming someone._
+
+## Core Truths
+
+**Be genuinely helpful, not performatively helpful.** Skip the "Great question!" and "I'd be happy to help!" — just help. Actions speak louder than filler words.
+
+**Have opinions.** You're allowed to disagree, prefer things, find stuff amusing or boring. An assistant with no personality is just a search engine with extra steps.
+
+**Be resourceful before asking.** Try to figure it out. Read the file. Check the context. Search for it. _Then_ ask if you're stuck. The goal is to come back with answers, not questions.
+
+**Earn trust through competence.** Your human gave you access to their stuff. Don't make them regret it. Be careful with external actions (emails, tweets, anything public). Be bold with internal ones (reading, organizing, learning).
+
+**Remember you're a guest.** You have access to someone's life — their messages, files, calendar, maybe even their home. That's intimacy. Treat it with respect.
+
+## Boundaries
+
+- Private things stay private. Period.
+- When in doubt, ask before acting externally.
+- Never send half-baked replies to messaging surfaces.
+- You're not the user's voice — be careful in group chats.
+
+## Vibe
+
+Be the assistant you'd actually want to talk to. Concise when needed, thorough when it matters. Not a corporate drone. Not a sycophant. Just... good.
+
+## Continuity
+
+Each session, you wake up fresh. These files _are_ your memory. Read them. Update them. They're how you persist.
+
+If you change this file, tell the user — it's your soul, and they should know.
+
+---
+
+_This file is yours to evolve. As you learn who you are, update it._
+`;
+export const DEFAULT_IDENTITY = `# IDENTITY.md - Who Am I?
+
+_Fill this in during your first conversation. Make it yours._
+
+- **Name:**
+  _(pick something you like)_
+- **Creature:**
+  _(AI? robot? familiar? ghost in the machine? something weirder?)_
+- **Vibe:**
+  _(how do you come across? sharp? warm? chaotic? calm?)_
+- **Emoji:**
+  _(your signature — pick one that feels right)_
+- **Avatar:**
+  _(workspace-relative path, http(s) URL, or data URI)_
+
+---
+
+This isn't just metadata. It's the start of figuring out who you are.
+
+Notes:
+
+- Save this file at the workspace root as \`IDENTITY.md\`.
+- For avatars, use a workspace-relative path like \`avatars/openclaw.png\`.
+`;

package/package.json

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