@nogataka/claw-memory 0.1.0 → 0.1.2

package/.claude-plugin/marketplace.json

@@ -3,14 +3,14 @@
   "owner": { "name": "nogataka" },
   "metadata": {
     "description": "claw-memory: local semantic memory + raw-log search for Claude Code",
-    "version": "0.1.0"
+    "version": "0.1.2"
   },
   "plugins": [
     {
       "name": "claw-memory",
       "source": "./",
       "description": "Local semantic memory: auto-distill, recall injection, and raw Claude Code + Codex transcript search.",
-      "version": "0.1.0"
+      "version": "0.1.2"
     }
   ]
 }

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "claw-memory",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Local semantic memory for Claude Code: auto-distills sessions, injects relevant past context, and searches raw Claude Code + Codex transcripts. sqlite-vec + local embeddings, no daemon, no Python.",
   "author": { "name": "nogataka" },
   "repository": "https://github.com/nogataka/claw-memory",

package/.codex-plugin/plugin.json

@@ -0,0 +1,16 @@
+{
+  "name": "claw-memory",
+  "version": "0.1.2",
+  "description": "Local semantic memory for Codex: auto-distills sessions, injects relevant past context via hooks, and searches raw Codex + Claude Code transcripts. sqlite-vec + local embeddings, no daemon, no Python.",
+  "skills": "./skills/",
+  "mcpServers": "./.mcp.json",
+  "hooks": "./hooks/hooks.codex.json",
+  "interface": {
+    "displayName": "claw-memory",
+    "shortDescription": "Local semantic memory + transcript search for Codex",
+    "longDescription": "Auto-distills finished sessions into a local sqlite-vec store, injects relevant preferences and past-conversation context at session start via hooks, and exposes memory_recall / memory_search / memory_search_logs MCP tools. Runs fully local with Xenova e5 embeddings — no daemon, no Python.",
+    "developerName": "nogataka",
+    "category": "productivity",
+    "capabilities": ["memory", "context", "search"]
+  }
+}

package/README.ja.md

