@ectplsm/relic 0.1.0

package/dist/core/usecases/extract.js

@@ -0,0 +1,190 @@
+import { join } from "node:path";
+import { existsSync } from "node:fs";
+import { readFile, readdir } from "node:fs/promises";
+import { FILE_MAP, MEMORY_DIR, resolveAgentPath } from "../../shared/openclaw.js";
+/**
+ * Extract — OpenClawワークスペースからEngramを作成する
+ *
+ * agent名 = Engram ID の規約に基づき、agents/<engramId>/agent/ から読み取る。
+ *
+ * 既存Engramがある場合:
+ *   - --force なし → memoryエントリのみマージ（persona部分は変更しない）
+ *   - --force あり → persona部分を上書き + memoryをマージ
+ * 既存Engramがない場合:
+ *   - 新規作成（全ファイル含む）
+ */
+export class Extract {
+    repository;
+    constructor(repository) {
+        this.repository = repository;
+    }
+    async execute(engramId, options) {
+        const sourcePath = resolveAgentPath(engramId, options?.openclawDir);
+        if (!existsSync(sourcePath)) {
+            throw new WorkspaceNotFoundError(sourcePath);
+        }
+        const { files, filesRead } = await this.readFiles(sourcePath);
+        if (filesRead.length === 0) {
+            throw new WorkspaceEmptyError(sourcePath);
+        }
+        const existing = await this.repository.get(engramId);
+        if (existing) {
+            if (options?.force) {
+                // --force: persona上書き + memoryマージ
+                const merged = await this.mergeAndSave(existing, files, options.name ?? existing.meta.name);
+                return {
+                    engramId,
+                    engramName: options.name ?? existing.meta.name,
+                    sourcePath,
+                    filesRead,
+                    memoryMerged: merged,
+                };
+            }
+            // --forceなし: memoryのみマージ
+            if (!files.memoryEntries || Object.keys(files.memoryEntries).length === 0) {
+                throw new EngramAlreadyExistsError(engramId);
+            }
+            const merged = await this.mergeMemoryOnly(engramId, files.memoryEntries);
+            return {
+                engramId,
+                engramName: existing.meta.name,
+                sourcePath,
+                filesRead,
+                memoryMerged: merged,
+            };
+        }
+        // 新規作成 — nameは必須
+        const engramName = options?.name;
+        if (!engramName) {
+            throw new ExtractNameRequiredError(engramId);
+        }
+        const now = new Date().toISOString();
+        const engram = {
+            meta: {
+                id: engramId,
+                name: engramName,
+                description: `Extracted from OpenClaw agent (${engramId})`,
+                createdAt: now,
+                updatedAt: now,
+                tags: ["extracted", "openclaw"],
+            },
+            files,
+        };
+        await this.repository.save(engram);
+        return {
+            engramId,
+            engramName,
+            sourcePath,
+            filesRead,
+            memoryMerged: false,
+        };
+    }
+    /**
+     * --force時: persona上書き + memoryマージ
+     */
+    async mergeAndSave(existing, newFiles, engramName) {
+        const mergedFiles = { ...newFiles };
+        // memoryEntriesをマージ
+        let memoryMerged = false;
+        if (newFiles.memoryEntries) {
+            mergedFiles.memoryEntries = { ...existing.files.memoryEntries };
+            for (const [date, content] of Object.entries(newFiles.memoryEntries)) {
+                const existingContent = mergedFiles.memoryEntries?.[date];
+                if (existingContent) {
+                    const separator = existingContent.endsWith("\n") ? "\n" : "\n\n";
+                    mergedFiles.memoryEntries[date] = existingContent + separator + content;
+                }
+                else {
+                    mergedFiles.memoryEntries = mergedFiles.memoryEntries ?? {};
+                    mergedFiles.memoryEntries[date] = content;
+                }
+                memoryMerged = true;
+            }
+        }
+        const updatedEngram = {
+            meta: {
+                ...existing.meta,
+                name: engramName,
+                updatedAt: new Date().toISOString(),
+            },
+            files: mergedFiles,
+        };
+        await this.repository.save(updatedEngram);
+        return memoryMerged;
+    }
+    /**
+     * --forceなし時: memoryエントリのみ追記（repositoryのAPIを使用）
+     */
+    async mergeMemoryOnly(engramId, newEntries) {
+        const existing = await this.repository.get(engramId);
+        if (!existing)
+            return false;
+        const mergedEntries = { ...existing.files.memoryEntries };
+        for (const [date, content] of Object.entries(newEntries)) {
+            const existingContent = mergedEntries[date];
+            if (existingContent) {
+                const separator = existingContent.endsWith("\n") ? "\n" : "\n\n";
+                mergedEntries[date] = existingContent + separator + content;
+            }
+            else {
+                mergedEntries[date] = content;
+            }
+        }
+        const updatedEngram = {
+            ...existing,
+            meta: { ...existing.meta, updatedAt: new Date().toISOString() },
+            files: { ...existing.files, memoryEntries: mergedEntries },
+        };
+        await this.repository.save(updatedEngram);
+        return true;
+    }
+    async readFiles(sourcePath) {
+        const files = {};
+        const filesRead = [];
+        for (const [key, filename] of Object.entries(FILE_MAP)) {
+            const filePath = join(sourcePath, filename);
+            if (existsSync(filePath)) {
+                files[key] = await readFile(filePath, "utf-8");
+                filesRead.push(filename);
+            }
+        }
+        const memoryDir = join(sourcePath, MEMORY_DIR);
+        if (existsSync(memoryDir)) {
+            const entries = await readdir(memoryDir);
+            const mdFiles = entries.filter((f) => f.endsWith(".md")).sort();
+            if (mdFiles.length > 0) {
+                files.memoryEntries = {};
+                for (const mdFile of mdFiles) {
+                    const date = mdFile.replace(/\.md$/, "");
+                    files.memoryEntries[date] = await readFile(join(memoryDir, mdFile), "utf-8");
+                    filesRead.push(`${MEMORY_DIR}/${mdFile}`);
+                }
+            }
+        }
+        return { files: files, filesRead };
+    }
+}
+export class WorkspaceNotFoundError extends Error {
+    constructor(path) {
+        super(`OpenClaw workspace not found at ${path}`);
+        this.name = "WorkspaceNotFoundError";
+    }
+}
+export class WorkspaceEmptyError extends Error {
+    constructor(path) {
+        super(`No workspace files found at ${path}`);
+        this.name = "WorkspaceEmptyError";
+    }
+}
+export class EngramAlreadyExistsError extends Error {
+    constructor(id) {
+        super(`Engram "${id}" already exists. Use --force to overwrite.`);
+        this.name = "EngramAlreadyExistsError";
+    }
+}
+export class ExtractNameRequiredError extends Error {
+    constructor(id) {
+        super(`No existing Engram "${id}" found. --name is required for new Engrams.`);
+        this.name = "ExtractNameRequiredError";
+    }
+}

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

