npm package: @hope666/melu
Description: Transparent AI memory agent — intercepts LLM API calls, injects persistent memory, extracts new memories automatically.
Author: Hong Yupeng
Latest version: 2.0.3

# Melu

Local memory proxy and observability dashboard for Claude Code.

Melu sits between Claude Code and the Anthropic Messages API. It can:

- inject relevant long-term memories into future requests
- extract new memories in the background
- keep all memory data local on your machine
- show a local dashboard for request flow, prompt packaging, tool use, and token timing

GitHub:

- Repository: [github.com/Hyp6666/melu](https://github.com/Hyp6666/melu)
- Issues: [github.com/Hyp6666/melu/issues](https://github.com/Hyp6666/melu/issues)

## What's New In v2

- local dashboard opens automatically after `melu run`
- request-level observability with Prompt / Answer inspection
- memory loading can be turned off entirely
- first-time setup now lets you skip model download if you do not want memory yet
- persistent config commands for language, mirror, memory, and dashboard behavior

## Quick Start

Install:

```bash
npm install -g @hope666/melu
```

Initialize:

```bash
melu init
```

Run Claude Code through Melu:

```bash
melu run -- claude
```

On first setup, Melu will ask:

1. which UI language to use
2. whether runtime memory should be enabled by default
3. which model mirror to use, if memory is enabled and the embedding model is not downloaded yet

If you choose to disable memory, Melu skips the embedding-model download and still works as a transparent proxy plus local dashboard.

## What Melu Does

When you run `melu run -- claude`, Melu starts a fixed three-process path:

1. Embedder daemon
2. Proxy / injection process
3. Extractor worker

Claude Code itself stays unmodified in the foreground.

The proxy intercepts Anthropic `POST /v1/messages`, optionally injects memories, forwards the request, and streams the response through. The extractor worker separately processes real user prompts and writes durable memories into a local SQLite `.memory` file.

## Dashboard

After startup succeeds, Melu opens:

```text
http://127.0.0.1:<port>/__melu
```

The dashboard is local-only and is meant for observability, not cloud analytics.

It currently shows:

- request overview and timing
- token and cache structure
- request chain per turn
- `↑ · Prompt` for uploaded prompt packaging
- `↓ · Answer` for model replies and tool instructions
- trace file access for the current run

You can disable auto-open later with:

```bash
melu config dashboard off
```

## Memory Is Optional

Melu now supports two modes:

### 1. Dashboard-only proxy mode

- no embedding model loaded
- no memory injection
- no memory extraction
- lower runtime footprint

### 2. Full memory mode

- local embedding model loaded once
- relevant memories injected into future prompts
- new durable memories extracted in the background

Toggle this for future runs:

```bash
melu config memory on
melu config memory off
```

## Command Reference

### Core

```bash
melu init
melu run -- claude
melu stop
melu status
```

### Memory files

```bash
melu list
melu show <id-prefix>
melu delete <id-prefix>
melu clear
melu export -o backup.memory
melu import backup.memory
```

### Persistent config

```bash
melu config show
melu config language zh-CN
melu config mirror modelscope
melu config memory on
melu config dashboard on
```

Available config switches:

- `melu config language [lang]`
- `melu config mirror [huggingface|modelscope]`
- `melu config memory [on|off]`
- `melu config dashboard [on|off]`

## Resource Notes

If memory is enabled, Melu downloads and uses:

- embedding model: `Qwen3-Embedding-0.6B-Q8_0.gguf`
- disk: about 600 MB once
- runtime memory: typically a few hundred MB for the embedder process

If memory is disabled, Melu skips that model entirely.

## Data And Privacy

All Melu state stays under:

```text
~/.melu/
```

Typical contents:

```text
~/.melu/
├── config.json
├── memories/
├── models/
├── pending-extractions/
├── sockets/
├── stats/
└── traces/
```

Important boundaries:

- memory databases are local SQLite files
- the embedding model runs locally
- Melu forwards your actual Claude requests only to Anthropic
- no separate Melu cloud service is involved

## Authentication

Melu works with Claude Code whether you authenticate with:

- Anthropic API key
- Claude OAuth login

It reuses Claude Code's normal upstream authentication path.

## Troubleshooting

Proxy did not start:

- check the port: `lsof -i :9800`
- try another port: `melu run -p 9801 -- claude`

Model download failed:

- switch mirror: `melu config mirror modelscope`
- then rerun `melu init` or enable memory from settings

No memories appearing:

- check `melu status`
- run `melu list`
- remember extraction runs in the background and may finish after the foreground session exits

Dashboard did not open:

- the URL is printed in the terminal after startup
- re-enable it with `melu config dashboard on`

## Requirements

- Node.js 20+
- Claude Code installed
- macOS or Linux

## License

[Apache-2.0](./LICENSE)

## Author

Hong Yupeng ([npm: hope666](https://www.npmjs.com/~hope666))