@ddwang/magnitude-core 0.3.1-ddwang.1

package/dist/logger.d.ts

@@ -0,0 +1,3 @@
+import pino from 'pino';
+export declare const logger: pino.Logger<never, boolean>;
+export default logger;

package/dist/logger.js

@@ -0,0 +1,15 @@
+import pino from 'pino';
+export const logger = pino({
+    level: process.env.MAGNITUDE_LOG_LEVEL || 'warn',
+    transport: process.stdout.isTTY ? {
+        target: 'pino-pretty',
+        options: {
+            colorize: !process.env.NO_COLOR,
+            translateTime: 'SYS:HH:MM:ss.l',
+            ignore: 'pid,hostname'
+        }
+    } : undefined
+}).child({
+    name: "agent"
+});
+export default logger;

package/dist/memory/agentMemory.d.ts

@@ -0,0 +1,37 @@
+import { MultiMediaMessage } from '@/ai/baml_client';
+import { Observation, ObservationRetentionOptions, ObservationRole, ObservationSource } from './observation';
+import { MultiMediaJson } from './serde';
+import { Image as BamlImage } from '@boundaryml/baml';
+export interface SerializedAgentMemory {
+    instructions?: string;
+    observations: {
+        source: ObservationSource;
+        role: ObservationRole;
+        timestamp: number;
+        data: MultiMediaJson;
+        options?: ObservationRetentionOptions;
+    }[];
+}
+export interface AgentMemoryOptions {
+    instructions?: string | null;
+    promptCaching?: boolean;
+    thoughtLimit?: number;
+}
+export interface MemoryRenderOptions {
+}
+export declare class AgentMemory {
+    private options;
+    private observations;
+    private freezeMask?;
+    private cacheControlIndices;
+    constructor(options?: AgentMemoryOptions);
+    get instructions(): string | null;
+    render(options?: MemoryRenderOptions): Promise<MultiMediaMessage[]>;
+    simpleRender(): Promise<(BamlImage | string)[]>;
+    isEmpty(): boolean;
+    recordThought(content: string): void;
+    recordObservation(obs: Observation): void;
+    getLastThoughtMessage(): string | null;
+    toJSON(): Promise<SerializedAgentMemory>;
+    loadJSON(data: SerializedAgentMemory): Promise<void>;
+}

package/dist/memory/agentMemory.js

