supermemory

Files (4)

• DISPLAY.json
• SKILL.md
• supermemory.png · assets/
• memory.py · scripts/

SKILL.md (first lines)

## Setup

1. Sign up at [supermemory.ai](https://supermemory.ai) and get an API key
2. Add `SUPERMEMORY_API_KEY` to your Zo secrets at [Settings > Advanced](/?t=settings&s=advanced)
3. Install this skill to `Skills/supermemory/`
4. (Optional) Install the CLI globally: `npm install -g supermemory`
5. (Optional) Set a default container tag: `npx supermemory config --set tag=<your-tag>`

**Important**: Always run commands through the Zo shell (`run_bash_command`), not the local shell. The API key is only available in the Zo environment.

## CLI

Primary CLI (official):
```bash
npx supermemory <command> [options]
```

Companion script (for commands not in the official CLI):
```bash
python3 Skills/supermemory/scripts/memory.py <command> [--container <name>] [options]
```

Container is set via `SUPERMEMORY_TAG` env var or `--tag` flag per command.

### Primary Commands (npx supermemory)

| Command | Purpose |
|---------|---------|
| remember | Save a memory directly (v4, immediately searchable) |
| search | Search memories with hybrid mode + reranking (v4) |
| profile | Get profile (static facts + dynamic context) |
| forget | Soft-delete a memory (v4) |
| update | Update a memory with versioning (v4) |
| add | Ingest content (text, file, URL) via document pipeline |
| tags | Manage container tags (list, info, create, delete, merge) |
| docs | Manage documents (list, get, delete, chunks, status) |

### Companion Commands (memory.py)

| Command | Purpose |
|---------|---------|
| conversation | Ingest structured messages via v4/conversations (role-attributed, incremental) |
| memories | List extracted memory entries with version history (v4/memories/list) |

## How Supermemory Works

Supermemory is a knowledge graph, not a key-value store. When you save content, it:

1. **Extracts facts** from the content
2. **Builds relationships** between memories:
   - **Updates**: New fact contradicts old one. Old gets deprioritized. Searches return current info.
   - **Extends**: New fact enriches existing one. Both remain valid.
   - **Derives**: System infers new facts from patterns.
3. **Maintains profiles** via `/v4/profile`, auto-generated from all accumulated memories.

### Two ingestion paths

- **Direct (v4/memories)**: `remember` command. Bypasses document pipeline. Immediately searchable. Best for entity-centric facts, decisions, preferences.
- **Pipeline (v3/documents)**: `add` command. Content goes through extraction, chunking, embedding. Best for URLs, long documents, files.

### Static vs dynamic memories

- **Static** (`--static`): Permanent traits that don't decay. Name, role, hometown, core preferences. Use for facts that should always surface in profiles.
- **Dynamic** (default): Normal memories subject to graph evolution, contradiction resolution, and time-based decay.

### Automatic forgetting

- **Contradiction resolution**: New facts supersede old ones in search results.
- **Noise filtering**: Casual content doesn't become permanent.
- **Soft delete**: `forget` marks memories as forgotten but preserves history.

You do NOT need to manually delete stale memories. The graph handles it.

## How to Use It

### RECALL (search when you need context)

Run `search` or `profile` whenever context would help:

- **Conversation start**: Profile for general context, search for topic-specific memories.
- **Mid-conversation**: When uncertain about prior decisions or preferences. Don't guess when you can check.
- **First mention of a person/company/project**: Search for existing context before responding.

Search modes:
- **memories** (default): Searches extracted memory entries only. Fast, low latency.
- **hybrid**: Searches both memories and document chunks. Best when you need both extracted facts and raw context.
- **documents**: Searches document chunks only. Use for RAG-style retrieval from ingested content.

Use `--rerank` when precision matters more than speed (~100ms overhead).
Use `--rewrite` to let Supermemory rewrite the query for better retrieval.

### CAPTURE (save when something worth remembering happens)

**For individual facts**: Use `remember`. Write entity-centric statements.
- Good: "User decided to use DuckDB for task management because of embedded SQL and zero dependencies."
- Bad: "We talked about databases and decided on DuckDB"

**For conversations**: Use `conversation` (companion script). The graph extracts multiple connected memories from the conversation structure, preserving relationships between facts that individual saves would lose.

**For URLs and documents**: Use `add`. Supermemory fetches the content, chunks it, extracts memories, and makes it searchable.

What to save:
- **Decisions** the moment they're made
- **Preferences** about tools, workflow, communication
- **Key facts** about people, companies, projects
- **Corrections** when a previous decision changes (reference what changed from what)

What NOT to save:
- Trivial exchanges
- Temporary/session-specific context
- Raw data that belongs in files
- Information already captured elsewhere

### Save Quality

Every save should be useful cold, readable with zero context about the current conversation.

Minimum bar: who/what entity, what the fact is, enough context that the "why" is inferrable. Under 15 words is probably too thin.

From Classified-AI-Core/skill-library, MIT.

More from Classified-AI-Core/skill-library