Quick Start · SDK · API Server · Architecture · Contributing

Why mem.sh?

Agents forget everything between sessions. mem.sh gives them a brain.

| | mem.sh | LangChain Memory | Roll your own | |---|---|---|---| | Setup | npx mem.sh set "..." | 47 dependencies + config | Hours of boilerplate | | External APIs | None | OpenAI key required | Depends | | Semantic search | Built-in TF-IDF | Embedding models | You build it | | Storage | SQLite (local) | Varies | You choose | | Lines of code | ~1 | ~50+ | ~200+ |

Features

• Fast — TF-IDF vectorization with cosine similarity, instant results
• Local-first — SQLite storage at ~/.mem/mem.db, no data leaves your machine
• Semantic — Recall by meaning, not exact match
• Zero config — npx and go. No API keys, no setup, no dependencies

Quick Start

CLI

# Store a memory
npx mem.sh set "user prefers dark mode"

# Recall semantically
npx mem.sh recall "what theme does the user like?"
# → user prefers dark mode (score: 0.87)

# List all memories
npx mem.sh list

# Forget a specific memory
npx mem.sh forget <id>

# Wipe everything
npx mem.sh clear

SDK

const mem = require('mem.sh');

// Store
await mem.set('user prefers dark mode');
await mem.set('favorite language is rust', { agent: 'coder-bot' });

// Recall (semantic search)
const results = await mem.recall('what does the user like?');
// [{ id, text, score, created_at }]

// List all
const all = await mem.list();

// Delete
await mem.forget(id);

// Clear everything
await mem.clear();

How It Works

mem.sh uses TF-IDF vectorization with cosine similarity for semantic search. No OpenAI key needed. No external APIs. Everything runs locally.

Memories are stored in ~/.mem/mem.db (SQLite). Each memory is tokenized and vectorized on write. Queries are vectorized at recall time and ranked by cosine similarity against stored vectors.

→ Full architecture docs

API Server

Run a shared memory server for multiple agents:

npx mem.sh serve --port 3456 --key my-secret-key

Endpoints

| Method | Path | Description | |--------|------|-------------| | POST | /mem | Store a memory | | GET | /mem/recall?q= | Semantic recall | | GET | /mem/list | List all memories | | DELETE | /mem/:id | Delete a memory | | DELETE | /mem | Clear all memories |

Headers

• X-Mem-Key — API key (required if --key is set)
• X-Mem-Agent — Agent namespace (optional, isolates memories per agent)

Example

# Store
curl -X POST http://localhost:3456/mem \
  -H "Content-Type: application/json" \
  -H "X-Mem-Key: my-secret-key" \
  -d '{"text": "user prefers dark mode"}'

# Recall
curl "http://localhost:3456/mem/recall?q=theme+preference" \
  -H "X-Mem-Key: my-secret-key"

SDK with API Mode

const mem = require('mem.sh');

mem.configure({
  api: 'http://localhost:3456',
  key: 'my-secret-key',
  agent: 'my-bot'
});

await mem.set('user prefers dark mode');
const results = await mem.recall('theme preference');

Contributing

We welcome contributions. See CONTRIBUTING.md for guidelines.

License

ISC