# Best Practices for Developing with Supermemory: Architecture and Implementation Guide > Learn Supermemory best practices for development. Master container tags, SDKs, and a three-step workflow to build a living knowledge graph. Optimize your implementation. - Repository: [supermemory/supermemory](https://github.com/supermemoryai/supermemory) - Tags: best-practices - Published: 2026-03-25 --- **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`](https://github.com/supermemoryai/supermemory/blob/main/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`](https://github.com/supermemoryai/supermemory/blob/main/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`](https://github.com/supermemoryai/supermemory/blob/main/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`](https://github.com/supermemoryai/supermemory/blob/main/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`](https://github.com/supermemoryai/supermemory/blob/main/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`](https://github.com/supermemoryai/supermemory/blob/main/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`](https://github.com/supermemoryai/supermemory/blob/main/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`](https://github.com/supermemoryai/supermemory/blob/main/skills/supermemory/references/architecture.md) for compliance requirements. ## Implementation Examples ### Initializing the TypeScript Client ```typescript 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 ```typescript 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 ```typescript await client.add({ content: "User prefers dark mode and TypeScript", containerTag: `user_${userId}`, metadata: { source: "chat", timestamp: new Date().toISOString(), }, }); ``` ### Python Async Implementation Patterns ```python 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`](https://github.com/supermemoryai/supermemory/blob/main/packages/validation/api.ts) and API contracts in [`packages/lib/api.ts`](https://github.com/supermemoryai/supermemory/blob/main/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`](https://github.com/supermemoryai/supermemory/blob/main/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`](https://github.com/supermemoryai/supermemory/blob/main/skills/supermemory/references/architecture.md) to align your infrastructure with these encryption standards and isolation requirements.