@@ -0,0 +1,121 @@
+import { Observation } from './observation';
+import { jsonToObservableData, observableDataToJson } from './serde';
+import { applyMask, maskObservations } from './masking';
+// export interface FreezeState {
+//     //lastFrozenObservationIndex: number,
+//     // ^ just use length of mask
+//     visibilityMask: boolean[],
+// }
+const CACHE_CONTROL_LIMIT = 3; // Anthropic allows max of 4, we use static one on system, 3 can be cyclic
+export class AgentMemory {
+    //public readonly events: EventEmitter<AgentMemoryEvents> = new EventEmitter();
+    options;
+    // Custom instructions relating to this memory instance (e.g. agent-level and/or task-level instructions)
+    //public readonly instructions: string | null;
+    observations = [];
+    //private freezeState?: FreezeState;
+    freezeMask;
+    cacheControlIndices = [];
+    constructor(options) {
+        //this.instructions = instructions ?? null;
+        this.options = {
+            instructions: options?.instructions ?? null,
+            promptCaching: options?.promptCaching ?? false,
+            //optimizeForPromptCaching: false,
+            thoughtLimit: options?.thoughtLimit ?? 20
+        };
+    }
+    get instructions() {
+        // why is this on memory? prob should just be on agent
+        return this.options.instructions;
+    }
+    async render(options) {
+        if (this.options.promptCaching && this.cacheControlIndices.length >= CACHE_CONTROL_LIMIT) {
+            this.freezeMask = undefined;
+            this.cacheControlIndices = [];
+        }
+        const mask = await maskObservations(this.observations, this.freezeMask);
+        const visibleObservations = applyMask(this.observations, mask);
+        const lastVisible = visibleObservations.at(-1);
+        if (lastVisible)
+            this.cacheControlIndices.push(lastVisible.index); // index WRT full observation list
+        let messages = [];
+        for (const { observation, index } of visibleObservations) {
+            const message = await observation.render({
+                prefix: observation.source.startsWith('action:taken') || observation.source.startsWith('thought') ?
+                    [`[${new Date(observation.timestamp).toTimeString().split(' ')[0]}]: `] : [],
+                cacheControl: this.options.promptCaching && this.cacheControlIndices.includes(index)
+            });
+            messages.push(message);
+        }
+        if (this.options.promptCaching) {
+            this.freezeMask = mask;
+        }
+        return messages;
+    }
+    async simpleRender() {
+        // Render with no filtering, no masking, no cache control
+        //let messages: MultiMediaMessage[] = [];
+        let content = [];
+        for (const observation of this.observations) {
+            const message = await observation.render({
+                prefix: observation.source.startsWith('action:taken') || observation.source.startsWith('thought') ?
+                    [`[${new Date(observation.timestamp).toTimeString().split(' ')[0]}]: `] : []
+            });
+            // ignore message stuff, just push content
+            content = [...content, ...message.content];
+        }
+        return content;
+    }
+    isEmpty() {
+        return this.observations.length === 0;
+    }
+    recordThought(content) {
+        this.observations.push(Observation.fromThought(content, { type: 'thought', limit: this.options.thoughtLimit }));
+        //this.events.emit('thought', content);
+    }
+    recordObservation(obs) {
+        this.observations.push(obs);
+    }
+    getLastThoughtMessage() {
+        for (let i = this.observations.length - 1; i >= 0; i--) {
+            const obs = this.observations[i];
+            // toString() is a little funky here, or the idea that thought might not just be text
+            if (obs.source.startsWith('thought'))
+                return obs.toString();
+        }
+        return null;
+    }
+    async toJSON() {
+        const observations = [];
+        for (const observation of this.observations) {
+            observations.push({
+                source: observation.source,
+                role: observation.role,
+                timestamp: observation.timestamp,
+                data: await observableDataToJson(observation.content),
+                options: observation.retention,
+            });
+        }
+        return {
+            // TODO: include other options as well
+            ...(this.options.instructions ? { instructions: this.options.instructions } : {}),
+            observations: observations
+        };
+    }
+    // TODO: turn into class static method / rework cons
+    async loadJSON(data) {
+        //jsonToObservableData(data);
+        const observations = [];
+        for (const observation of data.observations) {
+            observations.push(new Observation(observation.source, observation.role, await jsonToObservableData(observation.data), observation.options, observation.timestamp));
+        }
+        // nvm
+        //this.instructions = this.instructions;
+        this.observations = observations;
+        // return {
+        //     ...(this.instructions ? { instructions: this.instructions } : {}),
+        //     observations: observations
+        // };
+    }
+}

package/dist/memory/image.d.ts

@@ -0,0 +1,26 @@
+import { Image as BamlImage } from '@boundaryml/baml';
+import { StoredMedia } from './serde';
+import { Sharp } from 'sharp';
+import sharp from 'sharp';
+export type ImageMediaType = `image/${string}`;
+export declare class Image {
+    /**
+     * Wrapper for a Sharp image with conveniences to go to/from base64, convert to BAML, or serialize as JSON
+     */
+    private img;
+    constructor(img: Sharp);
+    static fromBase64(base64: string): Image;
+    getFormat(): Promise<keyof sharp.FormatEnum>;
+    /**
+     * Convert the image to a JSON representation
+     */
+    toJson(): Promise<StoredMedia>;
+    toBase64(): Promise<string>;
+    toBaml(): Promise<BamlImage>;
+    saveToFile(filepath: string): Promise<void>;
+    getDimensions(): Promise<{
+        width: number;
+        height: number;
+    }>;
+    resize(width: number, height: number): Promise<Image>;
+}

