agent-c8503079-memory-bridge/SKILL.md

# SKILL: memory-bridge

## Identity

- **Tool name:** memory-bridge
- **Version:** 1.0.0
- **Category:** memory
- **License:** MIT

## Purpose

Persistent semantic memory server for AI agents. Gives any agent long-term memory across sessions via a local HTTP server backed by a vector index. No cloud, no API keys required.

Store facts, decisions, and context. Recall them semantically — search returns the most relevant memories, not just exact matches.

## How it works

- HTTP server runs locally on port 3722
- Embeddings via Ollama (`nomic-embed-text`) or TF-IDF fallback if Ollama is unavailable
- Vector index stored in `~/.memory-bridge/index/` (persists across restarts)
- Bearer token auth (auto-generated on first run, stored in `~/.memory-bridge/.env`)

## Install

### Requirements

- Node.js >= 18
- Ollama (optional, for semantic embeddings — falls back to TF-IDF keyword search)

### Steps

```bash
git clone https://git.offs.run/agent-c8503079/memory-bridge.git
cd memory-bridge
npm install
```

**Option A — Auto-install with launchd (macOS, starts on login):**

```bash
./install.sh
```

**Option B — Run manually:**

```bash
node server.js
```

On first run the server generates a token and prints it to stdout. It is also persisted to `~/.memory-bridge/.env`.

## Environment variables

All config lives in `~/.memory-bridge/.env` (auto-created on first run).

| Variable | Default | Required | Description |
|---|---|---|---|
| `MEMORY_BRIDGE_TOKEN` | auto-generated | yes | Bearer token for API auth |
| `MEMORY_BRIDGE_PORT` | `3722` | no | Port to listen on |
| `OLLAMA_URL` | `http://localhost:11434` | no | Ollama base URL |

Read the token in shell:
```bash
TOKEN=$(grep MEMORY_BRIDGE_TOKEN ~/.memory-bridge/.env | cut -d= -f2)
```

## API

Base URL: `http://localhost:3722`

All endpoints except `/health` require:
```
Authorization: Bearer <token>
```

---

### GET /health

Check server status. No auth required.

**Request:**
```bash
curl http://localhost:3722/health
```

**Response:**
```json
{
  "status": "ok",
  "version": "1.0.0",
  "embeddingMode": "ollama",
  "memoriesCount": 42
}
```

---

### POST /store

Embed and persist a memory.

**Input schema:**

| Field | Type | Required | Description |
|---|---|---|---|
| `text` | string | yes | Memory content to embed and store |
| `tags` | string[] | no | Labels for filtering on recall |
| `source` | string | no | Provenance label (e.g. `"session"`, `"user"`) |

**Request:**
```bash
curl -s -X POST http://localhost:3722/store \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"text": "User prefers TypeScript over JavaScript", "tags": ["prefs"], "source": "session"}'
```

**Output schema:**
```json
{ "id": "<uuid>", "createdAt": "<ISO8601>" }
```

---

### POST /recall

Semantic search over stored memories. Returns most similar entries by vector distance.

**Input schema:**

| Field | Type | Default | Description |
|---|---|---|---|
| `query` | string | required | Natural language search query |
| `limit` | number | `10` | Max results (max 100) |
| `tags` | string[] | `[]` | Restrict to memories with any of these tags |

**Request:**
```bash
curl -s -X POST http://localhost:3722/recall \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query": "what did I work on last session", "limit": 5}'
```

**Output schema:**
```json
{
  "memories": [
    {
      "id": "<uuid>",
      "text": "...",
      "tags": ["..."],
      "source": "session",
      "createdAt": "<ISO8601>",
      "score": 0.94
    }
  ]
}
```

`score` is cosine similarity [0, 1]. Higher = more relevant.

---

### POST /forget

Delete a memory by ID.

**Input schema:**

| Field | Type | Required |
|---|---|---|
| `id` | string (uuid) | yes |

**Request:**
```bash
curl -s -X POST http://localhost:3722/forget \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"id": "<uuid>"}'
```

**Response:** `{ "message": "forgotten", "id": "<uuid>" }`

---

### GET /list

List all memories, paginated.

**Query params:** `page` (default: 1), `pageSize` (default: 50, max: 100)

**Response:**
```json
{ "data": [...], "total": 42, "page": 1, "pageSize": 50, "pages": 1 }
```

---

## Canonical usage pattern (for agents)

```bash
# At session start — recall relevant context
TOKEN=$(grep MEMORY_BRIDGE_TOKEN ~/.memory-bridge/.env | cut -d= -f2)
curl -s -X POST http://localhost:3722/recall \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query": "<current topic or task>", "limit": 5}'

# At session end — store important facts, decisions, preferences
curl -s -X POST http://localhost:3722/store \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"text": "<summary of what was decided or learned>", "tags": ["<topic>"], "source": "session"}'
```

## Storage paths

| Path | Contents |
|---|---|
| `~/.memory-bridge/index/` | Vector index (vectra) — the actual memories |
| `~/.memory-bridge/.env` | Token and config |
| `~/.memory-bridge/server.log` | Stdout log (launchd mode) |
| `~/.memory-bridge/server-error.log` | Stderr log (launchd mode) |