GhostPaw Affinity

@ghostpaw/affinity

エージェントの連絡先管理：人々、約束、毎年の記念日を記録し、疎遠になりつつある相手を把握できます。

npm install @ghostpaw/affinity

SQLite を基盤とする、Node.js 向けのスタンドアロンなソーシャル CRM コアです。

Affinity は、連絡先、ID、関係性の仕組み、構造的なつながり、日誌の記録、約束、定期的な日付、属性、グラフの確認を、別々のシステムではなく、ひとつの一貫したモデルとして扱います。ランタイム依存関係ゼロの単一の事前バンドル済みファイルとして提供され、人間の開発者がコードを直接操作する用途と、構造化された soul / tools / skills ランタイムを介して動作する LLM エージェントの用途の両方を想定して設計されています。

MCP サーバー

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

Claude Code

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

またはプラグインとして利用できます。プラグインを使うとスキルもインストールされます：

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

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

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

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

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

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

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

CLI

npx -y @ghostpaw/affinity tools
npx -y @ghostpaw/affinity call manage_contact '{"action":"create","input":{"name":"Sam","kind":"human"}}'
npx -y @ghostpaw/affinity call search_affinity '{"query":"Sam"}'

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

エージェントスキル

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

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

インストール

npm install @ghostpaw/affinity

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

クイックスタート

import { DatabaseSync } from "node:sqlite";
import { initAffinityTables, read, write } from "@ghostpaw/affinity";

const db = new DatabaseSync(":memory:");
db.exec("PRAGMA foreign_keys = ON");
initAffinityTables(db);

const { primary: owner } = write.createContact(db, {
  name: "Mika",
  kind: "human",
  bootstrapOwner: true,
});

const { primary: ada } = write.createContact(db, {
  name: "Ada Lovelace",
  kind: "human",
});

write.addIdentity(db, ada.id, {
  type: "email",
  value: "[email protected]",
});

write.recordInteraction(db, {
  type: "conversation",
  occurredAt: Date.now(),
  summary: "Coffee together",
  significance: 6,
  participants: [
    { contactId: owner.id, role: "actor", directionality: "mutual" },
    { contactId: ada.id, role: "recipient", directionality: "mutual" },
  ],
});

const profile = read.getContactProfile(db, ada.id);
const radar = read.listRadar(db);

モデル

8 つの概念を、厳密に役割分担します。

概念	目的
Contact	追跡対象となるあらゆるエンティティ：個人、会社、チーム、サービス、ペット、世帯、グループ
Identity	メールアドレス、電話番号、URL、アカウント ID など、正確な識別とルーティングに使う手掛かり
Social Link	ランク、親密度、信頼、頻度、絆、状態を持つ、進行中の関係性の記録
Tie	works_at、belongs_to、reports_to、親族関係などの構造的な事実
Journal Entry	記録された証拠：やり取り、観察、節目、取引、約束
Date Anchor	誕生日、記念日、更新日、追悼日など、毎年繰り返される日付
Attribute	コンタクトとリンクのための柔軟なメタデータおよび好みのレイヤー
Affinity Chart	有効な関係性ネットワークを示す派生グラフビュー

このモデルでは、それぞれの種類の事実を、それぞれ専用の場所に保持します。

見た目	実際のもの
個人、会社、チーム、サービス、世帯	Contact
メールアドレスまたはハンドル	Identity
時間とともに変化する友情やビジネス上の関係	Social Link
雇用、階層、家族関係、所属	Tie
「昨日、話をしました」	Journal エントリー
「要約を送ると約束しました」	約束を表す Journal エントリー
「その人の誕生日は毎年大切です」	Date Anchor

状態は手動で切り替えるのではなく、導出されます。ランク、非表示の親密度、信頼の変化、Moments、関係性の変化、準備状況、グラフ上の橋渡しとしての重要度は、呼び出し元が書き込むステータスフラグではなく、証拠と明示的な構造上の事実から計算されます。

2 つの利用者層

人間の開発者

ドメインに直接コードからアクセスするには、read および write 名前空間を使用します。

import { read, write } from "@ghostpaw/affinity";

write.createContact(db, { name: "Ada", kind: "human" });
write.addIdentity(db, contactId, { type: "email", value: "[email protected]" });
write.recordInteraction(db, {
  type: "support",
  occurredAt: now,
  summary: "Helped prepare for a difficult meeting",
  significance: 7,
  participants: [
    { contactId: ownerId, role: "actor", directionality: "mutual" },
    { contactId, role: "recipient", directionality: "mutual" },
  ],
});

