GhostPaw Questlog

@ghostpaw/questlog

書き記した成果をもってのみ完了となる、エージェントタスクのクエスト。

npm install @ghostpaw/questlog

SQLite を基盤とする、Node.js 向けの統合タスク・カレンダーモデルです。

Questlog は、タスク、イベント、締め切り、定期的な予定、未整理の受付項目を個別のシステムではなく、一貫したデータモデルとして扱います。ランタイム依存関係ゼロの、事前にバンドルされた単一ファイルとして提供されます。コードを直接扱う人間の開発者と、構造化されたツールファサードを介して動作する LLM エージェントの両方を対象に設計されています。

MCP サーバー

以下の各クライアントは、同じ stdio サーバーを起動します：npx -y @ghostpaw/questlog mcp。 GHOSTPAW_QUESTLOG_DB 環境変数（絶対パス）または --db <path> で別の場所を指定しない限り、データは ~/.ghostpaw/questlog.db に保存されます。

Claude Code

claude mcp add ghostpaw-questlog -- npx -y @ghostpaw/questlog mcp

または、スキルもインストールするプラグインとして使用できます：

/plugin marketplace add GhostPawJS/questlog
/plugin install ghostpaw-questlog@ghostpaw-questlog

Codex CLI（~/.codex/config.toml）

[mcp_servers.ghostpaw-questlog]
command = "npx"
args = ["-y", "@ghostpaw/questlog", "mcp"]

Cursor（.cursor/mcp.json）、Claude Desktop（claude_desktop_config.json） またはプロジェクトの .mcp.json：

{
  "mcpServers": {
    "ghostpaw-questlog": {
      "command": "npx",
      "args": ["-y", "@ghostpaw/questlog", "mcp"]
    }
  }
}

Claude Desktop のユーザーは、最新の GitHub リリースから server.mcpb をインストールすることもできます。 コンテナホスト向けに Dockerfile も含まれています： docker build -t ghostpaw-questlog . && docker run -i --rm -v questlog:/data ghostpaw-questlog。

サーバーは MCP 2026-07-28（ステートレス、server/discover）および initialize ベースのリビジョン 2025-11-25、2025-06-18、2025-03-26、2024-11-05 に対応しています。

CLI

npx -y @ghostpaw/questlog tools
npx -y @ghostpaw/questlog call capture_rumor '{"title":"Review release notes"}'
npx -y @ghostpaw/questlog call search_questlog '{"query":"release notes"}'

ghostpaw-questlog バイナリを使用するには、グローバルにインストールします：npm i -g @ghostpaw/questlog。 ghostpaw-questlog mcp で stdio サーバーを起動します。

エージェントスキル

SKILL.md（リポジトリのルート）と skills/questlog/SKILL.md は、 Agent Skills の形式に準拠しており、npm パッケージに同梱されています。 skills/questlog/ をエージェントのスキルフォルダーにコピーするか、内容を出力します：

npx -y @ghostpaw/questlog skill > SKILL.md

インストール

npm install @ghostpaw/questlog

Node.js 24 以降が必要です（組み込みの node:sqlite モジュールを使用します）。

クイックスタート

import { DatabaseSync } from 'node:sqlite';
import { initQuestlogTables, read, write } from '@ghostpaw/questlog';

const db = new DatabaseSync(':memory:');
initQuestlogTables(db);

// Capture incoming work as a rumor before committing to shape
const rumor = write.captureRumor(db, {
  title: 'Legal says the vendor terms changed',
  details: 'Need to understand pricing delta and termination clause.',
});

// Settle the rumor into real work once the shape is clear
write.settleRumor(db, rumor.id, {
  settledAt: Date.now(),
  questline: {
    title: 'Vendor Renewal',
    description: 'Commercial, legal, and approval work.',
  },
  quests: [
    { title: 'Collect redlines', objective: 'Obtain the latest legal markup.' },
    { title: 'Review pricing delta', objective: 'Compare current vs. proposed cost.' },
  ],
});

// Drive the day from derived views, not from memory
const available = read.listAvailableQuests(db);
const dueSoon = read.listDueSoonQuests(db, 7 * 24 * 60 * 60 * 1000);
const results = read.searchQuestlog(db, 'vendor');

モデル

7 つの概念を、関心ごとに厳密に分離しています。

概念	目的
Rumor	実際の作業になるかどうかが未確定の、受信したシグナル
Questline	関連するクエストのグループで共有されるコンテキストと集約情報
Quest	ライフサイクル、タイミング、成果を持つ、具体的な 1 つのコミットメント
Repeatable Quest	スケジュールに沿って新しいクエストを生成する、繰り返し可能なテンプレート
Unlock	厳密な前提条件。クエスト A が成功するまで、クエスト B はブロックされます
Reward	完了した作業に付随する、獲得ライフサイクルを持つ成果の説明
Tag	フィルタリングやレポート作成に使う、複数の対象にまたがるラベル

