GhostPaw Affinity

@ghostpaw/affinity

Agent 联系人：人物、承诺和年度日期，并可追踪渐行渐远的人。

npm install @ghostpaw/affinity

适用于 Node.js 的独立社交 CRM 核心，基于 SQLite 构建。

Affinity 将联系人、身份、关系机制、结构性纽带、日志记录、承诺、重复日期、属性和关系图审查整合为一个连贯模型，而不是拆分成彼此独立的系统。它以单个预打包文件的形式提供，运行时零依赖，同时面向两类用户：直接编写代码的人类开发者，以及通过结构化的 soul / tools / skills 运行时操作的 LLM Agent。

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。

命令行

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 服务。

Agent 技能

（仓库根目录的）SKILL.md 和 skills/affinity/SKILL.md 遵循 Agent Skills 格式，并随 npm 包一同发布。 将 skills/affinity/ 复制到 Agent 的技能文件夹中，或打印其内容：

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);

模型

八个概念，严格划分职责：

概念	用途
Contact	任何受跟踪的实体：个人、公司、团队、服务、宠物、家庭或群组
Identity	用于精确识别和路由的标识，例如电子邮件、电话号码、URL 或账户 ID
Social Link	持续记录关系的轨迹，包含 Rank、Affinity、Trust、互动频率、Bond 和状态
Tie	结构性事实，例如 works_at、belongs_to、reports_to 或亲属关系
Journal Entry	记录下来的证据：互动、观察、里程碑、交易或承诺
Date Anchor	每年重复的重要日期，例如生日、周年纪念日、续约日或忌日
Attribute	面向联系人和关系的灵活元数据与偏好层
Affinity Chart	活跃关系网络的派生图谱视图

该模型意味着，每种真实信息都有各自的归属：

表面上看起来是	实际上是
个人、公司、团队、服务或家庭	一个 Contact
电子邮件地址或标识	一个 Identity
随时间变化的友谊或商业关系	一个 Social Link
雇佣关系、层级关系、家庭关系或成员关系	一个 Tie
“我们昨天聊过”	一条 Journal Entry
“我答应发送会议纪要”	一条承诺型 Journal Entry
“他们的生日每年都很重要”	一个 Date Anchor

状态是推导得出的，而非手动切换。Rank、隐藏的 Affinity、Trust 变化、 Moments、关系变化、准备度和图谱桥接重要性，都是根据证据和明确的结构性事实计算得出， 而非由调用方编写状态标记。

两类受众

人类开发者

使用 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 Agent

使用 tools、skills 和 soul 命名空间，访问结构化运行时接口，以尽量降低 LLM 的认知负担：

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"、结构化实体、后续步骤提示和可执行的恢复信号。

请参阅 LLM.md，了解涵盖 soul、tools 和 skills 的完整 AI 指南。

工具

十二个围绕操作者意图设计的工具，而非原始存储操作：

工具	功能
search_affinity	按自然键或名称搜索联系人
review_affinity	以仪表板形式提供列表和图谱审查视图
inspect_affinity_item	查看某个确切的个人资料或关系详情
manage_contact	创建、修改联系人或更改其生命周期状态
merge_contacts	安全合并重复联系人
manage_duplicate_dismissal	忽略或恢复一对疑似重复联系人
manage_identity	添加、修改、验证或移除身份标识
manage_relationship	建立 Social Link、修改 bond/state、管理结构性关系
record_event	记录直接证据、观察、里程碑或交易
manage_commitment	记录或解决义务
manage_date_anchor	添加、修改或移除重复的重要日期
manage_attribute	设置、取消设置或替换联系人/关系元数据

每个工具都会导出运行时元数据、兼容 JSON Schema 的输入以及结构化输出， 使运行框架无需解析含糊的散文即可接入这些工具。

关键特性

• 零运行时依赖。 仅使用 node:sqlite（内置于 Node 24+）。
• 单个预打包文件。 在 dist/ 中包含一个 ESM 入口和一个 CJS 入口。没有子路径导出，也不拆分代码。
• 纯 SQLite 存储。 状态由 CHECK 约束，支持表由触发器维护，派生读取具有确定性。请自行提供 DatabaseSync。
• 派生机制。 排名、隐藏 Affinity、Trust、节奏、Moments、Radar 和桥接重要性均根据证据和结构计算，绝不会由调用方直接设置。
• 体现意图的写入。 createContact、setStructuralTie、recordInteraction、recordCommitment、addDateAnchor、mergeContacts：这些操作描述发生了什么或真相发生了什么变化，而不是通用 CRUD。
• 可扩展的 AI 运行时。 soul 用于设定行为姿态，tools 用于执行操作，skills 用于提供工作流指导。
• 测试与代码并置。 每个非类型模块都有一个并置的 .test.ts 文件。文档中说明的行为均有可执行测试覆盖。

包的公开接口

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 系统的 Agent 构建者
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