@framers/agentos 0.1.120 → 0.1.122

package/dist/emergent/ManageSkillsTool.js

@@ -0,0 +1,241 @@
+/**
+ * @fileoverview ManageSkillsTool — ITool implementation that enables agents to
+ * dynamically enable, disable, and search for skills at runtime.
+ *
+ * @module @framers/agentos/emergent/ManageSkillsTool
+ *
+ * Agents call `manage_skills` to self-modify their active skill set. The tool
+ * enforces an allowlist-based permission model:
+ * - Wildcard (`'*'`) allows all skills unconditionally.
+ * - Exact skill ID matches are always permitted.
+ * - Category-based allowlist entries (`'category:X'`) permit any skill in that category.
+ * - Same-category expansion: if any skill in category X is already active, other
+ *   skills in X are also permitted without explicit allowlist entry.
+ * - New categories may require approval when `requireApprovalForNewCategories` is set.
+ *
+ * Locked skills cannot be disabled.
+ */
+// ============================================================================
+// TOOL IMPLEMENTATION
+// ============================================================================
+/**
+ * ITool implementation enabling agents to dynamically manage their skill set
+ * at runtime, subject to allowlist and lock constraints.
+ *
+ * @example
+ * ```ts
+ * const tool = new ManageSkillsTool({
+ *   config: { allowlist: ['*'], requireApprovalForNewCategories: false },
+ *   getActiveSkills: () => agent.skills,
+ *   getLockedSkills: () => ['core-reasoning'],
+ *   loadSkill: (id) => skillRegistry.load(id),
+ *   unloadSkill: (id) => skillRegistry.unload(id),
+ *   searchSkills: (q) => skillRegistry.search(q),
+ * });
+ * ```
+ */
+export class ManageSkillsTool {
+    /**
+     * Create a new ManageSkillsTool.
+     *
+     * @param deps - Injected dependencies including config, skill accessors,
+     *   and loader/unloader functions.
+     */
+    constructor(deps) {
+        /** @inheritdoc */
+        this.id = 'com.framers.emergent.manage-skills';
+        /** @inheritdoc */
+        this.name = 'manage_skills';
+        /** @inheritdoc */
+        this.displayName = 'Manage Skills';
+        /** @inheritdoc */
+        this.description = 'Enable, disable, search, or list skills available to this agent. ' +
+            'Subject to allowlist and lock constraints.';
+        /** @inheritdoc */
+        this.category = 'emergent';
+        /** @inheritdoc */
+        this.hasSideEffects = true;
+        /** @inheritdoc */
+        this.inputSchema = {
+            type: 'object',
+            properties: {
+                action: {
+                    type: 'string',
+                    enum: ['enable', 'disable', 'search', 'list'],
+                    description: 'The skill management action to perform.',
+                },
+                skillId: {
+                    type: 'string',
+                    description: 'Skill ID to enable or disable.',
+                },
+                query: {
+                    type: 'string',
+                    description: 'Search query for finding skills.',
+                },
+            },
+            required: ['action'],
+        };
+        this.deps = deps;
+    }
+    // --------------------------------------------------------------------------
+    // EXECUTE
+    // --------------------------------------------------------------------------
+    /**
+     * Execute the requested skill management action.
+     *
+     * @param args - Action type and associated parameters.
+     * @param _context - Tool execution context (unused but required by ITool).
+     * @returns A {@link ToolExecutionResult} wrapping the action outcome.
+     */
+    async execute(args, _context) {
+        switch (args.action) {
+            case 'enable':
+                return this.handleEnable(args.skillId);
+            case 'disable':
+                return this.handleDisable(args.skillId);
+            case 'search':
+                return this.handleSearch(args.query);
+            case 'list':
+                return this.handleList();
+            default:
+                return {
+                    success: false,
+                    error: `Unknown action "${args.action}". Must be one of: enable, disable, search, list`,
+                };
+        }
+    }
+    // --------------------------------------------------------------------------
+    // ACTION HANDLERS
+    // --------------------------------------------------------------------------
+    /**
+     * Enable a skill after checking allowlist permissions.
+     *
+     * Allowlist resolution order:
+     * 1. `['*']` → always allowed
+     * 2. Exact skillId match → allowed
+     * 3. `'category:X'` in allowlist and skill.category === X → allowed
+     * 4. Skill's category already represented in active skills → allowed (same-category expansion)
+     * 5. Otherwise → `requires_approval` if requireApprovalForNewCategories, else `denied`
+     */
+    async handleEnable(skillId) {
+        if (!skillId) {
+            return { success: false, error: 'skillId is required for the enable action' };
+        }
+        // Load the skill first to get its metadata
+        let skill;
+        try {
+            skill = await this.deps.loadSkill(skillId);
+        }
+        catch (err) {
+            return {
+                success: false,
+                error: `Failed to load skill "${skillId}": ${err.message ?? String(err)}`,
+            };
+        }
+        // Resolve allowlist permission
+        const permissionResult = this.resolvePermission(skill);
+        if (permissionResult === 'allowed') {
+            return {
+                success: true,
+                output: {
+                    status: 'enabled',
+                    skill: { skillId: skill.skillId, name: skill.name, category: skill.category },
+                },
+            };
+        }
+        // Not allowed — unload the skill we speculatively loaded
+        try {
+            this.deps.unloadSkill(skillId);
+        }
+        catch {
+            // Best-effort unload; skill may not have been fully registered
+        }
+        if (permissionResult === 'requires_approval') {
+            return {
+                success: true,
+                output: {
+                    status: 'requires_approval',
+                    skillId,
+                    category: skill.category,
+                    reason: `Skill category "${skill.category}" is new and requires approval.`,
+                },
+            };
+        }
+        return {
+            success: false,
+            error: `Skill "${skillId}" is not permitted by the allowlist.`,
+        };
+    }
+    /**
+     * Resolve whether a skill is permitted by the allowlist configuration.
+     *
+     * @returns `'allowed'`, `'requires_approval'`, or `'denied'`
+     */
+    resolvePermission(skill) {
+        const { allowlist, requireApprovalForNewCategories } = this.deps.config;
+        // 1. Wildcard
+        if (allowlist.includes('*')) {
+            return 'allowed';
+        }
+        // 2. Exact skill ID match
+        if (allowlist.includes(skill.skillId)) {
+            return 'allowed';
+        }
+        // 3. Category-based allowlist entry
+        if (allowlist.includes(`category:${skill.category}`)) {
+            return 'allowed';
+        }
+        // 4. Same-category expansion: category already represented in active skills
+        const activeSkills = this.deps.getActiveSkills();
+        const activeCategories = new Set(activeSkills.map((s) => s.category));
+        if (activeCategories.has(skill.category)) {
+            return 'allowed';
+        }
+        // 5. Otherwise — requires approval or denied
+        return requireApprovalForNewCategories ? 'requires_approval' : 'denied';
+    }
+    /**
+     * Disable a skill, rejecting if it is locked.
+     */
+    async handleDisable(skillId) {
+        if (!skillId) {
+            return { success: false, error: 'skillId is required for the disable action' };
+        }
+        const lockedSkills = this.deps.getLockedSkills();
+        if (lockedSkills.includes(skillId)) {
+            return {
+                success: false,
+                error: `Skill "${skillId}" is locked and cannot be disabled.`,
+            };
+        }
+        this.deps.unloadSkill(skillId);
+        return {
+            success: true,
+            output: { status: 'disabled', skillId },
+        };
+    }
+    /**
+     * Search for available skills by query string.
+     */
+    async handleSearch(query) {
+        if (!query) {
+            return { success: false, error: 'query is required for the search action' };
+        }
+        const results = this.deps.searchSkills(query);
+        return {
+            success: true,
+            output: { results },
+        };
+    }
+    /**
+     * List currently active skills.
+     */
+    async handleList() {
+        const skills = this.deps.getActiveSkills();
+        return {
+            success: true,
+            output: { skills },
+        };
+    }
+}
+//# sourceMappingURL=ManageSkillsTool.js.map