統一されたモデルにより、時間に関わるあらゆる意図を 1 つのエンティティタイプで表現できます。

見た目	実際の内容
ToDo 項目	時間メタデータを持たないクエスト
期限	dueAt を持つクエスト
カレンダーイベント	scheduledStartAt と scheduledEndAt を持つクエスト
定期的なコミットメント	RRULE を持つ繰り返し可能なクエスト
完了したアクション	finishQuest で解決されたクエスト

状態は切り替えるのではなく、導出されます。クエストが利用可能かどうかは、そのライフサイクル、タイミングフィールド、Unlock グラフから決まります。これは読み取り時に計算され、ステータスフラグとして保存されることはありません。

ライフサイクルの概要

Questlog は、読み取りのたびに WoW スタイルのマーカーを計算します。作業がライフサイクルを進むにつれて、マーカーも変化します。

 

受付

$\color{Goldenrod}{\textsf{❗}}$	ベンダーの契約条件が変更されたと法務から連絡があった	rumor · open
	↓   クエストラインとクエストに整理する

クエストの進行

$\color{Goldenrod}{\textsf{❗}}$	価格差分を確認する	open · available
$\color{Gray}{\textsf{❓}}$	価格差分を確認する	in progress
$\color{Goldenrod}{\textsf{❓}}$	価格差分を確認する	done · reward unclaimed
✓	価格差分を確認する	done · reward claimed

その他のマーカー

$\color{CornflowerBlue}{\textsf{❗}}$	週次スタンドアップの議事録	repeatable · due
$\color{Gray}{\textsf{❗}}$	第 3 四半期のロードマップを計画する	open · deferred
$\color{Gray}{\textsf{❓}}$	財務部門の承認を得る	open · blocked

 

マーカー ID はセマンティック文字列（attention.available、progress.complete など）で、読み取り時に計算され、保存されることはありません。markers 名前空間は、それぞれのシンボル、色、ラベル、CSS クラスを対応付け、HTML、TTY、プレーンテキストで一貫した表示を実現します。

2 つの対象ユーザー

人間の開発者

read と write 名前空間を使って、すべてのドメイン操作にコードから直接アクセスできます。

import { read, write } from '@ghostpaw/questlog';

write.createQuest(db, { title: 'Ship release notes', objective: 'Draft and publish.' });
write.startQuest(db, questId);
write.finishQuest(db, questId, 'Published to blog and changelog.');

const blocked = read.listBlockedQuests(db);
const overdue = read.listOverdueQuests(db);

実例を交えた、人間向けの完全なガイドについては、HUMAN.md を参照してください。

LLM エージェント

LLM の認知負荷を最小限に抑えるよう設計された構造化ランタイムインターフェイスには、tools、skills、soul 名前空間を使用します。

import { tools, skills, soul } from '@ghostpaw/questlog';

// 12 intent-shaped tools with JSON Schema inputs and structured results
const allTools = tools.questlogTools;
const searchTool = tools.getQuestlogToolByName('search_questlog')!;
const result = searchTool.handler(db, { query: 'vendor', mode: 'browse' });

// 25 reusable workflow skills for common multi-step scenarios
const allSkills = skills.questlogSkills;

// Thinking foundation for system prompts
const prompt = soul.renderQuestlogSoulPromptFoundation();

すべてのツールは、outcome: 'success' | 'no_op' | 'needs_clarification' | 'error'、構造化されたエンティティ、次のステップのヒント、実行可能な復旧方法のアドバイスを含む、判別可能な結果を返します。解析が必要な例外や、曖昧な説明文はありません。

soul、tools、skills を網羅した、AI 向けの完全なガイドについては、LLM.md を参照してください。

ツール

生のストレージ操作ではなく、オペレーターの意図を軸に設計された12個のツールです。

ツール	機能
search_questlog	エンティティを横断する全文検索
review_questlog	フィルター付きリスト表示（利用可能、期限超過、期限間近など）
inspect_questlog_item	任意の単一エンティティの詳細な確認
capture_rumor	形にすることを決める前に、入ってきた作業を記録
shape_work	クエストやクエストラインの作成、噂の構造化
plan_quest	期限、延期日、予定期間を設定
run_quest	クエストの開始、完了、放棄、作業量の記録
organize_work	クエストをクエストライン間で移動、クエストラインのライフサイクルを管理
manage_repeatable	繰り返し可能なクエストテンプレートの作成と管理
tag_work	クエストと繰り返し可能な作業をタグで分類
reward_work	報酬の追加、更新、獲得、削除
retire_work	アクティブな画面から除外する項目を論理削除またはアーカイブ

