---
title: "Glossary"
description: "Every supermemory term, defined once — and linked to the page that goes deep."
---
Every term in these docs is defined once, here. When another page says "memory" or "container tag", this is exactly what it means. Skim the headings; each entry links to the page that goes deep.
Most of the vocabulary shows up in a single add call:
```typescript TypeScript
import Supermemory from "supermemory"
const client = new Supermemory({ apiKey: process.env.SUPERMEMORY_API_KEY })
await client.add({
content: "Sarah's being promoted to VP of Product", // becomes a document
containerTag: "user_4f8a", // the isolation boundary
customId: "slack-thread-9917", // your stable id for this document
metadata: { channel: "slack", team: "product" }, // dimensions inside the boundary
})
```
```python Python
from supermemory import Supermemory
client = Supermemory()
client.add(
content="Sarah's being promoted to VP of Product",
container_tag="user_4f8a",
custom_id="slack-thread-9917",
metadata={"channel": "slack", "team": "product"},
)
```
```bash curl
curl -X POST "https://api.supermemory.ai/v3/documents" \
-H "Authorization: Bearer $SUPERMEMORY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"content": "Sarah'\''s being promoted to VP of Product",
"containerTag": "user_4f8a",
"customId": "slack-thread-9917",
"metadata": { "channel": "slack", "team": "product" }
}'
```
The content becomes a **document**, the pipeline derives **memories** from it, the memories join the **graph**, and the **profile** for `user_4f8a` updates. The rest of this page defines each of those words — plus the ones that control the process.
## From content to memory
### Document
The unit of ingestion. Anything you feed supermemory — a text note, a full chat session, a file, a URL, an item pulled in by a [connector](#connector) — is stored as a document. The document keeps your original content; the pipeline derives [memories](#memory) from it. Document-level operations (add, list, delete) live under v3, like `POST /v3/documents` above — see [versioning](/versioning) for the full endpoint map, and [content types](/concepts/content-types) for what you can ingest.
### Memory
An individual fact derived from your documents by the ingestion pipeline — a custom fine-tuned memory model, not a chunking script. Each memory carries provenance (which document it came from) and time (when it was true), and memories interconnect into the [graph](/concepts/graph-memory) as entities and relations. Memories are what `client.search.memories` (`POST /v4/search`) returns. Memory-level operations run on v4 — the rule of thumb is in [versioning](/versioning). For when to search memories versus raw content, read [memory vs RAG](/concepts/memory-vs-rag).
### Chunk
A slice of a document, sized for retrieval. Search matches at the chunk level, so you get the relevant passage instead of a 40-page document. On memory search you pull them in with `searchMode: "hybrid"`; document search returns matching chunks directly. How chunks, memories, and the graph combine at query time is the subject of [hybrid search](/concepts/hybrid-search).
### Dreaming
A background consolidation pass over recently ingested memories. It runs about 5 minutes after ingestion and connects new facts to what's already known. Dreaming has its own status (`dreaming` → `done`), separate from document processing status — your memories are queryable as soon as processing hits `done`; dreaming improves them after. You can disable it via the API. {/* CONFIRM: exact param for disabling dreaming */}
## What supermemory knows
### Profile
The current derived understanding of whatever a [container tag](#container-tag) holds — usually one user. There's one profile per container tag: the profile samples the container. You fetch it with one call:
```typescript TypeScript
const result = await client.profile({ containerTag: "user_4f8a" })
```
```python Python
result = client.profile(container_tag="user_4f8a")
```
```bash curl
curl -X POST "https://api.supermemory.ai/v4/profile" \
-H "Authorization: Bearer $SUPERMEMORY_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "containerTag": "user_4f8a" }'
```
The shape is two lists:
```json
{
"profile": {
"static": ["Product manager at Vantor", "Prefers direct, short answers"],
"dynamic": ["Preparing for Sarah's promotion to VP of Product", "…"]
}
}
```
Profiles are what you inject into your system prompt. The full injection pattern is in [user profiles](/concepts/user-profiles).
### Static vs dynamic memory
The two halves of a profile. **Static** memories are durable facts that stay true across sessions — name, role, long-held preferences. **Dynamic** memories are what's current and changing — what the user is working on this week. The split exists so you can cache the stable part and refresh the changing part. [User profiles](/concepts/user-profiles) covers when each populates and how to prompt with them.
### Bucket
A named grouping that shapes what a profile tracks, managed under the profile endpoint (`POST /v4/profile/buckets`). Use buckets when one flat profile isn't enough structure for your use case. {/* CONFIRM: bucket semantics — precise definition and config shape */} Details live in [user profiles](/concepts/user-profiles).
## Boundaries
### Container tag
The isolation boundary. One container tag per tenant, user, or project — everything inside it (documents, memories, graph, profile) is scoped to it, and nothing crosses it. Older docs and the console sometimes call this a "space"; same thing, and these docs say container tag. Two things to know up front: `containerTag` is singular everywhere you write it, and tags are immutable after creation — pick IDs you control (your internal user ID, not a third-party auth ID you might migrate away from). Large containers carry no performance penalty. The full multi-tenancy design guide is [permissioning](/concepts/permissioning).
### Metadata
Dimensions *within* a boundary. Metadata is key-value pairs on documents, and search filters on it. The rule that keeps multi-tenant systems sane: container tag for who owns the data, metadata for slicing it — agent role, channel, pipeline stage. Encoding role into the tag is the classic anti-pattern; it silos agents that should share memory. Metadata lives on documents, so when you need it back from memory search, pass `include: { documents: true }`. See [permissioning](/concepts/permissioning) for the recipes.
### Scoped key
An API key restricted to specific container tags. It's the multi-tenant guardrail: a key minted for `user_4f8a` cannot read or write any other container, even if it leaks into client-side code. If you're building anything multi-tenant, scoped keys are not optional hardening — they're the design. How to mint and use them: [permissioning](/concepts/permissioning).
### customId
Your own stable identifier for a document. Add content with the same `customId` again and supermemory updates that document instead of creating a duplicate. This is the mechanism behind the best ingestion pattern we know: one conversation session, one `customId`, re-added as the session grows — the whole thread stays one document. The pattern in full: [ingestion best practices](/patterns/ingestion).
## Shaping what's remembered
### filterPrompt
Org-wide, plain-language rules about *what to remember* — and what to skip: "Remember decisions and preferences; ignore small talk." It applies at ingestion, to every container in your org.
### entityContext
A per-container description of *who or what the entity is*. It's fed to the memory model at ingestion, so it changes what gets extracted, prioritized, and skipped — an entity described as "a QA automation agent" produces different memories from the same content than "a personal companion".
### Organization Context
The console's no-code editor for [filterPrompt](#filterprompt) — the same org-wide setting with a UI on it, not a separate field. The two levers, `filterPrompt` and `entityContext`, are additive: your prompts are prepended to supermemory's base extraction rules, never replacing them. How to tune them, including the task-memory configuration, is in [customization](/concepts/customization).
### Forgetting and TTL
Memories can expire, but supermemory only sets an expiry when the content states explicitly time-bound intent: "remind me a week from now" produces an expiring memory; "I take this medication for a week" does **not** — that's a fact worth keeping. To forget deliberately, `DELETE /v4/memories` takes a memory ID or the exact content. For agentic mass-forgetting there's `POST /v4/memories/forget-matching`, with a `dryRun` flag and a `maxForget` cap (default 100, max 500) so an agent can't wipe a container by accident.
## Ways in
### Surface
A door into the engine. The API and SDKs, MCP, plugins and hooks, the filesystem mount (SMFS — each mount scoped to exactly one container tag), connectors, and Company Brain are all surfaces — doors into the *same* engine. One store of memories, one graph, one set of profiles: anything ingested through any door is retrievable through every other door. No surface is a separate product, and no surface has its own memory. Which door fits which situation: [surfaces](/concepts/surfaces).
### Connector
A surface where content flows in on its own. Connect Notion, Google Drive, OneDrive, or the web crawler and synced items become [documents](#document), same as anything you add by API. Connector auth links expire after 1 hour; syncs run on connect, roughly every 4 hours, on webhooks where the provider supports them, and on demand. Disconnecting keeps the documents unless you pass `deleteDocuments: true`. Start at the [connectors overview](/connectors/overview); the sync details are in the [sync lifecycle](/connectors/sync-lifecycle).
---
That's the whole vocabulary — seventeen terms, and every other page in these docs builds on them without redefining any.
## Where next
The pipeline that turns documents into memories, the graph, and profiles.
Design multi-tenant isolation with container tags, metadata, and scoped keys.
Pick the right door into the engine for your situation.
Add your first memory and search it back in a few minutes.