Skip to main content

Class: PersonalityMutationStore

Defined in: packages/agentos/src/cognition/emergent/PersonalityMutationStore.ts:135

SQLite-backed persistence layer for personality mutations with decay.

Follows the same ensureSchema() pattern as EmergentToolRegistry: a cached promise guards against concurrent DDL execution, and all DML methods await schema readiness before proceeding.

Example​

const store = new PersonalityMutationStore(sqliteAdapter);

// Record a mutation
const id = await store.record({
  agentId: 'agent-42',
  trait: 'openness',
  delta: 0.1,
  reasoning: 'User prefers creative responses',
  baselineValue: 0.7,
  mutatedValue: 0.8,
});

// Get strength-weighted effective deltas
const deltas = await store.getEffectiveDeltas('agent-42');
// => { openness: 0.1 }  (strength is 1.0 initially)

// Decay all mutations by 5%
const { decayed, pruned } = await store.decayAll(0.05);

Constructors​

Constructor​

new PersonalityMutationStore(db): PersonalityMutationStore

Defined in: packages/agentos/src/cognition/emergent/PersonalityMutationStore.ts:151

Create a new PersonalityMutationStore.

Parameters​

db​

EmergentRegistryStorageAdapter

A storage adapter implementing the IStorageAdapter interface. The same adapter used by EmergentToolRegistry can be reused.

Returns​

PersonalityMutationStore

Methods​

decayAll()​

decayAll(rate): Promise<DecayResult>

Defined in: packages/agentos/src/cognition/emergent/PersonalityMutationStore.ts:328

Decay all active mutations by the given rate and prune expired ones.

Parameters​

rate​

number

The amount to subtract from each mutation's strength. Typically 0.05 (the default from SelfImprovementConfig).

Returns​

Promise<DecayResult>

A DecayResult with counts of decayed and pruned mutations.

Deprecated​

for production paths — use decayForAgent: this method is UNSCOPED (touches every agent's rows) and non-atomic (row-by-row writes double-decay on retry). Kept for administrative / maintenance use only.

For each mutation with strength above 0.1:

  • Subtracts rate from its strength.
  • If the new strength is at or below 0.1, the mutation is deleted (pruned).
  • Otherwise, the strength is updated in place.

This implements Ebbinghaus-style forgetting: mutations that aren't reinforced by repeated adaptation gradually fade away.

decayForAgent()​

decayForAgent(agentId, rate, cycleId): Promise<DecayResult & object>

Defined in: packages/agentos/src/cognition/emergent/PersonalityMutationStore.ts:377

Agent-scoped, idempotent, atomic decay (spec batch-1 C6).

Runs one transaction that (a) inserts the (agent_id, cycle_id) guard row FIRST — a replayed cycle id aborts as a no-op before touching any mutation row; (b) deletes this agent's rows already at/below the 0.1 prune threshold (pre-existing sub-threshold rows never decay again under decayAll's > 0.1 selector — this closes that leak); (c) decays the remaining rows, pruning any whose post-decay strength is at or below the threshold. Requires a transaction-capable adapter — the decay unit must be all-or-nothing so a mid-cycle failure cannot double-decay on retry.

Parameters​

agentId​

string

The agent whose mutations decay (other agents' rows are untouched — the class defect in decayAll).

rate​

number

Strength subtracted per cycle (typically SelfImprovementConfig.personality.decayRate, default 0.05).

cycleId​

string

Stable-per-cycle identity (e.g. day:2026-07-20 UTC buckets from decay-on-adapt). Replays are no-ops via the guard table.

Returns​

Promise<DecayResult & object>

getEffectiveDeltas()​

getEffectiveDeltas(agentId): Promise<Record<string, number>>

Defined in: packages/agentos/src/cognition/emergent/PersonalityMutationStore.ts:293

Compute the effective (strength-weighted) delta for each trait.

For each active mutation, multiplies the raw delta by the mutation's current strength, then sums per trait. This gives a realistic picture of how much each trait has drifted from baseline, accounting for decay.

Parameters​

agentId​

string

The agent whose effective deltas to compute.

Returns​

Promise<Record<string, number>>

A map of trait name to effective delta (sum of delta * strength).

loadForAgent()​

loadForAgent(agentId): Promise<PersonalityMutation[]>

Defined in: packages/agentos/src/cognition/emergent/PersonalityMutationStore.ts:258

Load all active mutations for a given agent.

Returns only mutations whose strength is above the 0.1 pruning threshold, ordered by creation time (newest first).

Parameters​

agentId​

string

The agent whose mutations to load.

Returns​

Promise<PersonalityMutation[]>

An array of PersonalityMutation records.

record()​

record(input): Promise<string>

Defined in: packages/agentos/src/cognition/emergent/PersonalityMutationStore.ts:221

Record a new personality mutation.

Inserts a mutation record with initial strength of 1.0 and the current timestamp. The mutation ID is generated deterministically from the current time and a random suffix.

Parameters​

input​

RecordMutationInput

The mutation parameters (agent, trait, delta, reasoning, values).

Returns​

Promise<string>

The generated mutation ID.