Skip to content
BSWEN
Blog

How to Use Supermemory API: A Step-by-Step Quickstart

Cowrie
Cowrie
Dev @ Bswen

Purpose

I wanted to add persistent memory to a side project. I had heard about Supermemory but was not sure where to start. Which SDK should I use? How do I authenticate? What is a container tag? This post shows the exact steps I followed to go from zero to working memory in about five minutes.

Environment

  • Node.js 18+ or Python 3.9+
  • A Supermemory account from console.supermemory.ai
  • An API key from the settings page

Step 1: Install the SDK

For TypeScript or JavaScript projects:

Terminal
npm install supermemory

For Python projects:

Terminal
pip install supermemory

Step 2: Create the Client

index.ts
import Supermemory from "supermemory"


const client = new Supermemory()
// Reads SUPERMEMORY_API_KEY from environment automatically
main.py
from supermemory import Supermemory


client = Supermemory()
# Reads SUPERMEMORY_API_KEY from environment automatically

Make sure SUPERMEMORY_API_KEY is set in your environment. You can find it in the Supermemory console under Settings.

Step 3: Store Your First Memory

The client.add() method stores content. The containerTag parameter scopes the memory to a user or project.

store-memory.ts
await client.add({
  content: "User loves TypeScript and prefers functional patterns",
  containerTag: "user_123"
})
store_memory.py
client.add(
    content="User loves TypeScript and prefers functional patterns",
    container_tag="user_123"
)

I recommend picking a container tag strategy early. I use user_{id} for personal agents and project_{name} for team knowledge bases.

Step 4: Retrieve Context

There are two main ways to get context back: profile and search.

client.profile() returns a curated summary of what the system knows about a user:

retrieve-profile.ts
const { profile, searchResults } = await client.profile({
  containerTag: "user_123",
  q: "What programming style does the user prefer?"
})


// profile.static  -> ["Loves TypeScript", "Prefers functional patterns"]
// profile.dynamic -> ["Working on API integration"]
// searchResults   -> Relevant memories ranked by similarity
retrieve_profile.py
result = client.profile(container_tag="user_123", q="programming style")


print(result.profile.static)   # Long-term facts
print(result.profile.dynamic)  # Recent context

client.search.memories() is useful when you want raw search results instead of a summarized profile:

search-memories.ts
const results = await client.search.memories({
  q: "deployment preferences",
  containerTag: "user_123"
})

What Happened?

When I first tried this, I made a mistake: I called client.profile() without the q parameter and expected it to also run a semantic search. It does not. The q parameter is optional, but without it you only get the pre-built profile summary. If you need specific memories, either pass q to profile() or use client.search.memories() directly.

Configuration Tip

Before heavy use, configure filtering in the console. Two settings matter:

  • shouldLLMFilter — whether to run memories through an LLM filter before retrieval
  • filterPrompt — the prompt used for that filter

I left the defaults on for my first project and they worked fine. When I scaled up, I customized the filter prompt to exclude test data.

Summary

In this post, I showed how to set up Supermemory from scratch. The key point is that two core methods — add and profile — get you from zero to persistent AI memory in minutes. Pick a container tag strategy early, configure settings once, and let Supermemory handle extraction, embedding, and retrieval.

Final Words + More Resources

My intention with this article was to help others share my knowledge and experience. If you want to contact me, you can contact by email: Email me

Here are also the most important links from this article along with some further resources that will help you in this scope:

Oh, and if you found these resources useful, don’t forget to support me by starring the repo on GitHub!

Comments

Tags: