Best Practices for Developing with Supermemory: Architecture and Implementation Guide

The most effective way to develop with Supermemory involves using container tags for strict data isolation, leveraging the official TypeScript or Python SDKs for automatic retries and pagination, and following a three-step workflow of profiling, prompting, and adding memories to maintain a living knowledge graph.

Developing with Supermemory requires understanding its living knowledge graph architecture to build scalable AI applications with perfect recall. The supermemoryai/supermemory repository provides a state-of-the-art memory infrastructure that processes content through a six-stage pipeline and exposes a typed REST API. Following these best practices for developing with Supermemory ensures your integration remains fast, secure, and maintainable as your data grows.

Understanding the Core Architecture

The Living Knowledge Graph

Supermemory organizes content into semantic memories connected by three relationship types: Updates, Extends, and Derives. Unlike static file storage, this graph structure allows the system to traverse connections and retrieve contextually relevant information. According to the architecture reference in skills/supermemory/references/architecture.md, this design enables perfect recall by linking related concepts across time and documents.

The Six-Stage Processing Pipeline

Every document ingested into Supermemory passes through a strict sequence: Queued → Extracting → Chunking → Embedding → Indexing → Done. This pipeline, defined in the architecture documentation, ensures consistent chunk sizes, high-quality vector embeddings, and automatic relationship creation. Understanding these stages helps you set appropriate expectations for data availability and debug ingestion issues.

Container Tag Isolation

Container tags provide memory isolation and multi-tenancy through simple string identifiers like user_123, project_abc, or org_acme. The architecture reference specifies that tags guarantee privacy boundaries and performance optimization by partitioning the vector indexes. Every API operation requires a container tag to ensure data never leaks between users or organizations.

Typed API Layer

All interactions occur through a typed REST API defined in packages/lib/api.ts and exposed via the client SDKs. This contract specifies request/response shapes, authentication patterns, and endpoint behaviors. Using these typed definitions prevents integration errors and ensures your code remains compatible as the API evolves.

Semantic Search with HNSW Indexes

Queries undergo embedding and matching against HNSW vector indexes, followed by expansion through graph relationships. This two-phase approach, detailed in the architecture reference, returns highly relevant results by combining vector similarity with structural graph navigation.

Essential Development Practices

1. Isolate All Data with Container Tags

Every memory operation must specify a container tag to guarantee isolation. Tags enable per-user, per-project, or per-organization querying without data leakage. In multi-tenant environments, align your infrastructure isolation with Supermemory's security model by using consistent tagging schemes across your application layers.

2. Prefer Official SDKs Over Raw HTTP

The TypeScript SDK (npm i supermemory) and Python SDK (pip install supermemory) handle authentication, automatic retries, and pagination. These clients stay synchronized with the API contracts defined in packages/lib/api.ts, reducing boilerplate and preventing version mismatches. Raw HTTP requests require manual implementation of these resilience patterns.

3. Follow the Three-Step Context Workflow

Implement the profile-enrich-add pattern for optimal AI interactions:

1. Call profile() to retrieve static and dynamic context for a container tag
2. Enrich your LLM prompt with the retrieved facts
3. Call add() to store new memories after the interaction completes

This workflow guarantees the AI sees the most relevant historical context while continuously improving the knowledge graph.

4. Allow Platform-Controlled Chunking

Send complete documents rather than pre-chunked data. The processing pipeline in skills/supermemory/references/architecture.md optimizes chunk boundaries for embedding quality and recall performance. Only implement custom chunking if your content requires specific semantic boundaries not handled by the default extractors.

5. Attach Comprehensive Metadata

Include structured metadata such as source, timestamp, and custom tags when calling add(). Rich metadata enables fine-grained filtering during search and improves result ranking. The validation schemas in packages/validation/api.ts define acceptable metadata shapes to ensure compatibility.

6. Implement Strategic Client-Side Caching

Cache static profile data locally when requesting it frequently, but allow the server to handle dynamic profile freshness. The React Query provider in packages/lib/query-client.tsx demonstrates effective caching patterns with background refetching. This approach reduces API latency while preserving up-to-date context for critical operations.

7. Monitor Usage via Analytics Endpoints