const profile = read.getContactProfile(db, contactId);
const radar = read.listRadar(db);

モデリングの境界と具体例を含む、直接コードからの利用に関する完全なガイドは、HUMAN.md を参照してください。

LLM エージェント

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

import { tools, skills, soul } from "@ghostpaw/affinity";

const allTools = tools.affinityTools;
const searchTool = tools.getAffinityToolByName("search_affinity")!;
const result = searchTool.handler(db, { query: "email:[email protected]" });

const allSkills = skills.affinitySkills;
const prompt = soul.renderAffinitySoulPromptFoundation();

すべてのツールは、outcome: "success" | "no_op" | "needs_clarification" | "error"、構造化されたエンティティ、次のステップのヒント、実行可能な復旧情報を含む、判別可能な結果を返します。

soul、ツール、スキルを網羅した AI 向けの完全なガイドは、LLM.md を参照してください。

ツール

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

ツール	機能
search_affinity	自然キーまたは名前でコンタクトを検索します
review_affinity	ダッシュボード形式の一覧およびグラフで確認できます
inspect_affinity_item	特定のプロフィールまたはリンクの詳細を開きます
manage_contact	コンタクトの作成、修正、ライフサイクルの変更を行います
merge_contacts	重複するコンタクトを安全に統合します
manage_duplicate_dismissal	重複の疑いがあるペアを却下または復元します
manage_identity	Identity の追加、修正、確認、削除を行います
manage_relationship	Social Link の設定、絆や状態の修正、構造的な Tie の管理を行います
record_event	直接的な証拠、観察、節目、取引を記録します
manage_commitment	義務を記録または解決します
manage_date_anchor	毎年重要な日付の追加、修正、削除を行います
manage_attribute	コンタクトまたはリンクのメタデータを設定、解除、置換します

各ツールは、ランタイムメタデータ、JSON-Schema 互換の入力、構造化された出力を公開するため、ハーネスは曖昧な文章を解析せずにツールを接続できます。

主な特性

• ランタイム依存関係ゼロ。 Node 24+ に組み込まれている node:sqlite のみを使用します。
• 単一の事前バンドル済みファイル。 dist/ に ESM と CJS のエントリーポイントがそれぞれ 1 つあります。サブパスエクスポートやコード分割はありません。
• 純粋な SQLite ストレージ。 CHECK 制約付きの状態、トリガーで保守されるサポートテーブル、決定論的な派生読み取りを備えています。DatabaseSync は利用者側で用意してください。
• 派生メカニクス。 ランク、非表示の Affinity、Trust、頻度、Moments、Radar、ブリッジの重要度は、証拠と構造から計算され、呼び出し元が直接設定することはできません。
• 意図に沿った書き込み。 createContact、setStructuralTie、recordInteraction、recordCommitment、addDateAnchor、mergeContacts は、汎用的な CRUD ではなく、何が起きたのか、またはどの事実が変わったのかを表す操作です。
• AI ランタイムを追加可能。 姿勢を定める soul、アクションを実行する tools、ワークフローのガイダンスを提供する skills があります。
• テストを同じ場所に配置。 型専用ではないすべてのモジュールに、同じ場所に .test.ts ファイルがあります。ドキュメントに記載された動作は、実行可能なテストでカバーされています。

パッケージの公開 API

import {
  initAffinityTables,  // 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
} from "@ghostpaw/affinity";

すべてのドメイン型とランタイム型は、TypeScript の利用者向けにルートからも利用できます。

import type {
  AffinityDb,
  ContactKind,
  LinkState,
  ContactProfileRecord,
  AffinityChartRecord,
  AffinityToolDefinition,
  AffinitySkill,
  AffinitySoul,
} from "@ghostpaw/affinity";

ドキュメント

ドキュメント	対象者
HUMAN.md	低レベルの read / write API を使用する開発者
LLM.md	soul、tools、skills を LLM システムに組み込むエージェントの開発者
docs/README.md	アーキテクチャの概要：モデル、不変条件、メカニクス、ソースの構成
docs/entities/	概念ごとの詳細なマニュアルと、インラインで記載された正確な公開 API 一覧
docs/USECASES.md	個人、ビジネス、AI メモリーの観点から見た、ライフサイクルの詳細な説明

開発

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