各ツールは、名前、説明、JSON Schema、入力の説明、副作用レベルなどの実行時メタデータをエクスポートするため、エージェントのハーネスはドキュメントを読まずに接続できます。

run_quest ツールは、未達成のアンロック前提条件があるクエストの開始を拒否し、ブロックしているクエストと確認のヒントを返します。警告を伴って開始するには、force: true を設定してください。ライブラリの startQuest 関数は引き続き制限なく実行できます。

主な特長

• 実行時依存関係ゼロ。 Node 24+ に組み込まれている node:sqlite のみを使用します。
• 単一の事前バンドル済みファイル。 dist/ に ESM と CJS のエントリーポイントが1つずつあります。サブパスエクスポートやコード分割はありません。
• 純粋な SQLite ストレージ。 FTS5 全文検索、CHECK 制約付き状態遷移、トリガーで維持されるインデックスを使用します。DatabaseSync インスタンスは各自で用意してください。
• 派生状態。 利用可能性、ブロック状態、延期、期限超過、マーカーは、フラグとして保存せず、フィールドと関連情報から読み取り時に算出します。
• 意図に沿った書き込み。 captureRumor、settleRumor、startQuest、finishQuest、abandonQuest など、汎用的な CRUD ではなく、何が起きたかを表す操作を提供します。
• RFC 5545 に準拠した繰り返し。 繰り返し作業には標準の RRULE 文字列を使用します。独自の繰り返し形式はありません。
• WoW スタイルのマーカー。 意味を表すマーカー ID（attention.available、progress.complete など）を読み取りのたびに算出し、任意のチャネルに表示できます。
• テストを各モジュールに配置。 型定義のみのモジュールを除くすべてのモジュールに、同じ場所に .test.ts ファイルがあります。ドキュメントに記載された動作は、実行可能なテストで検証されています。

パフォーマンス

Node 24.14.0、Linux、Intel Xeon（共有クラウド vCPU）で、ファイルベースのデータベースに10,000件のクエストを格納し、npm run bench で測定しました。

操作	p50	p95
search_questlog（ツール）	0.06 ms	0.07 ms
MCP tools/call による検索（stdio フレーミングを含む）	0.07 ms	0.08 ms
read.searchQuestlog、一致するクエストが1件	0.07 ms	0.08 ms
read.searchQuestlog、一致するクエストが10,000件すべて	26.6 ms	41.9 ms
write.createQuest	0.22 ms	0.69 ms

ライブラリの検索は、強調表示されたスニペットとともにすべての一致結果を返すため、ログ全体に一致するクエリでは、それらすべての行を構築する分の時間がかかります。コールドスタート（プロセス起動から最初の応答までの中央値）は、--version と MCP サーバーで約30 msです。

パッケージの公開範囲

import {
  initQuestlogTables,  // schema setup
  read,                // all query functions
  write,               // all mutation functions
  tools,               // LLM tool definitions + registry
  skills,              // LLM workflow skills + registry
  soul,                // thinking foundation for system prompts
  markers,             // marker derivation and lookup
} from '@ghostpaw/questlog';

TypeScript の利用者は、すべてのドメイン型をルートからも利用できます。

import type {
  QuestlogDb,
  QuestState,
  QuestDetail,
  CreateQuestInput,
  QuestlogSearchResult,
  QuestlogToolDefinition,
  QuestlogSkill,
  QuestlogSoul,
} from '@ghostpaw/questlog';

ドキュメント

ドキュメント	対象
HUMAN.md	低レベルの read／write API を使用する開発者
LLM.md	LLM システムにツール、スキル、ソウルを接続するエージェント構築者
docs/README.md	アーキテクチャ概要：モデル、不変条件、ライフサイクル、マーカー
docs/entities/	エンティティごとの詳細マニュアルと、正確な公開 API 一覧

開発

npm install
npm test            # node:test runner
npm run typecheck   # tsc --noEmit
npm run lint        # biome check
npm run build       # ESM + CJS + declarations via tsup

このリポジトリでは、.nvmrc／.node-version／.tool-versions／mise.toml／Volta を使って Node 24.14.0 に固定しています。お好みのバージョンマネージャーを使用してください。

サポート

このパッケージがプロジェクトに役立った場合は、メンテナンスへのスポンサーをご検討ください。

---

Anonyfox • MIT License