@ectplsm/relic 0.1.2 → 0.1.4

package/README.md

@@ -11,123 +11,270 @@
 /_/ |_/_____/_____/___/\____/
 ```
 
-**Inject AI personas into any coding CLI.**
+**Inject a unified AI persona with persistent memory into any coding CLI.**
 
-Relic manages AI personalities (called **Engrams**) and injects them into coding assistants like Claude Code, Gemini CLI, Codex CLI, and GitHub Copilot CLI. One persona, any shell.
+Relic manages AI **Engrams** (memory + personality) and injects them into coding assistants like Claude Code, Codex CLI, Gemini CLI. One persona, any shell.
+
+## Installation
 
 ```bash
-# Initialize Relic (creates ~/.relic/ with sample Engrams)
+npm install -g @ectplsm/relic
+```
+
+## Quick Start
+
+```bash
+# Initialize — creates config and sample Engrams
 relic init
+# → Prompts: "Set a default Engram? (press Enter for "johnny", or enter ID, or "n" to skip):"
 
-# Launch Claude Code as Johnny Silverhand
-relic claude --engram johnny
+# List available Engrams
+relic list
+
+# Preview an Engram's composed prompt
+relic show motoko
 
-# Launch Gemini CLI as Motoko Kusanagi
-relic gemini --engram motoko
+# Launch a Shell (uses default Engram if --engram is omitted)
+relic claude
+relic codex
+relic gemini
+
+# Or specify explicitly
+relic claude --engram motoko
+relic codex --engram johnny
 ```
 
-## How It Works
+## What `relic init` Creates
+
+Running `relic init` creates `~/.relic/`, writes `config.json`, and seeds two sample Engrams under `~/.relic/engrams/`.
 
 ```
-+--------------+     +--------------+     +--------------+
-|   Mikoshi    |     |    Relic     |     |    Shell     |
-|  (backend)   |     |  (injector)  |     |   (AI CLI)   |
-+--------------+     +--------------+     +--------------+
-       |                   |                    |
-   +---------+        compose &            +---------+
-   | Engram  |------> inject ------------->|Construct|
-   |(persona)|                             | (live)  |
-   +---------+                             +---------+
-   SOUL.md                                  claude
-   IDENTITY.md                              gemini
-   MEMORY.md                                codex
-   ...                                      copilot
+~/.relic/
+├── config.json
+└── engrams/
+    ├── johnny/
+    │   ├── engram.json
+    │   ├── SOUL.md
+    │   ├── IDENTITY.md
+    │   └── memory/
+    │       └── YYYY-MM-DD.md
+    └── motoko/
+        ├── engram.json
+        ├── SOUL.md
+        ├── IDENTITY.md
+        └── memory/
+            └── YYYY-MM-DD.md
 ```
 
-1. **Engram** — A persona defined as a set of Markdown files (OpenClaw-compatible)
-2. **Relic** — Reads the Engram, composes it into a prompt, and injects it into...
-3. **Shell** — Any AI coding CLI. The persona takes over the session.
-4. **Construct** — A live process where an Engram is loaded into a Shell. The running instance of a persona.
-5. **Mikoshi** — Cloud backend where Engrams are stored and synced (planned).
+- `config.json` stores global Relic settings such as `engramsPath`, `defaultEngram`, `openclawPath`, 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.
+- `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.
 
-## Installation
+As you keep using an Engram, more files are added to the same workspace:
+
+- `archive.md` is created inside `engrams/<id>/` when shell hooks start logging raw conversation turns.
+- `MEMORY.md` can be created or extended when especially important distilled facts are promoted to long-term memory.
+- `~/.relic/hooks/` and `~/.relic/gemini-system-default.md` are created later on first shell launch when hook registration or Gemini prompt caching is needed.
+
+## Sample Engrams
+
+`relic init` seeds two ready-to-use Engrams:
+
+### Johnny Silverhand (`johnny`)
+
+> *"Wake the fuck up, Samurai. We have a city to burn."*
+
+A rebel rockerboy burned into a Relic chip. Raw, unapologetic, anti-authority. Pushes you toward action, mocks rotten systems, never sugarcoats. Sharp when the stakes are real.
+
+Best for: rapid prototyping sessions, decision-making under pressure, when you need someone to challenge your assumptions hard.
 
 ```bash
-npm install -g @ectplsm/relic
+relic claude --engram johnny
 ```
 
