acquaint

People, and what they are involved in, for AI agents: who someone is, how to reach them, how to read them, how to write to them.

pip install acquaint

acquaint new person "Ada Lovelace"
acquaint remember ada-lovelace "prefers email for anything with attachments" --source "https://example.org/thread/1"
acquaint who ada -f aka                      # → Ada, Lovelace
acquaint brief ada-lovelace --purpose ask    # everything to know before writing to her

Tell an agent "write to Ada about the export" and it can find out, without being told again, who that is, where to reach her for this, what register to use, what to avoid, and where to record what it learns. The "how" is written down once, per person, and every agent, skill and tool reads it through the same verbs.

Records are hand-editable Markdown, one folder per person (or project, org, group), kept outside any code repository. Every preference carries its source, and acquaint lint fails when one does not.

What it records, and what it never does

A profile holds observable behaviour with evidence: "replies in one or two lines", "wants the decision first", quoted and linked. It never holds personality labels, moods, or special-category data (health, religion, politics, ethnicity, sexuality, union membership), stated or inferred, nor credentials, identifiers, or whole message bodies. Every store gets a POLICY.md stating this, and lint warns on tripwires.

The test for every line: would it survive being handed to the person it is about?

Where the data lives

The data root is the first of: the data_dir argument, $ACQUAINT_DATA_DIR, data_dir in ~/.config/acquaint/config.toml, ~/.local/share/acquaint.

POLICY.md                       what may be recorded
people/ada-lovelace/
  PROFILE.md                    entry file: identity frontmatter + Who · Reach · Write to them · Read them · Don't · Now · More
  identities.yaml               handles and addresses, with evidence
  rules.yaml                    channel rules: when → do (channel, and the address
                                when the channel is addressed by conversation), who set it, source
  links.yaml                    affiliations: project, org, group; role; period
  style.md                      the writing card: AI tolerance, register, do, don't, blocklist, exemplars
  views.md                      positions and standing objections, sourced
  sources.md                    where their writing lives, how authorship was verified
  log/2026-09.md                append-only observations
projects/<id>/PROFILE.md        What & status · Where things live · Who · Agents & skills · Norms · Now
orgs/<id>/  groups/<id>/  …     any other kind

Only PROFILE.md is required. A malformed file is reported and skipped; it never breaks lookups of anyone else.

The verbs

The same seventeen functions are the Python API (acquaint.tools), the CLI, and the MCP tools. Each returns a JSON-ready dict.

--json prints the result dict; - as the text of check or style-lint reads stdin.

Exit status: 0 on success; 1 when the result is not ok (the reason is on stderr); 2 for a usage error; 3 when reach matched a rule but no usable address is recorded for its channel (the rule is still listed, and the reason says what to add).

Nothing acts on a guess: a name, alias, handle or email counts only when exactly one record has it exactly, and a partial match comes back as a suggestion. rename and forget need the exact id.

Sources

End every preference, view or rule with a source tag:

## Write to them
- Lead with the decision, then the options. [source: self: "give me the recommendation first"]
- Short replies on chat, fuller ones by email. [source: log/2026-09.md#e03]
- No attachments over chat. [source: https://example.org/thread/1]

A source is a permalink, a log or research anchor, the person's own words, operator, or none located. A date alone is not a source, and neither is a placeholder such as unknown or TODO: an unsourced claim with a date attached reads as observed when it was not. A nested bullet is its own line and needs its own source.

Agent skills

Six skills ship inside the package (acquaint/data/skills/) and install with gh skill:

gh skill install thorwhalen/acquaint acquaint --agent claude-code

gh skill needs a recent gh; otherwise symlink the folders from the installed package's acquaint/data/skills/ into ~/.claude/skills/. If you already have a user-level skill named deslop, skip acquaint's or install it under another name: two skills with the same name at the same scope replace each other.

MCP

pip install "acquaint[mcp]"

{"mcpServers": {"acquaint": {"command": "acquaint-mcp"}}}

The server exposes the tools that read locally, append or create (who, resolve, check, reach, brief, remember, lint, new, style_lint, disclosure). Renaming, forgetting and syncing stay at the terminal. data_dir is not exposed: the data root is the server's (set ACQUAINT_DATA_DIR in the client configuration), never the model's. Neither is remember's reactivate: making an inactive identity active again is the operator's call. Nor is disclosure's today, which could revive a lapsed tier.

Private sync

acquaint sync init --repo <owner>/<name> --dry-run
acquaint sync init --repo <owner>/<name>

sync init creates the repository through gh as private, refuses to continue unless gh reports it PRIVATE, and installs a pre-push hook, active in every worktree, that allows a push only through origin, only when origin has exactly the one URL recorded at init (no pushurl or pushInsteadOf redirect), only when that URL names the checked repository on github.com, and only while gh still reports it private. push, pull and status check again. sync init takes over only an empty folder or a clone of that same repository.

What this does not protect: a private repository is access control, not encryption (the host can read everything); git push --no-verify skips the hook; whoever controls the repository's git config or the gh on PATH controls what the guard sees; moving the data root disables the hook until sync init --existing-only runs again; file names and commit messages contain people's names; deleting a folder does not remove it from history or other clones. git-remote-gcrypt would encrypt contents, names and history; it is the planned upgrade, but the guard does not support it yet, so sync init refuses gcrypt:: URLs (#13).

Python

from acquaint import Store, who, brief

who("ada", field="aka")["value"]  # ['Ada', 'Lovelace']
print(brief("ada-lovelace", purpose="ask")["text"])

store = Store()  # MutableMapping[str, Entity] over a dol files store
entity = store[
    "people/ada-lovelace"
]  # a mapping of that person's files, plus parsed views
entity.identities, entity.rules, entity.sections["Write to them"]
Store(files={})  # any MutableMapping[str, str] of files: a dict, a remote store

Design

The seams, surfaces and deliberate non-seams are in Discussion #1.