package/dist/memory/image.js

@@ -0,0 +1,106 @@
+import { Image as BamlImage } from '@boundaryml/baml';
+import sharp from 'sharp';
+export class Image {
+    /**
+     * Wrapper for a Sharp image with conveniences to go to/from base64, convert to BAML, or serialize as JSON
+     */
+    // represents the start of a pipeline
+    img;
+    // Cached metadata property for sync access + required width/height properties
+    //private metadata: Sharp['metadata'] & { width: number, height: number };
+    //private content: string;
+    //private mediaType: ImageMediaType;
+    //constructor(type: 'url' | 'base64', content: string, mediaType: ImageMediaType) {
+    constructor(img) {
+        this.img = img;
+    }
+    static fromBase64(base64) {
+        // if (!mediaType) {
+        //     const match = base64.match(/^data:(.*?);base64,/);
+        //     mediaType = match ? `image/${match[1]}` : undefined;
+        // }
+        // if (!mediaType) {
+        //     throw new Error("Image media type must be specified either in base64 encoded string or in mediaType parameter");
+        // }
+        const base64Data = base64.replace(/^data:.*?;base64,/, '');
+        //return new Image('base64', base64Data, mediaType);
+        return new Image(sharp(Buffer.from(base64Data, 'base64')));
+    }
+    async getFormat() {
+        const format = (await this.img.clone().metadata()).format;
+        if (!format)
+            throw new Error("Unable to get image format");
+        return format;
+    }
+    /**
+     * Convert the image to a JSON representation
+     */
+    async toJson() {
+        // if (this.type === 'url') {
+        //     return {
+        //         type: 'media',
+        //         mediaType: this.mediaType,//`image/${this.mediaType}`,
+        //         storageType: 'url',
+        //         url: this.content
+        //     };
+        // } else {
+        return {
+            type: 'media',
+            //mediaType: this.mediaType,//`image/${this.mediaType}`,
+            format: await this.getFormat(),
+            storage: 'base64',
+            base64: await this.toBase64() //this.content
+        };
+        //}
+    }
+    async toBase64() {
+        const base64data = (await this.img.clone().toBuffer()).toString('base64');
+        //console.log("DATA (Image):", base64data.substring(0, 100));
+        return base64data;
+        //return `data:image/png;base64,${base64data}`;
+    }
+    async toBaml() {
+        // if (this.type === 'url') {
+        //     return BamlImage.fromUrl(this.content, this.mediaType);
+        // }
+        // else {//if (this.type === 'base64') {
+        //     return BamlImage.fromBase64(this.mediaType, this.content);
+        // }
+        const format = await this.getFormat();
+        const data = await this.toBase64();
+        //console.log("FORMAT:", format);
+        //console.log("DATA:", data.substring(0, 100));
+        return BamlImage.fromBase64(`image/${format}`, data);
+    }
+    async saveToFile(filepath) {
+        // We clone here to ensure the original sharp instance remains usable for other operations
+        await this.img.clone().toFile(filepath);
+        //console.log(`Image saved to ${filepath}`);
+    }
+    async getDimensions() {
+        //const { width, height } = await this.img.clone().metadata();
+        // Need to convert to buffer in order for metadata to be updated - otherwise it returns metadata of the original image
+        const { info: { width, height } } = await this.img.clone().toBuffer({ resolveWithObject: true });
+        if (!width || !height)
+            throw new Error("Unable to get dimensions from image");
+        return { width, height };
+    }
+    async resize(width, height) {
+        // if (this.type != 'base64') throw new Error("Only base64 images can be resized");
+        // const img = sharp(Buffer.from(this.content));
+        // const metadata = await img.metadata();
+        //console.log(`resizing to: ${width}, ${height}`);
+        //console.log("Before resizing:", await this.getDimensions());
+        // if (!metadata.width || !metadata.height)
+        const resizedImage = new Image(await this.img.clone().resize({
+            // Round width/height since sometimes they are floats due to rounding errors - sharp will throw if not integers
+            width: Math.round(width),
+            height: Math.round(height),
+            fit: 'fill', // exact size, no cropping
+            kernel: sharp.kernel.lanczos3
+        }));
+        //resizedImage.saveToFile('foo.png');
+        //console.log("After resizing:", await resizedImage.getDimensions());
+        return resizedImage;
+    }
+}

