npm package: @justedv/mem.sh
Description: Persistent memory for AI agents. Like localStorage but for LLMs.
Author: justedv
Latest version: 0.1.0

<div align="center">

<h1>mem.sh</h1>

<p><strong>Persistent memory for AI agents.</strong><br>One line to save. One line to recall.</p>

[![npm version](https://img.shields.io/npm/v/mem.sh.svg?style=flat-square)](https://www.npmjs.com/package/mem.sh)
[![license](https://img.shields.io/npm/l/mem.sh.svg?style=flat-square)](https://github.com/justedv/mem.sh/blob/main/LICENSE)
[![downloads](https://img.shields.io/npm/dm/mem.sh.svg?style=flat-square)](https://www.npmjs.com/package/mem.sh)
[![GitHub stars](https://img.shields.io/github/stars/justedv/mem.sh?style=flat-square)](https://github.com/justedv/mem.sh)

<br>

[Quick Start](#quick-start) · [SDK](#sdk) · [API Server](#api-server) · [Architecture](#how-it-works) · [Contributing](CONTRIBUTING.md)

</div>

---

## 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

```bash
# 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

```js
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](docs/ARCHITECTURE.md)

## API Server

Run a shared memory server for multiple agents:

```bash
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

```bash
# 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

```js
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](CONTRIBUTING.md) for guidelines.

## License

[ISC](LICENSE)

---

<div align="center">
<sub>Built for agents that need to remember.</sub><br>
<a href="https://www.npmjs.com/package/mem.sh">npm</a> · <a href="https://github.com/justedv/mem.sh">GitHub</a> · <a href="https://github.com/justedv/mem.sh/issues">Issues</a>
</div>