@ectplsm/relic 0.1.1 → 0.1.3

package/dist/shared/engram-composer.d.ts

@@ -1,4 +1,15 @@
-import type { EngramFiles } from "../core/entities/engram.js";
+import type { EngramFiles, EngramMeta } from "../core/entities/engram.js";
+/**
+ * Engram結合オプション
+ */
+export interface ComposeOptions {
+    /** Engramメタデータ（RELIC systemセクション生成用） */
+    meta?: EngramMeta;
+    /** 現在日付の上書き（テスト用、デフォルト: today） */
+    currentDate?: string;
+    /** システムプロンプトに含める直近メモリエントリ数（デフォルト: 2） */
+    memoryWindowSize?: number;
+}
 /**
  * EngramFilesの各Markdownを、Shell注入用の単一テキストに結合する。
  *
@@ -9,9 +20,11 @@ import type { EngramFiles } from "../core/entities/engram.js";
  * 4. AGENTS.md     — エージェント設定
  * 5. MEMORY.md     — 記憶インデックス（常にロード）
  * 6. memory/*.md   — 直近2日分のみロード（OpenClaw互換スライディングウィンドウ）
- * 7. HEARTBEAT.md  — 定期振り返り
+ * 7. RELIC        — システム情報（Engram ID、日付、Archive Protocol）
+ *
+ * archiveへの書き込みはバックグラウンドhookが自動で行う。
  */
-export declare function composeEngram(files: EngramFiles): string;
+export declare function composeEngram(files: EngramFiles, options?: ComposeOptions): string;
 /**
  * 直近N日分のメモリエントリを返す（日付降順でソートし、最新N件を日付昇順で返す）
  */

package/dist/shared/engram-composer.js

@@ -8,9 +8,11 @@
  * 4. AGENTS.md     — エージェント設定
  * 5. MEMORY.md     — 記憶インデックス（常にロード）
  * 6. memory/*.md   — 直近2日分のみロード（OpenClaw互換スライディングウィンドウ）
- * 7. HEARTBEAT.md  — 定期振り返り
+ * 7. RELIC        — システム情報（Engram ID、日付、Archive Protocol）
+ *
+ * archiveへの書き込みはバックグラウンドhookが自動で行う。
  */