Track consumption through the analytics endpoints (@get/analytics/*) defined in the API schema. Regular monitoring helps you stay within quota limits, identify performance regressions, and optimize expensive query patterns before they impact user experience.

8. Validate Custom Integrations with Schema Contracts

When building custom integrations or extending the API, use the Zod validation schemas in packages/validation/api.ts. These schemas enforce request and response shapes that match the server implementation, catching integration bugs during development rather than in production.

9. Deploy with Enterprise-Grade Security

Supermemory implements AES-256 encryption at rest and TLS 1.3 in transit. Ensure your deployment maintains these standards by using container-tag-based isolation and secure API key management. Reference the security section of skills/supermemory/references/architecture.md for compliance requirements.

Implementation Examples

Initializing the TypeScript Client

import { Supermemory } from "supermemory";

const client = new Supermemory({
  apiKey: process.env.SUPERMEMORY_API_KEY,
});

// Retrieve a user's static and dynamic profile
async function getUserContext(userId: string) {
  const response = await client.profile({
    containerTag: `user_${userId}`,
    q: "What does the user prefer?",
  });

  console.log("Static:", response.profile.static);
  console.log("Dynamic:", response.profile.dynamic);
  return response;
}

Enriching LLM Prompts with Retrieved Context

async function buildPrompt(userId: string, userMessage: string) {
  const ctx = await getUserContext(userId);
  const staticFacts = ctx.profile.static.map(f => `- ${f}`).join("\n");
  const dynamicFacts = ctx.profile.dynamic.map(f => `- ${f}`).join("\n");

  return `
Static Profile:
${staticFacts}

Recent Context:
${dynamicFacts}

User: ${userMessage}
`;
}

Storing New Memories After Interactions

await client.add({
  content: "User prefers dark mode and TypeScript",
  containerTag: `user_${userId}`,
  metadata: {
    source: "chat",
    timestamp: new Date().toISOString(),
  },
});

Python Async Implementation Patterns

import os, asyncio
from supermemory import AsyncSupermemory

async def main():
    client = AsyncSupermemory(api_key=os.getenv("SUPERMEMORY_API_KEY"))

    # Retrieve profile

    profile = await client.profile(
        container_tag="user_123", 
        q="What does the user prefer?"
    )
    print("Static:", profile["profile"]["static"])
    print("Dynamic:", profile["profile"]["dynamic"])

    # Store new memory

    await client.add(
        content="User mentioned they love dark mode",
        container_tag="user_123",
        metadata={"source": "chat"},
    )

asyncio.run(main())

Summary

• Container tags are mandatory for data isolation and must be included in every API call to ensure multi-tenancy and privacy.
• The official SDKs handle authentication, retries, and type safety automatically, making them superior to raw HTTP implementations.
• The profile-enrich-add workflow maximizes AI context quality while continuously improving the knowledge graph.
• Platform-controlled chunking in the six-stage pipeline produces optimal embeddings compared to client-side preprocessing.
• The validation schemas in packages/validation/api.ts and API contracts in packages/lib/api.ts provide authoritative references for integration development.

Frequently Asked Questions

What are container tags and why are they mandatory?

Container tags are string identifiers (like user_123 or project_abc) that partition the knowledge graph into isolated segments. They are mandatory because Supermemory uses these tags to enforce data privacy, enable multi-tenancy, and optimize vector index performance. Without container tags, the system cannot guarantee that queries return only authorized memories or maintain performance isolation between tenants.

Should I use raw HTTP requests or the official SDKs?

You should use the official TypeScript or Python SDKs for all production integrations. The SDKs implement automatic retry logic, pagination handling, and type safety based on the schemas in packages/lib/api.ts. Raw HTTP requires manual implementation of these patterns and risks drift when the API evolves, whereas the SDKs maintain backward compatibility and update automatically.

How does the processing pipeline impact memory availability?

Memories pass through six stages (Queued → Extracting → Chunking → Embedding → Indexing → Done) before becoming searchable. During the Queued and Extracting phases, content is not yet available for retrieval. Once a memory reaches the Done stage, it is fully indexed in the HNSW vector store and connected to the graph via Updates, Extends, or Derives relationships. Design your application to handle this latency by asynchronously processing documents and checking status when immediate recall is critical.

What security measures protect data in Supermemory?

Supermemory implements AES-256 encryption at rest and TLS 1.3 in transit for all data. The container tag architecture provides logical isolation between tenants, ensuring that memories tagged for user_123 are never returned in queries for user_456. For enterprise deployments, follow the security guidelines in skills/supermemory/references/architecture.md to align your infrastructure with these encryption standards and isolation requirements.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}