# local-memo

Local-only MCP server for saving and restoring conversation context across AI agent sessions. No cloud, no accounts — just JSON files on disk.

Inspired by [Upstash Memo](https://github.com/upstash/memo), but fully local.

## Why?

Memo is a great idea — save your conversation context, get a short ID, restore it later in a different session or agent. But there's no reason that data needs to leave your machine. This version replaces the cloud API + Redis with plain files in `~/.local-memo/`.

## Install

### Claude Code

```bash
claude mcp add local-memo -- npx local-memo
```

Or from a local clone:

```bash
claude mcp add local-memo -- node /path/to/local-memo/dist/index.js
```

### Claude Desktop / Cursor

Add to your MCP config:

```json
{
  "mcpServers": {
    "local-memo": {
      "command": "npx",
      "args": ["local-memo"]
    }
  }
}
```

## Usage

### Save context

Ask your AI agent to save the current conversation context. It will call `memo_set` and return a short ID:

```
> Please save our conversation context

Context saved locally.
ID: 4tJ630XqhCV5gQelx98pu
Expires: 2025-01-30T14:38:51.278Z (1440 minutes)
```

### Restore context

In a new session, give the agent the ID:

```
> Restore memo 4tJ630XqhCV5gQelx98pu
```

### List saved memos

```
> List my saved memos
```

### Delete a memo

```
> Delete memo 4tJ630XqhCV5gQelx98pu
```

## Tools

| Tool | Description |
|------|-------------|
| `memo_set` | Save structured context (goal, completed tasks, pending tasks, decisions, files, extra context). Returns an ID. |
| `memo_get` | Restore context by ID. Returns formatted markdown. |
| `memo_list` | List all unexpired memos with their IDs and goals. |
| `memo_delete` | Delete a memo by ID. |

## Options

| Flag | Default | Description |
|------|---------|-------------|
| `--ttl-mins` | `1440` (24h) | How long memos live before expiring |
| `--dir` | `~/.local-memo` | Storage directory |

Example with 7-day TTL:

```bash
claude mcp add local-memo -- npx local-memo --ttl-mins 10080
```

## Storage

Memos are plain JSON files in `~/.local-memo/memos/`:

```json
{
  "id": "4tJ630XqhCV5gQelx98pu",
  "createdAt": "2025-01-29T14:38:51.278Z",
  "expiresAt": "2025-01-30T14:38:51.278Z",
  "ttlMins": 1440,
  "context": {
    "goal": "Build a local memo system",
    "completed": ["Designed schema", "Wrote MCP server"],
    "pending": ["Test it"],
    "decisions": ["Use filesystem instead of Redis"],
    "files": ["index.ts", "package.json"],
    "context": "Extra notes here"
  }
}
```

Back them up, sync them, grep them — they're just files.

## License

MIT