-export function composeEngram(files) {
+export function composeEngram(files, options) {
     const sections = [];
     sections.push(wrapSection("SOUL", files.soul));
     sections.push(wrapSection("IDENTITY", files.identity));
@@ -24,16 +26,59 @@ export function composeEngram(files) {
         sections.push(wrapSection("MEMORY", files.memory));
     }
     if (files.memoryEntries) {
-        const recentEntries = getRecentMemoryEntries(files.memoryEntries, 2);
+        const windowSize = options?.memoryWindowSize ?? 2;
+        const recentEntries = getRecentMemoryEntries(files.memoryEntries, windowSize);
         for (const [date, content] of recentEntries) {
             sections.push(wrapSection(`MEMORY: ${date}`, content));
         }
     }
-    if (files.heartbeat) {
-        sections.push(wrapSection("HEARTBEAT", files.heartbeat));
+    // RELIC system section
+    if (options?.meta) {
+        sections.push(wrapSection("RELIC", composeRelicSection(options.meta, options.currentDate)));
     }
     return sections.join("\n\n");
 }
+/**
+ * RELICシステムセクションを生成する。
+ *
+ * archiveへの書き込みはバックグラウンドhookが自動で行う。
+ * [memory] タグ付きエントリだけが memory/*.md に永続化される。
+ */
+function composeRelicSection(meta, currentDate) {
+    const today = currentDate ?? new Date().toISOString().split("T")[0];
+    return `# Relic System
+
+- engramId: ${meta.id}
+- engramName: ${meta.name}
+- currentDate: ${today}
+
+# Archive Protocol (MCP)
+
+You have an archive via the Relic MCP tools for persistent memory.
+Your memories persist across ALL sessions and ALL LLM shells (Claude, Gemini, GPT, etc.).
+
+Session logs are written automatically by a background hook — do NOT write them yourself.
+
+## Recall
+
+To recall past context, use \`relic_archive_search\` to search your archive by keyword.
+
+## Distillation
+
+When the user asks you to organize or distill memories:
+1. Call \`relic_archive_pending\` **once** to get un-distilled session entries (up to 30)
+2. Review and distill them into:
+   - **content**: key facts, decisions, and insights for \`memory/YYYY-MM-DD.md\`
+   - **long_term** (optional): only the most important, enduring facts for \`MEMORY.md\` (e.g. user preferences, project architecture decisions, key constraints)
+3. Call \`relic_memory_write\` with \`content\`, \`count\`, and optionally \`long_term\`
+4. If \`remaining > 0\`, inform the user how many entries are still pending — do NOT fetch more automatically
+
+**Important:**
+- Write distilled memories in the **same language the user is using** in the current conversation
+- Do NOT loop or repeat the distillation process — one round per user request
+- \`long_term\` should be highly selective — only facts that matter across all future sessions
+- Distilled memories are loaded into your prompt on future sessions`;
+}
 /**
  * 直近N日分のメモリエントリを返す（日付降順でソートし、最新N件を日付昇順で返す）
  */

package/dist/shared/memory-inbox.d.ts

@@ -0,0 +1,78 @@
+/**
+ * MemoryInbox — ファイルベースのメモリ受付口 + セッションログ
+ *
+ * LLMが inbox.md に追記すると、fs.watchで検知して処理する。
+ * inbox.md は書き溜め式で、セッションを跨いで追記され続ける。
+ * 処理済みエントリ数は inbox.cursor に永続化され、
+ * クラッシュ後の再起動でも正確に未処理分だけを回収できる。
+ *
+ * エントリの種別:
+ *   - `[memory] ...` → memory/*.md に永続化される記憶
+ *   - タグ無し       → inbox.md にログとして残るだけ（会話サマリー等）
+ *
+ * フォーマット:
+ *   各エントリは `---` (前後に改行) で区切る。
+ *
+ * 例:
+ *   Discussed improving RELIC's memory system.
+ *   ---
+ *   Implemented inbox-based approach for cross-LLM persistence.
+ *   ---
+ *   [memory] User prefers Bun over Node.js for all TypeScript projects.
+ *   ---
+ *   [memory] Project RELIC uses clean architecture with Zod for validation.
+ */
+export declare class MemoryInbox {
+    private readonly engramId;
+    private readonly engramsPath;
+    private watcher;
+    private processedCount;
+    private processing;
+    private memorySaved;
+    private logCount;
+    private savedEntries;
+    readonly inboxPath: string;
+    private readonly cursorPath;
+    constructor(engramId: string, engramsPath: string);
+    /**
+     * Inboxを起動する。
+     *
+     * 1. cursorファイルから前回の処理済み位置を復元
+     * 2. inbox.md の未処理エントリを回収（クラッシュ回復）
+     * 3. fs.watch で監視開始
+     */
+    start(): Promise<MemoryInboxRecoveryResult>;
+    /**
+     * 監視を停止し、最終掃引を行う。
+     * inbox.md はそのまま残す（書き溜め式）。
+     */
+    stop(): Promise<MemoryInboxResult>;
+    /**
+     * ファイル全体をパースし、未処理のエントリだけを処理する。
+     *
+     * - `[memory]` タグ付き → MemoryWrite で永続化
+     * - タグ無し → カウントのみ（inbox.md にログとして残る）
+     *
+     * 処理成功ごとにカーソルを永続化するため、
+     * 途中でクラッシュしても処理済み分は再処理されない。
+     */
+    private processNewEntries;
+    private loadCursor;
+    private saveCursor;
+}
+export interface MemoryInboxResult {
+    /** memory/*.md に永続化されたエントリ数 */
+    memories: number;
+    /** ログとして記録されたエントリ数 */
+    logs: number;
+    /** 永続化されたメモリの内容 */
+    entries: string[];
+}
+export interface MemoryInboxRecoveryResult {
+    /** 回収されたメモリ数 */
+    recoveredMemories: number;
+    /** 回収されたログ数 */
+    recoveredLogs: number;
+    /** 回収されたメモリの内容 */
+    entries: string[];
+}

package/dist/shared/memory-inbox.js

@@ -0,0 +1,168 @@
+import { watch, existsSync, writeFileSync, readFileSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { MemoryWrite } from "../core/usecases/memory-write.js";
+const INBOX_FILE = "inbox.md";
+const CURSOR_FILE = "inbox.cursor";
+const ENTRY_SEPARATOR = /\n---\n/;
+const MEMORY_TAG = /^\[memory\]\s*/i;
+/**
+ * MemoryInbox — ファイルベースのメモリ受付口 + セッションログ
+ *
+ * LLMが inbox.md に追記すると、fs.watchで検知して処理する。
+ * inbox.md は書き溜め式で、セッションを跨いで追記され続ける。
+ * 処理済みエントリ数は inbox.cursor に永続化され、
+ * クラッシュ後の再起動でも正確に未処理分だけを回収できる。
+ *
+ * エントリの種別:
+ *   - `[memory] ...` → memory/*.md に永続化される記憶
+ *   - タグ無し       → inbox.md にログとして残るだけ（会話サマリー等）
+ *
+ * フォーマット:
+ *   各エントリは `---` (前後に改行) で区切る。
+ *
+ * 例:
+ *   Discussed improving RELIC's memory system.
+ *   ---
+ *   Implemented inbox-based approach for cross-LLM persistence.
+ *   ---
+ *   [memory] User prefers Bun over Node.js for all TypeScript projects.
+ *   ---
+ *   [memory] Project RELIC uses clean architecture with Zod for validation.
+ */
+export class MemoryInbox {
+    engramId;
+    engramsPath;
+    watcher = null;
+    processedCount = 0;
+    processing = false;
+    memorySaved = 0;
+    logCount = 0;
+    savedEntries = [];
+    inboxPath;
+    cursorPath;
+    constructor(engramId, engramsPath) {
+        this.engramId = engramId;
+        this.engramsPath = engramsPath;
+        const engramDir = join(engramsPath, engramId);
+        this.inboxPath = join(engramDir, INBOX_FILE);
+        this.cursorPath = join(engramDir, CURSOR_FILE);
+    }
+    /**
+     * Inboxを起動する。
+     *
+     * 1. cursorファイルから前回の処理済み位置を復元
+     * 2. inbox.md の未処理エントリを回収（クラッシュ回復）
+     * 3. fs.watch で監視開始
+     */
+    async start() {
+        if (!existsSync(this.inboxPath)) {
+            writeFileSync(this.inboxPath, "", "utf-8");
+        }
+        this.processedCount = this.loadCursor();
+        const recovered = await this.processNewEntries();
+        this.watcher = watch(this.inboxPath, async (eventType) => {
+            if (eventType === "change") {
+                await this.processNewEntries();
+            }
+        });
+        this.watcher.on("error", () => { });
+        return {
+            recoveredMemories: recovered.memories,
+            recoveredLogs: recovered.logs,
+            entries: recovered.savedEntries,
+        };
+    }
+    /**
+     * 監視を停止し、最終掃引を行う。
+     * inbox.md はそのまま残す（書き溜め式）。
+     */
+    async stop() {
+        if (this.watcher) {
+            this.watcher.close();
+            this.watcher = null;
+        }
+        await this.processNewEntries();
+        return {
+            memories: this.memorySaved,
+            logs: this.logCount,
+            entries: this.savedEntries,
+        };
+    }
+    /**
+     * ファイル全体をパースし、未処理のエントリだけを処理する。
+     *
+     * - `[memory]` タグ付き → MemoryWrite で永続化
+     * - タグ無し → カウントのみ（inbox.md にログとして残る）
+     *
+     * 処理成功ごとにカーソルを永続化するため、
+     * 途中でクラッシュしても処理済み分は再処理されない。
+     */
+    async processNewEntries() {
+        if (this.processing)
+            return { memories: 0, logs: 0, savedEntries: [] };
+        this.processing = true;
+        const result = { memories: 0, logs: 0, savedEntries: [] };
+        try {
+            if (!existsSync(this.inboxPath))
+                return result;
+            const fullContent = await readFile(this.inboxPath, "utf-8");
+            if (!fullContent.trim())
+                return result;
+            const allEntries = fullContent
+                .split(ENTRY_SEPARATOR)
+                .map((e) => e.trim())
+                .filter((e) => e.length > 0);
+            const newEntries = allEntries.slice(this.processedCount);
+            if (newEntries.length === 0)
+                return result;
+            const writer = new MemoryWrite(this.engramsPath);
+            for (const raw of newEntries) {
+                const isMemory = MEMORY_TAG.test(raw);
+                if (isMemory) {
+                    const content = raw.replace(MEMORY_TAG, "").trim();
+                    try {
+                        await writer.execute(this.engramId, content);
+                        this.memorySaved++;
+                        this.savedEntries.push(content);
+                        result.memories++;
+                        result.savedEntries.push(content);
+                    }
+                    catch (err) {
+                        console.error(`[relic:inbox] Failed to save memory: ${err}`);
+                    }
+                }
+                else {
+                    this.logCount++;
+                    result.logs++;
+                }
+                this.processedCount++;
+                this.saveCursor();
+            }
+        }
+        finally {
+            this.processing = false;
+        }
+        return result;
+    }
+    loadCursor() {
+        if (!existsSync(this.cursorPath))
+            return 0;
+        try {
+            const raw = readFileSync(this.cursorPath, "utf-8").trim();
+            const n = parseInt(raw, 10);
+            return Number.isNaN(n) ? 0 : n;
+        }
+        catch {
+            return 0;
+        }
+    }
+    saveCursor() {
+        try {
+            writeFileSync(this.cursorPath, String(this.processedCount), "utf-8");
+        }
+        catch {
+            /* best effort */
+        }
+    }
+}

package/dist/shared/session-recorder.d.ts

@@ -0,0 +1,47 @@
+/**
+ * SessionRecorder — PTYストリームから会話履歴とメモリを記録する
+ *
+ * 役割:
+ * 1. full_history.md に全会話を蓄積（ANSI除去済みテキスト）
+ * 2. ストリーム中の [memory] タグを検出し memory/*.md に永続化
+ *
+ * full_history.md は無限に蓄積され続ける。セッションごとにヘッダーが挿入される。
+ */
+export declare class SessionRecorder {
+    private readonly engramId;
+    private readonly engramsPath;
+    readonly historyPath: string;
+    private memoryBuffer;
+    private memorySaved;
+    private savedEntries;
+    constructor(engramId: string, engramsPath: string);
+    /**
+     * セッション開始。ヘッダーを full_history.md に追記する。
+     */
+    start(shellName: string): void;
+    /**
+     * PTYストリームのデータを処理する。
+     * spawnShellWithPty の onData コールバックから呼ぶ。
+     *
+     * - ANSI除去してfull_history.mdに追記
+     * - [memory] タグを検出してバッファに溜める
+     */
+    onData(rawData: string): void;
+    /**
+     * セッション終了。残りのバッファを処理する。
+     */
+    stop(): Promise<SessionRecorderResult>;
+    /**
+     * memoryBuffer から完成した行を取り出し、[memory] タグを検出して永続化する。
+     * final=true の場合は残りのバッファも全て処理する。
+     */
+    private flushMemoryBuffer;
+}
+export interface SessionRecorderResult {
+    /** memory/*.md に永続化されたメモリ数 */
+    memories: number;
+    /** 永続化されたメモリの内容 */
+    entries: string[];
+    /** full_history.md のパス */
+    historyPath: string;
+}

package/dist/shared/session-recorder.js

@@ -0,0 +1,112 @@
+import { appendFileSync } from "node:fs";
+import { join } from "node:path";
+import { MemoryWrite } from "../core/usecases/memory-write.js";
+const HISTORY_FILE = "full_history.md";
+const MEMORY_TAG = /\[memory\]\s*/gi;
+/**
+ * ANSIエスケープシーケンスを除去する
+ */
+// eslint-disable-next-line no-control-regex
+const ANSI_REGEX = /\x1b\[[0-9;]*[a-zA-Z]|\x1b\].*?(?:\x07|\x1b\\)|\x1b[()][0-9A-B]|\x1b[>=<]|\x08/g;
+function stripAnsi(text) {
+    return text.replace(ANSI_REGEX, "");
+}
+/**
+ * SessionRecorder — PTYストリームから会話履歴とメモリを記録する
+ *
+ * 役割:
+ * 1. full_history.md に全会話を蓄積（ANSI除去済みテキスト）
+ * 2. ストリーム中の [memory] タグを検出し memory/*.md に永続化
+ *
+ * full_history.md は無限に蓄積され続ける。セッションごとにヘッダーが挿入される。
+ */
+export class SessionRecorder {
+    engramId;
+    engramsPath;
+    historyPath;
+    memoryBuffer = "";
+    memorySaved = 0;
+    savedEntries = [];
+    constructor(engramId, engramsPath) {
+        this.engramId = engramId;
+        this.engramsPath = engramsPath;
+        this.historyPath = join(engramsPath, engramId, HISTORY_FILE);
+    }
+    /**
+     * セッション開始。ヘッダーを full_history.md に追記する。
+     */
+    start(shellName) {
+        const header = [
+            "",
+            "---",
+            `## Session: ${new Date().toISOString()}`,
+            `Shell: ${shellName}`,
+            `Engram: ${this.engramId}`,
+            "---",
+            "",
+        ].join("\n");
+        appendFileSync(this.historyPath, header, "utf-8");
+    }
+    /**
+     * PTYストリームのデータを処理する。
+     * spawnShellWithPty の onData コールバックから呼ぶ。
+     *
+     * - ANSI除去してfull_history.mdに追記
+     * - [memory] タグを検出してバッファに溜める
+     */
+    onData(rawData) {
+        const clean = stripAnsi(rawData);
+        if (clean) {
+            appendFileSync(this.historyPath, clean, "utf-8");
+        }
+        // [memory] タグの検出
+        // PTYは断片的にデータが来るので、バッファに溜めて行単位で処理
+        this.memoryBuffer += clean;
+        this.flushMemoryBuffer(false);
+    }
+    /**
+     * セッション終了。残りのバッファを処理する。
+     */
+    async stop() {
+        // 末尾の改行を追加
+        appendFileSync(this.historyPath, "\n", "utf-8");
+        // バッファ内の残りを処理
+        await this.flushMemoryBuffer(true);
+        return {
+            memories: this.memorySaved,
+            entries: this.savedEntries,
+            historyPath: this.historyPath,
+        };
+    }
+    /**
+     * memoryBuffer から完成した行を取り出し、[memory] タグを検出して永続化する。
+     * final=true の場合は残りのバッファも全て処理する。
+     */
+    async flushMemoryBuffer(final) {
+        const lines = this.memoryBuffer.split("\n");
+        // 最終行は未完成の可能性があるので、final でない限り保持
+        if (!final && lines.length > 0) {
+            this.memoryBuffer = lines.pop() || "";
+        }
+        else {
+            this.memoryBuffer = "";
+        }
+        const writer = new MemoryWrite(this.engramsPath);
+        for (const line of lines) {
+            const trimmed = line.trim();
+            if (MEMORY_TAG.test(trimmed)) {
+                const content = trimmed.replace(MEMORY_TAG, "").trim();
+                if (content) {
+                    try {
+                        await writer.execute(this.engramId, content);
+                        this.memorySaved++;
+                        this.savedEntries.push(content);
+                    }
+                    catch (err) {
+                        console.error(`[relic:session] Failed to save memory: ${err}`);
+                    }
+                }
+            }
+        }
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ectplsm/relic",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "PROJECT RELIC — Engram injection system for AI constructs",
   "license": "MIT",
   "repository": {
@@ -33,13 +33,13 @@
     "node": ">=18"
   },
   "dependencies": {
-    "zod": "^3.23.0",
+    "@modelcontextprotocol/sdk": "^1.12.0",
     "commander": "^13.0.0",
-    "@modelcontextprotocol/sdk": "^1.12.0"
+    "zod": "^3.23.0"
   },
   "devDependencies": {
-    "typescript": "^5.7.0",
+    "@types/node": "^22.0.0",
     "tsx": "^4.19.0",
-    "@types/node": "^22.0.0"
+    "typescript": "^5.7.0"
   }
 }