GhostPaw Affinity

@ghostpaw/affinity

Agent contacts: people, promises and yearly dates, with a radar for who is drifting.

A local social CRM: contacts, identities, relationships, journal events, commitments and recurring dates in one SQLite file. One self-contained binary per platform, an MCP server, and a zero-dependency TypeScript library.

Install

Each line downloads the latest release for one platform, checks it against SHA256SUMS, puts ghostpaw-affinity on your PATH and prints the version.

Linux x64

cd "$(mktemp -d)" && T=linux-x64 && V=$(curl -fsSLI -o /dev/null -w '%{url_effective}' https://github.com/GhostPawJS/affinity/releases/latest | sed 's|.*/v||') && F=ghostpaw-affinity-$V-$T.tar.gz && U=https://github.com/GhostPawJS/affinity/releases/download/v$V && curl -fsSL -O "$U/$F" -O "$U/SHA256SUMS" && grep " $F\$" SHA256SUMS | sha256sum -c - && tar -xzf "$F" ghostpaw-affinity && mkdir -p ~/.local/bin && mv ghostpaw-affinity ~/.local/bin/ && { case ":$PATH:" in *":$HOME/.local/bin:"*) ;; *) echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.profile; export PATH="$HOME/.local/bin:$PATH";; esac; } && ghostpaw-affinity --version

Linux arm64

cd "$(mktemp -d)" && T=linux-arm64 && V=$(curl -fsSLI -o /dev/null -w '%{url_effective}' https://github.com/GhostPawJS/affinity/releases/latest | sed 's|.*/v||') && F=ghostpaw-affinity-$V-$T.tar.gz && U=https://github.com/GhostPawJS/affinity/releases/download/v$V && curl -fsSL -O "$U/$F" -O "$U/SHA256SUMS" && grep " $F\$" SHA256SUMS | sha256sum -c - && tar -xzf "$F" ghostpaw-affinity && mkdir -p ~/.local/bin && mv ghostpaw-affinity ~/.local/bin/ && { case ":$PATH:" in *":$HOME/.local/bin:"*) ;; *) echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.profile; export PATH="$HOME/.local/bin:$PATH";; esac; } && ghostpaw-affinity --version

macOS Apple silicon

cd "$(mktemp -d)" && T=darwin-arm64 && V=$(curl -fsSLI -o /dev/null -w '%{url_effective}' https://github.com/GhostPawJS/affinity/releases/latest | sed 's|.*/v||') && F=ghostpaw-affinity-$V-$T.tar.gz && U=https://github.com/GhostPawJS/affinity/releases/download/v$V && curl -fsSL -O "$U/$F" -O "$U/SHA256SUMS" && grep " $F\$" SHA256SUMS | shasum -a 256 -c - && tar -xzf "$F" ghostpaw-affinity && sudo mkdir -p /usr/local/bin && sudo mv ghostpaw-affinity /usr/local/bin/ && ghostpaw-affinity --version

macOS Intel

cd "$(mktemp -d)" && T=darwin-x64 && V=$(curl -fsSLI -o /dev/null -w '%{url_effective}' https://github.com/GhostPawJS/affinity/releases/latest | sed 's|.*/v||') && F=ghostpaw-affinity-$V-$T.tar.gz && U=https://github.com/GhostPawJS/affinity/releases/download/v$V && curl -fsSL -O "$U/$F" -O "$U/SHA256SUMS" && grep " $F\$" SHA256SUMS | shasum -a 256 -c - && tar -xzf "$F" ghostpaw-affinity && sudo mkdir -p /usr/local/bin && sudo mv ghostpaw-affinity /usr/local/bin/ && ghostpaw-affinity --version

Windows x64 (PowerShell)

$r='GhostPawJS/affinity'; $v=(irm "https://api.github.com/repos/$r/releases/latest").tag_name; $f="ghostpaw-affinity-$($v.TrimStart('v'))-windows-x64.zip"; $u="https://github.com/$r/releases/download/$v"; $t=(New-Item -ItemType Directory (Join-Path $env:TEMP ([guid]::NewGuid()))).FullName; iwr "$u/$f" -OutFile "$t\$f" -UseBasicParsing; iwr "$u/SHA256SUMS" -OutFile "$t\SHA256SUMS" -UseBasicParsing; $want=((Get-Content "$t\SHA256SUMS" | Where-Object { $_ -like "* $f" }) -split '\s+')[0]; if (-not $want -or (Get-FileHash "$t\$f" -Algorithm SHA256).Hash -ne $want) { throw "checksum mismatch for $f" }; $d=Join-Path $env:LOCALAPPDATA 'Programs\ghostpaw\bin'; Expand-Archive "$t\$f" $t -Force; New-Item -ItemType Directory -Force $d | Out-Null; Copy-Item "$t\ghostpaw-affinity.exe" $d -Force; $p=[Environment]::GetEnvironmentVariable('Path','User'); if (";$p;" -notlike "*;$d;*") { [Environment]::SetEnvironmentVariable('Path',"$p;$d",'User') }; $env:Path="$d;$env:Path"; ghostpaw-affinity --version

These commands install the latest release in ~/.local/bin on Linux, /usr/local/bin on macOS (asks for sudo), or %LOCALAPPDATA%\Programs\ghostpaw\bin on Windows; Linux adds it to PATH via ~/.profile only if missing, and Windows adds it to the user PATH (open a new terminal afterwards). To pin a version, set V=0.6.0 instead of resolving latest ($v='v0.6.0' in PowerShell).

For a pinned Linux/macOS download to the current directory with no profile or PATH edits, choose the matching T (linux-x64, linux-arm64, darwin-arm64, or darwin-x64):

V=0.6.0

T=linux-x64 F=ghostpaw-affinity-$V-$T.tar.gz U=https://github.com/GhostPawJS/affinity/releases/download/v$V curl -fsSL -O "$U/$F" -O "$U/SHA256SUMS" && { case "$T" in darwin-*) grep " $F\$" SHA256SUMS | shasum -a 256 -c - ;; *) grep " $F\$" SHA256SUMS | sha256sum -c - ;; esac; } && tar -xzf "$F" ghostpaw-affinity && ./ghostpaw-affinity --version

Then:

ghostpaw-affinity contact create '{"name":"Sam","kind":"human"}'

ghostpaw-affinity search sam ghostpaw-affinity skill # cheat sheet and tool reference

Contacts live in ~/.ghostpaw/affinity.db unless --db or the GHOSTPAW_AFFINITY_DB environment variable says otherwise; relative paths resolve against the current directory.

A session with the linux-x64 binary against a fresh database:

The same session as an animated GIF.

npx / npm (for npm-based environments)

The npm package needs Node 24+ and has zero runtime dependencies:

npx -y @ghostpaw/affinity --help

npm install -g @ghostpaw/affinity # provides ghostpaw-affinity

Library (for harnesses)

npm install @ghostpaw/affinity

import { DatabaseSync } from "node:sqlite";

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

See Quick Start and docs/LLM.md for the tool facade.

Other installers and verification

Interactive installers (also verify SHA256SUMS):

curl -fsSL https://raw.githubusercontent.com/GhostPawJS/affinity/main/install.sh | sh

irm https://raw.githubusercontent.com/GhostPawJS/affinity/main/install.ps1 | iex

mise use -g github:GhostPawJS/affinity

ubi --project GhostPawJS/affinity --exe ghostpaw-affinity --in ~/.local/bin eget GhostPawJS/affinity

For aqua, define a github_release package in aqua.yaml:

registries:

• name: affinity type: local path: affinity-registry.yaml

packages:

• name: GhostPawJS/affinity@v registry: affinity

affinity-registry.yaml:

packages:

• type: github_release repo_owner: GhostPawJS repo_name: affinity asset: ghostpaw-affinity-{{trimV .Version}}-{{.OS}}-{{.Arch}}.tar.gz format: tar.gz replacements: { amd64: x64 } overrides:
• goos: windows asset: ghostpaw-affinity-{{trimV .Version}}-windows-{{.Arch}}.zip format: zip files:
• name: ghostpaw-affinity

SHA256SUMS covers every archive and server.mcpb. To verify a downloaded archive's build attestation:

gh attestation verify <archive> -R GhostPawJS/affinity

Set GHOSTPAW_VERIFY=attestation for attestation verification in install.sh. Binaries are unsigned; macOS binaries carry an ad-hoc signature. For a browser download on macOS, remove quarantine with xattr -d com.apple.quarantine /path/to/ghostpaw-affinity. Linux binaries require glibc 2.28+; use npx on Alpine. See the binary build workflow.

Each archive is roughly 40-46 MB (the binary embeds the Node runtime, 105-150 MB unpacked); the npm package is about 2 MB unpacked. Every release, including the one-liners above, is installed and run on ubuntu-24.04, macos-15 and windows-2025 by the install check.

MCP server

Every client below starts the same stdio server: ghostpaw-affinity mcp. Without the binary, use npx -y @ghostpaw/affinity mcp as the command instead.

Claude Code

claude mcp add ghostpaw-affinity -- ghostpaw-affinity mcp

or as a plugin, which also installs the skill:

/plugin marketplace add GhostPawJS/affinity

/plugin install ghostpaw-affinity@ghostpaw-affinity

Codex CLI (~/.codex/config.toml)

[mcp_servers.ghostpaw-affinity]

command = "ghostpaw-affinity" args = ["mcp"]

Cursor (.cursor/mcp.json), Claude Desktop (claude_desktop_config.json) or a project .mcp.json:

{

"mcpServers": { "ghostpaw-affinity": { "command": "ghostpaw-affinity", "args": ["mcp"] } } }

Claude Desktop users can also install server.mcpb from the latest GitHub release. A Dockerfile is included for container hosts: docker build -t ghostpaw-affinity . && docker run -i --rm -v affinity:/data ghostpaw-affinity.

The server speaks MCP 2026-07-28 (stateless, server/discover) and the initialize-based revisions 2025-11-25, 2025-06-18, 2025-03-26 and 2024-11-05.

Agent Skill

SKILL.md (repo root) and skills/affinity/SKILL.md follow the Agent Skills format and ship in the npm package. Copy skills/affinity/ into your agent's skills folder, or print it:

ghostpaw-affinity skill > SKILL.md

ghostpaw-affinity skill --list # workflow guides ghostpaw-affinity skill bootstrap-and-cold-start

Events

Record events and commitments with an optional externalRef: {source, id}. Both values are trimmed and non-empty; source is lowercased. The pair is unique across the database. Repeated intake returns the original event and no_op, without creating rows or relationship effects.

content preserves text exactly, including whitespace, empty strings and NUL, up to 1 MB (1,048,576 UTF-8 bytes). Supply a short summary, or omit it to derive one from the first non-empty content line (at most 140 characters; empty text becomes (no text)). Unknown event fields and moment kinds are validation errors. Journal/timeline rows omit content by default; use {includeContent: true} in library/tool options or CLI `--with-content