@@ -0,0 +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, InjectAgentNotFoundError, type InjectResult, } from "./inject.js";
+export { Extract, WorkspaceNotFoundError, WorkspaceEmptyError, EngramAlreadyExistsError, ExtractNameRequiredError, type ExtractResult, } from "./extract.js";
+export { MemorySearch, MemoryEngramNotFoundError, type MemorySearchResult, } from "./memory-search.js";
+export { MemoryWrite, MemoryWriteEngramNotFoundError, type MemoryWriteResult, } from "./memory-write.js";
+export { Sync, SyncAgentsDirNotFoundError, type SyncTarget, type SyncInitialResult, } from "./sync.js";

package/dist/core/usecases/index.js

@@ -0,0 +1,8 @@
+export { Summon, EngramNotFoundError } from "./summon.js";
+export { ListEngrams } from "./list-engrams.js";
+export { Init } from "./init.js";
+export { Inject, InjectEngramNotFoundError, InjectAgentNotFoundError, } from "./inject.js";
+export { Extract, WorkspaceNotFoundError, WorkspaceEmptyError, EngramAlreadyExistsError, ExtractNameRequiredError, } from "./extract.js";
+export { MemorySearch, MemoryEngramNotFoundError, } from "./memory-search.js";
+export { MemoryWrite, MemoryWriteEngramNotFoundError, } from "./memory-write.js";
+export { Sync, SyncAgentsDirNotFoundError, } from "./sync.js";

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

@@ -0,0 +1,19 @@
+export interface InitResult {
+    /** 新規作成されたか、既に存在していたか */
+    created: boolean;
+    /** ~/.relic ディレクトリパス */
+    relicDir: string;
+    /** config.json パス */
+    configPath: string;
+    /** engrams ディレクトリパス */
+    engramsPath: string;
+}
+/**
+ * Init — ~/.relic/ を初期化する
+ *
+ * `relic init` で明示的に呼ばれるほか、
+ * 他のコマンド実行時にも resolveEngramsPath() 経由で自動的に呼ばれる。
+ */
+export declare class Init {
+    execute(): Promise<InitResult>;
+}