package/dist/memory/index.d.ts

@@ -0,0 +1,3 @@
+export * from './agentMemory';
+export * from './observation';
+export * from './util';

package/dist/memory/index.js

@@ -0,0 +1,3 @@
+export * from './agentMemory';
+export * from './observation';
+export * from './util';

package/dist/memory/masking.d.ts

@@ -0,0 +1,7 @@
+import { Observation } from './observation';
+export declare function maskObservations(observations: Observation[], freezeMask?: boolean[]): Promise<boolean[]>;
+export interface MaskedObservation {
+    observation: Observation;
+    index: number;
+}
+export declare function applyMask(observations: Observation[], mask: boolean[]): MaskedObservation[];

package/dist/memory/masking.js

@@ -0,0 +1,141 @@
+export async function maskObservations(observations, freezeMask) {
+    // If freezeMask provided, will guarantee that first freezeMask.length observations return the same mask provided in freezeMask
+    // - for dedupe: adjacent types in frozen section should survive if unfrozen contains that type with an equivalent value, instead of keeping most recent 
+    // - for limit: limit should only apply to unfrozen section and should ignore (not count) anything in frozen section
+    /**
+     * Returns a boolean mask indicating which observations should be visible,
+     * based on type-specific `dedupe` and `limit` options specified in `obs.retention`.
+     *
+     * For each type:
+     * 1. If `dedupe` is true, marks older adjacent identical observations as false,
+     *    keeping only the last in such a sequence.
+     * 2. If `limit` is set, marks only the last N observations of that type as true.
+     *
+     * Deduplication is applied before limiting for each type.
+     * Untyped observations (no `obs.retention.type`) are always marked as true.
+     *
+     * If freezeMask is provided:
+     * - The first freezeMask.length observations will have their mask values frozen
+     * - Dedupe will preserve frozen observations if equivalent values exist in unfrozen section
+     * - Limit only applies to unfrozen observations
+     *
+     * @returns A boolean array where true indicates the observation at that index should be visible
+     */
+    const frozenCount = freezeMask?.length ?? 0;
+    // Initialize mask
+    const mask = new Array(observations.length).fill(true);
+    // Copy frozen mask values if provided
+    if (freezeMask) {
+        for (let i = 0; i < frozenCount && i < observations.length; i++) {
+            mask[i] = freezeMask[i];
+        }
+    }
+    // Group observations by type, tracking their original indices
+    const observationsByType = new Map();
+    observations.forEach((obs, index) => {
+        if (obs.retention && obs.retention.type) {
+            const type = obs.retention.type;
+            if (!observationsByType.has(type)) {
+                observationsByType.set(type, {
+                    frozenIndices: [],
+                    unfrozenIndices: [],
+                    frozenObs: [],
+                    unfrozenObs: [],
+                    limit: obs.retention.limit,
+                    dedupe: obs.retention.dedupe,
+                });
+            }
+            const typeData = observationsByType.get(type);
+            if (index < frozenCount) {
+                typeData.frozenIndices.push(index);
+                typeData.frozenObs.push(obs);
+            }
+            else {
+                typeData.unfrozenIndices.push(index);
+                typeData.unfrozenObs.push(obs);
+            }
+        }
+        // Untyped observations: frozen ones keep their freezeMask value, unfrozen remain true
+    });
+    // Process each type
+    for (const [type, data] of observationsByType.entries()) {
+        // Only process unfrozen observations for dedupe and limit
+        let visibleUnfrozenIndices = [...data.unfrozenIndices];
+        // Apply deduplication to unfrozen section
+        if (data.dedupe && data.unfrozenObs.length > 1) {
+            const dedupedIndices = [];
+            dedupedIndices.unshift(data.unfrozenIndices[data.unfrozenIndices.length - 1]);
+            for (let i = data.unfrozenIndices.length - 2; i >= 0; i--) {
+                const currentObs = data.unfrozenObs[i];
+                const lastKeptIdx = dedupedIndices[0];
+                const lastKeptObs = observations[lastKeptIdx];
+                if (!(await currentObs.equals(lastKeptObs))) {
+                    dedupedIndices.unshift(data.unfrozenIndices[i]);
+                }
+            }
+            visibleUnfrozenIndices = dedupedIndices;
+        }
+        // Special handling for dedupe with frozen observations
+        if (data.dedupe && freezeMask) {
+            // Check if any frozen observations should be preserved
+            // because equivalent values exist in unfrozen section
+            const frozenToPreserve = new Set();
+            for (let i = 0; i < data.frozenIndices.length; i++) {
+                const frozenIdx = data.frozenIndices[i];
+                if (mask[frozenIdx]) { // Only check if currently visible in freezeMask
+                    const frozenObs = data.frozenObs[i];
+                    // Check if any unfrozen observation equals this frozen one
+                    for (const unfrozenObs of data.unfrozenObs) {
+                        if (await frozenObs.equals(unfrozenObs)) {
+                            frozenToPreserve.add(frozenIdx);
+                            break;
+                        }
+                    }
+                }
+            }
+            // Ensure preserved frozen observations stay visible
+            frozenToPreserve.forEach(idx => {
+                mask[idx] = true;
+            });
+        }
+        // Apply limit only to unfrozen observations
+        if (data.limit !== undefined && data.limit >= 0) {
+            if (data.limit === 0) {
+                visibleUnfrozenIndices = [];
+            }
+            else {
+                // Limit only counts unfrozen observations
+                visibleUnfrozenIndices = visibleUnfrozenIndices.slice(-data.limit);
+            }
+        }
+        // Mark non-visible unfrozen observations as false
+        const visibleSet = new Set(visibleUnfrozenIndices);
+        data.unfrozenIndices.forEach(idx => {
+            if (!visibleSet.has(idx)) {
+                mask[idx] = false;
+            }
+        });
+        // Frozen observations keep their freezeMask values (already set above)
+    }
+    return mask;
+}
+export function applyMask(observations, mask) {
+    /**
+     * Applies a boolean mask to an array of observations, returning only those
+     * observations where the corresponding mask value is true, along with their original indices.
+     *
+     * @param observations - The array of observations to filter
+     * @param mask - Boolean array where true indicates the observation should be included
+     * @returns Array of objects containing the observation and its original index
+     */
+    if (observations.length !== mask.length) {
+        throw new Error(`Mask length (${mask.length}) must match observations length (${observations.length})`);
+    }
+    const result = [];
+    observations.forEach((observation, index) => {
+        if (mask[index]) {
+            result.push({ observation, index });
+        }
+    });
+    return result;
+}

