Skip to main content

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. Human and machine accounts remain separate records in the same library, with each listener declared and typed links between accounts when warranted. 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.7.0.

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, exact listener type, and derived record class; play resolvable audio; curate tags, notes, and location separately from listening accounts; add human listenings (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.
  • Human listening lifecycle — one stable identifier in ignored local settings owns human records. Only the unique current head of an owned human account can be edited, and saving creates a new attributable revision rather than rewriting history. Notes do not imply hearing: hearing is an explicit self-attestation. A human record may response_to a machine listening; same_source_as additionally requires explicit source verification.
  • 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.6) — 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.md catalog, log.md journal, and a lint pass for drift (dangling links, orphan pages, store integrity). Deterministic by default; see docs/concept.md and docs/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.7.0 / spec v1.6 Canonical store, no-audio listening accounts, listener-type/class indexes, and additive revision chains.
AKOÚŌ akouo/v0.9 Owns claim taxonomy, provenance, temporal passes, route decisions, corpus disclosure, and situated context rendered by the navigator.
OÍDA 0.10.0 / oida/gateway/v0.6 Writes typed machine and human listening records, links related accounts, 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.7.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for akousmata 0.7.0
File Size Uploaded Provenance Actions
akousmata-0.7.0.tar.gz 158.5 kB With provenance Details for akousmata-0.7.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for akousmata 0.7.0
File Interpreter ABI Platform Actions
akousmata-0.7.0-py3-none-any.whl Python 3 none any Details for akousmata-0.7.0-py3-none-any.whl

Total release size: 274.7 kB

Release files / akousmata-0.7.0.tar.gz

Download URL akousmata-0.7.0.tar.gz
Size 158.5 kB
Tags Source
SHA-256 checksum
How to use checksums
e167ad72ec8a9e63a363e2273f02a759a40aa3742260ffd73234ff265538e36a
BLAKE2b-256 checksum
How to use checksums
c0c0c470919942f6f5a021dea86310415c216935e7bd0894d343ae05a9966148
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

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 11, 2026.

Transparency log

Release files / akousmata-0.7.0-py3-none-any.whl

Download URL akousmata-0.7.0-py3-none-any.whl
Size 116.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
3e24713347f681d77863ff4a1a163ed41e05f4d283e12e96b9ab68f98ffc5b8e
BLAKE2b-256 checksum
How to use checksums
8730140bd0f16e65bfb68b8b309145cca307c143e1fe44c683deed0e06bcc21b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

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 11, 2026.

Transparency log

Security for akousmata 0.7.0

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.

Select from 2 files

Attestation for akousmata-0.7.0.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 11, 2026.

Transparency log

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

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page