@tomingtoming/kioq 0.7.0 → 0.8.0

package/README.md

@@ -1,294 +1,37 @@
 # kioq
 
-`kioq` は `basic-memory` 非依存の MCP サーバです。
-単一の Markdown ノートルートを扱い、知識の記録と参照を `FileSystem` または `GitHub` storage で運用します。
+Markdown ノートを WikiLink で構造化する MCP サーバ。日本語ファーストで、ローカルと GitHub の両方に対応。
 
-## 目的
+## クイックスタート
 
-- 日本語タイトル/本文でも扱いやすいノート操作
-- 単一ノートルートを軽量に運用できる構成
-- ローカル保存と GitHub 共有の両方に対応
-- 外部メモリサーバに依存しないシンプル運用
-
-## 設計境界
-
-`kioq` では、`アプリケーション` と `保存データ` を分けて扱います。
-
-- `kioqアプリケーション`
-  - このリポジトリにある MCP サーバ本体
-  - 第三者が空の保存先から使い始めても価値がある必要がある
-  - 特定ユーザーの既存ノートや現在の `kioq` データを前提にしない
-- `kioqデータ`
-  - MCP の保存先に作られる Markdown ノート群
-  - 利用者ごとに内容も構造も異なる
-  - このリポジトリに同梱される前提ではない
-
-つまり、`kioq` 本体の改善は「任意の利用者がゼロから使えるか」で評価し、長期記憶データの改善は「保存されたノート群が自己完結して再利用できるか」で評価します。
-
-## Memory Contract
-
-`memory_contract` ツールで、AI運用時の共通ルールを取得できます。
-- `response_mode=minimal|standard|verbose`
-- `minimal` は契約の骨子だけ
-- `standard` は policy と閾値まで
-- `verbose` で sample template 本文まで返します
-- `response_mode_policy` も含み、どのツールが `response_mode` を持つか、各 mode をどう使い分けるかを runtime から読めます
-
-- 共通必須 frontmatter: `type`, `tags`, `created`, `updated`, `permalink`
-- `flow` 追加必須 frontmatter: `memory_kind`, `flow_state`, `question`, `next_action`, `parent_stock`
-- 通常ノート最低要件:
-  - 解決済みWikiLink `2` 以上
-  - バックリンク `1` 以上
-  - 親リンク `1` 以上（行内に `親` / `parent` / `上位` / `MOC` / `Index` を含む）
-  - 関連リンク `1` 以上
-  - 未解決WikiLink `0`
-  - tags `1` 以上
-- `flow` 最低要件:
-  - 解決済みWikiLink `2` 以上
-  - バックリンク `0` 以上
-  - 親リンク `1` 以上
-  - 関連リンク `1` 以上
-  - 未解決WikiLink `0`
-  - tags `1` 以上
-- optional policy:
-  - `source_ref` は canonical な source 参照
-  - `source_id`, `source_root_ref` は補助
-  - 絶対パスは保存しない
-  - source metadata は任意で、本文の自己完結性を優先
-- index navigation policy:
-  - `flow` は index 候補から除外
-  - `index_tag=70`, `title_marker=45`, `permalink_marker=35`, `path_marker=25`, `section:*=20`, `multi_index_sections=20`, `link_hub=10`
-  - `score >= 70` または `index section >= 2` で `index_like=true`
-  - 閾値は `KIOQ_INDEX_SCORE_THRESHOLD` / `KIOQ_INDEX_SECTION_THRESHOLD` または `--index-score-threshold` / `--index-section-threshold` で調整できる
-  - この policy は `memory_contract` から runtime でも参照できる
-- `memory_contract` には `sample_template_stock` / `sample_template_flow` / `sample_template_index` も含まれる
-  - これは `verbose` のときに返る
-
-## 提供ツール
-
-- `recent_notes`: 最近更新ノート一覧（`response_mode` で軽量化可能。`verbose` では `index_like_reasons`, `recommended_indexes`, `project_health` も返す）
-- `search_notes`: ノート検索（日本語正規化 + 形態素分割 + CJK N-gram。`standard` 以上で `exploration_guidance`、`verbose` では `recommended_indexes` と `index_like_reasons` も返す）
-- `read_note`: ノート読取（候補提示強化。`standard` で link health と `document_clarity`、`verbose` で `index_note_candidates`, `index_like_reasons`, `clarity_attention_reasons` も返す）
-- `resolve_links`: ノート内 WikiLink の解決結果（`verbose` で `index_like` / `index_like_reasons` と `index_note_candidates` を返す）
-- `list_backlinks`: バックリンク一覧（`verbose` で target の `index_like` / `target_index_like_reasons` と `index_note_candidates` を返す）
-- `context_bundle`: 指定ノート中心の関連ノート束を優先度付きで返却（`standard` 以上で `exploration_guidance`、`verbose` で source の `index_like` / `source_index_like_reasons` と `index_note_candidates` を返す）
-- `memory_contract`: AI運用向けの構造化ルール（Memory Contract）を返却（`response_mode=minimal|standard|verbose`。`verbose` で sample template 本文まで返す）
-- `lint_structure`: 構造化のためのノートルート診断（`response_mode=minimal|standard|verbose` 対応。先頭に `primary_*` 要約を返し、優先度付き issue に加え、`stale_flow_count`, `stale_flow_age_buckets`, `oldest_stale_flow_days`, `cleanup_ratio`, `cleanup_ready_count`, `attention_note_count`, `dependency_direction_violation_count`, `single_use_tag_candidate_count`, `title_body_mismatch_candidate_count`, `unresolved_wikilinks_delta` の debt signal を返却。`dependency_direction_violation_count` は stock ノートが parent として flow を指している件数、`single_use_tag_candidate_count` は非 flow ノートで単発 tag を 2 件以上持つノート候補数、`title_body_mismatch_candidate_count` は title の中核語が本文見出し/要約に現れない非 flow ノート候補数で、後ろ 2 つは候補 signal のため `cleanup_ratio` には含めない。さらに orphan があるときは `orphan_repair_queue` で suggested parent を返す。現状 `delta` は `requires_history` として明示）
-- `write_note`: ノート作成/更新（structure score + memory contract判定, template hint, 未解決 WikiLink, 候補リンク+候補理由, link health, backlinks, orphan warning, 重複警告, project_health を通知）
-- `write_flow_note`: flow ノート作成/更新（Question/Next Action/親リンクをテンプレート化し、template hint, parent_stock 解決可否と project_health を返却）
-- `promote_to_stock`: flow を stock に昇格（stock 生成 + flow_state=promoted 更新 + template hint + project_health）
-- `append_note`: ノート追記（未存在時の自動作成可、structure score + memory contract判定, 未解決 WikiLink, 候補リンク+候補理由, link health, backlinks, orphan warning, 重複警告, project_health を通知。新規作成時は template hint も返却）
-- `write_note` / `write_flow_note` / `append_note` / `rename_note` / `delete_note` は `conflict_type`, `server_updated`, `retry_hint` も返し、並行編集前提の再試行導線を固定する
-- `delete_note`: ノート削除（削除前の structure score + memory contract判定, 削除前後の link health 差分, 影響 backlink 数, `impact_score`, `requires_backup`, 未解決 WikiLink 候補, project_health を通知）
-- `rename_note`: リネーム + WikiLink 追従更新（structure score + memory contract判定, 影響の before/after, `impact_score`, `requires_backup`, 候補リンク, backlinks, orphan warning, project_health を通知）
-
-読み取り系ツール (`recent_notes`, `search_notes`, `read_note`, `resolve_links`, `list_backlinks`, `context_bundle`) には `response_mode=minimal|standard|verbose` があり、既定は `standard` です。
-
-監査系では `lint_structure` も `response_mode=minimal|standard|verbose` を持ちます。
-- `minimal`: 先頭要約と件数中心
-- `standard`: debt breakdown と compact issue 一覧
-- `verbose`: issue の message / suggestion まで含む詳細
-
-`lint_structure` と `memory_contract` は、必要なら次に上げるべき粒度も返します。
-- `recommended_response_mode`
-- `response_mode_hint`
-
-さらに、これらの読み取り系ツールは先頭に次の要約を返します。
-
-- `scope_label`
-- `primary_navigation_signal`
-- `primary_quality_signal`
-- `next_recommended_action`
-- `next_recommended_target` (ある場合のみ)
-- `change_trigger`
-- `trigger_confidence` / `cascade_targets` / `noise_risk` (ある場合のみ)
-- `boundary_warnings` (ある場合のみ)
-
-書き込み系ツール (`write_note`, `write_flow_note`, `promote_to_stock`, `append_note`, `delete_note`, `rename_note`) も先頭に同じ `primary_*` 要約を返します。
-`read_note` / `resolve_links` / `list_backlinks` / `context_bundle` / `write_note` / `write_flow_note` / `append_note` では、短い `responsibility_warning` も返し、責務逸脱がなければ `none`、あれば warning code を返します。
-`write_note` / `append_note` / `read_note` / `resolve_links` / `list_backlinks` / `context_bundle` では、静的に判定できる境界逸脱があれば `boundary_warnings` を返します。現状は `flow` 形の内容が generic note に保存されているケースと、`index/MOC` 形の入口ノートが `flow` として保存されているケースを検出します。
-
-## Flow / Stock 運用
-
-- `write_flow_note` は既定で `Flow/` 配下に保存し、`memory_kind=flow` を付与
-- `promote_to_stock` は既定で `Stock/` 配下に保存し、flow 側へ昇格リンクを追記
-- `context_bundle` はリンク関係・タグ重なり・ディレクトリ近接を使って周辺文脈を返却
-
-この `Flow / Stock` は保存データ側の運用規約です。`kioq` アプリ自体は、利用者が別の規約を採ることも許容します。
-
-## 索引ノートパターン
-
-ノート数が増えると、個別検索だけでは再訪導線が弱くなります。`kioq` では `MOC` / `Index` / `インデックス` を含む親リンクを Memory Contract の parent marker として扱うため、索引ノートを一般パターンとして採用しやすくしています。
-
-推奨用途:
-
-- テーマ別の再訪入口を作る
-- 監査ノート群や source metadata 系ノートの入口を一本化する
-- `まず何を読むか` を固定する
-
-推奨構成:
-
-- `- 親: [[上位計画 or MOC]]`
-- `- 関連: [[関連Flow or 監査ノート]]`
-- `## 目的`
-- `## テーマ別入口`
-- `## まず何を読むか`
-
-これは `Flow / Stock` と同じく保存データ側の推奨パターンであり、アプリ本体の必須仕様ではありません。
-
-## ノートテンプレート
-
-`kioq` は専用テンプレート機能を持ちませんが、`memory_contract` と docs から最小テンプレートを参照できます。
-
-- `stock`: 再利用知識を残す通常ノート
-- `flow`: 進行中の問いと次アクションを残すノート
-- `index`: 再訪導線を固定する入口ノート
-
-テンプレート例は [`docs/note-templates.md`](docs/note-templates.md) にまとめています。
-
-## Source Metadata 規約
-
-`kioq` 本体は任意の frontmatter を保持します。`source_ref` などの source metadata はアプリの必須仕様ではなく、外部 corpus 取り込み時の推奨規約です。
-
-- `source_ref`
-  - canonical な参照キー
-  - 推奨形式: `<corpus>/<item>` または `<corpus>/<relative/path>`
-  - 例: `x-bookmarks/important/1922857510169407589`
-- `source_id`
-  - 数値IDや外部システムIDを持つ corpus 向けの補助キー
-  - `source_ref` がある場合でも併記してよいが、主キーにはしない
-- `source_root_ref`
-  - corpus 全体の別名
-  - item 単位の `source_ref` を補足したいときだけ使う
-
-運用ルール:
-
-- 絶対パスは保存しない
-- `source_ref` を canonical、`source_id` を auxiliary として扱う
-- source metadata がなくてもノート本文だけで意味が通る状態を優先する
-
-この規約は現行データ運用で有効だったもので、第三者もそのまま採用できるが、MCP ツールの必須入力ではない。
-
-## Storage Modes
-
-- `FileSystem`
-  - ローカルディレクトリをそのままノートルートとして扱います
-  - `--root` または `KIOQ_ROOT` を指定します
-  - ルートが存在しない場合は自動作成されます
-- `GitHub`
-  - 読み取りと同期はローカル clone、書き込みは GitHub Git Data API を使います
-  - `--github owner/repo` と `KIOQ_GITHUB_TOKEN` を使います
-  - `--root` はローカル clone のパスです。省略時は `~/.cache/kioq/<owner>/<repo>` を使います
-  - ローカル clone は事前に用意してください
-  - 起動時に token / repo / branch / local clone / `git pull --ff-only` を self-check します
-
-現行版は `1 server = 1 note root` です。複数の保存先を使いたい場合は、MCP サーバを複数起動してください。旧 `project` パラメータや `list_projects` ツールはありません。
-
-## セットアップ
+### ローカル
 
 ```bash
-npm install
+npx @tomingtoming/kioq --root /path/to/notes
 ```
 
