Class: ForgottenLedger
Defined in: packages/agentos/src/cognition/memory/suppression/ForgottenLedger.ts:337
The forgotten subjects of one store.
Example
const ledger = await ForgottenLedger.open({ primary: storeAdapter, copy: copyAdapter, key: { current: secret } });
await ledger.markForgotten({ kind: 'user', id: userId });
await ledger.isForgotten({ kind: 'user', id: userId }); // true
Properties
keyed
readonlykeyed:boolean
Defined in: packages/agentos/src/cognition/memory/suppression/ForgottenLedger.ts:341
Whether writes are keyed.
namespaces
readonlynamespaces: readonlystring[]
Defined in: packages/agentos/src/cognition/memory/suppression/ForgottenLedger.ts:339
The namespaces a check reads, '' first, each once.
Methods
countNotOf()
countNotOf(
subject):Promise<number>
Defined in: packages/agentos/src/cognition/memory/suppression/ForgottenLedger.ts:754
How many tombstones of either ledger, markers aside, are none of this subject's forms.
Parameters
subject
Returns
Promise<number>
Throws
For a subject with another kind or no id.
isForgotten()
isForgotten(
subject):Promise<boolean>
Defined in: packages/agentos/src/cognition/memory/suppression/ForgottenLedger.ts:699
Whether either ledger holds a tombstone of the subject: every form, every namespace.
Parameters
subject
Returns
Promise<boolean>
Throws
For a subject with another kind or no id.
markForgotten()
markForgotten(
subject):Promise<{form:"keyed"|"unkeyed";written:boolean; }>
Defined in: packages/agentos/src/cognition/memory/suppression/ForgottenLedger.ts:682
Writes the tombstone to the copy, then to the primary, each with its key's marker and a new state mark in one
transaction, after uniting the two sides' rows. written is false when both held it; the mark rises either way.
Rejects when either side's transaction fails: a caller deletes nothing without the tombstone in both.
Parameters
subject
Returns
Promise<{ form: "keyed" | "unkeyed"; written: boolean; }>
Throws
For a subject with another kind or no id.
Throws
LEDGER_IDENTITY_MISMATCH when a side no longer holds the ledger's identity,
LEDGER_STATE_INVALID when a side's identity or state row is damaged, KEY_REQUIRED for a key marker of a key
the handle was not given; nothing is written.
readState()
readState():
Promise<Readonly<{identity:string;mark:string; }>>
Defined in: packages/agentos/src/cognition/memory/suppression/ForgottenLedger.ts:733
Brings both sides up to date, as reconcile() does, and returns the ledger's identity and the state mark the
store holds after it: two strings, and nothing else. Read fresh from storage on every call.
Returns
Promise<Readonly<{ identity: string; mark: string; }>>
Throws
LEDGER_IDENTITY_MISMATCH when a side no longer holds the identity the open found
(its database was replaced under the open handle), LEDGER_STATE_INVALID when a side's rows are damaged.
Example
const { identity, mark } = await ledger.readState();
// Two marks of one identity: equal means no tombstone was written between the two reads.
reconcile()
reconcile():
Promise<{added:string[]; }>
Defined in: packages/agentos/src/cognition/memory/suppression/ForgottenLedger.ts:713
Fills missing rows in both directions and leaves both sides at the higher state mark; it never lowers one. A
tombstone one side holds without holding the higher mark was written outside the ledger, and raises the mark
once. added lists the tombstones brought back into the primary since the last reconcile() on this handle, its
own and those of an open, a deletion or a state read on the way, markers and a deletion's own tombstone left out.
With no copy there is nothing to bring back.
Returns
Promise<{ added: string[]; }>
size()
size():
Promise<number>
Defined in: packages/agentos/src/cognition/memory/suppression/ForgottenLedger.ts:741
How many tombstones either ledger holds, markers aside: 0 for a store that has forgotten nobody.
Returns
Promise<number>
hash()
statichash(namespace,subject,key?):Promise<string>
Defined in: packages/agentos/src/cognition/memory/suppression/ForgottenLedger.ts:662
SHA-256, or HMAC-SHA-256 with a key, over the canonical JSON [namespace, kind, id], as lowercase hex.
Parameters
namespace
string
subject
key?
Returns
Promise<string>
keyMarker()
statickeyMarker(key):Promise<string>
Defined in: packages/agentos/src/cognition/memory/suppression/ForgottenLedger.ts:668
k1: and the first 16 hex characters of SHA-256 over the key's bytes.
Parameters
key
Returns
Promise<string>
open()
staticopen(options):Promise<ForgottenLedger>
Defined in: packages/agentos/src/cognition/memory/suppression/ForgottenLedger.ts:388
Creates the table where missing on each adapter, then checks the copy marker, the key markers and the two rows
that name the ledger: i1:identity and s1:state.
A store that never had a copy and is given one has both marked as a pair. An existing copy is repaired from
the primary too, after marker validation, so replacing the copy with an older backup cannot lose tombstones.
The tombstones stay where they are on the store until reconcile().
A new ledger gets one identity, 16 random bytes, and one state mark, the same on both sides. A ledger made before these rows existed gains them and keeps every row it held. A store without them beside a copy that has them takes the copy's identity, state and tombstones, and a copy without them is repaired from its store, when the side without them holds no tombstone or key marker the other lacks.
Parameters
options
Returns
Promise<ForgottenLedger>
Throws
When any current or previous key is empty.
Throws
COPY_UNAVAILABLE when the copy is the primary database (the same adapter, the same
native SQLite file, or on Postgres the same table: one database and schema, through any pool; two adapters of
another kind on one file, sql.js among them, are not told apart), cannot be read, or when
the store had a copy and the copy given does not know it (or none is given); KEY_REQUIRED when either ledger holds the marker of a key
that was not passed; LEDGER_IDENTITY_MISMATCH when the store and the copy hold different identities, or the
side without an identity holds a tombstone or key marker the other lacks; LEDGER_STATE_INVALID when a side
holds one of the two rows without the other, a malformed one, or a tombstone the other side holds with another
namespace or time; LEDGER_UNAVAILABLE when an adapter has no transactions, the runtime has no secure random
source, or a side's write lock is held by another connection past the driver's wait. Nothing is copied or marked by an open that is refused, and each refusal writes one
memory.ledger_refused line.