acquaint.digests#
Digests: what a conversation with an entity said, written up through a watermark.
A digest is one Markdown file per conversation, in the entity’s folder
(people/<id>/digests/<name>.md, and the same under projects, orgs and groups). Its
frontmatter is the state of the processing, and its body is the notes:
schema: acquaint/digest/v1
ref: whatsapp:ada-lovelace # the correspond conversation reference: the SSOT
archive: correspond # where the raw messages live (never this store)
through: # the watermark, per scope: processed up to this time
content: '2026-11-03T19:37:47+01:00'
style: '2026-06-21T19:27:45+02:00'
checked: '2026-11-09T08:00:00+01:00' # when the conversation was last read, even if nothing new was in it
updated: '2026-11-04'
checked is not through: a channel read on a quiet day has no new message, so
through cannot move, yet the next sweep must know it was looked at (checked).
swept() gives, per channel, the oldest checked of its digests: “when did we last
read Slack for this entity?” without reading each file.
through answers “from which date and time is this conversation new?”: hand it to
correspond read <ref> --since <through> to get what has not been processed. Two scopes
exist because a conversation can be mined for how someone writes (style, the
acquaint-profile skill) separately from what it said (content, the
acquaint-digest skill).
The body has five sections: Orientation (who is in it, what it is for, its span),
Takeaways (decisions, agreements, asks, facts the operator will need), Themes (the
recurring subjects, each with where it comes up), Index (the conversation cut into
dated sections so an agent can go straight to one) and Open threads (what is waiting on
whom). Every item in those sections carries an anchor, [at: <ISO time>] (a message time
in the archive: rg -n '^2026-07-03T14:02' <transcript>) or a [source: …]; the
messages themselves stay in the archive, never here (POLICY.md: no whole message
bodies).
>>> digest_name("whatsapp:ada-lovelace"), digest_name("github:example/demo#12")
('digests/whatsapp-ada-lovelace.md', 'digests/github-example-demo-12.md')
Module Attributes
what the conversation said, and how its author writes. |
|
Sections whose every item needs an |
Functions
|
Add a dated batch ( |
|
The digest's file name inside the entity's folder, derived from the reference. |
|
|
|
Every digest of the entity: its reference, file and watermarks. |
|
The digest of one conversation, found by the |
|
Move the watermark of |
|
Stamp |
|
|
|
Create the digest of |
|
|
- acquaint.digests.ANCHORED_SECTIONS = ('Takeaways', 'Themes', 'Index', 'Open threads')#
Sections whose every item needs an
[at: …]or[source: …]anchor.
- acquaint.digests.SCOPES = ('content', 'style')#
what the conversation said, and how its author writes.
- Type:
What a watermark can cover
- acquaint.digests.append_batch(entity, ref, *, heading, rows, through=None, scope='content', force=False, today=None)[source]#
Add a dated batch (
### heading) at the end of each named section of a digest, in one write.rowsis{section: [line, ...]}, JSON text of that, orsection | line | anchorrows. Each line becomes one bullet and must be one line. Anything that would add an itemdigest_problems()flags as unanchored under Takeaways, Themes, Index or Open threads is refused, and then nothing is written. Withthroughthe watermark ofscopemoves in the same write (scopeandforcemean nothing without it).- Return type:
- acquaint.digests.digest_name(ref)[source]#
The digest’s file name inside the entity’s folder, derived from the reference.
- Return type:
- acquaint.digests.digest_problems(text)[source]#
(severity, line, rule, message)for one digest file: frontmatter shape, unanchored items, long quotes.
- acquaint.digests.digests(entity)[source]#
Every digest of the entity: its reference, file and watermarks.
- acquaint.digests.find_digest(entity, ref)[source]#
The digest of one conversation, found by the
refin its frontmatter (else by file name).
- acquaint.digests.mark_digest(entity, ref, through=None, *, checked=None, scope='content', force=False, today=None)[source]#
Move the watermark of
scopetothrough, and/or record when the conversation was last read (checked). Moving either back needsforce.- Return type:
- acquaint.digests.new_digest(entity, ref, *, archive='correspond', today=None)[source]#
Create the digest of
reffrom its template, with no watermark yet. Refuses when one exists.- Return type:
- acquaint.digests.parse_rows(rows)[source]#
{section: [line, ...]}from a mapping, JSON text, orsection | line | anchorrows (one per line; the anchor is optional).>>> parse_rows("takeaways | Agreed to ship | [at: 2026-11-03T10:00:00Z]") {'Takeaways': ['Agreed to ship [at: 2026-11-03T10:00:00Z]']} >>> parse_rows("Index | Kickoff | 2026-11-03T10:00:00Z") {'Index': ['Kickoff [at: 2026-11-03T10:00:00Z]']} >>> parse_rows('{"Themes": ["Pricing [source: thread-1]"]}') {'Themes': ['Pricing [source: thread-1]']}
- acquaint.digests.sweep_digests(entity, channel, checked, *, refs=(), archive='correspond', force=False, today=None)[source]#
Stamp
checkedon the digests ofchannelthat a sweep read, creating those that do not exist yet.With
refs(conversation references<channel>:…) exactly those are stamped, each created first when missing; without, every digest of the channel is (the sweep read the whole channel kind). A digest already checked later keeps that later time (unlessforce), so a sweep never fails halfway: every check is made before anything is written.- Return type:
- acquaint.digests.swept(entity)[source]#
{channel: oldest checked time}over the entity’s digests;Nonewhen one of the channel’s digests was never (validly) checked.The oldest, because a sweep is only as complete as its least-recently-read conversation. Digests without a
<channel>:<id>reference are not counted.