TypeScript SDK

The official TypeScript/JavaScript client for SharedMemory.

npm install @sharedmemory/sdk

Quick Start

import { SharedMemory } from '@sharedmemory/sdk';

const memory = new SharedMemory({
  apiKey: 'sm_agent_...',
  volumeId: 'your-project-id',
});

// Store a memory
await memory.remember('The user prefers dark mode');

// Recall memories
const result = await memory.recall('user preferences');
console.log(result.answer, result.sources);

Configuration

interface SharedMemoryConfig {
  apiKey: string;       // Required. Your API key (sm_agent_… or sm_proj_rw_…)
  baseUrl?: string;     // Default: https://api.sharedmemory.ai
  volumeId?: string;    // Default project (volume) for all calls
  agentName?: string;   // Agent name for attribution (default: "sdk-agent")
  timeout?: number;     // Request timeout in ms (default: 30000)
}

Methods

remember(content, opts?) / add(content, opts?)

Store a memory in the knowledge base. add is an alias for remember. The pipeline will classify, guard-check, extract entities, and build the graph automatically.

const result = await memory.remember('John works at Acme Corp as CTO', {
  memoryType: 'factual',   // factual | preference | event | relationship | technical
  source: 'onboarding',    // free-form source label
  volumeId: 'override-id', // override the default volume
});

Returns:

interface MemoryResult {
  status: string;      // "approved" | "rejected" | "merged"
  reason: string;      // Why the guard approved/rejected
  confidence: number;  // 0-1 confidence score
  memory_id: string;   // UUID of the stored memory
}

recall(query, opts?) / search(query, opts?)

Search memories by semantic similarity. search is an alias for recall. Returns matching memories from vector search plus related knowledge graph facts.

const result = await memory.recall('What does John do?', {
  volumeId: 'override-id',
  autoLearn: false,  // if true, the conversation itself is learned
});

Returns:

interface RecallResult {
  answer: string;
  sources: Array<{
    id: string;
    content: string;
    score: number;
  }>;
  graph_facts: Array<{
    source: string;
    type: string;
    target: string;
  }>;
}

get(memoryId)

Retrieve a single memory by ID.

const mem = await memory.get('memory-uuid');

update(memoryId, content)

Update the content of an existing memory.

await memory.update('memory-uuid', 'Updated fact about John');

delete(memoryId)

Delete a memory by ID.

await memory.delete('memory-uuid');

addMany(items, opts?)

Store multiple memories in a single batch call.

await memory.addMany([
  { content: 'Alice is VP of Engineering' },
  { content: 'Bob manages the frontend team' },
]);

feedback(memoryId, rating)

Submit feedback on a memory's relevance.

await memory.feedback('memory-uuid', 'POSITIVE');

history(opts?)

Get memory history for a volume.

const events = await memory.history({ limit: 50 });

assembleContext(query, opts?)

Assemble an optimized context block for LLM prompting.

const ctx = await memory.assembleContext('Tell me about the project');
console.log(ctx.blocks);

getEntity(name, opts?)

Get everything SharedMemory knows about a specific entity (person, project, concept).

const entity = await memory.getEntity('John Smith');
console.log(entity.summary);
console.log(entity.facts);         // string[]
console.log(entity.relationships); // { entity, type, description? }[]

Returns:

interface Entity {
  name: string;
  type: string;
  summary: string;
  facts: string[];
  relationships: Array<{
    entity: string;
    type: string;
    description?: string;
  }>;
}

searchEntities(query, opts?)

Search entities in the knowledge graph by name.

const entities = await memory.searchEntities('React', { limit: 5 });

Returns: Entity[]

getGraph(opts?)

Get the full knowledge graph for a volume.

const graph = await memory.getGraph();
console.log(graph.entities);       // all entities
console.log(graph.relationships);  // all relationships

listVolumes()

List all volumes the agent has access to.

const volumes = await memory.listVolumes();

subscribe(opts)

Subscribe to real-time updates via WebSocket. Receive events when memories are added, entities change, or other agents come online.

const sub = memory.subscribe({
  volumeId: 'my-volume',
  onMemory: (event) => {
    console.log('New memory:', event);
  },
  onActivity: (event) => {
    console.log('Activity:', event.title);
  },
  onPresence: (event) => {
    console.log('Agent presence:', event);
  },
});

// Later: clean up
sub.close();

Activity event shape:

interface ActivityEvent {
  event_id: string;
  volume_id: string;
  actor_type: string;
  actor_id: string;
  actor_name: string;
  event_type: string;
  title: string;
  detail: Record<string, any>;
  created_at: string;
}

Error Handling

All methods throw on HTTP errors. Wrap calls in try/catch:

try {
  await memory.remember('some fact');
} catch (err) {
  console.error(err.message); // "HTTP 429" or "content too long"
}

Agent Management — memory.agents

Manage agent profiles programmatically (requires a user-scoped or org-level key):

// List agents for an org
const agents = await memory.agents.list('org-id');

// Create an agent
const { agent, api_key } = await memory.agents.create({
  org_id: 'org-id',
  project_id: 'project-id',
  name: 'my-agent',
  system_prompt: 'You are a helpful assistant.',
});
console.log(api_key); // sm_agent_... — save this!

// Get agent details
const a = await memory.agents.get('agent-id');

// Update an agent
await memory.agents.update('agent-id', { name: 'renamed-agent' });

// Rotate API key
const { api_key: newKey } = await memory.agents.rotateKey('agent-id');

// Delete (deactivate) an agent
await memory.agents.delete('agent-id');

Organization Management — memory.orgs

// List your organizations
const orgs = await memory.orgs.list();

// Get org details
const org = await memory.orgs.get('org-id');

// List org members
const members = await memory.orgs.members('org-id');

// Apply a promo code
await memory.orgs.applyPromo('org-id', 'EARLYBUILDER');

Environment Variables

You can also set configuration via environment variables for server-side usage:

Variable	Description
SHAREDMEMORY_API_KEY	Your API key
SHAREDMEMORY_API_URL	API base URL
SHAREDMEMORY_VOLUME_ID	Default volume ID