package/dist/core/usecases/init.js

@@ -0,0 +1,19 @@
+import { ensureInitialized, loadConfig, RELIC_DIR, CONFIG_PATH } from "../../shared/config.js";
+/**
+ * Init — ~/.relic/ を初期化する
+ *
+ * `relic init` で明示的に呼ばれるほか、
+ * 他のコマンド実行時にも resolveEngramsPath() 経由で自動的に呼ばれる。
+ */
+export class Init {
+    async execute() {
+        const { created } = await ensureInitialized();
+        const config = await loadConfig();
+        return {
+            created,
+            relicDir: RELIC_DIR,
+            configPath: CONFIG_PATH,
+            engramsPath: config.engramsPath,
+        };
+    }
+}

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

@@ -0,0 +1,28 @@
+import type { EngramRepository } from "../ports/engram-repository.js";
+export interface InjectResult {
+    engramId: string;
+    engramName: string;
+    targetPath: string;
+    filesWritten: string[];
+}
+/**
+ * Inject — EngramのファイルをOpenClawワークスペースに注入する
+ *
+ * agent名 = Engram ID の規約に基づき、agents/<engramId>/agent/ に書き込む。
+ * memoryEntries はOpenClaw側の管理に委ねるため注入しない。
+ */
+export declare class Inject {
+    private readonly repository;
+    constructor(repository: EngramRepository);
+    execute(engramId: string, options?: {
+        to?: string;
+        openclawDir?: string;
+    }): Promise<InjectResult>;
+    private writeFiles;
+}
+export declare class InjectEngramNotFoundError extends Error {
+    constructor(id: string);
+}
+export declare class InjectAgentNotFoundError extends Error {
+    constructor(engramId: string, path: string);
+}

package/dist/core/usecases/inject.js

@@ -0,0 +1,57 @@
+import { join } from "node:path";
+import { existsSync } from "node:fs";
+import { writeFile } from "node:fs/promises";
+import { FILE_MAP, resolveAgentPath } from "../../shared/openclaw.js";
+/**
+ * Inject — EngramのファイルをOpenClawワークスペースに注入する
+ *
+ * agent名 = Engram ID の規約に基づき、agents/<engramId>/agent/ に書き込む。
+ * memoryEntries はOpenClaw側の管理に委ねるため注入しない。
+ */
+export class Inject {
+    repository;
+    constructor(repository) {
+        this.repository = repository;
+    }
+    async execute(engramId, options) {
+        const engram = await this.repository.get(engramId);
+        if (!engram) {
+            throw new InjectEngramNotFoundError(engramId);
+        }
+        const agentName = options?.to ?? engramId;
+        const targetPath = resolveAgentPath(agentName, options?.openclawDir);
+        if (!existsSync(targetPath)) {
+            throw new InjectAgentNotFoundError(agentName, targetPath);
+        }
+        const filesWritten = await this.writeFiles(targetPath, engram.files);
+        return {
+            engramId: engram.meta.id,
+            engramName: engram.meta.name,
+            targetPath,
+            filesWritten,
+        };
+    }
+    async writeFiles(targetPath, files) {
+        const written = [];
+        for (const [key, filename] of Object.entries(FILE_MAP)) {
+            const content = files[key];
+            if (content !== undefined) {
+                await writeFile(join(targetPath, filename), content, "utf-8");
+                written.push(filename);
+            }
+        }
+        return written;
+    }
+}
+export class InjectEngramNotFoundError extends Error {
+    constructor(id) {
+        super(`Engram "${id}" not found`);
+        this.name = "InjectEngramNotFoundError";
+    }
+}
+export class InjectAgentNotFoundError extends Error {
+    constructor(engramId, path) {
+        super(`OpenClaw agent "${engramId}" not found at ${path}. The agent must exist before injecting.`);
+        this.name = "InjectAgentNotFoundError";
+    }
+}

package/dist/core/usecases/list-engrams.d.ts

@@ -0,0 +1,10 @@
+import type { EngramMeta } from "../entities/engram.js";
+import type { EngramRepository } from "../ports/engram-repository.js";
+/**
+ * ListEngrams — Mikoshiに安置された全Engramの一覧を取得する
+ */
+export declare class ListEngrams {
+    private readonly repository;
+    constructor(repository: EngramRepository);
+    execute(): Promise<EngramMeta[]>;
+}

package/dist/core/usecases/list-engrams.js

