SDK Usage Guide (Python / TypeScript)

This guide aligns SDK usage with Awareness API + MCP semantics.

1. Installation

Python (PyPI):

pip install awareness-memory-cloud

TypeScript (npm):

npm install @awareness-sdk/memory-cloud

2. Client Setup

Python

import os
from memory_cloud import MemoryCloudClient

client = MemoryCloudClient(
    base_url=os.getenv("AWARENESS_API_BASE_URL", os.getenv("AWARENESS_BASE_URL", "https://awareness.market/api/v1")),
    api_key="YOUR_API_KEY",
)

TypeScript

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",
});

3. MCP-aligned Helpers (same semantics as MCP tools)

• begin_memory_session / beginMemorySession
• recall_for_task / recallForTask
• remember_step / rememberStep
• remember_batch / rememberBatch
• backfill_conversation_history / backfillConversationHistory

These helpers mirror MCP tool semantics for programmatic use.

Auto-Extraction

Pass an OpenAI or Anthropic client as extraction_llm / extractionLlm to enable automatic insight extraction. When remember_step / rememberStep returns an extraction_request, the SDK automatically calls your LLM in the background and submits the results.

# Python
client = MemoryCloudClient(base_url="...", api_key="...", extraction_llm=openai.OpenAI())

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

4. API-parity Methods

Both SDKs expose aligned methods for:

• Memory CRUD: create/list/get/update/delete
• Content: write/list/delete
• Retrieve/Chat/Timeline
• MCP ingest: events + content
• Export package download
• Upload + async job polling
• Insights
• API key create/list/revoke
• Memory wizard

5. Export + Read Package

Export (safetensors)

{
  "package_type": "vector_only",
  "vector_binary_format": "safetensors",
  "regenerate_vectors_if_missing": true
}

Read in Python

from memory_cloud import read_export_package

parsed = read_export_package("memory_export.zip")
print(parsed["manifest"])
print(parsed["chunks"])
print(parsed["safetensors"])

Read in TypeScript

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

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

6. Framework Integrations

See the AI Frameworks guide for integrations with LangChain, CrewAI, PraisonAI, and AutoGen.

7. Front-end Connect

Each memory's Connect page in the dashboard provides ready-to-use config snippets for MCP, Python SDK, and TypeScript SDK with your memory ID pre-filled.

8. Multi-User Memory Mode

A single Memory can hold data for millions of users. Pass user_id to scope reads and writes per user.

Python

# Write scoped to a user
client.remember_step(memory_id="mid", text="Alice fixed auth bug", user_id="alice")
client.remember_batch(memory_id="mid", steps=["Step 1", "Step 2"], user_id="alice")
client.ingest_events(memory_id="mid", events=[...], user_id="alice")

# Read scoped to a user
ctx = client.get_session_context(memory_id="mid", user_id="alice")
tasks = client.get_pending_tasks(memory_id="mid", user_id="alice")
cards = client.get_knowledge_base(memory_id="mid", user_id="alice")

# Semantic search with metadata filter
results = client.retrieve(
    memory_id="mid",
    query="authentication decisions",
    metadata_filter={"user_id": "alice"},
)

TypeScript

// Write scoped to a user
await client.rememberStep({ memoryId: "mid", text: "Alice fixed auth bug", userId: "alice" });
await client.rememberBatch({ memoryId: "mid", steps: ["Step 1", "Step 2"], userId: "alice" });
await client.ingestEvents({ memoryId: "mid", events: [...], userId: "alice" });

// Read scoped to a user
const ctx = await client.getSessionContext({ memoryId: "mid", userId: "alice" });
const tasks = await client.getPendingTasks({ memoryId: "mid", userId: "alice" });
const cards = await client.getKnowledgeBase({ memoryId: "mid", userId: "alice" });

Personal mode (default): Do not pass user_id. All behavior is identical to before — existing setups are not affected.

9. Task Management

Use update_task_status to mark tasks complete after finishing work.

Python

# Get open tasks
result = client.get_pending_tasks(memory_id="mid", priority="high")
task_id = result["tasks"][0]["id"]

# Always record what you did first
client.remember_step(memory_id="mid", text="Fixed the N+1 query by adding .include() in Prisma.")

# Then mark the task done
client.update_task_status(memory_id="mid", task_id=task_id, status="completed")

TypeScript

const { tasks } = await client.getPendingTasks({ memoryId: "mid", priority: "high" });
const taskId = tasks![0].id!;

await client.rememberStep({ memoryId: "mid", text: "Fixed the N+1 query." });
await client.updateTaskStatus({ memoryId: "mid", taskId, status: "completed" });

10. Session Context

Load full project state at the start of every session.

Python

ctx = client.get_session_context(memory_id="mid", days=7, max_cards=10, max_tasks=20)

print("Recent days:")
for day in ctx.get("recent_days", []):
    print(f"  {day['date']}: {day['narrative']}")

print("Open tasks:")
for task in ctx.get("open_tasks", []):
    print(f"  [{task['priority']}] {task['title']}")

print("Knowledge cards:")
for card in ctx.get("knowledge_cards", []):
    print(f"  [{card['category']}] {card['title']}")

TypeScript

const ctx = await client.getSessionContext({ memoryId: "mid", days: 7 });

for (const day of ctx.recent_days ?? []) {
  console.log(`${day.date}: ${day.narrative}`);
}
for (const task of ctx.open_tasks ?? []) {
  console.log(`[${task.priority}] ${task.title}`);
}

11. Advanced Retrieval

Both retrieve and recall_for_task support advanced vector enhancement parameters:

Python

results = client.retrieve(
    memory_id="mid",
    query="authentication architecture",
    multi_level=True,        # search session and time-range context for broader recall
    cluster_expand=True,     # expand via topic-based grouping
)

ctx = client.recall_for_task(
    memory_id="mid",
    task="summarize all auth decisions",
    multi_level=True,
    cluster_expand=True,
)

TypeScript

const results = await client.retrieve({
  memoryId: "mid",
  query: "authentication architecture",
  multiLevel: true,
  clusterExpand: true,
});

const ctx = await client.recallForTask({
  memoryId: "mid",
  task: "summarize all auth decisions",
  multiLevel: true,
  clusterExpand: true,
});

These parameters can be combined with existing options like reconstruct_chunks, use_hybrid_search, and recall_mode.

12. Validation Coverage (Python + TypeScript)

Recent SDK validation includes:

• Conversation compaction before extraction (both SDKs)
• MCP-style recall helpers (recall_for_task / recallForTask) request-shape checks
• Streaming chat parsing (chat_stream / chatStream) callback flow checks
• Injected demo full journey (write -> extraction submit -> recall in fresh session)

Reference test paths:

• sdks/python/tests/test_client_recall_and_compaction.py
• sdks/typescript/tests/client.test.cjs
• sdks/typescript/tests/interceptor.test.cjs