package/dist/emergent/ManageSkillsTool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ManageSkillsTool.js","sourceRoot":"","sources":["../../src/emergent/ManageSkillsTool.ts"],"names":[],"mappings":"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"}

package/dist/emergent/PersonalityMutationStore.d.ts

@@ -0,0 +1,183 @@
+/**
+ * @fileoverview SQLite persistence for personality mutations with
+ * Ebbinghaus-style strength decay.
+ *
+ * Mutations persist across sessions and gradually fade toward baseline
+ * unless reinforced by repeated adaptation. The ConsolidationLoop calls
+ * {@link PersonalityMutationStore.decayAll} each cycle to reduce mutation
+ * strengths; mutations whose strength drops below the 0.1 threshold are
+ * pruned automatically.
+ *
+ * Uses the same {@link IStorageAdapter} interface as EmergentToolRegistry,
+ * keeping storage concerns decoupled from specific SQLite drivers.
+ *
+ * @module @framers/agentos/emergent/PersonalityMutationStore
+ */
+import type { IStorageAdapter } from './EmergentToolRegistry.js';
+/**
+ * A single persisted personality mutation record.
+ *
+ * Represents a specific HEXACO trait adjustment made by the agent, along with
+ * its current strength (which decays over time) and the reasoning that
+ * motivated the change.
+ */
+export interface PersonalityMutation {
+    /** Unique mutation identifier (format: `pm_<timestamp>_<random>`). */
+    id: string;
+    /** The agent that made this mutation. */
+    agentId: string;
+    /** The HEXACO trait that was mutated (e.g., `'openness'`, `'conscientiousness'`). */
+    trait: string;
+    /** The signed delta applied to the trait value. Positive = increase, negative = decrease. */
+    delta: number;
+    /** Free-text reasoning explaining why the agent chose to mutate this trait. */
+    reasoning: string;
+    /** The trait value before this mutation was applied. */
+    baselineValue: number;
+    /** The trait value after this mutation was applied. */
+    mutatedValue: number;
+    /**
+     * Current strength of this mutation in the range (0, 1].
+     *
+     * Starts at 1.0 when recorded and decays each consolidation cycle.
+     * When strength drops to 0.1 or below, the mutation is pruned.
+     */
+    strength: number;
+    /** Unix epoch millisecond timestamp of when this mutation was recorded. */
+    createdAt: number;
+}
+/**
+ * Input parameters for recording a new personality mutation.
+ *
+ * The `strength` and `createdAt` fields are set automatically by the store
+ * (1.0 and `Date.now()` respectively).
+ */
+export interface RecordMutationInput {
+    /** The agent making the mutation. */
+    agentId: string;
+    /** The HEXACO trait being mutated. */
+    trait: string;
+    /** The signed delta to apply. */
+    delta: number;
+    /** Free-text reasoning for the mutation. */
+    reasoning: string;
+    /** The trait value before mutation. */
+    baselineValue: number;
+    /** The trait value after mutation. */
+    mutatedValue: number;
+}
+/**
+ * Result of a decay cycle, reporting how many mutations were weakened
+ * and how many were pruned (deleted) for falling below the threshold.
+ */
+export interface DecayResult {
+    /** Number of mutations whose strength was reduced but still above threshold. */
+    decayed: number;
+    /** Number of mutations deleted for falling at or below the 0.1 threshold. */
+    pruned: number;
+}
+/**
+ * SQLite-backed persistence layer for personality mutations with decay.
+ *
+ * Follows the same `ensureSchema()` pattern as {@link EmergentToolRegistry}:
+ * a cached promise guards against concurrent DDL execution, and all DML
+ * methods await schema readiness before proceeding.
+ *
+ * @example
+ * ```ts
+ * 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);
+ * ```
+ */
+export declare class PersonalityMutationStore {
+    /** The underlying SQLite storage adapter. */
+    private readonly db;
+    /**
+     * Cached schema initialization promise.
+     * Ensures DDL runs exactly once, even under concurrent access.
+     */
+    private schemaReady;
+    /**
+     * Create a new PersonalityMutationStore.
+     *
+     * @param db - A storage adapter implementing the {@link IStorageAdapter}
+     *   interface. The same adapter used by EmergentToolRegistry can be reused.
+     */
+    constructor(db: IStorageAdapter);
+    /**
+     * Idempotent schema initialization.
+     *
+     * Creates the `personality_mutations` table and its agent/trait index if
+     * they don't already exist. Uses the adapter's `exec()` method when
+     * available (for multi-statement DDL), falling back to individual `run()`
+     * calls for adapters that don't support it.
+     *
+     * @returns A promise that resolves when the schema is ready.
+     */
+    private ensureSchema;
+    /**
+     * 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.
+     *
+     * @param input - The mutation parameters (agent, trait, delta, reasoning, values).
+     * @returns The generated mutation ID.
+     */
+    record(input: RecordMutationInput): Promise<string>;
+    /**
+     * 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).
+     *
+     * @param agentId - The agent whose mutations to load.
+     * @returns An array of {@link PersonalityMutation} records.
+     */
+    loadForAgent(agentId: string): Promise<PersonalityMutation[]>;
+    /**
+     * 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.
+     *
+     * @param agentId - The agent whose effective deltas to compute.
+     * @returns A map of trait name to effective delta (sum of `delta * strength`).
+     */
+    getEffectiveDeltas(agentId: string): Promise<Record<string, number>>;
+    /**
+     * Decay all active mutations by the given rate and prune expired ones.
+     *
+     * 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.
+     *
+     * @param rate - The amount to subtract from each mutation's strength.
+     *   Typically 0.05 (the default from SelfImprovementConfig).
+     * @returns A {@link DecayResult} with counts of decayed and pruned mutations.
+     */
+    decayAll(rate: number): Promise<DecayResult>;
+}
+//# sourceMappingURL=PersonalityMutationStore.d.ts.map