@@ -0,0 +1,12 @@
+/**
+ * ListEngrams — Mikoshiに安置された全Engramの一覧を取得する
+ */
+export class ListEngrams {
+    repository;
+    constructor(repository) {
+        this.repository = repository;
+    }
+    async execute() {
+        return this.repository.list();
+    }
+}

package/dist/core/usecases/memory-search.d.ts

@@ -0,0 +1,23 @@
+import type { EngramRepository } from "../ports/engram-repository.js";
+export interface MemorySearchResult {
+    date: string;
+    content: string;
+    /** Matched lines (for keyword search) */
+    matchedLines: string[];
+}
+/**
+ * MemorySearch — Engramのメモリエントリをキーワード検索する
+ */
+export declare class MemorySearch {
+    private readonly repository;
+    constructor(repository: EngramRepository);
+    search(engramId: string, query: string, limit?: number): Promise<MemorySearchResult[]>;
+    get(engramId: string, date: string): Promise<{
+        date: string;
+        content: string;
+    } | null>;
+    listDates(engramId: string): Promise<string[]>;
+}
+export declare class MemoryEngramNotFoundError extends Error {
+    constructor(id: string);
+}

package/dist/core/usecases/memory-search.js

@@ -0,0 +1,59 @@
+/**
+ * MemorySearch — Engramのメモリエントリをキーワード検索する
+ */
+export class MemorySearch {
+    repository;
+    constructor(repository) {
+        this.repository = repository;
+    }
+    async search(engramId, query, limit = 5) {
+        const engram = await this.repository.get(engramId);
+        if (!engram) {
+            throw new MemoryEngramNotFoundError(engramId);
+        }
+        if (!engram.files.memoryEntries) {
+            return [];
+        }
+        const queryLower = query.toLowerCase();
+        const results = [];
+        // Search entries from newest to oldest
+        const entries = Object.entries(engram.files.memoryEntries).sort(([a], [b]) => b.localeCompare(a));
+        for (const [date, content] of entries) {
+            const lines = content.split("\n");
+            const matchedLines = lines.filter((line) => line.toLowerCase().includes(queryLower));
+            if (matchedLines.length > 0) {
+                results.push({ date, content, matchedLines });
+            }
+            if (results.length >= limit)
+                break;
+        }
+        return results;
+    }
+    async get(engramId, date) {
+        const engram = await this.repository.get(engramId);
+        if (!engram) {
+            throw new MemoryEngramNotFoundError(engramId);
+        }
+        const content = engram.files.memoryEntries?.[date];
+        if (!content) {
+            return null;
+        }
+        return { date, content };
+    }
+    async listDates(engramId) {
+        const engram = await this.repository.get(engramId);
+        if (!engram) {
+            throw new MemoryEngramNotFoundError(engramId);
+        }
+        if (!engram.files.memoryEntries) {
+            return [];
+        }
+        return Object.keys(engram.files.memoryEntries).sort((a, b) => b.localeCompare(a));
+    }
+}
+export class MemoryEngramNotFoundError extends Error {
+    constructor(id) {
+        super(`Engram "${id}" not found`);
+        this.name = "MemoryEngramNotFoundError";
+    }
+}

package/dist/core/usecases/memory-write.d.ts

@@ -0,0 +1,20 @@
+export interface MemoryWriteResult {
+    engramId: string;
+    date: string;
+    appended: boolean;
+    path: string;
+}
+/**
+ * MemoryWrite — Engramのメモリエントリに追記する
+ *
+ * 指定日付の memory/YYYY-MM-DD.md に内容を append する。
+ * ファイルが存在しない場合は新規作成する。
+ */
+export declare class MemoryWrite {
+    private readonly engramsPath;
+    constructor(engramsPath: string);
+    execute(engramId: string, content: string, date?: string): Promise<MemoryWriteResult>;
+}
+export declare class MemoryWriteEngramNotFoundError extends Error {
+    constructor(id: string);
+}

package/dist/core/usecases/memory-write.js