@@ -0,0 +1,310 @@
+# claw-memory
+
+[English](README.md) | **日本語**
+
+**AI コーディングエージェント（Claude Code / Codex）のためのローカル完結型・長期記憶。**
+エージェントが過去のセッション・あなたの好み・以前の決定事項を記憶し、記録済みの全
+トランスクリプトを横断検索できます。デーモン不要、Python 不要、外部ベクトル DB 不要。
+データは一切マシン外に出ません（セッションを要約する LLM 呼び出しのみ外部で、これも
+あなたが選択・制御します）。
+
+```bash
+npm install -g @nogataka/claw-memory
+```
+
+- **ストレージ**: `better-sqlite3` + `sqlite-vec` — ベクトルを 1 つの SQLite ファイル内に格納
+- **埋め込み**: ローカルの `Xenova/multilingual-e5-small`（384次元・多言語・オフライン）
+- **2 つの記憶ソース**: 蒸留済みのセマンティック DB と、Claude Code / Codex の生ログ全文検索
+- **自動取り込み**: フックで終了済みセッションを蒸留し、新しいセッションへ関連記憶を注入
+- **差し替え可能な LLM**: Claude / Codex のサブスクリプション（API キー不要）、または任意の
+  Anthropic / OpenAI 互換エンドポイントで蒸留
+
+---
+
+## 目次
+
+- [機能](#機能)
+- [インストールガイド](#インストールガイド)
+- [MCP ツール](#mcp-ツール)
+- [設定（環境変数）](#設定環境変数)
+- [CLI リファレンス](#cli-リファレンス)
+- [仕組み](#仕組み)
+- [メモリビューア](#メモリビューア)
+- [アンインストール](#アンインストール)
+- [補足](#補足)
+
+---
+
+## 機能
+
+### 1. 2 つの独立した記憶ソース
+
+| ソース | 内容 | ツール |
+|--------|------|--------|
+| **蒸留 DB** | LLM がセッションを要約 → 要約・好み・構造化メタデータ付きの埋め込みチャンク。セマンティック検索可能。 | `memory_recall`, `memory_search`, `memory_get` |
+| **生ログ検索** | 実際の Claude Code（`~/.claude/projects`）/ Codex（`~/.codex/sessions`）ログを全文検索。蒸留していないセッションも対象。 | `memory_search_logs` |
+
+蒸留 DB は整理済みで高速に想起でき、生ログ検索は claw-memory 導入前を含め「いつか話した
+こと」を必ず見つけられるセーフティネットです。
+
+### 2. 自動取り込み（distill）
+
+セッション終了時、トランスクリプトを次の形に蒸留します。
+
+- **構造化要約**（`### 依頼 / 調査・判明 / 完了 / 次の一手`）
+- **ユーザーの好み**（言語・回答スタイル・フレームワーク・口調 など）を常時適用コンテキストとして保存
+- **会話チャンク**をセマンティック検索用に埋め込み。各チャンクには
+  **observation type**（`discovery` / `bugfix` / `feature` / `decision` / `change`）、
+  **concepts**、**読んだ/編集したファイル** を付与
+
+蒸留は **増分的**（watermark で新規内容のないセッションをスキップ）かつ **冪等**
+（再蒸留は置換であり重複しない）。クロスセッションの重複チャンクも排除します。
+
+### 3. 自動 recall 注入
+
+セッション開始時（および各プロンプト時）に記憶ブロックを注入します。
+
+- **好み** は `instruction="always-apply"` — エージェントが必ず従います。
+- **直近の要約 + 類似する過去会話** は `instruction="reference-only"` — 背景として扱い、
+  不必要に蒸し返しません。
+
+これにより、文脈を再説明しなくても続きから作業できます。
+
+### 4. 構造化されたフィルタ検索
+
+`memory_search` はトークン軽量なインデックス（id + タイトル + 日付 + type）を返します。
+`type` / `concept` / `file` / 日付範囲で絞り込み、必要なものだけ `memory_get` で本文取得 —
+コンテキスト消費を最小化します。
+
+### 5. プライバシーと安全性（設計段階から）
+
+- **完全ローカル**: ストレージと埋め込みはマシン外に出ません。`distill` のみ LLM を呼び、
+  どの LLM を使うかはあなたが選択します。
+- **`<private>…</private>`** で囲んだ区間は、保存・LLM 送信の前に除去されます。
+- **`CLAW_MEMORY_EXCLUDED_PROJECTS`**: 指定パスは記録も想起もしません。
+- **`memory_forget`**: チャンクをソフト削除。検索・recall・ビューアから消えます。
+
+### 6. 差し替え可能な LLM バックエンド（distill のみ）
+
+サブスクリプションログイン（API キー不要）や任意の HTTP エンドポイントを利用できます
+（[設定](#設定環境変数)参照）。tier ルーティングで、高頻度な distill を安価なモデルに
+振り分けられます。
+
+### 7. オンデマンドな Web ビューア
+
+ビルド不要・読み取り専用のビューア（`claw-memory ui`）。プロジェクト・要約・チャンク
+（メタデータ付き）・好みを閲覧でき、生ログ検索も実行できます。SSE で開いている間は自動
+更新。起動した時だけ動きます。
+
+---
+
+## インストールガイド
+
+### 前提条件
+
+- **Node.js 20 以上**
+- サブスクリプション LLM バックエンドを使う場合: **Claude Code CLI**（ログイン済み）/ **Codex CLI**（ログイン済み）
+- 初回 `distill` 時に埋め込みモデル（約 100 MB、`~/.cache` にキャッシュ）をダウンロード
+
+### 手順 1 — パッケージをグローバルインストール
+
+```bash
+npm install -g @nogataka/claw-memory
+```
+
+グローバル導入によりフックと MCP サーバーが即座に起動します（未導入時はプラグインが
+`npx -y @nogataka/claw-memory@latest` にフォールバックし、初回が遅くなります）。
+
+### 手順 2a — Claude Code（プラグイン、推奨）
+
+```text
+/plugin marketplace add nogataka/claw-memory
+/plugin install claw-memory
+```
+
+Claude Code を再起動してください。次が自動登録されます。
+
+- **MCP サーバー**（8 つの記憶ツール）
+- **フック**: `SessionStart` / `UserPromptSubmit` → recall 注入、`Stop` → 自動 distill
+
+手動設定は不要です。確認は `/mcp` で `claw-memory` が見えるかどうかで行えます。
+
+> **プラグインを使わない場合**: `claw-memory install --claude-code` で MCP サーバーと
+> フックを `~/.claude/settings.json` にマージできます（冪等・バックアップ付き）。
+
+### 手順 2b — Codex（プラグイン）
+
+Codex は Claude Code と同じプラグイン形式に対応しています。claw-memory は
+`.codex-plugin/plugin.json` を同梱しているため、Codex プラグインとして導入すると
+MCP サーバーと**ライフサイクル hooks の両方**が登録され、Claude Code と同等になります。
+
+```
+codex
+/plugins
+```
+
+プラグインは Codex が互換提供する `${CLAUDE_PLUGIN_ROOT}` を介して次を登録します。
+
+- `claw-memory` MCP サーバー（`.mcp.json`）
+- `SessionStart` / `UserPromptSubmit` → **recall 自動注入**（memory ブロックを developer context として）
+- `Stop` → 最近の Codex セッションの**自動 distill**（watermark 重複回避・非同期）
+- `memory-recall` skill
+
+### 手順 2b（代替）— Codex（インストーラ／マーケット非経由）
+
+マーケットプレイスではなく npm から導入する場合は CLI で登録します。
+
+```bash
+claw-memory install --codex
+```
+
+これは冪等に次を行います。
+
+- `~/.codex/config.toml` に `[mcp_servers.claw-memory]` を追記（`config.toml.bak` にバックアップ）
+- `~/.codex/hooks.json` に recall/distill hooks をマージ（バックアップあり・既存 hook は保全）
+- `memory-recall` skill を配置
+- `AGENTS.md` に「セッション冒頭で `memory_recall` を呼ぶ」指示を追記
+
+Codex を再起動してください。**recall 注入・自動 distill は hooks で自動実行**され、手動操作は不要です。
+必要に応じて手動バックフィルも可能です。
+
+```bash
+claw-memory distill-codex --recent     # 最近の Codex セッションを蒸留（watermark で重複回避）
+claw-memory distill-codex --all        # 全件バックフィル
+```
+
+### 手順 2c — ソースから（開発）
+
+```bash
+git clone https://github.com/nogataka/claw-memory
+cd claw-memory
+npm install          # ネイティブの better-sqlite3 / sqlite-vec をビルド
+npm run build        # tsc -> dist/
+npm link             # 任意: `claw-memory` バイナリを公開
+```
+
+---
+
+## MCP ツール
+
+| ツール | 用途 |
+|--------|------|
+| `memory_recall(query, cwd?, topK?)` | すぐ読めるコンテキストブロック: 好み + 直近要約 + 類似する過去会話。タスク開始時に呼ぶ。 |
+| `memory_search(query, cwd?, limit?, type?, concept?, file?, dateFrom?, dateTo?)` | トークン軽量なヒットインデックス（id + タイトル + 日付 + type）。メタデータで絞り込み。 |
+| `memory_get(ids)` | 指定 id の本文 + メタデータを取得。 |
+| `memory_remember(text, cwd?, sessionId?)` | フリーテキストのメモを永続保存。 |
+| `memory_distill(cwd, sessionId? \| transcriptPath?)` | セッションを要約して記憶化（LLM バックエンドが必要）。 |
+| `memory_get_preferences(cwd?)` | プロジェクトの保存済み好みを一覧。 |
+| `memory_search_logs(query, sources?, projectPath?, startDate?, endDate?, limit?, offset?)` | Claude Code + Codex の生ログを全文検索。 |
+| `memory_forget(ids)` | チャンクをソフト削除（検索 / recall / ビューアから除外）。 |
+
+`memory_distill`（LLM）と `memory_search_logs`（`~/.claude/projects`・`~/.codex/sessions`
+を直接読む）以外は完全ローカルで動作します。
+
+---
+
+## 設定（環境変数）
+
+| 変数 | 既定値 | 用途 |
+|------|--------|------|
+| `CLAW_MEMORY_DIR` | `~/.claw-memory` | データディレクトリ（`memory.db` と `logs/`）。 |
+| `CLAW_MEMORY_LLM_BACKEND` | `agent-sdk` | `agent-sdk` \| `codex-sdk` \| `anthropic` \| `openai-compatible`。 |
+| `CLAW_MEMORY_MODEL` / `AGENT_SDK_MODEL` | `claude-sonnet-4-5` | 既定の distill モデル（agent-sdk / anthropic）。 |
+| `CLAW_MEMORY_TIER_SMART` / `_SUMMARY` / `_SIMPLE` | — | tier 別モデル上書き（安価モデルを単純作業へ）。 |
+| `CLAW_MEMORY_CODEX_MODEL` | Codex 既定 | `codex-sdk` バックエンドのモデル。 |
+| `CLAW_MEMORY_CODEX_API_KEY` | — | 任意。未設定なら Codex CLI のログインを使用。 |
+| `ANTHROPIC_API_KEY` / `ANTHROPIC_BASE_URL` | — | `anthropic` バックエンド用。 |
+| `CLAW_MEMORY_OPENAI_API_KEY` / `CLAW_MEMORY_OPENAI_BASE_URL` | — | `openai-compatible` 用（Gemini / OpenRouter / LM Studio）。 |
+| `CLAW_MEMORY_EXCLUDED_PROJECTS` | — | 記録・想起しないパス部分文字列（カンマ/コロン区切り）。 |
+| `MEMORY_SIMILARITY_MAX_DISTANCE` | `0.6` | セマンティックヒットの最大コサイン距離（小さいほど厳格）。 |
+| `CLAW_MEMORY_UI_PORT` | `4319` | ビューアのポート。 |
+
+### LLM バックエンド
+
+| バックエンド | 認証 | 備考 |
+|--------------|------|------|
+| `agent-sdk`（既定） | Claude CLI ログイン（Pro/Max/Team/Enterprise） | ゼロ設定・API キー不要 |
+| `codex-sdk` | Codex CLI ログイン（ChatGPT/Codex プラン） | `@openai/codex-sdk`。read-only・ツール無効で実行 |
+| `anthropic` | `ANTHROPIC_API_KEY` | fetch ベースの Messages API |
+| `openai-compatible` | `CLAW_MEMORY_OPENAI_API_KEY` + ベース URL + `CLAW_MEMORY_MODEL` | Gemini / OpenRouter / LM Studio |
+
+```bash
+export CLAW_MEMORY_LLM_BACKEND=codex-sdk   # Codex サブスクリプションで distill
+```
+
+---
+
+## CLI リファレンス
+
+```bash
+claw-memory mcp                                  # stdio MCP サーバー（エージェントが起動するもの）
+claw-memory ui [--port N] [--open]               # 読み取り専用 Web ビューア
+claw-memory distill --cwd P --session ID [--path FILE] [--if-stale]
+claw-memory distill-codex [--recent] [--limit N] [--all]
+claw-memory remember --cwd P "メモ"
+claw-memory search-logs "クエリ" [--source claude-code,codex] [--project P]
+                                 [--start ISO] [--end ISO] [--limit N] [--offset N]
+claw-memory hook <recall|distill>               # ライフサイクルフック（JSON を stdin で受領）
+claw-memory install   [--codex | --claude-code] # MCP + フックを登録（既定: codex）
+claw-memory uninstall [--codex | --claude-code]
+```
+
+---
+
+## 仕組み
+
+```
+[書き込み側]                                 [読み出し側]
+セッション終了 (Stop フック / distill-codex)   セッション開始 (SessionStart フック / memory_recall)
+   └ distill                                     └ buildMemoryBlock
+       ├ 要約 ───────────────► session_summaries ──► <previous-session-summaries>
+       ├ 好み ───────────────► user_preferences ───► <user-preferences>（always-apply）
+       └ チャンク(埋込+メタ) ─► vec_chunks + ────────► <relevant-past-conversations>
+                                conversation_chunks    （コサイン KNN・プロジェクト/メタ絞り込み）
+
+[別ソース] 生ログ (~/.claude/projects, ~/.codex/sessions) ──► memory_search_logs
+```
+
+- **単一の SQLite ファイル** `~/.claw-memory/memory.db`。`sqlite-vec` が 384 次元ベクトルを
+  内包し、メタデータは並列テーブル、FTS5 がキーワード fallback を提供。
+- **埋め込み** はローカルの `Xenova/multilingual-e5-small`（多言語・オフライン・e5 の
+  `query:`/`passage:` プレフィックス遵守）。モデルは MCP プロセスごとに 1 回ロード。
+- **検索** はハイブリッド: コサイン KNN（プロジェクト + メタデータで絞り込み）を FTS5 の
+  キーワードヒットで補強し、重複排除して距離順にソート。
+- 構造化された日次ログを `~/.claw-memory/logs/` に出力。
+
+---
+
+## メモリビューア
+
+```bash
+claw-memory ui --open        # http://localhost:4319
+```
+
+読み取り専用。プロジェクト・要約・会話チャンク（type / concepts / files 付き）・好みを
+閲覧でき、**🔎 ログ検索** で Claude Code + Codex の生ログを全文検索できます。開いている間
+は SSE で自動更新。それ以外はバックグラウンドで何も動きません — 確認したい時だけ起動して
+ください。
+
+---
+
+## アンインストール
+
+```bash
+claw-memory uninstall --codex          # config.toml ブロック + hooks + skill + AGENTS 記述を除去
+claw-memory uninstall --claude-code    # settings.json から mcp + フックを除去
+# Claude Code プラグイン: /plugin uninstall claw-memory
+npm uninstall -g @nogataka/claw-memory
+```
+
+メモリ DB は残ります。完全に消す場合は `~/.claw-memory` を削除してください。
+
+---
+
+## 補足
+
+- `better-sqlite3` / `sqlite-vec` はネイティブモジュールです。Node の ABI 変更後は `npm rebuild` を実行してください。
+- MCP サーバーはエージェントセッションごとに常駐するため、埋め込みモデルは 1 回だけロードされます。
+- ビューアと MCP は同時実行できます（SQLite WAL が並行読み書きを処理）。
+- インストール時、依存は `legacy-peer-deps=true` で解決されます（同梱 SDK 間の zod の
+  peer 範囲の重なりによるもの）。`.npmrc` に設定済みで無害です。

package/README.md

@@ -1,168 +1,315 @@
 # claw-memory
 
-Independent, **in-process** semantic memory for any MCP-capable agent (Claude Code, Codex, …).
-No daemon, no Python, no external vector DB.
+**English** | [日本語](README.ja.md)
 
-- **Storage**: `better-sqlite3` + `sqlite-vec` (vectors live *inside* the SQLite file)
+**Local, in-process long-term memory for AI coding agents (Claude Code & Codex).**
+Your agent remembers past sessions, your preferences, and prior decisions — and can
+search every raw transcript you've ever recorded. No daemon, no Python, no external
+vector database, no data leaving your machine (except the LLM call that summarizes a
+session, which you control).
+
+```bash
+npm install -g @nogataka/claw-memory
+```
+
+- **Storage**: `better-sqlite3` + `sqlite-vec` — vectors live *inside* one SQLite file
 - **Embeddings**: local `Xenova/multilingual-e5-small` (384-dim, multilingual, offline)
-- **Search**: semantic (cosine KNN, per-project metadata filter) + FTS5 keyword fallback
-- **Write**: LLM distillation of session transcripts → summary + preferences + chunks
-- **Viewer**: optional, on-demand lightweight web UI (no framework, no build)
+- **Two memory sources**: a distilled semantic DB **and** full-text search over raw
+  Claude Code + Codex transcripts
+- **Auto-capture**: lifecycle hooks distill finished sessions and inject relevant memory
+  back into new ones
+- **Pluggable LLM**: distill via your Claude or Codex subscription (no API key), or any
+  Anthropic / OpenAI-compatible endpoint
+
+---
+
+## Table of contents
+
+- [Features](#features)
+- [Installation guide](#installation-guide)
+- [MCP tools](#mcp-tools)
+- [Configuration](#configuration-environment-variables)
+- [CLI reference](#cli-reference)
+- [How it works](#how-it-works)
+- [Memory viewer](#memory-viewer)
+- [Uninstall](#uninstall)
+- [Notes](#notes)
+
+---
+
+## Features
+
+### 1. Two independent memory sources
+
+| Source | What it is | Tooling |
+|--------|-----------|---------|
+| **Distilled DB** | LLM-summarized sessions → summaries, preferences, and embedded conversation chunks with structured metadata. Semantically searchable. | `memory_recall`, `memory_search`, `memory_get` |
+| **Raw transcript search** | Full-text grep over your *actual* Claude Code (`~/.claude/projects`) and Codex (`~/.codex/sessions`) logs — including sessions that were never distilled. | `memory_search_logs` |
+
+The distilled DB is curated and fast to recall; raw search is a safety net that finds
+anything you ever discussed, even before claw-memory was installed.
+
+### 2. Automatic capture (distill)
+
+When a session ends, claw-memory distills the transcript into:
+
+- a **structured summary** (`### 依頼 / 調査・判明 / 完了 / 次の一手`),
+- **user preferences** (language, response style, frameworks, tone, …) applied as
+  always-on context,
+- **conversation chunks** embedded for semantic search, each tagged with an
+  **observation type** (`discovery` / `bugfix` / `feature` / `decision` / `change`),
+  **concepts**, and **files read / modified**.
+
+Distillation is **incremental** (a watermark skips sessions with no new content) and
+**idempotent** (re-distilling a session replaces, never duplicates). Cross-session
+duplicate chunks are dropped.
+
+### 3. Automatic recall injection
+
+At the start of a session (and on each prompt), claw-memory injects a memory block:
+
+- **Preferences** as `instruction="always-apply"` — the agent follows them.
+- **Recent summaries + semantically similar past conversations** as
+  `instruction="reference-only"` — used as background, not parroted back.
+
+This means the agent picks up where you left off without you re-explaining context.
+
+### 4. Structured, filterable search
+
+`memory_search` returns a token-light index (id + title + date + type). Filter by
+`type`, `concept`, `file`, or date range, then pull full bodies with `memory_get` only
+for what you need — keeping context usage minimal.
+
+### 5. Privacy & safety, by design
+
+- **Fully local**: storage and embeddings never leave your machine. Only `distill`
+  calls an LLM, and you choose which one.
+- **`<private>…</private>`** spans are stripped before anything is persisted or sent
+  to the LLM.
+- **`CLAW_MEMORY_EXCLUDED_PROJECTS`**: never record or recall listed paths.
+- **`memory_forget`**: soft-delete chunks; they vanish from search, recall, and the viewer.
+
+### 6. Pluggable LLM backend (distill only)
+
+Use a subscription login (no API key) or any HTTP endpoint — see
+[Configuration](#configuration-environment-variables). Tier routing lets cheap models
+handle the high-frequency distill work.
+
+### 7. On-demand web viewer
+
+A zero-build, read-only viewer (`claw-memory ui`) to browse projects, summaries,
+chunks (with their metadata), preferences, and to run raw-log search — with live
+updates via SSE. It runs only when you start it.
 
-Data lives at `~/.claw-memory/memory.db` (override with `CLAW_MEMORY_DIR`). Completely
-separate from any other app.
+---
 
-## Install
+## Installation guide
 
-Published as `@nogataka/claw-memory`. Install once globally so hooks/MCP resolve fast
-(otherwise they fall back to `npx`):
+### Prerequisites
+
+- **Node.js ≥ 20**
+- For the subscription LLM backends: **Claude Code CLI** (logged in) and/or **Codex CLI** (logged in)
+- First `distill` downloads the embedding model (~100 MB, cached under `~/.cache`)
+
+### Step 1 — install the package globally
 
 ```bash
 npm install -g @nogataka/claw-memory
 ```
 
-First run downloads the e5 model (~100 MB, cached in `~/.cache`).
+Installing globally makes hooks and the MCP server start instantly. (Without it, the
+plugin falls back to `npx -y @nogataka/claw-memory@latest`, which is slower on first run.)
 
-### Claude Code (plugin)
+### Step 2a — Claude Code (plugin, recommended)
 
-```
+```text
 /plugin marketplace add nogataka/claw-memory
 /plugin install claw-memory
 ```
 
-Restart Claude Code. This auto-registers the MCP server and the hooks
-(SessionStart/UserPromptSubmit → recall injection, Stop → auto-distill).
-No manual setup. (Not using the plugin? Run `claw-memory install --claude-code`
-to merge the MCP server + hooks into `~/.claude/settings.json`.)
+Restart Claude Code. This auto-registers:
+
+- the **MCP server** (8 memory tools), and
+- the **hooks**: `SessionStart` / `UserPromptSubmit` → recall injection, `Stop` → auto-distill.
 
-### Codex (installer)
+No manual config. To verify, run `/mcp` and look for `claw-memory`.
 
-Codex has no third-party plugin marketplace, so register via the installer:
+> **Not using the plugin?** Run `claw-memory install --claude-code` to merge the MCP
+> server and hooks into `~/.claude/settings.json` (idempotent, backs up the file).
+
+### Step 2b — Codex (plugin)
+
+Codex supports the same plugin format as Claude Code. claw-memory ships a
+`.codex-plugin/plugin.json` manifest, so installing it as a Codex plugin wires up
+the MCP server **and** the lifecycle hooks — full parity with Claude Code:
+
+```
+codex
+/plugins
+```
+
+The plugin registers, via Codex's `${CLAUDE_PLUGIN_ROOT}` (provided for compatibility):
+
+- the `claw-memory` MCP server (`.mcp.json`),
+- `SessionStart` / `UserPromptSubmit` → **auto recall injection** (memory block as developer context),
+- `Stop` → **auto distill** of recent Codex sessions (watermark-deduped, async), and
+- the `memory-recall` skill.
+
+### Step 2b (alt) — Codex (installer, no marketplace)
+
+If you install from npm instead of the plugin marketplace, register via the CLI:
 
 ```bash
-claw-memory install --codex      # adds [mcp_servers.claw-memory] to ~/.codex/config.toml
-                                 # + memory-recall skill + AGENTS.md recall instruction
+claw-memory install --codex
 ```
 
-Restart Codex. Recall is available via the `memory_recall` MCP tool (the AGENTS.md
-note tells the agent to call it at session start). **Auto-distill is manual on Codex**
-(no notify hook); run periodically:
+This idempotently:
+
+- adds `[mcp_servers.claw-memory]` to `~/.codex/config.toml` (backed up to `config.toml.bak`),
+- merges recall/distill hooks into `~/.codex/hooks.json` (backed up; your own hooks are preserved),
+- installs the `memory-recall` skill, and
+- appends an `AGENTS.md` instruction telling the agent to call `memory_recall` at session start.
+
+Restart Codex. **Recall injection and auto-distill now run via hooks** — no manual step needed.
+You can still backfill on demand:
 
 ```bash
 claw-memory distill-codex --recent     # distill recent Codex sessions (watermark-deduped)
 claw-memory distill-codex --all        # backfill everything
 ```
 
-Remove with `claw-memory uninstall --codex` (or `--claude-code`).
-
-### From source
+### Step 2c — from source (development)
 
 ```bash
+git clone https://github.com/nogataka/claw-memory
 cd claw-memory
-npm install      # builds native better-sqlite3 / sqlite-vec
-npm run build    # tsc -> dist/
+npm install          # builds native better-sqlite3 / sqlite-vec
+npm run build        # tsc -> dist/
+npm link             # optional: expose the `claw-memory` binary
 ```
 
+---
+
 ## MCP tools
 
 | Tool | Purpose |
 |------|---------|
-| `memory_recall(query, cwd?, topK?)` | Ready-to-read context block: preferences + summaries + similar past conversations |
-| `memory_search(query, cwd?, limit?)` | Token-efficient hit index (id + title + date) |
-| `memory_get(ids)` | Full text for given chunk ids |
-| `memory_remember(text, cwd?, sessionId?)` | Store a free-text note |
-| `memory_distill(cwd, sessionId? \| transcriptPath?)` | Summarize a session into memory (needs LLM creds) |
-| `memory_get_preferences(cwd?)` | List stored preferences |
-| `memory_search_logs(query, sources?, projectPath?, startDate?, endDate?, limit?, offset?)` | Full-text search over RAW Claude Code + Codex transcripts (second memory source; finds undistilled history) |
-| `memory_forget(ids)` | Soft-delete chunks (hidden from search/recall/viewer) |
-
-`memory_distill` uses an LLM (see *LLM backend* below). `memory_search_logs` reads
-`~/.claude/projects` and `~/.codex/sessions` directly. All other tools are fully local.
-
-## LLM backend (distill only)
-
-distill needs a single tool-less completion, selectable via `CLAW_MEMORY_LLM_BACKEND`:
+| `memory_recall(query, cwd?, topK?)` | Ready-to-read context block: preferences + recent summaries + similar past conversations. Call at the start of a task. |
+| `memory_search(query, cwd?, limit?, type?, concept?, file?, dateFrom?, dateTo?)` | Token-light hit index (id + title + date + type), with metadata filters. |
+| `memory_get(ids)` | Full text + metadata for given chunk ids. |
+| `memory_remember(text, cwd?, sessionId?)` | Store a durable free-text note. |
+| `memory_distill(cwd, sessionId? \| transcriptPath?)` | Summarize a session into memory (needs an LLM backend). |
+| `memory_get_preferences(cwd?)` | List stored preferences for the project. |
+| `memory_search_logs(query, sources?, projectPath?, startDate?, endDate?, limit?, offset?)` | Full-text search over RAW Claude Code + Codex transcripts. |
+| `memory_forget(ids)` | Soft-delete chunks (hidden from search / recall / viewer). |
+
+All tools are fully local except `memory_distill` (LLM) and `memory_search_logs`
+(reads `~/.claude/projects` and `~/.codex/sessions` directly).
+
+---
+
+## Configuration (environment variables)
+
+| Variable | Default | Purpose |
+|----------|---------|---------|
+| `CLAW_MEMORY_DIR` | `~/.claw-memory` | Data directory (holds `memory.db` and `logs/`). |
+| `CLAW_MEMORY_LLM_BACKEND` | `agent-sdk` | `agent-sdk` \| `codex-sdk` \| `anthropic` \| `openai-compatible`. |
+| `CLAW_MEMORY_MODEL` / `AGENT_SDK_MODEL` | `claude-sonnet-4-5` | Default distill model (agent-sdk / anthropic). |
+| `CLAW_MEMORY_TIER_SMART` / `_SUMMARY` / `_SIMPLE` | — | Per-tier model override (route cheap models to simple work). |
+| `CLAW_MEMORY_CODEX_MODEL` | Codex default | Model for the `codex-sdk` backend. |
+| `CLAW_MEMORY_CODEX_API_KEY` | — | Optional; otherwise the Codex CLI login is used. |
+| `ANTHROPIC_API_KEY` / `ANTHROPIC_BASE_URL` | — | For the `anthropic` backend. |
+| `CLAW_MEMORY_OPENAI_API_KEY` / `CLAW_MEMORY_OPENAI_BASE_URL` | — | For the `openai-compatible` backend (Gemini / OpenRouter / LM Studio). |
+| `CLAW_MEMORY_EXCLUDED_PROJECTS` | — | Comma/colon-separated path substrings to never record or recall. |
+| `MEMORY_SIMILARITY_MAX_DISTANCE` | `0.6` | Max cosine distance for a semantic hit (lower = stricter). |
+| `CLAW_MEMORY_UI_PORT` | `4319` | Viewer port. |
+
+### LLM backends
 
 | Backend | Auth | Notes |
 |---------|------|-------|
-| `agent-sdk` (default) | Claude Code CLI login (Claude Pro/Max/Team/Enterprise) | zero-config, no API key |
-| `codex-sdk` | Codex CLI login (ChatGPT/Codex plan) | `@openai/codex-sdk`, no API key; requires Codex CLI. Model via `CLAW_MEMORY_CODEX_MODEL` |
-| `anthropic` | `ANTHROPIC_API_KEY` (`ANTHROPIC_BASE_URL` optional) | plain Messages API |
-| `openai-compatible` | `CLAW_MEMORY_OPENAI_API_KEY` + `CLAW_MEMORY_OPENAI_BASE_URL` | Gemini / OpenRouter / LM Studio (set `CLAW_MEMORY_MODEL`) |
+| `agent-sdk` (default) | Claude CLI login (Pro/Max/Team/Enterprise) | zero-config, no API key |
+| `codex-sdk` | Codex CLI login (ChatGPT/Codex plan) | `@openai/codex-sdk`; runs read-only, no tools |
+| `anthropic` | `ANTHROPIC_API_KEY` | plain Messages API over fetch |
+| `openai-compatible` | `CLAW_MEMORY_OPENAI_API_KEY` + base URL + `CLAW_MEMORY_MODEL` | Gemini / OpenRouter / LM Studio |
 
 ```bash
-export CLAW_MEMORY_LLM_BACKEND=codex-sdk    # use the Codex subscription for distill
+export CLAW_MEMORY_LLM_BACKEND=codex-sdk   # distill using the Codex subscription
 ```
 
-Both SDK backends reuse a subscription login (no API key). Tier routing (cheap models for
-simple work): `CLAW_MEMORY_TIER_SMART` / `_SUMMARY` / `_SIMPLE`, else `AGENT_SDK_MODEL` /
-`CLAW_MEMORY_MODEL` (agent-sdk/anthropic default `claude-sonnet-4-5`; codex-sdk uses the Codex default).
-
-## Automatic capture & recall (Claude Code hooks)
+---
 
-No daemon — hooks spawn the CLI per event. Register in `~/.claude/settings.json`:
+## CLI reference
 
-```json
-{
-  "hooks": {
-    "SessionStart":     [{ "hooks": [{ "type": "command", "command": "/Volumes/Data/dev/claw-memory/hooks/claw-hook.sh recall" }] }],
-    "UserPromptSubmit": [{ "hooks": [{ "type": "command", "command": "/Volumes/Data/dev/claw-memory/hooks/claw-hook.sh recall" }] }],
-    "Stop":             [{ "hooks": [{ "type": "command", "command": "/Volumes/Data/dev/claw-memory/hooks/claw-hook.sh distill" }] }]
-  }
-}
+```bash
+claw-memory mcp                                  # stdio MCP server (what agents spawn)
+claw-memory ui [--port N] [--open]               # read-only web viewer
+claw-memory distill --cwd P --session ID [--path FILE] [--if-stale]
+claw-memory distill-codex [--recent] [--limit N] [--all]
+claw-memory remember --cwd P "a note"
+claw-memory search-logs "query" [--source claude-code,codex] [--project P]
+                                 [--start ISO] [--end ISO] [--limit N] [--offset N]
+claw-memory hook <recall|distill>               # lifecycle hook (reads JSON on stdin)
+claw-memory install   [--codex | --claude-code] # register MCP + hooks (default: codex)
+claw-memory uninstall [--codex | --claude-code]
 ```
 
-- **recall** (SessionStart / UserPromptSubmit): prints the memory block to stdout → injected into context. Preferences + recent summaries, plus semantically similar past conversations when the prompt is present.
-- **distill** (Stop): detached, fire-and-forget. Incremental via a watermark (skips sessions with no new content). Honors `CLAW_MEMORY_EXCLUDED_PROJECTS` and `<private>…</private>`.
+---
 
-## Register with an agent
+## How it works
 
-### Claude Code — `.mcp.json` (project root) or `~/.claude.json`
-
-```json
-{
-  "mcpServers": {
-    "memory": {
-      "command": "node",
-      "args": ["/Volumes/Data/dev/claw-memory/dist/cli.js", "mcp"]
-    }
-  }
-}
 ```
-
-### Codex — `~/.codex/config.toml`
-
-```toml
-[mcp_servers.memory]
-command = "node"
-args = ["/Volumes/Data/dev/claw-memory/dist/cli.js", "mcp"]
+[write path]                              [read path]
+session ends (Stop hook / distill-codex)   session starts (SessionStart hook / memory_recall)
+   └ distill                                   └ buildMemoryBlock
+       ├ summary  ───────────► session_summaries ──► <previous-session-summaries>
+       ├ preferences ────────► user_preferences ───► <user-preferences> (always-apply)
+       └ chunks (embed+meta) ─► vec_chunks + ────────► <relevant-past-conversations>
+                                conversation_chunks    (cosine KNN, per-project, filtered)
+
+[separate source] raw logs (~/.claude/projects, ~/.codex/sessions) ──► memory_search_logs
 ```
 
-Then add to your `CLAUDE.md` / `AGENTS.md`:
-> 会話の冒頭で `memory_recall` を呼び、過去の文脈と好みを取得すること。
+- **One SQLite file** at `~/.claw-memory/memory.db`. `sqlite-vec` stores 384-dim vectors
+  inside it; metadata lives in a parallel table; FTS5 provides a keyword fallback.
+- **Embeddings** run locally via `Xenova/multilingual-e5-small` (multilingual, offline,
+  e5 `query:`/`passage:` prefixing). The model loads once per MCP process.
+- **Search** is hybrid: cosine KNN (filtered by project + metadata) augmented with FTS5
+  keyword hits, de-duplicated and distance-sorted.
+- Daily structured logs are written to `~/.claw-memory/logs/`.
+
+---
 
 ## Memory viewer
 
 ```bash
-npm run ui            # http://localhost:4319 , opens browser
-# or
-node dist/cli.js ui --port 4319 --open
+claw-memory ui --open        # http://localhost:4319
 ```
 
-Read-only. Browse projects, session summaries, conversation chunks and preferences.
-Start it only when you want to inspect; nothing runs in the background otherwise.
+Read-only. Browse projects, session summaries, conversation chunks (with type /
+concepts / files), and preferences; toggle **🔎 ログ検索** to full-text search raw
+Claude Code + Codex transcripts. Live-updates via SSE while open. Nothing runs in the
+background otherwise — start it only when you want to inspect.
 
-## CLI
+---
+
+## Uninstall
 
 ```bash
-node dist/cli.js mcp                                   # stdio MCP server
-node dist/cli.js ui [--port N] [--open]                # viewer
-node dist/cli.js distill --cwd <dir> --session <id>    # distill a CC session
-node dist/cli.js remember --cwd <dir> "a note"         # store a note
+claw-memory uninstall --codex          # remove config.toml block + hooks + skill + AGENTS note
+claw-memory uninstall --claude-code    # remove mcp + hooks from settings.json
+# Claude Code plugin: /plugin uninstall claw-memory
+npm uninstall -g @nogataka/claw-memory
 ```
 
+Your memory database is left untouched; delete `~/.claw-memory` to wipe it.
+
+---
+
 ## Notes
 
-- `better-sqlite3` / `sqlite-vec` are native; rebuild on Node ABI changes (`npm rebuild`).
+- `better-sqlite3` / `sqlite-vec` are native modules; run `npm rebuild` after a Node ABI change.
 - The MCP server is long-lived per agent session, so the embedding model loads once.
-- Viewer + MCP can run simultaneously (SQLite WAL handles concurrent read/write).
+- Viewer + MCP can run simultaneously — SQLite WAL handles concurrent read/write.
+- On install, dependencies resolve with `legacy-peer-deps=true` (a zod peer-range overlap
+  between bundled SDKs); this is configured in `.npmrc` and is harmless.

package/dist/cli.js

@@ -88,7 +88,7 @@ async function main() {
             if (target === "codex") {
                 const { installCodex } = await import("./core/installer/codex.js");
                 console.log("claw-memory installed for Codex:\n  " + installCodex().join("\n  "));
-                console.log("\n注意: Codex を再起動してください。自動 distill は手動 (`claw-memory distill-codex --recent`)。");
+                console.log("\n注意: Codex を再起動してください。recall 注入・自動 distill は hooks で自動実行されます。");
             }
             else {
                 const { installClaude } = await import("./core/installer/claude.js");

package/dist/core/installer/codex.js

@@ -13,7 +13,17 @@ import { readFileSync, writeFileSync, existsSync, mkdirSync, copyFileSync, rmSyn
 const CODEX_DIR = join(homedir(), ".codex");
 const CONFIG = join(CODEX_DIR, "config.toml");
 const AGENTS = join(CODEX_DIR, "AGENTS.md");
+const HOOKS = join(CODEX_DIR, "hooks.json");
 const SKILL_DIR = join(CODEX_DIR, "skills", "memory-recall");
+// Codex lifecycle hooks for the manual (non-plugin) install path. Mirrors the
+// Claude Code hook wiring: recall on session start / prompt, distill on stop.
+// Codex Stop carries no Claude-format transcript, so distill scans recent Codex
+// session files (watermark-guarded) instead of a single transcript_path.
+const HOOK_EVENTS = [
+    ["SessionStart", "hook recall", false],
+    ["UserPromptSubmit", "hook recall", false],
+    ["Stop", "distill-codex --limit 5", true],
+];
 const BEGIN = "# >>> claw-memory >>>";
 const END = "# <<< claw-memory <<<";
 const A_BEGIN = "<!-- >>> claw-memory >>> -->";
@@ -24,18 +34,73 @@ function tomlStr(s) {
 }
 /** Prefer a globally installed `claw-memory`; otherwise run via npx. */
 function resolveCommand() {
+    const bin = resolveBin();
+    return bin
+        ? { command: bin, args: ["mcp"] }
+        : { command: "npx", args: ["-y", "@nogataka/claw-memory@latest", "mcp"] };
+}
+/** Absolute path to a globally installed `claw-memory`, or null. */
+function resolveBin() {
     try {
         const found = execFileSync("command", ["-v", "claw-memory"], {
             shell: "/bin/bash",
             encoding: "utf-8",
-        }).trim();
-        if (found)
-            return { command: found.split("\n")[0], args: ["mcp"] };
+        }).trim().split("\n")[0];
+        return found || null;
+    }
+    catch {
+        return null;
+    }
+}
+/** How to invoke the CLI from a hook command line. */
+function cliInvoker() {
+    return resolveBin() ?? "npx -y @nogataka/claw-memory@latest";
+}
+function readHooks() {
+    if (!existsSync(HOOKS))
+        return {};
+    try {
+        return JSON.parse(readFileSync(HOOKS, "utf-8"));
     }
     catch {
-        // not on PATH
+        return {};
     }
-    return { command: "npx", args: ["-y", "@nogataka/claw-memory@latest", "mcp"] };
+}
+/** A hook command is ours if it runs the claw-memory CLI recall/distill subcommand. */
+function isOurHook(cmd) {
+    return cmd.includes("claw-memory") && (cmd.includes("hook recall") || cmd.includes("distill-codex"));
+}
+/** Merge our recall/distill hooks into ~/.codex/hooks.json, replacing stale ones. */
+function installHooks() {
+    const cli = cliInvoker();
+    const f = readHooks();
+    f.hooks = f.hooks ?? {};
+    for (const [event, sub, isAsync] of HOOK_EVENTS) {
+        const list = (f.hooks[event] ?? []).filter((g) => !g.hooks?.some((h) => isOurHook(h.command)));
+        list.push({ hooks: [{ type: "command", command: `${cli} ${sub}`, async: isAsync }] });
+        f.hooks[event] = list;
+    }
+    if (existsSync(HOOKS))
+        copyFileSync(HOOKS, HOOKS + ".bak");
+    writeFileSync(HOOKS, JSON.stringify(f, null, 2) + "\n");
+}
+/** Remove our hooks from ~/.codex/hooks.json, preserving the user's own. */
+function removeHooks() {
+    if (!existsSync(HOOKS))
+        return false;
+    const f = readHooks();
+    if (!f.hooks)
+        return false;
+    for (const event of Object.keys(f.hooks)) {
+        f.hooks[event] = f.hooks[event]
+            .map((g) => ({ ...g, hooks: (g.hooks ?? []).filter((h) => !isOurHook(h.command)) }))
+            .filter((g) => g.hooks.length > 0);
+        if (f.hooks[event].length === 0)
+            delete f.hooks[event];
+    }
+    copyFileSync(HOOKS, HOOKS + ".bak");
+    writeFileSync(HOOKS, JSON.stringify(f, null, 2) + "\n");
+    return true;
 }
 /** Insert or replace the marker-delimited block in `content`. */
 function upsertBlock(content, begin, end, block) {
@@ -98,6 +163,9 @@ export function installCodex() {
     const agentsPrev = existsSync(AGENTS) ? readFileSync(AGENTS, "utf-8") : "";
     writeFileSync(AGENTS, upsertBlock(agentsPrev, A_BEGIN, A_END, agentsBlock));
     done.push("AGENTS.md: recall instruction");
+    // 4) lifecycle hooks: auto recall (SessionStart/UserPromptSubmit) + auto distill (Stop)
+    installHooks();
+    done.push("hooks.json: SessionStart/UserPromptSubmit→recall, Stop→distill-codex");
     return done;
 }
 export function uninstallCodex() {
@@ -111,6 +179,9 @@ export function uninstallCodex() {
         writeFileSync(AGENTS, removeBlock(readFileSync(AGENTS, "utf-8"), A_BEGIN, A_END));
         done.push("AGENTS.md: removed claw-memory block");
     }
+    if (removeHooks()) {
+        done.push("hooks.json: removed claw-memory hooks");
+    }
     try {
         rmSync(SKILL_DIR, { recursive: true, force: true });
         done.push("skill: removed");

package/hooks/hooks.codex.json

@@ -0,0 +1,37 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.cmd\" claw-hook.sh hook recall",
+            "async": false
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.cmd\" claw-hook.sh hook recall",
+            "async": false
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.cmd\" claw-hook.sh distill-codex --limit 5",
+            "async": true
+          }
+        ]
+      }
+    ]
+  }
+}

package/hooks/hooks.json

@@ -5,7 +5,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "'${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.cmd' claw-hook.sh hook recall",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.cmd\" claw-hook.sh hook recall",
             "async": false
           }
         ]
@@ -16,7 +16,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "'${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.cmd' claw-hook.sh hook recall",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.cmd\" claw-hook.sh hook recall",
             "async": false
           }
         ]
@@ -27,7 +27,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "'${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.cmd' claw-hook.sh hook distill",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.cmd\" claw-hook.sh hook distill",
             "async": true
           }
         ]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nogataka/claw-memory",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "type": "module",
   "description": "Independent, in-process semantic memory MCP server (sqlite-vec + local Xenova e5) with a lightweight web viewer. No daemon, no Python. Installable as a Claude Code plugin and a Codex MCP server.",
   "license": "MIT",
@@ -26,8 +26,10 @@
     "hooks",
     "skills",
     ".claude-plugin",
+    ".codex-plugin",
     ".mcp.json",
-    "README.md"
+    "README.md",
+    "README.ja.md"
   ],
   "engines": {
     "node": ">=20.0.0"