package/dist/emergent/PersonalityMutationStore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PersonalityMutationStore.d.ts","sourceRoot":"","sources":["../../src/emergent/PersonalityMutationStore.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAMjE;;;;;;GAMG;AACH,MAAM,WAAW,mBAAmB;IAClC,sEAAsE;IACtE,EAAE,EAAE,MAAM,CAAC;IAEX,yCAAyC;IACzC,OAAO,EAAE,MAAM,CAAC;IAEhB,qFAAqF;IACrF,KAAK,EAAE,MAAM,CAAC;IAEd,6FAA6F;IAC7F,KAAK,EAAE,MAAM,CAAC;IAEd,+EAA+E;IAC/E,SAAS,EAAE,MAAM,CAAC;IAElB,wDAAwD;IACxD,aAAa,EAAE,MAAM,CAAC;IAEtB,uDAAuD;IACvD,YAAY,EAAE,MAAM,CAAC;IAErB;;;;;OAKG;IACH,QAAQ,EAAE,MAAM,CAAC;IAEjB,2EAA2E;IAC3E,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;GAKG;AACH,MAAM,WAAW,mBAAmB;IAClC,qCAAqC;IACrC,OAAO,EAAE,MAAM,CAAC;IAEhB,sCAAsC;IACtC,KAAK,EAAE,MAAM,CAAC;IAEd,iCAAiC;IACjC,KAAK,EAAE,MAAM,CAAC;IAEd,4CAA4C;IAC5C,SAAS,EAAE,MAAM,CAAC;IAElB,uCAAuC;IACvC,aAAa,EAAE,MAAM,CAAC;IAEtB,sCAAsC;IACtC,YAAY,EAAE,MAAM,CAAC;CACtB;AAED;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B,gFAAgF;IAChF,OAAO,EAAE,MAAM,CAAC;IAEhB,6EAA6E;IAC7E,MAAM,EAAE,MAAM,CAAC;CAChB;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,qBAAa,wBAAwB;IACnC,6CAA6C;IAC7C,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAkB;IAErC;;;OAGG;IACH,OAAO,CAAC,WAAW,CAA8B;IAEjD;;;;;OAKG;gBACS,EAAE,EAAE,eAAe;IAQ/B;;;;;;;;;OASG;YACW,YAAY;IAoC1B;;;;;;;;;OASG;IACG,MAAM,CAAC,KAAK,EAAE,mBAAmB,GAAG,OAAO,CAAC,MAAM,CAAC;IA4BzD;;;;;;;;OAQG;IACG,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,EAAE,CAAC;IAyBnE;;;;;;;;;OASG;IACG,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAe1E;;;;;;;;;;;;;;OAcG;IACG,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC;CA4BnD"}

