memorylens 0.1.0

package/README.md

@@ -0,0 +1,79 @@
+# MemoryLens JS/TS SDK
+
+**Observability and debugging for AI agent memory systems.**
+
+TypeScript SDK for instrumenting memory operations in JavaScript/TypeScript AI agents. Sends traces to the [MemoryLens](https://github.com/memorylens/memorylens) dashboard via OTLP.
+
+## Install
+
+```bash
+npm install memorylens
+```
+
+## Quick Start
+
+```typescript
+import { init, instrumentWrite, instrumentRead, context } from 'memorylens';
+
+// Initialize — sends traces to MemoryLens UI by default
+init();
+
+// Wrap your memory functions
+const store = instrumentWrite(async (content: string) => {
+  return await db.save(content);
+}, { backend: 'my_db' });
+
+const search = instrumentRead(async (query: string) => {
+  return await db.search(query);
+}, { backend: 'my_db' });
+
+// Add context for session tracking
+await context({ agentId: 'support-bot', sessionId: 'sess-123' }, async () => {
+  await store('user prefers dark mode');
+  const results = await search('user preferences');
+});
+```
+
+## Auto-Instrumentation (LangChain.js)
+
+```typescript
+import { init } from 'memorylens';
+import { LangChainInstrumentor } from 'memorylens/integrations/langchain';
+
+init();
+new LangChainInstrumentor().instrument();
+// All LangChain memory operations are now traced
+```
+
+## Configuration
+
+```typescript
+init({
+  serviceName: 'my-agent',
+  exporter: 'otlp',                              // 'otlp' or 'console'
+  endpoint: 'http://localhost:8000/v1/traces',    // MemoryLens UI ingest
+  captureContent: true,
+  sampleRate: 1.0,
+});
+```
+
+Or via environment variables:
+
+```bash
+export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:8000/v1/traces
+export OTEL_SERVICE_NAME=my-agent
+```
+
+## View Traces
+
+Start the MemoryLens dashboard (Python):
+
+```bash
+pip install memorylens[ui]
+memorylens ui --ingest
+# Open http://localhost:8000
+```
+
+## License
+
+Apache 2.0

package/dist/index-BZqWj0_R.d.mts

@@ -0,0 +1,6 @@
+interface Instrumentor {
+    instrument(options?: Record<string, unknown>): void;
+    uninstrument(): void;
+}
+
+export type { Instrumentor as I };

package/dist/index-BZqWj0_R.d.ts

@@ -0,0 +1,6 @@
+interface Instrumentor {
+    instrument(options?: Record<string, unknown>): void;
+    uninstrument(): void;
+}
+
+export type { Instrumentor as I };

package/dist/index.d.mts

@@ -0,0 +1,171 @@
+export { I as Instrumentor } from './index-BZqWj0_R.mjs';
+
+declare class Sampler {
+    private rate;
+    constructor(rate?: number);
+    shouldSample(): boolean;
+    getRate(): number;
+}
+
+type MemoryOperation = 'memory.write' | 'memory.read' | 'memory.compress' | 'memory.update';
+type SpanStatus = 'ok' | 'error' | 'dropped';
+declare enum ExportResult {
+    SUCCESS = 0,
+    FAILURE = 1
+}
+interface MemorySpan {
+    spanId: string;
+    traceId: string;
+    parentSpanId: string | null;
+    operation: MemoryOperation;
+    status: SpanStatus;
+    startTime: number;
+    endTime: number;
+    durationMs: number;
+    agentId: string | null;
+    sessionId: string | null;
+    userId: string | null;
+    inputContent: string | null;
+    outputContent: string | null;
+    attributes: Record<string, unknown>;
+}
+interface SpanProcessor {
+    onStart(span: MemorySpan): void;
+    onEnd(span: MemorySpan): void;
+    shutdown(): Promise<void>;
+    forceFlush(timeoutMs?: number): Promise<boolean>;
+}
+interface SpanExporter {
+    export(spans: MemorySpan[]): Promise<ExportResult>;
+    shutdown(): Promise<void>;
+}
+interface MemoryContext {
+    agentId?: string | null;
+    sessionId?: string | null;
+    userId?: string | null;
+}
+
+declare class MutableSpan {
+    readonly traceId: string;
+    readonly spanId: string;
+    readonly operation: MemoryOperation;
+    readonly parentSpanId: string | null;
+    status: SpanStatus;
+    readonly startTime: number;
+    endTime: number;
+    agentId: string | null;
+    sessionId: string | null;
+    userId: string | null;
+    inputContent: string | null;
+    outputContent: string | null;
+    attributes: Record<string, unknown>;
+    constructor(options: {
+        operation: MemoryOperation;
+        parentSpanId?: string | null;
+        agentId?: string | null;
+        sessionId?: string | null;
+        userId?: string | null;
+        attributes?: Record<string, unknown>;
+    });
+    setAttribute(key: string, value: unknown): void;
+    setContent(input?: string | null, output?: string | null): void;
+    setStatus(status: SpanStatus): void;
+    setError(error: unknown): void;
+    end(): MemorySpan;
+}
+declare class Tracer {
+    private name;
+    private provider;
+    constructor(name: string, provider: TracerProvider);
+    getName(): string;
+    startSpan(operation: MemoryOperation, attributes?: Record<string, unknown>): MutableSpan;
+    endSpan(span: MutableSpan): void;
+}
+declare class TracerProvider {
+    private static instance;
+    processors: SpanProcessor[];
+    sampler: Sampler;
+    serviceName: string;
+    static get(): TracerProvider;
+    static reset(): void;
+    addProcessor(processor: SpanProcessor): void;
+    getTracer(name: string): Tracer;
+    shutdown(): Promise<void>;
+}
+
+declare function runWithContext<T>(ctx: MemoryContext, fn: () => T): T;
+declare function getCurrentContext(): MemoryContext | undefined;
+
+declare class SimpleSpanProcessor implements SpanProcessor {
+    private exporter;
+    constructor(exporter: SpanExporter);
+    onStart(_span: MemorySpan): void;
+    onEnd(span: MemorySpan): void;
+    shutdown(): Promise<void>;
+    forceFlush(_timeoutMs?: number): Promise<boolean>;
+}
+declare class BatchSpanProcessor implements SpanProcessor {
+    private exporter;
+    private queue;
+    private maxBatchSize;
+    private scheduleDelayMs;
+    private maxQueueSize;
+    private timer;
+    private isShutdown;
+    constructor(exporter: SpanExporter, options?: {
+        maxBatchSize?: number;
+        scheduleDelayMs?: number;
+        maxQueueSize?: number;
+    });
+    onStart(_span: MemorySpan): void;
+    onEnd(span: MemorySpan): void;
+    shutdown(): Promise<void>;
+    forceFlush(_timeoutMs?: number): Promise<boolean>;
+    private flush;
+    private scheduleFlush;
+}
+
+declare class ConsoleExporter implements SpanExporter {
+    export(spans: MemorySpan[]): Promise<ExportResult>;
+    shutdown(): Promise<void>;
+}
+
+/**
+ * OTLP HTTP exporter — maps MemorySpan to OpenTelemetry protobuf-JSON format
+ * and ships to the MemoryLens ingest endpoint (or any OTLP-compatible backend).
+ */
+declare class OTLPExporter implements SpanExporter {
+    private endpoint;
+    constructor(options?: {
+        endpoint?: string;
+    });
+    export(spans: MemorySpan[]): Promise<ExportResult>;
+    shutdown(): Promise<void>;
+    private buildOTLPPayload;
+    private spanToOTLP;
+}
+
+interface WrapperOptions {
+    captureContent?: boolean;
+    [key: string]: unknown;
+}
+type AnyAsyncFn<TArgs extends unknown[], TReturn> = (...args: TArgs) => Promise<TReturn>;
+declare function instrumentWrite<TArgs extends unknown[], TReturn>(fn: AnyAsyncFn<TArgs, TReturn>, options?: WrapperOptions): AnyAsyncFn<TArgs, TReturn>;
+declare function instrumentRead<TArgs extends unknown[], TReturn>(fn: AnyAsyncFn<TArgs, TReturn>, options?: WrapperOptions): AnyAsyncFn<TArgs, TReturn>;
+declare function instrumentCompress<TArgs extends unknown[], TReturn>(fn: AnyAsyncFn<TArgs, TReturn>, options?: WrapperOptions): AnyAsyncFn<TArgs, TReturn>;
+declare function instrumentUpdate<TArgs extends unknown[], TReturn>(fn: AnyAsyncFn<TArgs, TReturn>, options?: WrapperOptions): AnyAsyncFn<TArgs, TReturn>;
+
+interface InitOptions {
+    serviceName?: string;
+    exporter?: 'otlp' | 'console';
+    endpoint?: string;
+    captureContent?: boolean;
+    sampleRate?: number;
+    batch?: boolean;
+}
+declare function init(options?: InitOptions): void;
+declare function shutdown(): Promise<void>;
+declare function context<T>(ctx: MemoryContext, fn: () => Promise<T>): Promise<T>;
+declare function getTracer(name: string): Tracer;
+
+export { BatchSpanProcessor, ConsoleExporter, ExportResult, type InitOptions, type MemoryContext, type MemoryOperation, type MemorySpan, MutableSpan, OTLPExporter, Sampler, SimpleSpanProcessor, type SpanExporter, type SpanProcessor, type SpanStatus, Tracer, TracerProvider, context, getCurrentContext, getTracer, init, instrumentCompress, instrumentRead, instrumentUpdate, instrumentWrite, runWithContext, shutdown };

package/dist/index.d.ts

@@ -0,0 +1,171 @@
+export { I as Instrumentor } from './index-BZqWj0_R.js';
+
+declare class Sampler {
+    private rate;
+    constructor(rate?: number);
+    shouldSample(): boolean;
+    getRate(): number;
+}
+
+type MemoryOperation = 'memory.write' | 'memory.read' | 'memory.compress' | 'memory.update';
+type SpanStatus = 'ok' | 'error' | 'dropped';
+declare enum ExportResult {
+    SUCCESS = 0,
+    FAILURE = 1
+}
+interface MemorySpan {
+    spanId: string;
+    traceId: string;
+    parentSpanId: string | null;
+    operation: MemoryOperation;
+    status: SpanStatus;
+    startTime: number;
+    endTime: number;
+    durationMs: number;
+    agentId: string | null;
+    sessionId: string | null;
+    userId: string | null;
+    inputContent: string | null;
+    outputContent: string | null;
+    attributes: Record<string, unknown>;
+}
+interface SpanProcessor {
+    onStart(span: MemorySpan): void;
+    onEnd(span: MemorySpan): void;
+    shutdown(): Promise<void>;
+    forceFlush(timeoutMs?: number): Promise<boolean>;
+}
+interface SpanExporter {
+    export(spans: MemorySpan[]): Promise<ExportResult>;
+    shutdown(): Promise<void>;
+}
+interface MemoryContext {
+    agentId?: string | null;
+    sessionId?: string | null;
+    userId?: string | null;
+}
+
+declare class MutableSpan {
+    readonly traceId: string;
+    readonly spanId: string;
+    readonly operation: MemoryOperation;
+    readonly parentSpanId: string | null;
+    status: SpanStatus;
+    readonly startTime: number;
+    endTime: number;
+    agentId: string | null;
+    sessionId: string | null;
+    userId: string | null;
+    inputContent: string | null;
+    outputContent: string | null;
+    attributes: Record<string, unknown>;
+    constructor(options: {
+        operation: MemoryOperation;
+        parentSpanId?: string | null;
+        agentId?: string | null;
+        sessionId?: string | null;
+        userId?: string | null;
+        attributes?: Record<string, unknown>;
+    });
+    setAttribute(key: string, value: unknown): void;
+    setContent(input?: string | null, output?: string | null): void;
+    setStatus(status: SpanStatus): void;
+    setError(error: unknown): void;
+    end(): MemorySpan;
+}
+declare class Tracer {
+    private name;
+    private provider;
+    constructor(name: string, provider: TracerProvider);
+    getName(): string;
+    startSpan(operation: MemoryOperation, attributes?: Record<string, unknown>): MutableSpan;
+    endSpan(span: MutableSpan): void;
+}
+declare class TracerProvider {
+    private static instance;
+    processors: SpanProcessor[];
+    sampler: Sampler;
+    serviceName: string;
+    static get(): TracerProvider;
+    static reset(): void;
+    addProcessor(processor: SpanProcessor): void;
+    getTracer(name: string): Tracer;
+    shutdown(): Promise<void>;
+}
+
+declare function runWithContext<T>(ctx: MemoryContext, fn: () => T): T;
+declare function getCurrentContext(): MemoryContext | undefined;
+
+declare class SimpleSpanProcessor implements SpanProcessor {
+    private exporter;
+    constructor(exporter: SpanExporter);
+    onStart(_span: MemorySpan): void;
+    onEnd(span: MemorySpan): void;
+    shutdown(): Promise<void>;
+    forceFlush(_timeoutMs?: number): Promise<boolean>;
+}
+declare class BatchSpanProcessor implements SpanProcessor {
+    private exporter;
+    private queue;
+    private maxBatchSize;
+    private scheduleDelayMs;
+    private maxQueueSize;
+    private timer;
+    private isShutdown;
+    constructor(exporter: SpanExporter, options?: {
+        maxBatchSize?: number;
+        scheduleDelayMs?: number;
+        maxQueueSize?: number;
+    });
+    onStart(_span: MemorySpan): void;
+    onEnd(span: MemorySpan): void;
+    shutdown(): Promise<void>;
+    forceFlush(_timeoutMs?: number): Promise<boolean>;
+    private flush;
+    private scheduleFlush;
+}
+
+declare class ConsoleExporter implements SpanExporter {
+    export(spans: MemorySpan[]): Promise<ExportResult>;
+    shutdown(): Promise<void>;
+}
+
+/**
+ * OTLP HTTP exporter — maps MemorySpan to OpenTelemetry protobuf-JSON format
+ * and ships to the MemoryLens ingest endpoint (or any OTLP-compatible backend).
+ */
+declare class OTLPExporter implements SpanExporter {
+    private endpoint;
+    constructor(options?: {
+        endpoint?: string;
+    });
+    export(spans: MemorySpan[]): Promise<ExportResult>;
+    shutdown(): Promise<void>;
+    private buildOTLPPayload;
+    private spanToOTLP;
+}
+
+interface WrapperOptions {
+    captureContent?: boolean;
+    [key: string]: unknown;
+}
+type AnyAsyncFn<TArgs extends unknown[], TReturn> = (...args: TArgs) => Promise<TReturn>;
+declare function instrumentWrite<TArgs extends unknown[], TReturn>(fn: AnyAsyncFn<TArgs, TReturn>, options?: WrapperOptions): AnyAsyncFn<TArgs, TReturn>;
+declare function instrumentRead<TArgs extends unknown[], TReturn>(fn: AnyAsyncFn<TArgs, TReturn>, options?: WrapperOptions): AnyAsyncFn<TArgs, TReturn>;
+declare function instrumentCompress<TArgs extends unknown[], TReturn>(fn: AnyAsyncFn<TArgs, TReturn>, options?: WrapperOptions): AnyAsyncFn<TArgs, TReturn>;
+declare function instrumentUpdate<TArgs extends unknown[], TReturn>(fn: AnyAsyncFn<TArgs, TReturn>, options?: WrapperOptions): AnyAsyncFn<TArgs, TReturn>;
+
+interface InitOptions {
+    serviceName?: string;
+    exporter?: 'otlp' | 'console';
+    endpoint?: string;
+    captureContent?: boolean;
+    sampleRate?: number;
+    batch?: boolean;
+}
+declare function init(options?: InitOptions): void;
+declare function shutdown(): Promise<void>;
+declare function context<T>(ctx: MemoryContext, fn: () => Promise<T>): Promise<T>;
+declare function getTracer(name: string): Tracer;
+
+export { BatchSpanProcessor, ConsoleExporter, ExportResult, type InitOptions, type MemoryContext, type MemoryOperation, type MemorySpan, MutableSpan, OTLPExporter, Sampler, SimpleSpanProcessor, type SpanExporter, type SpanProcessor, type SpanStatus, Tracer, TracerProvider, context, getCurrentContext, getTracer, init, instrumentCompress, instrumentRead, instrumentUpdate, instrumentWrite, runWithContext, shutdown };