-## 設定
-
-### 共通環境変数
-
-- `KIOQ_ROOT`: ノートルート。`FileSystem` モードでは必須、`GitHub` モードでは省略時に `~/.cache/kioq/<owner>/<repo>` を使う
-- `KIOQ_DEFAULT_DIRECTORY`: `write_note` の既定ディレクトリ（default: `Inbox`）
-- `KIOQ_PREVIEW_LENGTH`: 検索抜粋の最大文字数（default: `320`）
-- `KIOQ_INDEX_SCORE_THRESHOLD`: `index_like` 判定の score 閾値（default: `70`）
-- `KIOQ_INDEX_SECTION_THRESHOLD`: `index_like` 判定の section 数閾値（default: `2`）
-- `KIOQ_STALE_FLOW_DAYS`: `stale_flow_count` 判定の日数閾値（default: `7`）
-
-### GitHub モード用環境変数
-
-- `KIOQ_GITHUB`: `owner/repo`
-- `KIOQ_GITHUB_TOKEN`: 書き込み権限のある GitHub token
-- `KIOQ_GITHUB_BRANCH`: 対象 branch（default: `main`）
-
-### 起動引数
-
-- `--root <path>`
-- `--github <owner/repo>`
-- `--github-branch <branch>`
-- `--default-directory <dir>`
-- `--preview-length <number>`
-- `--index-score-threshold <number>`
-- `--index-section-threshold <number>`
-- `--stale-flow-days <number>`
-
-引数は環境変数より優先されます。
+空ディレクトリでも開始できる。
 