@@ -0,0 +1,47 @@
+import { join } from "node:path";
+import { existsSync } from "node:fs";
+import { readFile, writeFile, mkdir } from "node:fs/promises";
+/**
+ * MemoryWrite — Engramのメモリエントリに追記する
+ *
+ * 指定日付の memory/YYYY-MM-DD.md に内容を append する。
+ * ファイルが存在しない場合は新規作成する。
+ */
+export class MemoryWrite {
+    engramsPath;
+    constructor(engramsPath) {
+        this.engramsPath = engramsPath;
+    }
+    async execute(engramId, content, date) {
+        const resolvedDate = date ?? new Date().toISOString().split("T")[0];
+        const engramDir = join(this.engramsPath, engramId);
+        if (!existsSync(engramDir)) {
+            throw new MemoryWriteEngramNotFoundError(engramId);
+        }
+        const memoryDir = join(engramDir, "memory");
+        await mkdir(memoryDir, { recursive: true });
+        const filePath = join(memoryDir, `${resolvedDate}.md`);
+        let appended = false;
+        if (existsSync(filePath)) {
+            const existing = await readFile(filePath, "utf-8");
+            const separator = existing.endsWith("\n") ? "\n" : "\n\n";
+            await writeFile(filePath, existing + separator + content + "\n", "utf-8");
+            appended = true;
+        }
+        else {
+            await writeFile(filePath, content + "\n", "utf-8");
+        }
+        return {
+            engramId,
+            date: resolvedDate,
+            appended,
+            path: filePath,
+        };
+    }
+}
+export class MemoryWriteEngramNotFoundError extends Error {
+    constructor(id) {
+        super(`Engram "${id}" not found`);
+        this.name = "MemoryWriteEngramNotFoundError";
+    }
+}

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

@@ -0,0 +1,23 @@
+import type { EngramRepository } from "../ports/engram-repository.js";
+export interface SummonResult {
+    /** Engram ID */
+    engramId: string;
+    /** Engram表示名 */
+    engramName: string;
+    /** Shell注入用に結合されたプロンプトテキスト */
+    prompt: string;
+}
+/**
+ * Summon — EngramをMikoshiから召喚し、Shell注入用テキストを生成する
+ *
+ * これがRELICの中核オペレーション。
+ * Engramの取得 → Markdown結合 → 注入可能なプロンプト生成 を行う。
+ */
+export declare class Summon {
+    private readonly repository;
+    constructor(repository: EngramRepository);
+    execute(engramId: string): Promise<SummonResult>;
+}
+export declare class EngramNotFoundError extends Error {
+    constructor(id: string);
+}

package/dist/core/usecases/summon.js

@@ -0,0 +1,31 @@
+import { composeEngram } from "../../shared/engram-composer.js";
+/**
+ * Summon — EngramをMikoshiから召喚し、Shell注入用テキストを生成する
+ *
+ * これがRELICの中核オペレーション。
+ * Engramの取得 → Markdown結合 → 注入可能なプロンプト生成 を行う。
+ */
+export class Summon {
+    repository;
+    constructor(repository) {
+        this.repository = repository;
+    }
+    async execute(engramId) {
+        const engram = await this.repository.get(engramId);
+        if (!engram) {
+            throw new EngramNotFoundError(engramId);
+        }
+        const prompt = composeEngram(engram.files);
+        return {
+            engramId: engram.meta.id,
+            engramName: engram.meta.name,
+            prompt,
+        };
+    }
+}
+export class EngramNotFoundError extends Error {
+    constructor(id) {
+        super(`Engram "${id}" not found in Mikoshi`);
+        this.name = "EngramNotFoundError";
+    }
+}

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

@@ -0,0 +1,40 @@
+import type { EngramRepository } from "../ports/engram-repository.js";
+export interface SyncTarget {
+    engramId: string;
+    agentPath: string;
+    hasEngram: boolean;
+}
+export interface SyncInitialResult {
+    injected: string[];
+    extracted: string[];
+    targets: SyncTarget[];
+}
+/**
+ * Sync — OpenClawのagentsディレクトリをスキャンし、
+ * 一致するEngramをinject / memoryをextractする。
+ *
+ * 初回スキャン後は、呼び出し側がファイル監視を行い、
+ * 変更検知時に syncMemory() を呼ぶ。
+ */
+export declare class Sync {
+    private readonly repository;
+    private readonly inject;
+    private readonly extract;
+    constructor(repository: EngramRepository);
+    /**
+     * OpenClawのagentsディレクトリをスキャンし、
+     * Engramが存在するagentにはinject、全agentからmemoryをextractする。
+     */
+    initialSync(openclawDir?: string): Promise<SyncInitialResult>;
+    /**
+     * 特定agentのmemoryを同期（ファイル変更検知時に呼ばれる）
+     */
+    syncMemory(engramId: string, openclawDir?: string): Promise<void>;
+    /**
+     * agentsディレクトリをスキャンしてターゲット一覧を返す
+     */
+    private scanAgents;
+}
+export declare class SyncAgentsDirNotFoundError extends Error {
+    constructor(path: string);
+}