akousmata — the listening navigator
akousma (ἄκουσμα, "a thing heard"; plural akousmata) — one sound's memory. Earworm is the protocol, the akousma is the shared record, the akousmata is the whole library: a network of listened things and their relations. This app is how you walk it — navigating sonic memories, not audio files.
The akousmata stores what agents listen (oída's ears, algophony's evaluations, germ's cultivations) and what you listen: manual human listening events live in the same library, with the listener declared. Every memory carries provenance and causal lineage ("made from") plus typed kinship ("belongs with"): variants, recurrences, series, responses. A heard memory carries attributable listenings; a gate that closed before hearing can instead carry a decision-only auditum without pretending that sound occurred.
Current release: 0.6.1.
What it is
A local-first library app over the shared akousmata store. It loads no models and runs no agents — it is the quiet room of the Listening Stack:
- Library — filter by app, origin, tag, text, time; play resolvable audio; edit tags, notes, and summaries; add manual memories (heard live or from a file, which is content-addressed into the store); forget with a content-free durable receipt that leaves absence visible without retaining the forgotten description.
- Graph — the memory system as a navigable graph: solid edges are lineage, dashed edges are kinship, colors are originating apps.
- Map — the listening map: where listenings happened, not where sounds live. A hand-rolled Web-Mercator canvas (embedded Natural Earth coastlines, no map library) with clustering and click-through to the library; an OSM street-tile layer exists behind an explicit opt-in and is the only remote call the UI can make. Locations are consent-scoped (spec v1.2), editable from each record's "place" section, and always stripped from export packs.
- Constellations — saved, ordered graph selections that remain playable as soundwalks; forgotten members stay visible as meaningful absences.
- Timeline — day, month, calendar-season, and year views plus weekday/hour recurrence rhythms. Calendar seasons are organizational labels, never ecological claims.
- Kin search — accountable similarity from tags, description overlap, duration, stored DSP features, and optional already-computed local embeddings. The navigator never calls a remote embedding service.
- Listening diary — quick human capture with one maintained wiki digest per day.
- Consent and export — an audit of consent, rights notes, and capture conditions; restricted or unknown records are blocked from sanitized, manifest-bearing research packs.
- Covenants (spec v1.3) — records made under a listening covenant say so: the detail pane shows under which ethics a sound was listened (the covenant's identity and lineage, the rules that acted, what was withheld — counted and attributed, never described — and the commitments it carries), and one click filters the library to everything heard under that covenant. The navigator displays sovereignty; it never edits it.
- Accountable auditums (spec v1.5) — cards, detail pages, the wiki, graph, and Audit view expose each attributable listener and route, temporal-pass and provenance references, preserved disagreement, honest absences, action authority, route decisions, receipts, and revisions. A refusal before hearing is rendered as a decision-only memory with no audio or acoustic claim. Legacy v1.x records remain valid and are named as legacy, not defective.
- Plural listening and declared ear swarms — several listeners stay distinct by default. The navigator uses “ear swarm” only for an explicit ensemble that records influence, preserved permissions and disagreements, and a dissolution rule; listener count alone never manufactures consensus.
- Listen again — a record with resolvable audio can make a fresh pass through the Oída gateway; the new claims, routes, apparatus, and summary are filed as a new revision record that points to the earlier hearing. Re-listening never silently overwrites or mutates the account it revises.
- Wiki — an LLM-wiki (after Karpathy's llm-wiki pattern) forked into
sonic memories: a maintained markdown layer over the records with one page
per memory, per tag, plus topic syntheses;
index.mdcatalog,log.mdjournal, and a lint pass for drift (dangling links, orphan pages, store integrity). Deterministic by default; seedocs/concept.mdanddocs/wiki-conventions.md. - Research — ask the library a question. Without an LLM it produces a deterministic traversal report (the graph already answers recurrence and kinship questions); with a BYOK provider it runs a bounded research loop and files the answer back as a topic page, so answers compound.
- BYOK LLM — optional: any OpenAI-compatible endpoint (OpenAI, xAI/Grok,
OpenRouter, Ollama, llama.cpp), Anthropic, or a local CLI agent
(codex, opencode — the prompt goes to stdin, nothing leaves your machine).
Keys live in your local
settings.json, never in the repo. CLI commands are parsed as an executable and arguments; use a wrapper script if you need shell pipelines or redirection. - Optional GERM handoff — configure a local GERM URL to send a memory as sound, prompt, or lineage. With no URL configured, the library has no GERM dependency and shows no handoff controls.
- Realtime — the navigator watches the store; memories written by oída or germ appear as they happen.
- Durable maintenance watcher — immediately reconciles records created while the app was offline, persists a tie-safe cursor, refreshes diary digests, and runs scheduled lint. Intervals are live-editable in Settings.
The store
By default the store data lives in the platform application-data directory
and is never tracked: index.sqlite, objects/ (content-addressed
audio), wiki/ (the maintained layer), and settings.json. Set
AKOUSMATA_PATH when the Listening Stack should share another location. The store API is
earworm/packages/py-akousma
(spec: earworm/docs/akousma_spec_v1.md) — this app is a navigator over
that protocol, not a fork of it.
Listening Stack compatibility
| Component | Version / contract | Relationship |
|---|---|---|
| Earworm | akousma 0.6.1 / spec v1.5 |
Canonical store and addressable auditum contract: decisions, lineage, attributable disagreement resolution, absence, forgetting receipts, ensembles, authority, and mechanically additive revision. |
| AKOÚŌ | akouo/v0.9 |
Owns claim taxonomy, provenance, temporal passes, route decisions, corpus disclosure, and situated context rendered by the navigator. |
| OÍDA | 0.9.2 / oida/gateway/v0.5 |
Writes listening events v0.3 and decision-only route outcomes; produces additive re-listening revisions and embeds the navigator at /library/. |
| GERM | 0.3.3 (optional) | Receives explicit sound, prompt, and lineage handoffs when separately configured. |
| Algophony | 0.5.2 | Adds batch evaluation stamps and comparison relations. |
| ORAM | 0.4.1 | ORAM exports can enter the store through OÍDA or another akousma producer; ORAM is not a direct store writer. |
Run
pip install -e . # installs the canonical akousma dependency too
akousmata # http://127.0.0.1:5180
Installing Oída installs and mounts this navigator at /library/; standalone
mode remains useful for library-only work. In the Sonic Field monorepo the
canonical sibling packages are editable. Tests: uv run pytest -q.
The stack around it
- oída listens and remembers (and embeds this library view as its history); optional GERM can cultivate remembered sounds into new ones; algophony evaluates batches and stamps results back onto records; AKOÚŌ defines how everything listens. The akousmata is where all of it — and you — keep one shared memory.
License
MIT. The store data is yours and never part of the repository.
Metadata
Release files for akousmata 0.6.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| akousmata-0.6.1.tar.gz | 148.5 kB | With provenance | Details for akousmata-0.6.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| akousmata-0.6.1-py3-none-any.whl | Python 3 | none | any | Details for akousmata-0.6.1-py3-none-any.whl |
Total release size: 256.8 kB
Release files / akousmata-0.6.1.tar.gz
| Download URL | akousmata-0.6.1.tar.gz |
|---|---|
| Size | 148.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
24005669eb8fee345e63a67a905f3b6cf58cdae64b695f63c5736c1c1600a362
|
|
BLAKE2b-256 checksum How to use checksums |
97129a0b4fc58772a888dc87e18d8e433f12ebf7cc1678b31549e89f88dfe189
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.13
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 3, 2026.
Transparency logRelease files / akousmata-0.6.1-py3-none-any.whl
| Download URL | akousmata-0.6.1-py3-none-any.whl |
|---|---|
| Size | 108.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
2e53c70ab637588881c4ee063ca658cef928233b1ec991b3a5aaa0e3d4d99a98
|
|
BLAKE2b-256 checksum How to use checksums |
de33e4e11c2817ae4a9cae1cd0f1d0c5cefe8b6a72e4934f2741a8a82737e714
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.13
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 3, 2026.
Transparency logSecurity for akousmata 0.6.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for akousmata-0.6.1.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 3, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.