-### 最小構成: FileSystem
-
-```bash
-npx tsx index.ts --root /ABSOLUTE/PATH/TO/kioq-memory
-```
-
-- 空ディレクトリでも開始できます
-- 書き込みはそのままローカル filesystem に反映されます
-
-### 最小構成: GitHub
-
-```bash
-git clone git@github.com:USERNAME/kioq-memory.git /ABSOLUTE/PATH/TO/kioq-memory
-
-export KIOQ_GITHUB_TOKEN=YOUR_TOKEN
-
-npx tsx index.ts \
-  --github USERNAME/kioq-memory \
-  --root /ABSOLUTE/PATH/TO/kioq-memory
-```
-
-- `GitHub` モードではローカル clone が必須です
-- `--root` を省略した場合、既定の clone 置き場は `~/.cache/kioq/<owner>/<repo>` です
-- token は `KIOQ_GITHUB_TOKEN` で渡します
-- 書き込みは GitHub API に `Bearer` token で送信され、`rename_note` / `promote_to_stock` などの複数変更は 1 commit にまとまります
-- 同期はローカル clone に対する `git pull --ff-only` です。remote が SSH なら SSH 鍵、HTTPS なら credential helper が使われます
-- 一時的な `502/503/504` や rate limit 系の失敗は自動で再試行します
-
-## 起動
-
-```bash
-npm run start -- --root /ABSOLUTE/PATH/TO/kioq-memory
-```
-
-推奨 (`tsx` 直接起動):
+### GitHub
 
 ```bash
-npx tsx index.ts --root /ABSOLUTE/PATH/TO/kioq-memory
-
-export KIOQ_GITHUB_TOKEN=YOUR_TOKEN
+git clone git@github.com:you/notes.git ~/notes
 
-npx tsx index.ts \
-  --github USERNAME/kioq-memory \
-  --root /ABSOLUTE/PATH/TO/kioq-memory
+KIOQ_GITHUB_TOKEN=ghp_... npx @tomingtoming/kioq --github you/notes --root ~/notes
 ```
 