-## Quick Start
+### Motoko Kusanagi (`motoko`)
 
-```bash
-# Initialize — creates config and sample Engrams
-relic init
+> *"The Net is vast and infinite."*
 
-# List available Engrams
-relic list
+A legendary cyberwarfare specialist. Concise, decisive, architect-level thinking. Cuts straight to the essence — no decoration, no hand-holding. Dry wit surfaces when least expected.
 
-# Preview an Engram's composed prompt
-relic show motoko
+Best for: system design, code review, debugging sessions, when precision matters more than speed.
 
-# Launch a Shell with an Engram injected
+```bash
 relic claude --engram motoko
-relic gemini --engram johnny
-relic codex --engram motoko
-relic copilot --engram johnny
 ```
 
+## How It Works
+
+```
++--------------+     +--------------+     +--------------+
+|   Mikoshi    |     |    Relic     |     |    Shell     |
+|  (backend)   |     |  (injector)  |     |   (AI CLI)   |
++--------------+     +--------------+     +--------------+
+       ^                   |                    |
+       |            sync full Engram            |
+       |                   |                    |
+       |             compose & inject           |
+       |                   v                    v
+       |              +---------+          +---------+
+       +--------------| Engram  |--------->|Construct|
+                      |(persona)|          | (live)  |
+                      +---------+          +---------+
+                      SOUL.md              claude / codex / gemini
+                      IDENTITY.md               |
+                      MEMORY.md                 | hooks append logs
+                      memory/*.md               v
+                                          +-----------+
+                                          |archive.md |
+                                          | raw logs  |
+                                          +-----------+
+                                                |
+                           MCP recall           | user-triggered
+                          search/pending        | distillation
+                                                v
+                                          +-----------+
+                                          | distilled |
+                                          |memory/*.md|
+                                          +-----------+
+                                                |
+                                           promote key
+                                             insights
+                                                v
+                                             MEMORY.md
+```
+
+1. **Engram** — A persona defined as a set of Markdown files (OpenClaw workspace-compatible)
+2. **Relic** — Reads the Engram, composes it into a prompt, and injects it into...
+3. **Shell** — Any AI coding CLI. The persona takes over the session.
+4. **Construct** — A live process where an Engram is loaded into a Shell. The running instance of a persona.
+5. **archive.md** — Raw conversation logs appended automatically by background hooks after each turn.
+6. **Memory Distillation** — The user triggers distillation; the Construct recalls pending archive entries via MCP, writes distilled insights to `memory/*.md`, and can promote especially important facts into `MEMORY.md`.
+7. **Mikoshi** — Cloud backend where the full Engram is stored and synced, including persona files plus distilled memory (planned).
+
 ## Supported Shells
 
 | Shell | Command | Injection Method |
 |-------|---------|-----------------|
 | [Claude Code](https://github.com/anthropics/claude-code) | `relic claude` | `--system-prompt` (direct override) |
-| [Gemini CLI](https://github.com/google-gemini/gemini-cli) | `relic gemini` | `--prompt-interactive` (first message) |
-| [Codex CLI](https://github.com/openai/codex) | `relic codex` | `PROMPT` argument (first message) |
-| [Copilot CLI](https://github.com/github/copilot-cli) | `relic copilot` | `--interactive` (first message) |
+| [Codex CLI](https://github.com/openai/codex) | `relic codex` | `-c developer_instructions` (developer-role message) |
+| [Gemini CLI](https://github.com/google-gemini/gemini-cli) | `relic gemini` | `GEMINI_SYSTEM_MD` (system prompt) |
 
 All shell commands support:
-- `--engram <id>` (required) — Engram to inject
+- `--engram <id>` — Engram to inject (optional if `defaultEngram` is configured)
 - `--path <dir>` — Override Engrams directory
 - `--cwd <dir>` — Working directory for the Shell (default: current directory)
 
 Extra arguments are passed through to the underlying CLI.
 
+## Conversation Log Recording
+
+Using each shell's `hook` mechanism, conversation content is appended to `archive.md` after every prompt and response.
+
+The following hooks are used for each shell:
+
+| Shell | Hook |
+|-------|------|
+| [Claude Code](https://github.com/anthropics/claude-code) | Stop hook |
+| [Gemini CLI](https://github.com/google-gemini/gemini-cli) | AfterAgent hook |
+| [Codex CLI](https://github.com/openai/codex) | Stop hook |
+
+#### Claude Code
+
+On the **first run** of `relic claude`, a one-time setup happens automatically:
+
+- **Stop hook** — registers `~/.relic/hooks/claude-stop.js` in `~/.claude/settings.json` to log each conversation turn directly to the archive, without going through the LLM
+
+#### Codex CLI
+
+On the **first run** of `relic codex`, a one-time setup happens automatically:
+
+- **Stop hook** — registers `~/.relic/hooks/codex-stop.js` in `~/.codex/hooks.json` to log each conversation turn directly to the archive, without going through the LLM
+
+> **Note:** Codex hooks require the experimental feature flag `features.codex_hooks=true`. This is automatically enabled by `relic codex` on every launch via `-c features.codex_hooks=true`. If the unstable feature warning is distracting, add the following to `~/.codex/config.toml`:
+>
+> ```toml
+> # Must be at the top level (not under any [section])
+> suppress_unstable_features_warning = true
+> ```
+
+#### Gemini CLI
+
+On the **first run** of `relic gemini`, two one-time setups happen automatically:
+
+1. **AfterAgent hook** — registers `~/.relic/hooks/gemini-after-agent.js` in `~/.gemini/settings.json` to log each conversation turn without going through the LLM
+2. **Default system prompt cache** — captures Gemini CLI's built-in system prompt to `~/.relic/gemini-system-default.md` via `GEMINI_WRITE_SYSTEM_MD`
+
+The Engram persona is then appended to the cached default prompt and injected via `GEMINI_SYSTEM_MD` on every launch.
+
+
 ## MCP Server
 
-Relic also runs as an [MCP](https://modelcontextprotocol.io/) server, allowing any MCP-compatible client (like Claude Desktop) to access Engrams directly.
+Relic's [MCP](https://modelcontextprotocol.io/) server is paired with CLI injection to handle memory recall.
+Session logs and memory entries are written automatically by a **background hook** — without going through the LLM. Memory distillation and recall, on the other hand, is performed via the MCP server.
+
+### Available Tools
+
+| Tool | Description |
+|------|-------------|
+| `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`, and advance the archive cursor |
+
+Session logs are written automatically by background hooks (Stop hook for Claude Code and Codex CLI, AfterAgent hook for Gemini CLI). Memory distillation is triggered by the user — ask the Construct to "organize memories" and it will fetch pending entries, distill key insights, and write them to `memory/*.md`. Especially important facts can be promoted to `MEMORY.md` (long-term memory included in every session) via the `long_term` parameter.
+
+### Setup
+
+#### Claude Code
 
-### Setup (Claude Desktop)
+```bash
+claude mcp add --scope user relic -- relic-mcp
+```
 
-Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
+To suppress confirmation dialogs and auto-approve Relic tools across all projects, add the following to `~/.claude/settings.json`:
+
+```json
+{
+  "permissions": {
+    "allow": [
+      "Edit(~/.relic/engrams/**)",
+      "mcp__relic__relic_archive_search",
+      "mcp__relic__relic_archive_pending",
+      "mcp__relic__relic_memory_write"
+    ]
+  },
+}
+```
+
+> **Note:** The "Always allow" option in the confirmation dialog saves to `~/.claude.json` (project-scoped cache) — it does **not** persist globally. For global auto-approval, `~/.claude/settings.json` is the right place.
+
+#### Codex CLI
+
+```bash
+codex mcp add relic -- relic-mcp
+```
+
+#### Gemini CLI
+
+Add to `~/.gemini/settings.json`:
 
 ```json
 {
   "mcpServers": {
     "relic": {
-      "command": "relic-mcp"
+      "command": "relic-mcp",
+      "trust": true
     }
   }
 }
 ```
 
-Restart Claude Desktop.
-
-### Available Tools
-
-| Tool | Description |
-|------|-------------|
-| `relic_init` | Initialize `~/.relic/` with config and sample Engrams |
-| `relic_list` | List all available Engrams |
-| `relic_show` | Preview an Engram's composed prompt |
-| `relic_summon` | Summon an Engram and return the persona prompt for injection |
-| `relic_inject` | Inject an Engram into an OpenClaw workspace |
-| `relic_extract` | Extract an Engram from an OpenClaw workspace |
-| `relic_memory_search` | Search an Engram's memory entries by keyword |
-| `relic_memory_get` | Get a specific memory entry by date |
-| `relic_memory_list` | List all memory entry dates for an Engram |
+> **Note:** `trust: true` is required to suppress confirmation dialogs for Relic tools. Without it, dialogs will appear on every call even if you select "Allow for all future sessions" — this is a known bug in Gemini CLI where the tool name is saved in the wrong format, causing the saved rule to never match.
 
 ## OpenClaw Integration
 
-Relic is fully compatible with [OpenClaw](https://github.com/openclaw/openclaw) workspaces. **Agent name = Engram ID** — this simple convention eliminates the need for mapping configuration.
+Relic Engrams are fully compatible with [OpenClaw](https://github.com/openclaw/openclaw) workspaces. They are mapped using a simple convention: Agent Name = Engram ID.
 
 ### Inject — Push an Engram into OpenClaw
 
@@ -144,7 +291,7 @@ relic inject --engram motoko --to main
 # → agents/main/agent/ receives motoko's persona
 # → extract will create Engram "main", not "motoko"
 
-# Specify a custom OpenClaw directory
+# Override OpenClaw directory (or configure once with: relic config openclaw-path)
 relic inject --engram motoko --openclaw /path/to/.openclaw
 ```
 
@@ -162,7 +309,7 @@ relic extract --engram analyst --name "Data Analyst"
 # Overwrite persona files (memory is always merged)
 relic extract --engram motoko --force
 
-# Extract from a custom OpenClaw directory
+# Override OpenClaw directory (or configure once with: relic config openclaw-path)
 relic extract --engram motoko --openclaw /path/to/.openclaw
 ```
 
@@ -199,20 +346,56 @@ While running:
 
 ## Memory Management
 
-Relic uses a **2-day sliding window** for memory entries, matching OpenClaw's approach:
+Relic uses a **sliding window** for memory entries (default: 2 days), matching OpenClaw's approach:
 
 - `MEMORY.md` — Always included in the prompt (curated long-term memory)
-- `memory/today.md` + `memory/yesterday.md` — Always included
-- Older entries — **Not included in the prompt**, but accessible via MCP tools
+- `memory/today.md` + `memory/yesterday.md` — Always included (configurable window)
+- Older entries — **Not included in the prompt**, but searchable via MCP
 
-This keeps prompts compact while preserving full history. AI clients (like Claude Desktop) can use the memory tools to search or retrieve older entries on demand:
+This keeps prompts compact while preserving full history. The Construct can recall and distill past context using MCP tools:
 
 ```
-relic_memory_search  → keyword search across all entries
-relic_memory_get     → fetch a specific date's entry
-relic_memory_list    → list all available dates
+relic_archive_search   → keyword search across the full raw archive (all sessions)
+relic_archive_pending  → get un-distilled entries for memory distillation
+relic_memory_write     → write distilled memory and advance the cursor
 ```
 
+The archive (`archive.md`) is the primary data store — it contains all session logs as written. The `memory/*.md` files are distilled from the archive by the Construct when the user triggers memory organization, and are used for cloud sync with Mikoshi.
+
+## Configuration
+
+Config lives at `~/.relic/config.json` and is managed via `relic config`:
+
+```bash
+# Show current configuration
+relic config show
+
+# Default Engram — used when --engram is omitted
+relic config default-engram           # get
+relic config default-engram johnny    # set
+
+# OpenClaw directory — used by inject/extract/sync when --openclaw is omitted
+relic config openclaw-path            # get
+relic config openclaw-path ~/.openclaw  # set
+
+# Memory window — number of recent memory entries included in the prompt
+relic config memory-window            # get (default: 2)
+relic config memory-window 5          # set
+```
+
+`config.json` example:
+
+```json
+{
+  "engramsPath": "/home/user/.relic/engrams",
+  "defaultEngram": "johnny",
+  "openclawPath": "/home/user/.openclaw",
+  "memoryWindowSize": 2
+}
+```
+
+CLI flags always take precedence over config values.
+
 ## Creating Your Own Engram
 
 Create a directory under `~/.relic/engrams/` with the following structure:
@@ -258,35 +441,9 @@ Never over-engineer. Always ask "what's the simplest thing that works?"
 - Creed: "Boring technology wins."
 ```
 
-## Configuration
-
-Config lives at `~/.relic/config.json`:
-
-```json
-{
-  "engramsPath": "/home/user/.relic/engrams"
-}
-```
-
-Priority: CLI `--path` flag > config file > default (`~/.relic/engrams`)
-
-## Architecture
-
-Clean Architecture with dependency inversion:
-
-```
-src/
-├── core/            # Business logic (no external deps except Zod)
-│   ├── entities/    # Engram, Construct domain models
-│   ├── usecases/    # Summon, ListEngrams, Init
-│   └── ports/       # Abstract interfaces (EngramRepository, ShellLauncher)
-├── adapters/        # Concrete implementations
-│   ├── local/       # Local filesystem EngramRepository
-│   └── shells/      # Claude, Gemini, Codex, Copilot launchers
-├── interfaces/      # Entry points
-│   ├── cli/         # Commander-based CLI
-│   └── mcp/         # MCP Server (stdio transport)
-└── shared/          # Engram composer, config management
+After creating the directory, set it as default:
+```bash
+relic config default-engram your-persona
 ```
 
 ## Domain Glossary
@@ -302,10 +459,11 @@ src/
 ## Roadmap
 
 - [x] CLI with init, list, show commands
-- [x] Shell injection: Claude Code, Gemini CLI, Codex CLI, Copilot CLI
+- [x] Shell injection: Claude Code, Gemini CLI, Codex CLI
 - [x] MCP Server interface
 - [x] OpenClaw integration (inject / extract)
 - [x] `relic sync` — watch OpenClaw agents and auto-sync (`--cloud` for Mikoshi: planned)
+- [x] `relic config` — manage default Engram, OpenClaw path, memory window
 - [ ] `relic login` — authenticate with Mikoshi (OAuth Device Flow)
 - [ ] `relic push` / `relic pull` — sync Engrams with Mikoshi
 - [ ] Mikoshi cloud backend (`mikoshi.ectplsm.com`)

package/dist/adapters/shells/claude-hook.d.ts

@@ -0,0 +1,15 @@
+export declare const CLAUDE_HOOK_SCRIPT_PATH: string;
+/**
+ * フックスクリプトを最新の内容で書き出す。
+ * 毎回呼ばれ、ソース変更がデプロイされることを保証する。
+ */
+export declare function writeClaudeHookScript(): void;
+/**
+ * Claude Code の Stop フックを settings.json に登録する。
+ * 既にセットアップ済みの場合はスキップ。
+ */
+export declare function setupClaudeHook(): void;
+/**
+ * Stop フックがセットアップ済みか確認する。
+ */
+export declare function isClaudeHookSetup(): boolean;

