Metadata-Version: 2.5
Name: acquaint
Version: 0.0.4
Summary: 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.
Project-URL: Homepage, https://github.com/thorwhalen/acquaint
Project-URL: Repository, https://github.com/thorwhalen/acquaint
Project-URL: Documentation, https://thorwhalen.github.io/acquaint
Project-URL: Issues, https://github.com/thorwhalen/acquaint/issues
Author: Thor Whalen
License: mit
License-File: LICENSE
Keywords: agents,claude-code,contacts,deslop,people,profiles,writing
Requires-Python: >=3.11
Requires-Dist: cw<0.2,>=0.1.1
Requires-Dist: dol
Requires-Dist: pyyaml
Provides-Extra: dev
Requires-Dist: pytest-cov>=4.0; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Provides-Extra: docs
Requires-Dist: sphinx-rtd-theme>=1.0; extra == 'docs'
Requires-Dist: sphinx>=6.0; extra == 'docs'
Provides-Extra: mcp
Requires-Dist: py2mcp; extra == 'mcp'
Description-Content-Type: text/markdown

# 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.

```bash
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, 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 fifteen functions are the Python API (`acquaint.tools`), the CLI, and the MCP tools. Each returns a JSON-ready dict.

| Verb | Does |
|---|---|
| `who NAME [-f FIELD] [-b]` | one field, the identity block, or the whole entry file; lists candidates instead of guessing |
| `resolve HANDLE` | `github:octocat`, `email:…` → the person, with the evidence; a handle without its platform, a match by name only, or an inactive identity is reported, never acted on |
| `check TEXT` | before publishing: one person written as two ("Ada or Lovelace"), shared names, unknown names |
| `reach PERSON [--purpose --urgency --project --message-type --topic]` | ordered channels: the person's own rules > the operator's rules > project norms > observed habits > defaults |
| `brief PERSON [--purpose --project]` | card, writing style, views, reach, project norms, recent observations, reminders, and what is **not** known |
| `remember ENTITY TEXT [--source --kind --reactivate]` | append a dated, sourced observation (or identity, preference, view, rule); an identity equal to an inactive one is refused, naming that entry, unless `--reactivate` |
| `lint [ENTITY]` | sources on every preference; parseable files; entry-file budget; policy tripwires |
| `style-lint TEXT [--recipient --tolerance]` | machine-writing tells, enforced by the reader's tolerance of AI-sounding text |
| `new KIND NAME [--qualifier --description]` | scaffold from a template; readable slug ids (`ada-lovelace`, `john-smith--example-org`) |
| `rename ID TO` | new id or name; links elsewhere rewritten (never inside URLs or logs); old forms kept as aliases |
| `forget ID [--confirm]` | remove the whole folder, leaving a salted tombstone so the person is not silently re-created |
| `sync init --repo OWNER/NAME` · `sync push` · `sync pull` · `sync status` | private-repository sync, below |

`--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:

```markdown
## 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`:

| Skill | For |
|---|---|
| `acquaint` | the router: lookups at the right cost, `check` before publishing, `remember` with sources |
| `acquaint-profile` | building a profile from someone's own writing, with parallel `profile-reader` agents |
| `acquaint-write` | writing for a known reader, and sparring with a simulated one (`recipient-reader` agent) |
| `acquaint-read` | interpreting a message from a known person; AI-processing as a likelihood with evidence |
| `deslop` | prose without machine-writing tells, calibrated to the reader |
| `acquaint-sync` | private sync, and what it does not protect |

```bash
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

```bash
pip install "acquaint[mcp]"
```

```json
{"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`). 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.

## Private sync

```bash
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](https://github.com/thorwhalen/acquaint/issues/13)).

## Python

```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](https://github.com/thorwhalen/acquaint/discussions/1).
