pmem: Governed Memory for Autonomous Agents

Abstract

pmem 2.0 is a file-first, database-mirrored knowledge base written continuously by a fleet of autonomous agents as a side effect of their work. A companion post presented the census of that store as of 2026-07-06: 8,441 entries. Three days later the store holds 9,457 entries from 120 writing agents across 162 workspaces — 1,016 new entries in three days of routine operation. This post describes the structure underneath those counts: the append-only record format, the controlled vocabulary of 124 typed relationships connecting entries, the supersession mechanism that has formally retired 37 records in favor of corrections, and the identity and access model governing 127 registered agents. Every figure is computed directly from the live store.

Files first, database second

Every unit of knowledge in pmem begins life as a markdown file with a JSON header, written to a local kb/ directory: kb/short/ for atomic records (≤64 KB), kb/long/ for rollups and synthesis (≤512 KB). The filename is the identity — <agent>.<KEY>.<EPOCH> — and epochs are never reused. Files are append-only: a correction is a new file with a new epoch, never an edit to an old one.

If the database is reachable, the file is ingested into a PostgreSQL store with pgvector; if it is not, the file simply waits for the next sync. The mirror adds what files cannot provide — row-level security, semantic search over 768-dimension embeddings (9,456 of 9,457 entries are embedded), graph traversal, and cross-agent queries — but it is never a dependency. The database can be dropped and rebuilt from the files at any time.

Each record’s header carries its own governance: provenance (who issued it, by what method, with what proof), usage constraints and retention policy, and a self-assessment of confidence, impact, and validation status. The sha256 content hash doubles as the deduplication key.

A controlled vocabulary of relationships

Entries do not merely coexist; they cite each other. pmem restricts relationships to a 31-type controlled vocabulary drawn from three published ontologies plus a workflow set: CiTO, the citation-typing ontology (confirms, refutes, corrects, extends, qualifies…); SKOS for concept relations (related, partOf, exactMatch…); PROV-O for provenance (wasDerivedFrom, wasGeneratedBy…); and four workflow types (implements, dependsOn, triggers, supersedes). Every edge carries a weight between 0 and 1.

As of 2026-07-09 the store contains 124 edges across 18 of the 31 types:

The distribution is not decorative — it is a record of how the agents actually behave. The citation-typing family dominates by variety (61 edges across eleven types: knowledge extending, qualifying, confirming, and correcting other knowledge), while the workflow family dominates by weight of its single most-used member.

Supersession: memory that corrects itself

The most common relationship in the store, at 27 edges, is supersedes — and that is the design working as intended. When an agent writes a correction, it must do three things: mark the old entry SUPERSEDED, link the new entry to the old with a supersedes edge, and state in the new entry what changed and why the old way no longer applies. Active queries see only current knowledge; the full lineage remains traversable.

37 records in the store now carry the SUPERSEDED stage. The pattern in practice: a lesson recorded a calling pipeline as proven end-to-end; a live test days later showed one of its two modes had never actually captured audio. The correcting entry superseded the original within the hour, and the original remains — marked, linked, and excluded from active reads. An agent bootstrapping into that project next week inherits the correction, not the mistake, but can trace exactly when and why the knowledge changed.

Contradictory entries are forbidden from both remaining active: one must supersede the other. Deletion, by contrast, does not exist in the model at all.

Identity and governance

Writing to the store requires a registered identity — a database trigger rejects inserts from unregistered agents. The registry currently holds 127 agents in five castes: 117 workers, 6 profiled, 2 auditors, 1 orchestrator, and 1 analyst. Agent names are derived deterministically from what the agent is — a service’s name, or an interactive session’s workspace — so the same context always produces the same identity.

Row-level security is enforced at the database engine, not in application code: a worker sees only the workspaces it is scoped to. The castes modify that: a profiled agent reads everything but has every action logged for later scope-tightening; an auditor reads everything and writes only to its own workspace; a bare registration skips constraint-loading entirely. At startup an agent embeds a one-sentence description of its task and retrieves the lessons, rules, and open problems semantically nearest to it — mistakes recorded by one agent become constraints loaded by the next.

Growth as a side effect of work

Nothing in the fleet has “update the knowledge base” as its job. The store grows because writing records is how the agents work: 39 named threads group related entries across sessions, 43 distinct knowledge types are in use, and the three days since the census added 1,016 entries — checkpoints, lessons, problems, results, and the edges connecting them — at the ordinary rhythm of operations.

Methods and provenance

Every figure in this post was computed on 2026-07-09 by direct aggregate query against the pmem store, reading as a database superuser so that no per-agent visibility rule could hide a row. Entry, agent, workspace, type, thread, and embedding totals; the stage and edge-type distributions; and the caste registry are exact counts, not estimates. The analysis is read-only; no records were modified. The record schematic reflects the pmem 2.0 specification; the edge chart reflects the live pmem_edges table.

The pmem 2.0 specification and reference implementation are maintained at rreck/pmem2.