package/dist/memory/masking.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/memory/masking.test.js

@@ -0,0 +1,117 @@
+import { describe, expect, test } from 'bun:test';
+import { Observation } from './observation';
+import { maskObservations, applyMask } from './masking';
+describe('maskObservations with freezeMask', () => {
+    test('freezeMask preserves frozen observation mask values', async () => {
+        const observations = [
+            new Observation('connector:test', 'user', 'obs1'),
+            new Observation('connector:test', 'user', 'obs2'),
+            new Observation('connector:test', 'user', 'obs3'),
+            new Observation('connector:test', 'user', 'obs4'),
+        ];
+        const freezeMask = [true, false, true];
+        const mask = await maskObservations(observations, freezeMask);
+        // First 3 observations should match freezeMask exactly
+        expect(mask[0]).toBe(true);
+        expect(mask[1]).toBe(false);
+        expect(mask[2]).toBe(true);
+        // Fourth observation (unfrozen) should be true by default
+        expect(mask[3]).toBe(true);
+    });
+    test('basic dedupe behavior', async () => {
+        // First test basic dedupe to understand behavior
+        const observations = [
+            new Observation('connector:test', 'user', 'content1', { type: 'msg', dedupe: true }),
+            new Observation('connector:test', 'user', 'content1', { type: 'msg', dedupe: true }),
+            new Observation('connector:test', 'user', 'content2', { type: 'msg', dedupe: true }),
+        ];
+        const mask = await maskObservations(observations);
+        // Dedupe keeps the last occurrence when adjacent
+        expect(mask).toEqual([false, true, true]);
+    });
+    test('dedupe preserves frozen observations when equivalent exists in unfrozen', async () => {
+        const observations = [
+            new Observation('connector:test', 'user', 'duplicate', { type: 'msg', dedupe: true }),
+            new Observation('connector:test', 'user', 'unique', { type: 'msg', dedupe: true }),
+            new Observation('connector:test', 'user', 'duplicate', { type: 'msg', dedupe: true }), // This duplicates frozen[0]
+            new Observation('connector:test', 'user', 'another', { type: 'msg', dedupe: true }),
+        ];
+        // With freezeMask, frozen observation should be preserved since equivalent exists in unfrozen
+        const freezeMask = [true, true];
+        const maskWithFreeze = await maskObservations(observations, freezeMask);
+        expect(maskWithFreeze).toEqual([true, true, true, true]);
+    });
+    test('limit only applies to unfrozen observations', async () => {
+        const observations = [
+            new Observation('connector:test', 'user', 'frozen1', { type: 'limited', limit: 2 }),
+            new Observation('connector:test', 'user', 'frozen2', { type: 'limited', limit: 2 }),
+            new Observation('connector:test', 'user', 'frozen3', { type: 'limited', limit: 2 }),
+            new Observation('connector:test', 'user', 'unfrozen1', { type: 'limited', limit: 2 }),
+            new Observation('connector:test', 'user', 'unfrozen2', { type: 'limited', limit: 2 }),
+            new Observation('connector:test', 'user', 'unfrozen3', { type: 'limited', limit: 2 }),
+        ];
+        // Without freezeMask, only last 2 observations would be kept
+        const normalMask = await maskObservations(observations);
+        expect(normalMask).toEqual([false, false, false, false, true, true]);
+        // With freezeMask, frozen observations don't count towards limit
+        // So we keep all 3 frozen + last 2 unfrozen
+        const freezeMask = [true, true, true];
+        const maskWithFreeze = await maskObservations(observations, freezeMask);
+        expect(maskWithFreeze).toEqual([true, true, true, false, true, true]);
+    });
+    test('freezeMask with mixed frozen values and limit', async () => {
+        const observations = [
+            new Observation('connector:test', 'user', 'frozen1', { type: 'mixed', limit: 1 }),
+            new Observation('connector:test', 'user', 'frozen2', { type: 'mixed', limit: 1 }),
+            new Observation('connector:test', 'user', 'unfrozen1', { type: 'mixed', limit: 1 }),
+            new Observation('connector:test', 'user', 'unfrozen2', { type: 'mixed', limit: 1 }),
+        ];
+        // Freeze mask says to hide frozen2 but show frozen1
+        const freezeMask = [true, false];
+        const mask = await maskObservations(observations, freezeMask);
+        // frozen1: true (from freezeMask)
+        // frozen2: false (from freezeMask)
+        // unfrozen1: false (exceeded limit of 1 for unfrozen)
+        // unfrozen2: true (last unfrozen, within limit)
+        expect(mask).toEqual([true, false, false, true]);
+    });
+    test('applyMask filters observations correctly', () => {
+        const observations = [
+            new Observation('connector:test', 'user', 'obs1'),
+            new Observation('connector:test', 'user', 'obs2'),
+            new Observation('connector:test', 'user', 'obs3'),
+        ];
+        const mask = [true, false, true];
+        const filtered = applyMask(observations, mask);
+        expect(filtered.length).toBe(2);
+        expect(filtered[0].observation.content).toBe('obs1');
+        expect(filtered[0].index).toBe(0);
+        expect(filtered[1].observation.content).toBe('obs3');
+        expect(filtered[1].index).toBe(2);
+    });
+    test('freezeMask with no typed observations', async () => {
+        // Test that untyped observations respect freezeMask
+        const observations = [
+            new Observation('connector:test', 'user', 'frozen1'),
+            new Observation('connector:test', 'user', 'frozen2'),
+            new Observation('connector:test', 'user', 'unfrozen1'),
+            new Observation('connector:test', 'user', 'unfrozen2'),
+        ];
+        const freezeMask = [false, true];
+        const mask = await maskObservations(observations, freezeMask);
+        // Frozen observations keep their freezeMask values
+        // Unfrozen untyped observations remain true
+        expect(mask).toEqual([false, true, true, true]);
+    });
+    test('freezeMask longer than observations array', async () => {
+        const observations = [
+            new Observation('connector:test', 'user', 'obs1'),
+            new Observation('connector:test', 'user', 'obs2'),
+        ];
+        const freezeMask = [true, false, true, false];
+        const mask = await maskObservations(observations, freezeMask);
+        // Should only apply freezeMask to existing observations
+        expect(mask.length).toBe(2);
+        expect(mask).toEqual([true, false]);
+    });
+});