package/dist/emergent/PersonalityMutationStore.js

@@ -0,0 +1,222 @@
+/**
+ * @fileoverview SQLite persistence for personality mutations with
+ * Ebbinghaus-style strength decay.
+ *
+ * Mutations persist across sessions and gradually fade toward baseline
+ * unless reinforced by repeated adaptation. The ConsolidationLoop calls
+ * {@link PersonalityMutationStore.decayAll} each cycle to reduce mutation
+ * strengths; mutations whose strength drops below the 0.1 threshold are
+ * pruned automatically.
+ *
+ * Uses the same {@link IStorageAdapter} interface as EmergentToolRegistry,
+ * keeping storage concerns decoupled from specific SQLite drivers.
+ *
+ * @module @framers/agentos/emergent/PersonalityMutationStore
+ */
+// ============================================================================
+// STORE
+// ============================================================================
+/**
+ * SQLite-backed persistence layer for personality mutations with decay.
+ *
+ * Follows the same `ensureSchema()` pattern as {@link EmergentToolRegistry}:
+ * a cached promise guards against concurrent DDL execution, and all DML
+ * methods await schema readiness before proceeding.
+ *
+ * @example
+ * ```ts
+ * 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);
+ * ```
+ */
+export class PersonalityMutationStore {
+    /**
+     * Create a new PersonalityMutationStore.
+     *
+     * @param db - A storage adapter implementing the {@link IStorageAdapter}
+     *   interface. The same adapter used by EmergentToolRegistry can be reused.
+     */
+    constructor(db) {
+        /**
+         * Cached schema initialization promise.
+         * Ensures DDL runs exactly once, even under concurrent access.
+         */
+        this.schemaReady = null;
+        this.db = db;
+    }
+    // --------------------------------------------------------------------------
+    // SCHEMA
+    // --------------------------------------------------------------------------
+    /**
+     * Idempotent schema initialization.
+     *
+     * Creates the `personality_mutations` table and its agent/trait index if
+     * they don't already exist. Uses the adapter's `exec()` method when
+     * available (for multi-statement DDL), falling back to individual `run()`
+     * calls for adapters that don't support it.
+     *
+     * @returns A promise that resolves when the schema is ready.
+     */
+    async ensureSchema() {
+        if (!this.schemaReady) {
+            this.schemaReady = (async () => {
+                const ddl = `
+          CREATE TABLE IF NOT EXISTS personality_mutations (
+            id TEXT PRIMARY KEY,
+            agent_id TEXT NOT NULL,
+            trait TEXT NOT NULL,
+            delta REAL NOT NULL,
+            reasoning TEXT NOT NULL,
+            baseline_value REAL NOT NULL,
+            mutated_value REAL NOT NULL,
+            strength REAL NOT NULL DEFAULT 1.0,
+            created_at BIGINT NOT NULL
+          );
+          CREATE INDEX IF NOT EXISTS idx_personality_mutations_agent
+            ON personality_mutations(agent_id, trait);
+        `;
+                if (this.db.exec) {
+                    await this.db.exec(ddl);
+                }
+                else {
+                    // Split on semicolons and execute each non-empty statement individually.
+                    for (const stmt of ddl.split(';').filter((s) => s.trim())) {
+                        await this.db.run(stmt);
+                    }
+                }
+            })();
+        }
+        return this.schemaReady;
+    }
+    // --------------------------------------------------------------------------
+    // RECORD
+    // --------------------------------------------------------------------------
+    /**
+     * 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.
+     *
+     * @param input - The mutation parameters (agent, trait, delta, reasoning, values).
+     * @returns The generated mutation ID.
+     */
+    async record(input) {
+        await this.ensureSchema();
+        const id = `pm_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
+        await this.db.run(`INSERT INTO personality_mutations
+        (id, agent_id, trait, delta, reasoning, baseline_value, mutated_value, strength, created_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?, 1.0, ?)`, [
+            id,
+            input.agentId,
+            input.trait,
+            input.delta,
+            input.reasoning,
+            input.baselineValue,
+            input.mutatedValue,
+            Date.now(),
+        ]);
+        return id;
+    }
+    // --------------------------------------------------------------------------
+    // LOAD
+    // --------------------------------------------------------------------------
+    /**
+     * 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).
+     *
+     * @param agentId - The agent whose mutations to load.
+     * @returns An array of {@link PersonalityMutation} records.
+     */
+    async loadForAgent(agentId) {
+        await this.ensureSchema();
+        const rows = await this.db.all('SELECT * FROM personality_mutations WHERE agent_id = ? AND strength > 0.1 ORDER BY created_at DESC', [agentId]);
+        return rows.map((r) => ({
+            id: r.id,
+            agentId: r.agent_id,
+            trait: r.trait,
+            delta: r.delta,
+            reasoning: r.reasoning,
+            baselineValue: r.baseline_value,
+            mutatedValue: r.mutated_value,
+            strength: r.strength,
+            createdAt: r.created_at,
+        }));
+    }
+    // --------------------------------------------------------------------------
+    // EFFECTIVE DELTAS
+    // --------------------------------------------------------------------------
+    /**
+     * 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.
+     *
+     * @param agentId - The agent whose effective deltas to compute.
+     * @returns A map of trait name to effective delta (sum of `delta * strength`).
+     */
+    async getEffectiveDeltas(agentId) {
+        const mutations = await this.loadForAgent(agentId);
+        const deltas = {};
+        for (const m of mutations) {
+            deltas[m.trait] = (deltas[m.trait] ?? 0) + m.delta * m.strength;
+        }
+        return deltas;
+    }
+    // --------------------------------------------------------------------------
+    // DECAY
+    // --------------------------------------------------------------------------
+    /**
+     * Decay all active mutations by the given rate and prune expired ones.
+     *
+     * 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.
+     *
+     * @param rate - The amount to subtract from each mutation's strength.
+     *   Typically 0.05 (the default from SelfImprovementConfig).
+     * @returns A {@link DecayResult} with counts of decayed and pruned mutations.
+     */
+    async decayAll(rate) {
+        await this.ensureSchema();
+        const all = await this.db.all('SELECT id, strength FROM personality_mutations WHERE strength > 0.1', []);
+        let decayed = 0;
+        let pruned = 0;
+        for (const row of all) {
+            const newStrength = row.strength - rate;
+            if (newStrength <= 0.1) {
+                await this.db.run('DELETE FROM personality_mutations WHERE id = ?', [row.id]);
+                pruned++;
+            }
+            else {
+                await this.db.run('UPDATE personality_mutations SET strength = ? WHERE id = ?', [newStrength, row.id]);
+                decayed++;
+            }
+        }
+        return { decayed, pruned };
+    }
+}
+//# sourceMappingURL=PersonalityMutationStore.js.map

package/dist/emergent/PersonalityMutationStore.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"PersonalityMutationStore.js","sourceRoot":"","sources":["../../src/emergent/PersonalityMutationStore.ts"],"names":[],"mappings":"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"}