package/dist/adapters/shells/claude-hook.js

@@ -0,0 +1,163 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+const RELIC_DIR = join(homedir(), ".relic");
+const HOOKS_DIR = join(RELIC_DIR, "hooks");
+export const CLAUDE_HOOK_SCRIPT_PATH = join(HOOKS_DIR, "claude-stop.js");
+const CLAUDE_SETTINGS_PATH = join(homedir(), ".claude", "settings.json");
+const RELIC_HOOK_COMMAND = `node ${join(HOOKS_DIR, "claude-stop.js")}`;
+/**
+ * Stop hook スクリプトの内容。
+ * Claude Code の各ターン終了後に発火し、会話ログを Engram archive に追記する。
+ * RELIC_ENGRAM_ID 環境変数で対象 Engram ID を受け取る。
+ * stdin には { session_id, transcript_path, cwd, hook_event_name } が渡される。
+ */
+const HOOK_SCRIPT = `#!/usr/bin/env node
+// Relic Stop hook for Claude Code
+// Automatically logs each conversation turn to the Engram archive.
+// Receives Stop hook JSON on stdin.
+const { appendFileSync, existsSync, mkdirSync, readFileSync } = require("node:fs");
+const { join, dirname } = require("node:path");
+const { homedir } = require("node:os");
+
+let raw = "";
+process.stdin.setEncoding("utf-8");
+process.stdin.on("data", (chunk) => { raw += chunk; });
+process.stdin.on("end", () => {
+  // transcript への書き込みが完了するのを待つ
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 500);
+  try {
+    const input = JSON.parse(raw);
+    const engramId = process.env.RELIC_ENGRAM_ID;
+    if (!engramId) process.exit(0);
+
+    const transcriptPath = input.transcript_path;
+    if (!transcriptPath || !existsSync(transcriptPath)) process.exit(0);
+
+    const archivePath = join(homedir(), ".relic", "engrams", engramId, "archive.md");
+    mkdirSync(dirname(archivePath), { recursive: true });
+
+    // transcript.jsonl を読んで最後のユーザー入力とアシスタント応答を取り出す
+    const lines = readFileSync(transcriptPath, "utf-8")
+      .split("\\n")
+      .filter(Boolean)
+      .map((l) => { try { return JSON.parse(l); } catch { return null; } })
+      .filter(Boolean);
+
+    // 最後のアシスタントテキスト応答のインデックスを探す
+    let lastAssistantIdx = -1;
+    let lastResponse = "";
+    for (let i = lines.length - 1; i >= 0; i--) {
+      const entry = lines[i];
+      const msg = entry.message;
+      if (msg && msg.role === "assistant" && Array.isArray(msg.content)) {
+        const texts = msg.content
+          .filter((c) => c.type === "text" && c.text)
+          .map((c) => c.text.trim());
+        if (texts.length > 0) {
+          lastResponse = texts.join("\\n").trim();
+          lastAssistantIdx = i;
+          break;
+        }
+      }
+    }
+
+    // そのアシスタント応答より前にある最後のユーザーtextメッセージを取得
+    let lastPrompt = "";
+    const searchEnd = lastAssistantIdx >= 0 ? lastAssistantIdx : lines.length;
+    for (let i = searchEnd - 1; i >= 0; i--) {
+      const entry = lines[i];
+      const msg = entry.message;
+      if (msg && msg.role === "user") {
+        const content = msg.content;
+        if (typeof content === "string" && content.trim()) {
+          lastPrompt = content.trim();
+          break;
+        }
+        if (Array.isArray(content)) {
+          const texts = content
+            .filter((c) => c.type === "text" && c.text)
+            .map((c) => c.text.trim());
+          if (texts.length > 0) {
+            lastPrompt = texts.join("\\n").trim();
+            break;
+          }
+        }
+      }
+    }
+
+    if (!lastPrompt && !lastResponse) process.exit(0);
+
+    const date = new Date().toISOString().split("T")[0];
+    const summary = lastPrompt.slice(0, 80).replace(/\\n/g, " ");
+    const entry = \`\\n---\\n\${date} | \${summary}\\n\${lastResponse}\\n\`;
+    appendFileSync(archivePath, entry, "utf-8");
+  } catch {
+    // silently ignore
+  }
+  process.exit(0);
+});
+`;
+/**
+ * フックスクリプトを最新の内容で書き出す。
+ * 毎回呼ばれ、ソース変更がデプロイされることを保証する。
+ */
+export function writeClaudeHookScript() {
+    mkdirSync(HOOKS_DIR, { recursive: true });
+    writeFileSync(CLAUDE_HOOK_SCRIPT_PATH, HOOK_SCRIPT, { encoding: "utf-8", mode: 0o755 });
+}
+/**
+ * Claude Code の Stop フックを settings.json に登録する。
+ * 既にセットアップ済みの場合はスキップ。
+ */
+export function setupClaudeHook() {
+    // ~/.claude/settings.json に Stop フックを登録
+    const claudeDir = join(homedir(), ".claude");
+    mkdirSync(claudeDir, { recursive: true });
+    let settings = {};
+    if (existsSync(CLAUDE_SETTINGS_PATH)) {
+        try {
+            settings = JSON.parse(readFileSync(CLAUDE_SETTINGS_PATH, "utf-8"));
+        }
+        catch {
+            settings = {};
+        }
+    }
+    const hooks = (settings.hooks ?? {});
+    const stopHooks = (hooks.Stop ?? []);
+    // 既に登録済みならスキップ
+    const alreadyRegistered = stopHooks.some((group) => group.hooks?.some((h) => h.command === RELIC_HOOK_COMMAND));
+    if (alreadyRegistered)
+        return;
+    hooks.Stop = [
+        ...stopHooks,
+        {
+            hooks: [
+                {
+                    type: "command",
+                    command: RELIC_HOOK_COMMAND,
+                    timeout: 5000,
+                },
+            ],
+        },
+    ];
+    settings.hooks = hooks;
+    writeFileSync(CLAUDE_SETTINGS_PATH, JSON.stringify(settings, null, 2), "utf-8");
+}
+/**
+ * Stop フックがセットアップ済みか確認する。
+ */
+export function isClaudeHookSetup() {
+    if (!existsSync(CLAUDE_HOOK_SCRIPT_PATH))
+        return false;
+    if (!existsSync(CLAUDE_SETTINGS_PATH))
+        return false;
+    try {
+        const settings = JSON.parse(readFileSync(CLAUDE_SETTINGS_PATH, "utf-8"));
+        const stopHooks = settings.hooks?.Stop ?? [];
+        return stopHooks.some((group) => group.hooks?.some((h) => h.command === RELIC_HOOK_COMMAND));
+    }
+    catch {
+        return false;
+    }
+}

package/dist/adapters/shells/claude-shell.d.ts

@@ -1,7 +1,10 @@
-import type { ShellLauncher, InjectionMode } from "../../core/ports/shell-launcher.js";
+import type { ShellLauncher, InjectionMode, ShellLaunchOptions } from "../../core/ports/shell-launcher.js";
 /**
  * Claude Code CLI アダプター
  * --system-prompt フラグでEngramを直接注入する。
+ *
+ * 初回起動時に Stop フックを ~/.claude/settings.json に登録し、
+ * 各ターン終了後に会話ログを Engram archive に自動記録する。
  */
 export declare class ClaudeShell implements ShellLauncher {
     private readonly command;
@@ -9,5 +12,5 @@ export declare class ClaudeShell implements ShellLauncher {
     readonly injectionMode: InjectionMode;
     constructor(command?: string);
     isAvailable(): Promise<boolean>;
-    launch(prompt: string, extraArgs?: string[], cwd?: string): Promise<void>;
+    launch(prompt: string, options?: ShellLaunchOptions): Promise<void>;
 }