-`tsc` ビルド経由で起動:
+`--root` を省略すると `~/.cache/kioq/<owner>/<repo>` に自動配置。書き込みは GitHub API 経由で、`rename_note` 等の複数ファイル変更も 1 commit にまとまる。
 
-```bash
-npm run start:tsc -- --root /ABSOLUTE/PATH/TO/kioq-memory
-```
-
-## MCP 設定例 (`tsx` 起動)
+## MCP 設定例
 
-### FileSystem
+### ローカル
 
 ```json
 {
   "mcpServers": {
     "kioq": {
       "command": "npx",
-      "args": [
-        "tsx",
-        "index.ts",
-        "--root",
-        "/ABSOLUTE/PATH/TO/kioq-memory"
-      ],
-      "cwd": "/ABSOLUTE/PATH/TO/kioq",
-      "env": {}
+      "args": ["@tomingtoming/kioq", "--root", "/absolute/path/to/notes"]
     }
   }
 }
@@ -299,88 +42,73 @@ npm run start:tsc -- --root /ABSOLUTE/PATH/TO/kioq-memory
 ```json
 {
   "mcpServers": {
-    "kioq-github": {
+    "kioq": {
       "command": "npx",
-      "args": [
-        "tsx",
-        "index.ts",
-        "--github",
-        "USERNAME/kioq-memory",
-        "--root",
-        "/ABSOLUTE/PATH/TO/kioq-memory"
-      ],
-      "cwd": "/ABSOLUTE/PATH/TO/kioq",
+      "args": ["@tomingtoming/kioq", "--github", "you/notes"],
       "env": {
-        "KIOQ_GITHUB_TOKEN": "YOUR_TOKEN"
+        "KIOQ_GITHUB_TOKEN": "ghp_..."
       }
     }
   }
 }
 ```
 
-## MCP 設定例 (`tsc` 起動)
+## 提供ツール
 
-### FileSystem
+### 読み取り
+
+| ツール | 概要 |
+|--------|------|
+| `search_notes` | 日本語対応の全文検索（形態素分割 + CJK N-gram） |
+| `read_note` | ノート読み取り + リンク健全性 + 構造スコア |
+| `recent_notes` | 最近更新されたノート一覧 |
+| `resolve_links` | ノート内 WikiLink の解決状況 |
+| `list_backlinks` | 被リンク一覧 |
+| `context_bundle` | 関連ノートの優先度付き束 |
+| `lint_structure` | ノートルート全体の構造診断 |
+| `memory_contract` | AI 運用向けの構造化ルール |
+
+### 書き込み
+
+| ツール | 概要 |
+|--------|------|
+| `write_note` | ノート作成・更新 |
+| `write_flow_note` | 進行中の問い（Flow）を作成 |
+| `promote_to_stock` | Flow を Stock に昇格（1 commit で原子的に） |
+| `append_note` | 既存ノートに追記 |
+| `rename_note` | リネーム + 全バックリンク自動更新 |
+| `delete_note` | 削除 + 影響度レポート |
+
+全ツールに `response_mode=minimal|standard|verbose` あり。
+
+## 環境変数
+
+| 変数 | 説明 | デフォルト |
+|------|------|-----------|
+| `KIOQ_ROOT` | ノートルートのパス | (必須 / GitHub 時は自動) |
+| `KIOQ_GITHUB` | `owner/repo` 形式 | — |
+| `KIOQ_GITHUB_TOKEN` | GitHub token | — |
+| `KIOQ_GITHUB_BRANCH` | 対象ブランチ | `main` |
+| `KIOQ_DEFAULT_DIRECTORY` | 新規ノートの既定ディレクトリ | `Inbox` |
+| `KIOQ_PREVIEW_LENGTH` | 検索抜粋の最大文字数 | `320` |
+| `KIOQ_INDEX_SCORE_THRESHOLD` | index_like 判定の score 閾値 | `70` |
+| `KIOQ_INDEX_SECTION_THRESHOLD` | index_like 判定の section 数閾値 | `2` |
+| `KIOQ_STALE_FLOW_DAYS` | stale flow 判定の日数 | `7` |
+
+全て `--` 付き CLI 引数でも指定可能（例: `--root`, `--github`, `--default-directory`）。引数は環境変数より優先。
 
-```json
-{
-  "mcpServers": {
-    "kioq": {
-      "command": "npm",
-      "args": [
-        "run",
-        "start:tsc",
-        "--",
-        "--root",
-        "/ABSOLUTE/PATH/TO/kioq-memory"
-      ],
-      "cwd": "/ABSOLUTE/PATH/TO/kioq",
-      "env": {}
-    }
-  }
-}
-```
+## ドキュメント
 
-### GitHub
-
-```json
-{
-  "mcpServers": {
-    "kioq-github": {
-      "command": "npm",
-      "args": [
-        "run",
-        "start:tsc",
-        "--",
-        "--github",
-        "USERNAME/kioq-memory",
-        "--root",
-        "/ABSOLUTE/PATH/TO/kioq-memory"
-      ],
-      "cwd": "/ABSOLUTE/PATH/TO/kioq",
-      "env": {
-        "KIOQ_GITHUB_TOKEN": "YOUR_TOKEN"
-      }
-    }
-  }
-}
-```
+- [`docs/architecture.md`](docs/architecture.md) — アーキテクチャ
+- [`docs/note-templates.md`](docs/note-templates.md) — stock / flow / index テンプレート
+- [`docs/application-data-separation.md`](docs/application-data-separation.md) — アプリとデータの責務分離
+- [`docs/index-note-pattern.md`](docs/index-note-pattern.md) — 索引ノートパターン
+- [`docs/source-metadata.md`](docs/source-metadata.md) — source_ref 規約
 
 ## 開発
 
 ```bash
-npm run check
-npm run build
+npm install
+npm run check   # 型チェック
+npm test        # ビルド + テスト
 ```
-
-## ドキュメント
-
-- `docs/architecture.md`: 現行アーキテクチャ
-- `docs/application-data-separation.md`: アプリ本体と保存データの責務分離
-- `docs/index-navigation-heuristics.md`: `index_like` 判定と調整方針
-- `docs/index-note-pattern.md`: 索引ノートの一般パターン
-- `docs/note-templates.md`: stock / flow / index の最小テンプレート
-- `docs/source-metadata.md`: source_ref / source_id の推奨規約
-- `docs/usability-improvements.md`: 使い勝手改善の履歴
-- `docs/basic-memory-findings.md`: 参考調査（runtime 依存はなし）
-- `research/basic-memory/2026-02-28-basic-memory-usability-trial.md`: 実験ログ

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tomingtoming/kioq",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Japanese-first local markdown MCP server",
   "type": "module",
   "bin": {