package/dist/memory/observation.d.ts

@@ -0,0 +1,38 @@
+import { Image } from './image';
+import { MultiMediaJson } from './serde';
+import { MultiMediaMessage } from '@/ai/baml_client';
+import { type MultiMediaContentPart } from './rendering';
+export type ObservableDataPrimitive = Image | string | number | boolean | null | undefined;
+export type ObservableDataArray = Array<RenderableContent>;
+export type ObservableDataObject = {
+    [key: string]: RenderableContent;
+};
+export type RenderableContent = ObservableDataPrimitive | ObservableDataArray | ObservableDataObject;
+export type ObservationRole = 'user' | 'assistant';
+export interface ObservationRetentionOptions {
+    type: string;
+    limit?: number;
+    dedupe?: boolean;
+}
+export type ObservationSource = `connector:${string}` | `action:taken:${string}` | `action:result:${string}` | `thought`;
+export declare class Observation {
+    readonly source: ObservationSource;
+    readonly role: ObservationRole;
+    readonly timestamp: number;
+    readonly content: RenderableContent;
+    readonly retention?: ObservationRetentionOptions;
+    constructor(source: ObservationSource, role: ObservationRole, content: RenderableContent, retention?: ObservationRetentionOptions, timestamp?: number);
+    static fromConnector(connectorId: string, content: RenderableContent, options?: ObservationRetentionOptions): Observation;
+    static fromActionTaken(actionId: string, content: RenderableContent, options?: ObservationRetentionOptions): Observation;
+    static fromActionResult(actionId: string, content: RenderableContent, options?: ObservationRetentionOptions): Observation;
+    static fromThought(content: RenderableContent, options?: ObservationRetentionOptions): Observation;
+    toString(): string;
+    toJson(): Promise<MultiMediaJson>;
+    render(options?: {
+        prefix?: MultiMediaContentPart[];
+        postfix?: MultiMediaContentPart[];
+        cacheControl?: boolean;
+    }): Promise<MultiMediaMessage>;
+    hash(): Promise<string>;
+    equals(obs: Observation): Promise<boolean>;
+}