@scitrera/memorylayer-sdk 0.0.3

package/README.md

@@ -0,0 +1,374 @@
+# MemoryLayer TypeScript SDK
+
+TypeScript/JavaScript SDK for [MemoryLayer.ai](https://memorylayer.ai) - memory infrastructure for AI agents.
+
+## Installation
+
+```bash
+npm install @scitrera/memorylayer-sdk
+```
+
+## Quick Start
+
+```typescript
+import { MemoryLayerClient, MemoryType } from "@scitrera/memorylayer-sdk";
+
+const client = new MemoryLayerClient({
+  baseUrl: "http://localhost:61001",  // Optional, this is the default
+  apiKey: "your-api-key",             // Optional for local development
+  workspaceId: "my-workspace",
+});
+
+// Store a memory
+const memory = await client.remember("User prefers dark mode", {
+  type: MemoryType.SEMANTIC,
+  importance: 0.8,
+  tags: ["preference", "ui"],
+});
+
+// Recall memories
+const result = await client.recall("What are the user's UI preferences?", {
+  limit: 5,
+  minRelevance: 0.7,
+});
+
+console.log(result.memories);
+```
+
+## Features
+
+- **Full TypeScript Support** - Complete type definitions included
+- **Memory Operations** - Remember, recall, reflect, forget, decay
+- **Relationship Graph** - Link memories with 60+ typed relationships
+- **Session Management** - Working memory with TTL and commit
+- **Batch Operations** - Bulk create, update, delete
+- **Graph Traversal** - Multi-hop relationship queries
+- **Error Handling** - Typed exception hierarchy
+
+## Core Memory Operations
+
+### Remember (Store)
+
+```typescript
+// Basic storage
+const memory = await client.remember("Fixed authentication bug in login flow");
+
+// With options
+const memory = await client.remember("Implemented retry logic with exponential backoff", {
+  type: MemoryType.PROCEDURAL,
+  subtype: MemorySubtype.CODE_PATTERN,
+  importance: 0.9,
+  tags: ["retry", "error-handling"],
+  metadata: {
+    file: "src/api/client.ts",
+    author: "alice@example.com",
+  },
+});
+```
+
+### Recall (Retrieve)
+
+```typescript
+// Simple recall
+const result = await client.recall("How do we handle retries?");
+
+// Advanced recall with filters
+const result = await client.recall("authentication patterns", {
+  types: [MemoryType.PROCEDURAL, MemoryType.SEMANTIC],
+  tags: ["auth"],
+  limit: 10,
+  minRelevance: 0.6,
+  includeAssociations: true,
+  createdAfter: new Date("2024-01-01"),
+  mode: RecallMode.RAG,        // or LLM, HYBRID
+  detailLevel: DetailLevel.FULL, // or ABSTRACT, OVERVIEW
+});
+```
+
+### Reflect (Synthesize)
+
+```typescript
+const reflection = await client.reflect(
+  "What patterns have we learned about error handling?",
+  {
+    maxTokens: 1000,
+    depth: 3,
+    types: [MemoryType.PROCEDURAL],
+    includeSources: true,
+  }
+);
+
+console.log(reflection.reflection);
+console.log(`Based on ${reflection.source_memories.length} memories`);
+```
+
+### Memory Management
+
+```typescript
+// Get a specific memory
+const memory = await client.getMemory("mem-123");
+
+// Update a memory
+const updated = await client.updateMemory("mem-123", {
+  importance: 0.95,
+  tags: ["critical", "security"],
+});
+
+// Soft delete (archive)
+await client.forget("mem-123");
+
+// Hard delete (permanent)
+await client.forget("mem-123", true);
+
+// Apply decay to reduce importance
+const decayed = await client.decay("mem-123", 0.1);
+
+// Trace memory provenance
+const trace = await client.traceMemory("mem-123");
+```
+
+### Batch Operations
+
+```typescript
+const result = await client.batchMemories([
+  { action: "create", memory: { content: "Memory 1", importance: 0.7 } },
+  { action: "create", memory: { content: "Memory 2", importance: 0.8 } },
+  { action: "delete", memory_id: "mem-old", hard: false },
+]);
+
+console.log(`Successful: ${result.successful}, Failed: ${result.failed}`);
+```
+
+## Associations
+
+```typescript
+import { RelationshipType } from "@scitrera/memorylayer-sdk";
+
+// Create relationships between memories
+const association = await client.associate(
+  "mem-problem-123",
+  "mem-solution-456",
+  RelationshipType.SOLVES,
+  0.9
+);
+
+// Or use the full options interface
+const association = await client.createAssociation({
+  sourceId: "mem-problem-123",
+  targetId: "mem-solution-456",
+  relationship: RelationshipType.SOLVES,
+  strength: 0.9,
+  metadata: { verified: true },
+});
+
+// Get all associations for a memory
+const associations = await client.getAssociations("mem-123", "both");
+
+// Traverse the knowledge graph
+const result = await client.traverseGraph("mem-123", {
+  relationshipTypes: [RelationshipType.CAUSES, RelationshipType.LEADS_TO],
+  maxDepth: 3,
+  direction: "both",
+  minStrength: 0.5,
+});
+```
+
+## Session Management
+
+Sessions provide working memory with TTL that can be committed to long-term storage.
+
+```typescript
+// Create a session (auto-sets session ID for subsequent requests)
+const { session, briefing } = await client.createSession({
+  workspaceId: "my-workspace",
+  ttlSeconds: 3600,
+  briefing: true,  // Get briefing on session start
+});
+
+// Session ID is automatically included in subsequent requests
+// Or manually manage it:
+client.setSession(session.id);
+console.log(client.getSessionId());
+client.clearSession();
+
+// Store working memory on server
+await client.setWorkingMemory(session.id, "current_task", {
+  description: "Debugging auth",
+  file: "auth.py"
+});
+
+// Retrieve working memory
+const memory = await client.getWorkingMemory(session.id, "current_task");
+
+// Extend session TTL
+const updated = await client.touchSession(session.id);
+
+// Commit working memory to long-term storage
+const commitResult = await client.commitSession(session.id, {
+  minImportance: 0.5,
+  deduplicate: true,
+  maxMemories: 50,
+});
+console.log(`Created ${commitResult.memories_created} memories`);
+
+// Delete session
+await client.deleteSession(session.id);
+
+// Get briefing of recent activity
+const briefing = await client.getBriefing(24, true);
+console.log(briefing.recent_activity_summary);
+console.log(briefing.open_threads);
+```
+
+## Workspace Management
+
+```typescript
+// Create a workspace
+const workspace = await client.createWorkspace("My Project", {
+  embedding_model: "text-embedding-3-small",
+  default_importance: 0.5,
+});
+
+// Get workspace details
+const workspace = await client.getWorkspace("ws-123");
+
+// Update workspace
+const updated = await client.updateWorkspace("ws-123", {
+  name: "New Name",
+  settings: { key: "value" },
+});
+
+// Get workspace schema (relationship types, memory subtypes)
+const schema = await client.getWorkspaceSchema("ws-123");
+console.log(schema.relationship_types);
+console.log(schema.memory_subtypes);
+```
+
+## Types & Enums
+
+### MemoryType
+
+```typescript
+enum MemoryType {
+  EPISODIC = "episodic",     // Events and experiences
+  SEMANTIC = "semantic",     // Facts and knowledge
+  PROCEDURAL = "procedural", // How-to knowledge
+  WORKING = "working",       // Temporary context
+}
+```
+
+### MemorySubtype
+
+```typescript
+enum MemorySubtype {
+  SOLUTION = "solution",
+  PROBLEM = "problem",
+  CODE_PATTERN = "code_pattern",
+  FIX = "fix",
+  ERROR = "error",
+  WORKFLOW = "workflow",
+  PREFERENCE = "preference",
+  DECISION = "decision",
+  PROFILE = "profile",
+  ENTITY = "entity",
+  EVENT = "event",
+}
+```
+
+### RecallMode
+
+```typescript
+enum RecallMode {
+  RAG = "rag",       // Vector similarity search
+  LLM = "llm",       // LLM-powered semantic search
+  HYBRID = "hybrid", // Combination of both
+}
+```
+
+### RelationshipType
+
+60+ relationship types across 11 categories. Most commonly used:
+
+- **Hierarchical**: `parent_of`, `child_of`, `part_of`, `contains`, `instance_of`, `subtype_of`
+- **Causal**: `causes`, `triggers`, `leads_to`, `prevents`
+- **Solution**: `solves`, `addresses`, `alternative_to`, `improves`
+- **Context**: `occurs_in`, `applies_to`, `works_with`, `requires`
+- **Learning**: `builds_on`, `contradicts`, `confirms`, `supersedes`
+- **Similarity**: `similar_to`, `variant_of`, `related_to`
+- **Workflow**: `follows`, `depends_on`, `enables`, `blocks`
+- **Quality**: `effective_for`, `preferred_over`, `deprecated_by`
+- **Temporal**: `precedes`, `concurrent_with`, `follows_temporally`
+- **Refinement**: `refines`, `abstracts`, `specializes`, `generalizes`
+- **Reference**: `references`, `referenced_by`
+
+Use `getWorkspaceSchema()` to list all available types.
+
+## Error Handling
+
+```typescript
+import {
+  MemoryLayerError,
+  AuthenticationError,
+  AuthorizationError,
+  NotFoundError,
+  ValidationError,
+  RateLimitError,
+} from "@scitrera/memorylayer-sdk";
+
+try {
+  await client.remember("test");
+} catch (error) {
+  if (error instanceof AuthenticationError) {
+    console.error("Invalid API key");
+  } else if (error instanceof AuthorizationError) {
+    console.error("Access denied");
+  } else if (error instanceof NotFoundError) {
+    console.error("Resource not found");
+  } else if (error instanceof ValidationError) {
+    console.error("Validation failed:", error.details);
+  } else if (error instanceof RateLimitError) {
+    console.error(`Rate limited. Retry after ${error.retryAfter}s`);
+  } else if (error instanceof MemoryLayerError) {
+    console.error(`Error ${error.statusCode}: ${error.message}`);
+  }
+}
+```
+
+## Configuration
+
+```typescript
+const client = new MemoryLayerClient({
+  baseUrl: "http://localhost:61001", // Default
+  apiKey: process.env.MEMORYLAYER_API_KEY,
+  workspaceId: process.env.MEMORYLAYER_WORKSPACE_ID,
+  sessionId: "optional-session-id",  // Auto-include in requests
+  timeout: 30000, // Request timeout in ms (default: 30000)
+});
+```
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Build
+npm run build
+
+# Run tests
+npm test
+```
+
+## TypeScript Support
+
+This SDK is written in TypeScript and provides full type definitions out of the box. No need for `@types/*` packages.
+
+## License
+
+Apache 2.0 License - see LICENSE file for details.
+
+## Links
+
+- [Documentation](https://docs.memorylayer.ai)
+- [GitHub](https://github.com/scitrera/memorylayer)
+- [Homepage](https://memorylayer.ai)

package/dist/client.d.ts

@@ -0,0 +1,75 @@
+import type { Memory, RecallResult, ReflectResult, Association, Session, SessionBriefing, Workspace, Context, RememberOptions, RecallOptions, ReflectOptions, ClientConfig, SessionCreateOptions, SessionStartResponse, CommitOptions, CommitResponse, GraphTraverseOptions, GraphQueryResult, BatchOperation, BatchResult, AssociationCreateOptions, WorkspaceSchema, ContextExecOptions, ContextExecResult, ContextInspectOptions, ContextInspectResult, ContextLoadOptions, ContextLoadResult, ContextInjectOptions, ContextInjectResult, ContextQueryOptions, ContextQueryResult, ContextRlmOptions, ContextRlmResult, ContextStatusResult } from "./types.js";
+import { RelationshipType } from "./types.js";
+export declare class MemoryLayerClient {
+    private baseUrl;
+    private apiKey?;
+    private workspaceId?;
+    private sessionId?;
+    private timeout;
+    constructor(config?: ClientConfig);
+    /**
+     * Set the active session ID. All subsequent requests will include
+     * this session ID in the X-Session-ID header, enabling session-based
+     * workspace resolution.
+     */
+    setSession(sessionId: string): void;
+    /**
+     * Clear the active session ID.
+     */
+    clearSession(): void;
+    /**
+     * Get the current session ID, if any.
+     */
+    getSessionId(): string | undefined;
+    private request;
+    private handleError;
+    remember(content: string, options?: RememberOptions): Promise<Memory>;
+    recall(query: string, options?: RecallOptions): Promise<RecallResult>;
+    reflect(query: string, options?: ReflectOptions): Promise<ReflectResult>;
+    getMemory(memoryId: string): Promise<Memory>;
+    updateMemory(memoryId: string, updates: Partial<RememberOptions> & {
+        content?: string;
+    }): Promise<Memory>;
+    forget(memoryId: string, hard?: boolean): Promise<void>;
+    decay(memoryId: string, decayRate?: number): Promise<Memory>;
+    associate(sourceId: string, targetId: string, relationship: RelationshipType, strength?: number): Promise<Association>;
+    getAssociations(memoryId: string, direction?: "outgoing" | "incoming" | "both"): Promise<Association[]>;
+    /**
+     * Create a new session.
+     *
+     * @param options Session creation options
+     * @param autoSetSession If true (default), automatically set this session
+     *                       as the active session for subsequent requests
+     */
+    createSession(options?: SessionCreateOptions, autoSetSession?: boolean): Promise<SessionStartResponse>;
+    getSession(sessionId: string): Promise<Session>;
+    deleteSession(sessionId: string): Promise<void>;
+    setWorkingMemory(sessionId: string, key: string, value: unknown): Promise<void>;
+    getWorkingMemory(sessionId: string, key?: string): Promise<Record<string, unknown>>;
+    commitSession(sessionId: string, options?: CommitOptions): Promise<CommitResponse>;
+    touchSession(sessionId: string, ttlSeconds?: number): Promise<Session>;
+    getBriefing(lookbackHours?: number, includeContradictions?: boolean): Promise<SessionBriefing>;
+    createWorkspace(name: string, settings?: Record<string, unknown>): Promise<Workspace>;
+    getWorkspace(workspaceId?: string): Promise<Workspace>;
+    updateWorkspace(workspaceId: string, updates: {
+        name?: string;
+        settings?: Record<string, unknown>;
+    }): Promise<Workspace>;
+    createContext(name: string, description?: string, settings?: Record<string, unknown>): Promise<Context>;
+    listContexts(): Promise<Context[]>;
+    batchMemories(operations: BatchOperation[]): Promise<BatchResult>;
+    traceMemory(memoryId: string): Promise<Record<string, unknown>>;
+    traverseGraph(startMemoryId: string, options?: GraphTraverseOptions): Promise<GraphQueryResult>;
+    createAssociation(options: AssociationCreateOptions): Promise<Association>;
+    getWorkspaceSchema(workspaceId?: string): Promise<WorkspaceSchema>;
+    contextExec(code: string, options?: ContextExecOptions): Promise<ContextExecResult>;
+    contextInspect(options?: ContextInspectOptions): Promise<ContextInspectResult>;
+    contextLoad(varName: string, query: string, options?: ContextLoadOptions): Promise<ContextLoadResult>;
+    contextInject(key: string, value: unknown, options?: ContextInjectOptions): Promise<ContextInjectResult>;
+    contextQuery(prompt: string, variables: string[], options?: ContextQueryOptions): Promise<ContextQueryResult>;
+    contextRlm(goal: string, options?: ContextRlmOptions): Promise<ContextRlmResult>;
+    contextStatus(): Promise<ContextStatusResult>;
+    contextCleanup(): Promise<void>;
+    contextCheckpoint(): Promise<void>;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

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