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

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):

./install.sh

Option B — Run manually:

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:

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:

curl http://localhost:3722/health

Response:

{
  "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:

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:

{ "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:

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:

{
  "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:

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:

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

---

Canonical usage pattern (for agents)

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