Awareness Memory Cloud TypeScript SDK

TypeScript SDK for Awareness Memory Cloud APIs and MCP-style memory workflows.

Install

npm install @awareness-sdk/memory-cloud

Quickstart

import { MemoryCloudClient } from "@awareness-sdk/memory-cloud";

const client = new MemoryCloudClient({
  baseUrl: process.env.AWARENESS_API_BASE_URL || "https://awareness.market/api/v1",
  apiKey: "YOUR_API_KEY",
});

await client.write({
  memoryId: "memory_123",
  content: "Customer asked for SOC2 report and DPA clause details.",
  kwargs: { source: "typescript-sdk", session_id: "demo-session" },
});

const result = await client.retrieve({
  memoryId: "memory_123",
  query: "What did the customer ask for?",
  customKwargs: { k: 3 },
});

console.log(result.results);

API Coverage (SDK/API aligned)

MemoryCloudClient includes:

Memory: createMemory, listMemories, getMemory, updateMemory, deleteMemory
Content: write, listMemoryContent, deleteMemoryContent
Retrieval/Chat: retrieve, chat, chatStream, memoryTimeline
MCP ingest: ingestEvents, ingestContent
Export: exportMemoryPackage
Async jobs & upload: getAsyncJobStatus, uploadFile, getUploadJobStatus
Insights/API keys/wizard: insights, createApiKey, listApiKeys, revokeApiKey, memoryWizard

MCP-style Helpers (SDK/MCP aligned)

beginMemorySession
recallForTask
rememberStep
rememberBatch
backfillConversationHistory

const session = client.beginMemorySession({ memoryId: "memory_123", source: "ts-sdk" });
await client.rememberStep({
  memoryId: "memory_123",
  text: "Refactored auth middleware and added tests.",
});
const ctx = await client.recallForTask({
  memoryId: "memory_123",
  task: "summarize latest auth changes",
  limit: 8,
  multiLevel: false,        // enable multi-level retrieval for broader context
  clusterExpand: false,     // enable topic-based context expansion for comprehensive recall
});
console.log(ctx.results);

Read Exported Packages

SDK includes export readers:

readExportPackage(input)
parseJsonlText(text)

import { readExportPackage } from "@awareness-sdk/memory-cloud";

const parsed = await readExportPackage(zipBytes);
console.log(parsed.manifest);
console.log(parsed.chunks.length);
console.log(Boolean(parsed.safetensors));
console.log(parsed.kvSummary);

Client Auto-Extraction

Pass an OpenAI or Anthropic client to MemoryCloudClient to automatically extract insights when rememberStep/rememberBatch returns an extraction_request:

import { MemoryCloudClient } from "@awareness-sdk/memory-cloud";
import OpenAI from "openai";

const client = new MemoryCloudClient({
  baseUrl: "...",
  apiKey: "...",
  extractionLlm: new OpenAI(),  // or new Anthropic()
});

// Now rememberStep automatically extracts insights in the background
await client.rememberStep({ memoryId: "mem-xxx", text: "Fixed auth bug in login.py." });

Client extraction options: extractionLlm (OpenAI/Anthropic client), extractionModel (default: "gpt-4o-mini" / "claude-haiku-4-5-20251001"), extractionMaxTokens (default 16384, env: AWARENESS_EXTRACTION_MAX_TOKENS), userId, agentRole.

Agent Profiles & Sub-Agent Prompts

Retrieve enriched agent profiles with auto-generated activation prompts:

// List all agent profiles (with system_prompt and activation_prompt)
const agents = await client.listAgents({ memoryId: "mem-xxx" });
for (const agent of agents.agents ?? []) {
  console.log(agent.agent_role, agent.title);
  console.log(agent.activation_prompt);  // Ready-to-use prompt for sub-agent spawning
}

// Get activation prompt for a specific role
const prompt = await client.getAgentPrompt({ memoryId: "mem-xxx", agentRole: "backend_engineer" });

If a profile has a custom system_prompt (set in the frontend Settings), it is used as-is. Otherwise, a prompt is auto-generated from the profile fields (identity, critical_rules, workflow, etc.).

Interceptor (Transparent Injection)

The AwarenessInterceptor wraps any OpenAI/Anthropic client to automatically inject memory context pre-call and store conversations post-call:

import { MemoryCloudClient, AwarenessInterceptor } from "@awareness-sdk/memory-cloud";
import OpenAI from "openai";

const client = new MemoryCloudClient({ baseUrl: "...", apiKey: "..." });
const interceptor = await AwarenessInterceptor.create({
  client,
  memoryId: "mem-xxx",
  minRelevanceScore: 0.5,  // Filter low-score results (default 0.5)
  maxInjectItems: 5,        // Cap injected items (default 5)
  queryRewrite: "rule",     // Query rewrite mode (default "rule")
});

const oai = new OpenAI();
interceptor.wrapOpenAI(oai);
// Now all oai.chat.completions.create() calls get memory injection automatically

Interceptor options: retrieveLimit (default 8), maxContextChars (default 4000), minRelevanceScore (default 0.5), maxInjectItems (default 5), autoRemember (default true), enableExtraction (default true), extractionModel (default "gpt-4o-mini"), extractionMaxTokens (default 16384), queryRewrite (default "rule").

Query Rewrite Modes

"rule" (default): Context-aware query (recent 3 turns) + structural keyword extraction. Zero extra latency.
"llm": Uses the wrapped LLM to rewrite queries. Best for ambiguous or non-technical queries. Adds ~200-500ms.
"none": Raw last user message only (legacy behavior).

Injected Demo (Streaming + Full Journey)

Run the TypeScript injected-mode demo:

node scripts/run_ts_sdk_injected_conversation_demo.cjs --stream --full-user-journey

This demo validates:

Prompt-only injection mode (AwarenessInterceptor.registerFunction)
Client-side extraction submission (extraction_request -> submitInsights)
Event compaction before extraction (bounded by event count and char budget)
Cross-session recall in a new simulated follow-up session
Streaming LLM output for live run-state inspection

Environment Variables

export AWARENESS_API_BASE_URL="https://your-domain.com/api/v1"
export AWARENESS_API_KEY="aw_xxx"

# Optional: configure extraction LLM behavior
export AWARENESS_EXTRACTION_MODEL="gpt-4o-mini"        # Model used for insight extraction (default: gpt-4o-mini)
export AWARENESS_EXTRACTION_MAX_TOKENS="16384"          # Max tokens for extraction output (default: 16384)

All environment variables can also be set via constructor parameters (which take priority over env vars).

Documentation

TypeScript SDK