Reflect-Memory

# Reflect Memory

[![npm: reflect-memory-sdk](https://img.shields.io/npm/dm/reflect-memory-sdk?label=reflect-memory-sdk&color=blue)](https://www.npmjs.com/package/reflect-memory-sdk)
[![npm: reflect-memory-mcp](https://img.shields.io/npm/dm/reflect-memory-mcp?label=reflect-memory-mcp&color=blue)](https://www.npmjs.com/package/reflect-memory-mcp)
[![npm: n8n-nodes-reflect-memory](https://img.shields.io/npm/dm/n8n-nodes-reflect-memory?label=n8n-nodes-reflect-memory&color=blue)](https://www.npmjs.com/package/n8n-nodes-reflect-memory)
[![GitHub stars](https://img.shields.io/github/stars/van-reflect/Reflect-Memory?style=social)](https://github.com/van-reflect/Reflect-Memory)

Privacy-first AI memory system. All memory is explicitly user-authored, structured, editable, and deletable. The AI model is stateless -- it sees only what you choose to show it.

## Requirements

- Node.js >= 20.0.0 (LTS)
- An OpenAI-compatible API key (OpenAI, local model via ollama, etc.)

## Setup

```bash
npm install
```

## Environment Variables

Required:

```bash
export RM_API_KEY="your-secret-api-key"        # User key -- full access to all endpoints
export RM_MODEL_API_KEY="sk-..."               # Your OpenAI (or compatible) API key
export RM_MODEL_NAME="gpt-4o-mini"             # Model identifier
```

Optional:

```bash
export RM_PORT=3000                            # HTTP port (default: 3000)
export RM_DB_PATH="/data/reflect-memory.db"     # SQLite file path (default on Railway)
export RM_MODEL_BASE_URL="https://api.openai.com/v1"  # Model API base URL
export RM_MODEL_TEMPERATURE=0.7                # Temperature (default: 0.7)
export RM_MODEL_MAX_TOKENS=1024                # Max tokens (default: 1024)
export RM_SYSTEM_PROMPT="Your custom prompt"   # System prompt for AI queries
```

Agent keys (per-vendor, optional):

```bash
export RM_AGENT_KEY_CHATGPT="agent-key-for-chatgpt"   # Registers vendor "chatgpt"
export RM_AGENT_KEY_CLAUDE="agent-key-for-claude"      # Registers vendor "claude"
# RM_AGENT_KEY_<NAME> -- any env var matching this pattern registers a vendor
```

Dashboard multi-user auth (required for dashboard deployment):

```bash
export RM_DASHBOARD_SERVICE_KEY="..."   # Shared with dashboard. Generate: openssl rand -hex 32
export RM_DASHBOARD_JWT_SECRET="..."    # Must match dashboard AUTH_SECRET. Same value for JWT verification.
```

Multi-vendor chat (dashboard Chat tab -- enables GPT, Claude, Gemini, Perplexity, Grok):

```bash
export RM_CHAT_OPENAI_KEY="sk-..."        # Defaults to RM_MODEL_API_KEY if omitted
export RM_CHAT_ANTHROPIC_KEY="sk-ant-..." # Claude (console.anthropic.com)
export RM_CHAT_GOOGLE_KEY="..."           # Gemini (aistudio.google.com)
export RM_CHAT_PERPLEXITY_KEY="..."       # Perplexity (perplexity.ai/settings/api)
export RM_CHAT_XAI_KEY="..."             # Grok (x.ai)
```

Each agent key gives the vendor scoped access:
- Can write memories via `POST /agent/memories`
- Can query via `POST /query` (sees only memories with `allowed_vendors` containing `"*"` or their vendor name)
- Can check identity via `GET /whoami`
- Cannot access user endpoints (`POST /memories`, `GET /memories/:id`, `PUT /memories/:id`, `DELETE /memories/:id`, `POST /memories/list`)

## Run

Development (with hot reload via tsx):

```bash
npm run dev
```

Production:

```bash
npm run build
npm start
```

## API

All requests (except `/health`) require the `Authorization` header:

```
Authorization: Bearer your-secret-api-key
```

### Health check (no auth required)

```bash
curl -s https://api.reflectmemory.com/health | jq
```

### Who am I? (identity debugging)

```bash
curl -s https://api.reflectmemory.com/whoami \
  -H "Authorization: Bearer your-secret-api-key" | jq
```

Response:

```json
{ "role": "user", "vendor": null }
```

With an agent key:

```json
{ "role": "agent", "vendor": "chatgpt" }
```

### Create a memory (user path)

```bash
curl -s -X POST http://localhost:3000/memories \
  -H "Authorization: Bearer your-secret-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Project deadline",
    "content": "The API migration must be completed by end of Q3 2026.",
    "tags": ["work", "deadlines"]
  }' | jq
```

`allowed_vendors` is optional for user writes. If omitted, defaults to `["*"]` (all vendors can see it). To restrict:

```bash
curl -s -X POST http://localhost:3000/memories \
  -H "Authorization: Bearer your-secret-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Private note",
    "content": "Only Claude should see this.",
    "tags": ["private"],
    "allowed_vendors": ["claude"]
  }' | jq
```

### Create a memory (agent path)

Agents must use `POST /agent/memories`. The `origin` field is set server-side from the agent's key -- it cannot be self-reported. `allowed_vendors` is required.

```bash
curl -s -X POST http://localhost:3000/agent/memories \
  -H "Authorization: Bearer agent-key-for-chatgpt" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "ChatGPT learned this",
    "content": "User prefers bullet points over paragraphs.",
    "tags": ["preference"],
    "allowed_vendors": ["chatgpt"]
  }' | jq
```

Response (201):

```json
{
  "id": "a1b2c3d4-...",
  "user_id": "...",
  "title": "ChatGPT learned this",
  "content": "User prefers bullet points over paragraphs.",
  "tags": ["preference"],
  "origin": "chatgpt",
  "allowed_vendors": ["chatgpt"],
  "created_at": "2026-02-08T...",
  "updated_at": "2026-02-08T..."
}
```

### Read a memory by ID

```bash
curl -s http://localhost:3000/memories/MEMORY_ID \
  -H "Authorization: Bearer your-secret-api-key" | jq
```

### List memories (explicit filter required)

All memories:

```bash
curl -s -X POST http://localhost:3000/memories/list \
  -H "Authorization: Bearer your-secret-api-key" \
  -H "Content-Type: application/json" \
  -d '{ "filter": { "by": "all" } }' | jq
```

By tags:

```bash
curl -s -X POST http://localhost:3000/memories/list \
  -H "Authorization: Bearer your-secret-api-key" \
  -H "Content-Type: application/json" \
  -d '{ "filter": { "by": "tags", "tags": ["work"] } }' | jq
```

### Update a memory (full replacement)

Now requires `allowed_vendors` in the body (full replacement -- all fields required).

```bash
curl -s -X PUT http://localhost:3000/memories/MEMORY_ID \
  -H "Authorization: Bearer your-secret-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Project deadline (revised)",
    "content": "The API migration deadline has been extended to Q4 2026.",
    "tags": ["work", "deadlines", "revised"],
    "allowed_vendors": ["*"]
  }' | jq
```

### Delete a memory

```bash
curl -s -X DELETE http://localhost:3000/memories/MEMORY_ID \
  -H "Authorization: Bearer your-secret-api-key" -w "\nHTTP %{http_code}\n"
```

Returns `204 No Content` on success. The row is gone.

### Query the AI (with memory context)

User key sees all memories matching the filter:

```bash
curl -s -X POST http://localhost:3000/query \
  -H "Authorization: Bearer your-secret-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "When is the API migration deadline?",
    "memory_filter": { "by": "tags", "tags": ["deadlines"] }
  }' | jq
```

Agent key sees only memories where `allowed_vendors` contains `"*"` or the agent's vendor name:

```bash
curl -s -X POST http://localhost:3000/query \
  -H "Authorization: Bearer agent-key-for-chatgpt" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What are the user preferences?",
    "memory_filter": { "by": "all" }
  }' | jq
```

The `vendor_filter` field in the receipt shows which vendor filter was applied (`null` for users, vendor name for agents).

## Deploy to Railway

### 1. Environment variables

Set these in the Railway service's **Variables** tab:

| Variable | Required | Value |
|---|---|---|
| `RM_API_KEY` | Yes | A strong random string (your user API key) |
| `RM_MODEL_API_KEY` | Yes | Your OpenAI API key (`sk-...`) |
| `RM_MODEL_NAME` | Yes

[truncated…]